Repository navigation
Implement AsyncInterop\Promise #78
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
6701e92
82e0d4b
4b42c60
91ab8a4
d10bc89
ab4b4de
cb77cb5
7924b23
53ce643
b9c5183
40fa021
c2fbbcf
b7efdff
0c8a3fd
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -43,6 +43,7 @@ Table of Contents | |
| * [map()](#map) | ||
| * [reduce()](#reduce) | ||
| * [PromisorInterface](#promisorinterface) | ||
| * [AsyncInterop\Promise compatibility](#asyncinteroppromise-compatibility) | ||
| 4. [Examples](#examples) | ||
| * [How to use Deferred](#how-to-use-deferred) | ||
| * [How promise forwarding works](#how-promise-forwarding-works) | ||
|
|
@@ -151,6 +152,11 @@ and an associated value, or rejection (failure) and an associated reason. | |
| Once in the fulfilled or rejected state, a promise becomes immutable. | ||
| Neither its state nor its result (or error) can be modified. | ||
|
|
||
| This interface extends the | ||
| [`AsyncInterop\Promise`](https://github.com/async-interop/promise) interface. | ||
| See [`AsyncInterop\Promise` compatibility](#asyncinteroppromise-compatibility), | ||
| for further information. | ||
|
|
||
| #### Implementations | ||
|
|
||
| * [Promise](#promise-1) | ||
|
|
@@ -402,11 +408,48 @@ Creates a promise for the supplied `$promiseOrValue`. | |
| If `$promiseOrValue` is a value, it will be the resolution value of the | ||
| returned promise. | ||
|
|
||
| ```php | ||
| React\Promise\resolve(1)->then(function ($value) { | ||
| assert(1 === $value); | ||
| }); | ||
| ``` | ||
|
|
||
| If `$promiseOrValue` is a | ||
| [`AsyncInterop\Promise`](https://github.com/async-interop/promise), a trusted | ||
| promise that follows the state of the `AsyncInterop\Promise` is returned. | ||
|
|
||
| ```php | ||
| $asyncInteropPromise = getAsyncInteropPromiseWhichResolvesTo1(); | ||
|
|
||
| assert($asyncInteropPromise instanceof AsyncInterop\Promise); | ||
|
|
||
| React\Promise\resolve($asyncInteropPromise)->then(function ($value) { | ||
| assert(1 === $value); | ||
| }); | ||
| ``` | ||
|
|
||
| If `$promiseOrValue` is a thenable (any object that provides a `then()` method), | ||
| a trusted promise that follows the state of the thenable is returned. | ||
|
|
||
| ```php | ||
| $thenable = getThenableWhichResolvesTo1(); | ||
|
|
||
| assert(method_exists($thenable, 'then')); | ||
|
|
||
| React\Promise\resolve($asyncInteropPromise)->then(function ($value) { | ||
| assert(1 === $value); | ||
| }); | ||
| ``` | ||
|
|
||
| If `$promiseOrValue` is a promise, it will be returned as is. | ||
|
|
||
| ```php | ||
| $promise1 = React\Promise\resolve(1); | ||
| $promise2 = React\Promise\resolve($promise1); | ||
|
|
||
| assert($promise1 === $promise2); | ||
| ``` | ||
|
|
||
| #### reject() | ||
|
|
||
| ```php | ||
|
|
@@ -512,6 +555,70 @@ The `React\Promise\PromisorInterface` provides a common interface for objects | |
| that provide a promise. `React\Promise\Deferred` implements it, but since it | ||
| is part of the public API anyone can implement it. | ||
|
|
||
| ### AsyncInterop\Promise compatibility | ||
|
|
||
| The [`PromiseInterface`](#promiseinterface) extends the | ||
| [`AsyncInterop\Promise`](https://github.com/async-interop/promise) interface and | ||
| thereby all promise implementations from React/Promise implement its `when()` | ||
| method. | ||
|
|
||
| The `AsyncInterop\Promise` interface is intended for interoperability with other | ||
| libraries and their combinator and conversion functions. | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Suggestion: "The
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @kelunik While I understand your point, I actually prefer the current version (which is slightly more conservative and less enthusiastic). After all, while we all aim for this, "allows interoperability" has yet to be proven :-)
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @jsor Can we add a very simple example to show how this interoperability may look like from a consumer perspective? Such as a dummy combinator function with the proper typehint etc.? See also above for the documentation and/or example on how we can consume an AsyncInteropPromise. |
||
|
|
||
| Note, that although the `AsyncInterop\Promise` interface is named *Promise*, | ||
| it's API is different from promises commonly known from the | ||
| [CommonJS Promises/A](http://wiki.commonjs.org/wiki/Promises/A), | ||
| [Promises/A+](https://promisesaplus.com) or | ||
| [ECMAScript 2015 (ES6)](http://www.ecma-international.org/ecma-262/6.0/#sec-promise-constructor) | ||
| specifications. | ||
|
|
||
| If you're using React/Promise as your primary value placeholder implementation, | ||
| it is recommended to **not** use the `when()` method directly but the high level | ||
| consumption methods `then()`, `done()`, `otherwise()` and `always()` to consume | ||
| a promise's value or reason. | ||
|
|
||
| #### Examples | ||
|
|
||
| You can cast every foreign promise implementing `AsyncInterop\Promise` to a | ||
| trusted promise by passing it through [`resolve()`](#resolve). | ||
|
|
||
| It is also possible to return an `AsyncInterop\Promise` instance inside promise | ||
| chains. | ||
|
|
||
| ```php | ||
| $asyncInteropPromise = OtherLib\doAsyncTaskAndReturnAsyncInteropPromise(); | ||
|
|
||
| $reactPromise = React\Promise\resolve($asyncInteropPromise) | ||
| ->then(function ($value) { | ||
| // You can also return `AsyncInterop\Promise` instances | ||
| // from promise handlers | ||
| return NextLib\transformValueAndReturnAsyncInteropPromise($value); | ||
| }) | ||
| ->then(function ($transformedValue) { | ||
|
|
||
| }) | ||
| ; | ||
| ``` | ||
|
|
||
| Since promises from React/Promise also implement the `AsyncInterop\Promise` | ||
| interface, you can use these promises with combinator, conversion and coroutine | ||
| implementations of other libraries which support `AsyncInterop\Promise`. | ||
|
|
||
| ```php | ||
| $observable = Observable::fromPromise( | ||
| $reactSocketClient->connect('google.com:443') | ||
| ); | ||
|
|
||
| coroutine(function() { | ||
| $promiseArray = [ | ||
| $reactSocketClient->connect('google.com:443'), | ||
| $reactSocketClient->connect('google.de:443') | ||
| ]; | ||
|
|
||
| $stream = (yield first($promiseArray)); | ||
| }); | ||
| ``` | ||
|
|
||
| Examples | ||
| -------- | ||
|
|
||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| <?php | ||
|
|
||
| namespace React\Promise\AsyncInterop; | ||
|
|
||
| use AsyncInterop\Promise\Test; | ||
| use React\Promise\Deferred; | ||
|
|
||
| class DeferredTest extends Test | ||
| { | ||
| public function promise(callable $canceller = null) | ||
| { | ||
| $d = new Deferred($canceller); | ||
|
|
||
| return [ | ||
| $d->promise(), | ||
| [$d, 'resolve'], | ||
| [$d, 'reject'] | ||
| ]; | ||
| } | ||
| } |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| <?php | ||
|
|
||
| namespace React\Promise\AsyncInterop; | ||
|
|
||
| use AsyncInterop\Promise\Test; | ||
| use React\Promise\Deferred; | ||
| use React\Promise\LazyPromise; | ||
|
|
||
| class LazyPromiseTest extends Test | ||
| { | ||
| public function promise(callable $canceller = null) | ||
| { | ||
| $d = new Deferred($canceller); | ||
|
|
||
| $factory = function () use ($d) { | ||
| return $d->promise(); | ||
| }; | ||
|
|
||
| return [ | ||
| new LazyPromise($factory), | ||
| [$d, 'resolve'], | ||
| [$d, 'reject'] | ||
| ]; | ||
| } | ||
| } |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| <?php | ||
|
|
||
| namespace React\Promise\AsyncInterop; | ||
|
|
||
| use AsyncInterop\Promise\Test; | ||
| use React\Promise\Promise; | ||
|
|
||
| class PromiseTest extends Test | ||
| { | ||
| public function promise(callable $canceller = null) | ||
| { | ||
| $resolveCallback = $rejectCallback = null; | ||
|
|
||
| $promise = new Promise(function ($resolve, $reject) use (&$resolveCallback, &$rejectCallback) { | ||
| $resolveCallback = $resolve; | ||
| $rejectCallback = $reject; | ||
| }, $canceller); | ||
|
|
||
| return [ | ||
| $promise, | ||
| $resolveCallback, | ||
| $rejectCallback | ||
| ]; | ||
| } | ||
| } |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can we add a very simple example how we can consume an AsyncInteropPromise? Such as passing this through the
resolve()function etc.?