Merge promise interfaces

CHANGELOG.md

@@ -12,3 +12,8 @@ CHANGELOG for 3.x
       `some()`, `map()`, `reduce()`) now require an array of promises or values
       as input. Before, arrays and promises which resolve to an array were
       supported, other input types resolved to empty arrays or `null`. (#35).
+    * BC break: The interfaces `PromiseInterface`, `ExtendedPromiseInterface`
+      and `CancellablePromiseInterface` have been merged into a single
+      `PromiseInterface`. The `CancellablePromiseInterface` has been kept for
+      backward compatibility but is marked as deprecated and must not be used
+      anymore.

README.md

@@ -25,12 +25,10 @@ Table of Contents
      * [Deferred::reject()](#deferredreject)
    * [PromiseInterface](#promiseinterface)
      * [PromiseInterface::then()](#promiseinterfacethen)
-   * [ExtendedPromiseInterface](#extendedpromiseinterface)
-        * [ExtendedPromiseInterface::done()](#extendedpromiseinterfacedone)
-        * [ExtendedPromiseInterface::otherwise()](#extendedpromiseinterfaceotherwise)
-        * [ExtendedPromiseInterface::always()](#extendedpromiseinterfacealways)
-   * [CancellablePromiseInterface](#cancellablepromiseinterface)
-        * [CancellablePromiseInterface::cancel()](#cancellablepromiseinterfacecancel)
+     * [PromiseInterface::done()](#promiseinterfacedone)
+     * [PromiseInterface::otherwise()](#promiseinterfaceotherwise)
+     * [PromiseInterface::always()](#promiseinterfacealways)
+     * [PromiseInterface::cancel()](#promiseinterfacecancel)
    * [Promise](#promise-1)
    * [FulfilledPromise](#fulfilledpromise)
    * [RejectedPromise](#rejectedpromise)
@@ -193,22 +191,10 @@ the same call to `then()`:
 
 * [resolve()](#resolve) - Creating a resolved promise
 * [reject()](#reject) - Creating a rejected promise
-* [ExtendedPromiseInterface::done()](#extendedpromiseinterfacedone)
+* [PromiseInterface::done()](#promiseinterfacedone)
 * [done() vs. then()](#done-vs-then)
 
-### ExtendedPromiseInterface
-
-The ExtendedPromiseInterface extends the PromiseInterface with useful shortcut
-and utility methods which are not part of the Promises/A specification.
-
-#### Implementations
-
-* [Promise](#promise-1)
-* [FulfilledPromise](#fulfilledpromise)
-* [RejectedPromise](#rejectedpromise)
-* [LazyPromise](#lazypromise)
-
-#### ExtendedPromiseInterface::done()
+#### PromiseInterface::done()
 
 ```php
 $promise->done(callable $onFulfilled = null, callable $onRejected = null);
@@ -228,7 +214,7 @@ Since the purpose of `done()` is consumption rather than transformation,
 * [PromiseInterface::then()](#promiseinterfacethen)
 * [done() vs. then()](#done-vs-then)
 
-#### ExtendedPromiseInterface::otherwise()
+#### PromiseInterface::otherwise()
 
 ```php
 $promise->otherwise(callable $onRejected);
@@ -254,7 +240,7 @@ $promise
     )};
 ```
 
-#### ExtendedPromiseInterface::always()
+#### PromiseInterface::always()
 
 ```php
 $newPromise = $promise->always(callable $onFulfilledOrRejected);
@@ -301,13 +287,7 @@ return doSomething()
     ->always('cleanup');
 ```
 
-### CancellablePromiseInterface
-
-A cancellable promise provides a mechanism for consumers to notify the creator
-of the promise that they are not longer interested in the result of an
-operation.
-
-#### CancellablePromiseInterface::cancel()
+#### PromiseInterface::cancel()
 
 ``` php
 $promise->cancel();
@@ -319,13 +299,6 @@ further interest in the results of the operation.
 Once a promise is settled (either fulfilled or rejected), calling `cancel()` on
 a promise has no effect.
 
-#### Implementations
-
-* [Promise](#promise-1)
-* [FulfilledPromise](#fulfilledpromise)
-* [RejectedPromise](#rejectedpromise)
-* [LazyPromise](#lazypromise)
-
 ### Promise
 
 Creates a promise whose state is controlled by the functions passed to
@@ -435,11 +408,6 @@ a trusted promise that follows the state of the thenable is returned.
 
 If `$promiseOrValue` is a promise, it will be returned as is.
 
-Note: The promise returned is always a promise implementing
-[ExtendedPromiseInterface](#extendedpromiseinterface). If you pass in a custom
-promise which only implements [PromiseInterface](#promiseinterface), this
-promise will be assimilated to a extended promise following `$promiseOrValue`.
-
 #### reject()
 
 ```php

src/CancellablePromiseInterface.php

@@ -2,8 +2,19 @@
 
 namespace React\Promise;
 
-interface CancellablePromiseInterface extends PromiseInterface
+/**
+ * This interface is only kept for backward compatibility and must not be used
+ * anymore.
+ *
+ * @deprecated
+ */
+interface CancellablePromiseInterface
 {
+    /**
+     * @return PromiseInterface
+     */
+    public function then(callable $onFulfilled = null, callable $onRejected = null);
+
     /**
      * @return void
      */

src/FulfilledPromise.php

@@ -2,7 +2,7 @@
 
 namespace React\Promise;
 
-class FulfilledPromise implements ExtendedPromiseInterface, CancellablePromiseInterface
+class FulfilledPromise implements PromiseInterface, CancellablePromiseInterface
 {
     private $value;
 
@@ -43,7 +43,7 @@ public function done(callable $onFulfilled = null, callable $onRejected = null)
         queue()->enqueue(function () use ($onFulfilled) {
             $result = $onFulfilled($this->value);
 
-            if ($result instanceof ExtendedPromiseInterface) {
+            if ($result instanceof PromiseInterface) {
                 $result->done();
             }
         });

src/LazyPromise.php

@@ -2,7 +2,7 @@
 
 namespace React\Promise;
 
-class LazyPromise implements ExtendedPromiseInterface, CancellablePromiseInterface
+class LazyPromise implements PromiseInterface, CancellablePromiseInterface
 {
     private $factory;
     private $promise;

src/Promise.php

@@ -2,7 +2,7 @@
 
 namespace React\Promise;
 
-class Promise implements ExtendedPromiseInterface, CancellablePromiseInterface
+class Promise implements PromiseInterface, CancellablePromiseInterface
 {
     private $canceller;
     private $result;
@@ -45,7 +45,7 @@ public function done(callable $onFulfilled = null, callable $onRejected = null)
             return $this->result()->done($onFulfilled, $onRejected);
         }
 
-        $this->handlers[] = function (ExtendedPromiseInterface $promise) use ($onFulfilled, $onRejected) {
+        $this->handlers[] = function (PromiseInterface $promise) use ($onFulfilled, $onRejected) {
             $promise
                 ->done($onFulfilled, $onRejected);
         };
@@ -90,7 +90,7 @@ public function cancel()
     private function resolver(callable $onFulfilled = null, callable $onRejected = null)
     {
         return function ($resolve, $reject) use ($onFulfilled, $onRejected) {
-            $this->handlers[] = function (ExtendedPromiseInterface $promise) use ($onFulfilled, $onRejected, $resolve, $reject) {
+            $this->handlers[] = function (PromiseInterface $promise) use ($onFulfilled, $onRejected, $resolve, $reject) {
                 $promise
                     ->then($onFulfilled, $onRejected)
                     ->done($resolve, $reject);
@@ -116,7 +116,7 @@ private function reject($reason = null)
         $this->settle(reject($reason));
     }
 
-    private function settle(ExtendedPromiseInterface $result)
+    private function settle(PromiseInterface $result)
     {
         if ($result instanceof LazyPromise) {
             $result = $result->promise();

src/PromiseInterface.php

@@ -8,4 +8,24 @@ interface PromiseInterface
      * @return PromiseInterface
      */
     public function then(callable $onFulfilled = null, callable $onRejected = null);
+
+    /**
+     * @return void
+     */
+    public function done(callable $onFulfilled = null, callable $onRejected = null);
+
+    /**
+     * @return PromiseInterface
+     */
+    public function otherwise(callable $onRejected);
+
+    /**
+     * @return PromiseInterface
+     */
+    public function always(callable $onFulfilledOrRejected);
+
+    /**
+     * @return void
+     */
+    public function cancel();
 }

src/RejectedPromise.php

@@ -2,7 +2,7 @@
 
 namespace React\Promise;
 
-class RejectedPromise implements ExtendedPromiseInterface, CancellablePromiseInterface
+class RejectedPromise implements PromiseInterface, CancellablePromiseInterface
 {
     private $reason;
 
@@ -47,7 +47,7 @@ public function done(callable $onFulfilled = null, callable $onRejected = null)
                 throw UnhandledRejectionException::resolve($result->reason);
             }
 
-            if ($result instanceof ExtendedPromiseInterface) {
+            if ($result instanceof PromiseInterface) {
                 $result->done();
             }
         });

src/functions.php

@@ -4,7 +4,7 @@
 
 function resolve($promiseOrValue = null)
 {
-    if ($promiseOrValue instanceof ExtendedPromiseInterface) {
+    if ($promiseOrValue instanceof PromiseInterface) {
         return $promiseOrValue;
     }
 

tests/CancellationQueueTest.php

@@ -75,7 +75,7 @@ public function rethrowsExceptionsThrownFromCancel()
         $this->setExpectedException('\Exception', 'test');
 
         $mock = $this
-            ->getMockBuilder('React\Promise\CancellablePromiseInterface')
+            ->getMockBuilder('React\Promise\PromiseInterface')
             ->getMock();
         $mock
             ->expects($this->once())

tests/FunctionAnyTest.php

@@ -99,14 +99,14 @@ public function shouldNotRelyOnArryIndexesWhenUnwrappingToASingleResolutionValue
     public function shouldCancelInputArrayPromises()
     {
         $mock1 = $this
-            ->getMockBuilder('React\Promise\CancellablePromiseInterface')
+            ->getMockBuilder('React\Promise\PromiseInterface')
             ->getMock();
         $mock1
             ->expects($this->once())
             ->method('cancel');
 
         $mock2 = $this
-            ->getMockBuilder('React\Promise\CancellablePromiseInterface')
+            ->getMockBuilder('React\Promise\PromiseInterface')
             ->getMock();
         $mock2
             ->expects($this->once())
@@ -128,7 +128,7 @@ public function shouldNotCancelOtherPendingInputArrayPromisesIfOnePromiseFulfill
         $deferred->resolve();
 
         $mock2 = $this
-            ->getMockBuilder('React\Promise\CancellablePromiseInterface')
+            ->getMockBuilder('React\Promise\PromiseInterface')
             ->getMock();
         $mock2
             ->expects($this->never())

tests/FunctionMapTest.php

@@ -97,15 +97,21 @@ public function shouldRejectWhenInputContainsRejection()
     public function shouldCancelInputArrayPromises()
     {
         $mock1 = $this
-            ->getMockBuilder('React\Promise\CancellablePromiseInterface')
+            ->getMockBuilder('React\Promise\PromiseInterface')
             ->getMock();
+        $mock1
+            ->method('then')
+            ->will($this->returnSelf());
         $mock1
             ->expects($this->once())
             ->method('cancel');
 
         $mock2 = $this
-            ->getMockBuilder('React\Promise\CancellablePromiseInterface')
+            ->getMockBuilder('React\Promise\PromiseInterface')
             ->getMock();
+        $mock2
+            ->method('then')
+            ->will($this->returnSelf());
         $mock2
             ->expects($this->once())
             ->method('cancel');

tests/FunctionRaceTest.php

@@ -96,14 +96,14 @@ public function shouldRejectIfFirstSettledPromiseRejects()
     public function shouldCancelInputArrayPromises()
     {
         $mock1 = $this
-            ->getMockBuilder('React\Promise\CancellablePromiseInterface')
+            ->getMockBuilder('React\Promise\PromiseInterface')
             ->getMock();
         $mock1
             ->expects($this->once())
             ->method('cancel');
 
         $mock2 = $this
-            ->getMockBuilder('React\Promise\CancellablePromiseInterface')
+            ->getMockBuilder('React\Promise\PromiseInterface')
             ->getMock();
         $mock2
             ->expects($this->once())
@@ -124,7 +124,7 @@ public function shouldNotCancelOtherPendingInputArrayPromisesIfOnePromiseFulfill
         $deferred->resolve();
 
         $mock2 = $this
-            ->getMockBuilder('React\Promise\CancellablePromiseInterface')
+            ->getMockBuilder('React\Promise\PromiseInterface')
             ->getMock();
         $mock2
             ->expects($this->never())
@@ -145,7 +145,7 @@ public function shouldNotCancelOtherPendingInputArrayPromisesIfOnePromiseRejects
         $deferred->reject();
 
         $mock2 = $this
-            ->getMockBuilder('React\Promise\CancellablePromiseInterface')
+            ->getMockBuilder('React\Promise\PromiseInterface')
             ->getMock();
         $mock2
             ->expects($this->never())

tests/FunctionReduceTest.php

@@ -260,15 +260,21 @@ public function shouldProvideCorrectBasisValue()
     public function shouldCancelInputArrayPromises()
     {
         $mock1 = $this
-            ->getMockBuilder('React\Promise\CancellablePromiseInterface')
+            ->getMockBuilder('React\Promise\PromiseInterface')
             ->getMock();
+        $mock1
+            ->method('then')
+            ->will($this->returnSelf());
         $mock1
             ->expects($this->once())
             ->method('cancel');
 
         $mock2 = $this
-            ->getMockBuilder('React\Promise\CancellablePromiseInterface')
+            ->getMockBuilder('React\Promise\PromiseInterface')
             ->getMock();
+        $mock2
+            ->method('then')
+            ->will($this->returnSelf());
         $mock2
             ->expects($this->once())
             ->method('cancel');