Promise

The Promise type represents a promise, as defined by the Promises/A+ 1.1 specification. A promise (a.k.a. future or task) represents an operation that completes at some point in the future, optionally producing a value. This implementation of the Promise type actually functions more as an interface or wrapper that accepts and exposes a then method. This provides a consistent mechanism for abstracting the inner workings of a promise implementation from its interface, allowing implementations (e.g. the Deferred type) to expose only the functionality required by the specification.

Constructor

Promise(thenMethod)

Constructs a new instance of a Promise that wraps and exposes the provided then method.

Parameters

thenMethod
A method that implements the Promises/A+ specification for the then method. This method will be exposed via the then method of this instance, receiving the same parameters upon invocation.

Instance Methods

then(onFulfilled, onRejected)

Registers methods to be invoked when the current instance is either fulfilled or rejected, returning a new Promise that represents the return value (if any) of the invoked method.

Parameters

onFulfilled (optional)
A method that is called after the promise is fulfilled. The fulfillment value of the promise (if present) is provided to this method as the first parameter when it is invoked. This method is invoked either one time (if the promise is fulfilled) or not at all (if the promise is rejected). If this parameter is not a function, it is ignored.
onRejected (optional)
A method that is called after the promise is rejected. The rejection reason of the promise (if present) is provided to this method as the first parameter when it is invoked. This method is invoked either one time (if the promise is rejected) or not at all (if the promise is fulfilled). If this parameter is not a function, it is ignored.

Return Value

A new Promise that is fulfilled or rejected after onFulfilled or onRejected has been invoked as a result of the completion of the original Promise (i.e. a continuation). If both onFulfilled and onRejected are ignored (i.e. not functions), this method returns the original Promise instance, not a new one.

The fulfillment value or rejection reason (if any) of the new promise is the return value produced by either onFulfilled or onRejected, whichever is invoked. If the return value of onFulfilled or onRejected is a Promise, the Promise returned by the then method assumes the state of this inner Promise. See the Promises/A+ specification or the examples for more information.

Promise Extensions

Expanding upon the functionality defined by the Promises/A+ specification, several extension methods and static instances are provided to simplify common development tasks.

Static Instances

Promise.fulfilled
A Promise that has been fulfilled with no result.
Promise.never
A Promise that will never be resolved. All invocations of the then method will return Promise.never. Any onFulfilled or onRejected parameters provided to the then method will be ignored and discarded – because the instance will never complete, these parameters will never be invoked, so they are not stored.
Promise.rejected
A Promise that has been rejected with no reason provided.

Instance Methods

always(onFulfilledOrRejected)

Registers a method to be invoked when the current instance is either fulfilled or rejected (regardless of the outcome), returning a new Promise that represents the return value (if any) of the invoked method. This is a convenience method equivalent to passing the same continuation method to both the onFulfilled and onRejected parameters of the then method. made available on every Promise object

Parameters

onFulfilledOrRejected
A method that is called after the promise is fulfilled or rejected, regardless of the final state. The value passed to the method depends upon the completion state of the Promise: it is either the fulfillment value if the Promise is fulfilled, or it is the rejection reason if the Promise is rejected.

Return Value

A new Promise that is fulfilled or rejected after onFulfilledOrRejected has been invoked as a result of the completion of the original Promise (i.e. a continuation).

Static Methods

fromThenable(thenable)

Attempts to consume a "thenable" (i.e. promise-like object), transforming it into a specification-compliant Promise. This method allows non-compliant promise implementations (e.g. jQuery promises & Deferreds) to be consumed in such a way that their behavior is standardized in a specification-compliant way, ensuring fulfillment and rejection propagation, as well as scheduling compliance.

Parameters

thenable
A promise-like entity.

Return Value

If thenable does not possess a "then" method, then null. If attempting to access the "then" method of thenable produces an exception, then a new, rejected Promise is returned whose rejection reason is the exception encountered. Otherwise, a Promise that represents thenable, conveying the fulfillment or rejection values (as produced) by that object.

fulfilledWith(result)

Creates a Promise that has been fulfilled with the (optional) provided result. This method provides a convenient mechanism for creating a fulfilled Promise when the resulting value is known immediately.

Parameters

result (optional)
The optional result / fulfillment value.

Return Value

A Promise that is fulfilled with the provided result.

rejectedWith(reason)

Creates a Promise that has been rejected with the (optional) provided reason. This method provides a convenient mechanism for creating a rejected Promise when the reason for rejection is known immediately.

Parameters

reason (optional)
The optional reason for rejection.

Return Value

A Promise that is rejected for the specified reason.

whenAll(promises)

Creates a Promise that is fulfilled when all the specified Promises are fulfilled, or rejected when one of the Promises is rejected.

Parameters

promises
An array of promises.

Return Value

A promise that represents the completed state of all the provided promises. This promise is:

  • Fulfilled when all provided promises have been fulfilled.
  • Rejected when one or more of the provided promises have been rejected. Rejection of the promise occurs when any one provided promise is rejected.

If the array of provided promises is empty, Promise.fulfilled is returned. If the array of provided promises contains only one promise, that promise is returned.

Static Methods

whenAny(promises)

Creates a Promise that is fulfilled when any of the specified Promises are completed.

Parameters

promises
An array of promises.

Return Value

A Promise that is fulfilled when any one of the specified Promises are fulfilled or rejected. The returned Promise assumes the state / value of the first completed (i.e. fulfilled or rejected) Promise (i.e. becomes the completed Promise).

If the array of provided promises is empty, Promise.fulfilled is returned. If the array of provided promises contains only one promise, that promise is returned.

Last edited Mar 21, 2014 at 9:31 PM by CommanderQ, version 11