extrinsic-promises
extrinsic-promises
is a JavaScript module that provides a convenient promises anti-pattern
for those times when you just really need to settle (fulfill or reject) your promise from
outside the promise's work-function.
Specifically, an ExtrinsicPromise
is a thennable that you construct without a
work-function, and instead call public fulfill
and reject
methods on the object
to settle the state of the promise.
Note: this is generally a promises antipattern. It is not recommended for most use cases,
but there are some situations that can't reasonably be handled with traditional promises (at
least not without re-implementing extrinsic-promises.)
Installation
npm install --save extrinsic-promises
Example
Basic usage:
import ExtrinsicPromise from 'extrinsic-promises'
const promise = new ExtrinsicPromise()
promise.then((value) => {
console.log('Promise was fulfilled with value:', value)
})
promise.fulfill('Some value')
Rejecting a promise:
const promise = new ExtrinsicPromise()
promise.then(null, (reason) => {
console.log('Promise was reject for reason:', reason)
})
promise.reject(new Error('some reason'))
Getting an Extended API
The ExtrinsicPromise
only provides the basic .then(onFulfill, onReject)
method for promises. If
you want the convenience methods provided by your favoritate promises library, you can usually use that
library to wrap an ExtrinsicPromise
appropriately:
import Promise from 'bluebird'
import ExtrinsicPromise from 'extrinsic-promises'
const exPromise = new ExtrinsicPromise()
const bluebirdPromise = Promise.fulfill(exPromise)
Or, if the library doesn't provide a method like that, you can use the standard Promise
constructor
as follows:
import ExtrinsicPromise from 'extrinsic-promises'
const exPromise = new ExtrinsicPromise()
const otherPromise = new Promise((fulfill, reject) => {
exPromise.then(fulfill, reject)
})
API
The ExtrinsicPromise
class exports the following public methods:
ExtrinsicPromise::then(onFulfill[, onReject])
The standard then
method of the Promises/A+ standard,
used to register an on-fulfill and/or on-reject handler for the promise.
ExtrinsicPromise::fulfill([withValue])
Resolve (fulfill) the ExtrinsicPromise
with the optional given value. Note that there is no gaurantee as to when
fulfillment occurs (i.e., synchronously or asynchronously).
This method is already bound and can be used correctly as a function reference. E.g.,:
const exPromise = new ExtrinsicPromise()
const fulfillLater = exPromise.fulfill
fulfillLater(value)
ExtrinsicPromise::reject([forReason])
Reject the ExtrinsicPromise
with the optional given reason (typically, an Error object). Note that there is
no gaurantee as to when rejection occurs (i.e., synchronously or asynchronously).
This method is already bound and can be used correctly as a function reference. E.g.,:
const exPromise = new ExtrinsicPromise()
const rejectLater = exPromise.reject
rejectLater(reason)
ExtrinsicPromise::adopt(thennable)
Adopt the state of the given thennable, once the thennable settles, if this extrinsic promise has not already
settled. This is a convenience for using this extrinsic promise's fulfill
and reject
methods as the on-fulfill
and on-reject handlers, respectively, of the given thennable, as follows:
const exPromise = new ExtrinsicPromise()
thennable.then(exPromise.fulfill, exPromise.reject)
ExtrinsicPromise::work(workfunction)
An alternative interface for settling the promise, this allows you to pass in a work-function just like
you normally would pass to the Promise
constructor, but in this case you're passing it in after the promise
has already been constructed.
The given work function will be invoked unconditionally (even if the promise is already settled) with
two arguments, typically called fulfill
and reject
. These are functions that are used to settle the state
of the promise once the work you promise to do is done, just like the .fulfill()
and .reject()
methods on
the ExtrinsicPromise
.
If an error is thrown inside the workfunction, it will be treated as a rejection.
Note that the work function will be called asynchronously, i.e., the call to .work()
will return before
the given work function has been called.
ExtrinsicPromise::hide()
Returns a minimal thennable object which only exposes the .then()
method of this object as a bound function.
This allows you to pass around this object as a promise, without exposing it's state-mutating methods like
.fulfill()
and .reject()
.
How Does it Work?
It's pretty simple, feel free to read the code. There's a few details necessary to avoid race conditions, but
the gist of it is to simply save the fulfill
and reject
signalling functions that the promise passes in
to the work function:
constructor () {
new Promise((fulfill, reject) => {
this.fulfill = fulfill
this.reject = reject
})
}