Merge remote-tracking branch 'origin/lazy-promise'

* origin/lazy-promise:
  Add When::lazy() to readme and changelog
  Add tests for When::lazy
  Add test for factory throwing an exception
  Add lazy promise

Author: igorw

CHANGELOG.md

@@ -5,6 +5,8 @@ CHANGELOG
 
   * Trigger PHP errors when invalid callback is passed.
   * Fully resolve rejection value before calling rejection handler.
+  * Add When::lazy() to create lazy promises which will be initialized once a
+    consumer calls the then() method.
 
 * 1.0.3 (2012-11-17)
 

README.md

@@ -26,6 +26,7 @@ Table of Contents
      * [When::reduce()](#whenreduce)
      * [When::resolve()](#whenresolve)
      * [When::reject()](#whenreject)
+     * [When::lazy()](#whenlazy)
    * [Promisor](#promisor)
 4. [Examples](#examples)
    * [How to use Deferred](#how-to-use-deferred)
@@ -282,6 +283,31 @@ This can be useful in situations where you need to reject a Promise without
 throwing an exception. For example, it allows you to propagate a rejection with
 the value of another Promise.
 
+#### When::lazy()
+
+``` php
+$promise = React\Promise\When::lazy(callable $factory);
+```
+
+Creates a Promise which will be lazily initialized by `$factory` once a consumer
+calls the `then()` method.
+
+```php
+$factory = function () {
+    $deferred = new React\Promise\Deferred();
+
+    // Do some heavy stuff here and resolve the Deferred once completed
+
+    return $deferred->promise();
+};
+
+$promise = React\Promise\When::lazy($factory);
+
+// $factory will only be executed once we call then()
+$promise->then(function ($value) {
+});
+```
+
 ### Promisor
 
 The `React\Promise\PromisorInterface` provides a common interface for objects

src/React/Promise/LazyPromise.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace React\Promise;
+
+class LazyPromise implements PromiseInterface
+{
+    private $factory;
+    private $promise;
+
+    public function __construct($factory)
+    {
+        $this->factory = $factory;
+    }
+
+    public function then($fulfilledHandler = null, $errorHandler = null, $progressHandler = null)
+    {
+        if (null === $this->promise) {
+            try {
+                $this->promise = Util::promiseFor(call_user_func($this->factory));
+            } catch (\Exception $exception) {
+                $this->promise = new RejectedPromise($exception);
+            }
+        }
+
+        return $this->promise->then($fulfilledHandler, $errorHandler, $progressHandler);
+    }
+}

src/React/Promise/When.php

@@ -14,6 +14,11 @@ public static function reject($promiseOrValue = null)
         return Util::rejectedPromiseFor($promiseOrValue);
     }
 
+    public static function lazy($factory)
+    {
+        return new LazyPromise($factory);
+    }
+
     public static function all($promisesOrValues, $fulfilledHandler = null, $errorHandler = null, $progressHandler = null)
     {
         $promise = static::map($promisesOrValues, function ($val) {

tests/React/Promise/LazyPromiseTest.php

@@ -0,0 +1,88 @@
+<?php
+
+namespace React\Promise;
+
+/**
+ * @group Promise
+ * @group LazyPromise
+ */
+class LazyPromiseTest extends TestCase
+{
+    /** @test */
+    public function shouldNotCallFactoryIfThenIsNotInvoked()
+    {
+        $factory = $this->createCallableMock();
+        $factory
+            ->expects($this->never())
+            ->method('__invoke');
+
+        new LazyPromise($factory);
+    }
+
+    /** @test */
+    public function shouldCallFactoryIfThenIsInvoked()
+    {
+        $factory = $this->createCallableMock();
+        $factory
+            ->expects($this->once())
+            ->method('__invoke');
+
+        $p = new LazyPromise($factory);
+        $p->then();
+    }
+
+    /** @test */
+    public function shouldReturnPromiseFromFactory()
+    {
+        $factory = $this->createCallableMock();
+        $factory
+            ->expects($this->once())
+            ->method('__invoke')
+            ->will($this->returnValue(new FulfilledPromise(1)));
+
+        $fulfilledHandler = $this->createCallableMock();
+        $fulfilledHandler
+            ->expects($this->once())
+            ->method('__invoke')
+            ->with($this->identicalTo(1));
+
+        $p = new LazyPromise($factory);
+
+        $p->then($fulfilledHandler);
+    }
+
+    /** @test */
+    public function shouldReturnPromiseIfFactoryReturnsNull()
+    {
+        $factory = $this->createCallableMock();
+        $factory
+            ->expects($this->once())
+            ->method('__invoke')
+            ->will($this->returnValue(null));
+
+        $p = new LazyPromise($factory);
+        $this->assertInstanceOf('React\\Promise\\PromiseInterface', $p->then());
+    }
+    
+    /** @test */
+    public function shouldReturnRejectedPromiseIfFactoryThrowsException()
+    {
+        $exception = new \Exception();
+        
+        $factory = $this->createCallableMock();
+        $factory
+            ->expects($this->once())
+            ->method('__invoke')
+            ->will($this->throwException($exception));
+
+        $errorHandler = $this->createCallableMock();
+        $errorHandler
+            ->expects($this->once())
+            ->method('__invoke')
+            ->with($this->identicalTo($exception));
+
+        $p = new LazyPromise($factory);
+
+        $p->then($this->expectCallableNever(), $errorHandler);
+    }
+}

tests/React/Promise/WhenLazyTest.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace React\Promise;
+
+/**
+ * @group When
+ * @group WhenLazy
+ */
+class WhenLazyTest extends TestCase
+{
+    /** @test */
+    public function shouldReturnALazyPromise()
+    {
+        $this->assertInstanceOf('React\\Promise\\PromiseInterface',  When::lazy(function () {}));
+    }
+
+    /** @test */
+    public function shouldCallFactoryIfThenIsInvoked()
+    {
+        $factory = $this->createCallableMock();
+        $factory
+            ->expects($this->once())
+            ->method('__invoke');
+
+        When::lazy($factory)
+            ->then();
+    }
+}