Status

This proposal has progressed to the Draft ECMAScript 6 Specification, which is available for review on the official ECMAScript wiki. When referencing the promises specification, you should reference the draft ECMAScript 6 spec, and not this repository.

We are still using this repository as a way to fix the remaining issues with the promises specification, and as such it may be slightly ahead of the draft specification as we perform that work. However, we must emphasize it is only a staging ground.

Promise Objects

A Promise is an object that is used as a placeholder for the eventual results of a deferred (and possibly asynchronous) computation.

Any Promise object is in one of three mutually exclusive states: fulfilled, rejected, and pending:

• A promise p is fulfilled if p.then(f, r) will immediately enqueue a Task to call the function f.
• A promise p is rejected if p.then(f, r) will immediately enqueue a Task to call the function r.
• A promise is pending if it is neither fulfilled nor rejected.

A promise said to be settled if it is not pending, i.e. if it is either fulfilled or rejected.

A promise is resolved if it is settled or if it has been "locked in" match the state of another promise. Attempting to resolve or reject a resolved promise has no effect. A promise is unresolved if it is not resolved. An unresolved promise is always in the pending state. A resolved promise may be pending, fullfilled, or rejected.

Promise Abstract Operations

PromiseCapability Records

A PromiseCapability is a Record value used to encapsulate a promise object along with the functions that are capable of resolving or rejecting that promise object. PromiseCapability records are produced by the NewPromiseCapability abstract operation.

PromiseCapability Records have the fields listed in this table.

IfAbruptRejectPromise ( value, capability )

IfAbruptRejectPromise is a short hand for a sequence of algorithm steps that use a PromiseCapability record. An algorithm step of the form:

1. IfAbruptRejectPromise(value, capability).

means the same things as:

1. If value is an abrupt completion,
   1. Let rejectResult be the result of calling the [[Call]] internal method of capability.[[Reject]] with undefined as thisArgument and (value.[[value]]) as argumentsList.
   2. ReturnIfAbrupt(rejectResult).
   3. Return capability.[[Promise]].
2. Else if value is a Completion Record, then let value be value.[[value]].

PromiseReaction Records

The PromiseReaction is a Record value used to store information about how a promise should react when it becomes resolved or rejected with a given value. PromiseReaction records are created by the then method of the Promise prototype, and are used by a PromiseReactionTask.

PromiseReaction records have the fields listed in this table.

CreateResolvingFunctions ( promise )

When CreateResolvingFunctions is performed with argument promise, the following steps are taken:

1. Let alreadyResolved be a new Record { [[value]]: false }.
2. Let resolve be a new built-in function object as defined in Promise Resolve Functions.
3. Set the [[Promise]] internal slot of resolve to promise.
4. Set the [[AlreadyResolved]] internal slot of resolve to alreadyResolved.
5. Let reject be a new built-in function object as defined in Promise Reject Functions.
6. Set the [[Promise]] internal slot of reject to promise.
7. Set the [[AlreadyResolved]] internal slot of reject to alreadyResolved.
8. Return a new Record { [[Resolve]]: resolve, [[Reject]]: reject }.

Promise Reject Functions

A promise reject function is an anonymous built-in function that has [[Promise]] and [[AlreadyResolved]] internal slots.

When a promise reject function F is called with argument reason, the following steps are taken:

1. Assert: F has a [[Promise]] internal slot whose value is an Object.
2. Let promise be the value of F's [[Promise]] internal slot.
3. Let alreadyResolved be the value of F's [[AlreadyResolved]] internal slot.
4. If alreadyResolved.[[value]] is true, then return undefined.
5. Set alreadyResolved.[[value]] to true.
6. Return RejectPromise(promise, reason).

Promise Resolve Functions

A promise resolve function is an anonymous built-in function that has [[Promise]] and [[AlreadyResolved]] internal slots.

When a promise resolve function F is called with argument resolution, the following steps are taken:

1. Assert: F has a [[Promise]] internal slot whose value is an Object.
2. Let promise be the value of F's [[Promise]] internal slot.
3. Let alreadyResolved be the value of F's [[AlreadyResolved]] internal slot.
4. If alreadyResolved.[[value]] is true, then return undefined.
5. Set alreadyResolved.[[value]] to true.
6. If SameValue(resolution, promise) is true, then
   1. Let selfResolutionError be a newly-created TypeError object.
   2. Return RejectPromise(promise, selfResolutionError).
7. If Type(resolution) is not Object, then
   1. Return FulfillPromise(promise, resolution).
8. Let then be Get(resolution, "then").
9. If then is an abrupt completion, then
   1. Return RejectPromise(promise, then.[[value]]).
10. Let then be then.[[value]].
11. If IsCallable(then) is false, then
    1. Return FulfillPromise(promise, resolution).
12. Perform EnqueueTask("PromiseTasks", ResolvePromiseViaThenableTask, (promise, resolution, then)).
13. Return undefined.

FulfillPromise ( promise, value )

1. Assert: the value of promise's [[PromiseState]] internal slot is "pending".
2. Let reactions be the value of promise's [[PromiseFulfillReactions]] internal slot.
3. Set the value of promise's [[PromiseResult]] internal slot to value.
4. Set the value of promise's [[PromiseFulfillReactions]] internal slot to undefined.
5. Set the value of promise's [[PromiseRejectReactions]] internal slot to undefined.
6. Set the value of promise's [[PromiseState]] internal slot to "fulfilled".
7. Return TriggerPromiseReactions(reactions, value).

NewPromiseCapability ( C )

The abstract operation NewPromiseCapability takes a constructor function, and attempts to use that constructor function in the fashion of the built-in Promise constructor to create a Promise object and extract its resolve and reject functions. The promise plus the resolve and reject functions are used to initialise a new PromiseCapability record which is returned as the value of this abstract operation.

1. If IsConstructor(C) is false, throw a TypeError.
2. Assert: C is a constructor function that supports the parameter conventions of the Promise constructor.
3. Let promise be CreateFromConstructor(C).
4. ReturnIfAbrupt(promise).
5. If Type(promise) is not Object, then throw a TypeError exception.
6. Return CreatePromiseCapabilityRecord(promise, C).

NOTE: This abstract operation supports Promise subclassing, as it is generic on any constructor that calls a passed executor function argument in the same way as the Promise constructor. It is used to generalize static methods of the Promise constructor to any subclass.

CreatePromiseCapabilityRecord ( promise, constructor )

1. Assert: promise is an uninitialized object created as if by invoking @@create on constructor.
2. Let promiseCapability be a new PromiseCapability { [[Promise]]: promise, [[Resolve]]: undefined, [[Reject]]: undefined }.
3. Let executor be a new built-in function object as defined in GetCapabilitiesExecutor Functions.
4. Set the [[Capability]] internal slot of executor to promiseCapability.
5. Let constructorResult be the result of calling the [[Call]] internal method of constructor, passing promise and (executor) as the arguments.
6. ReturnIfAbrupt(constructorResult).
7. If IsCallable(promiseCapability.[[Resolve]]) is false, then throw a TypeError exception.
8. If IsCallable(promiseCapability.[[Reject]]) is false, then throw a TypeError exception.
9. If Type(constructorResult) is Object and SameValue(promise, constructorResult) is false, then throw a TypeError exception.
10. Return promiseCapability.

GetCapabilitiesExecutor Functions

A GetCapabilitiesExecutor function is an anonymous built-in function that has a [[Capability]] internal slot.

When a GetCapabilitiesExecutor function F is called with arguments resolve and reject the following steps are taken:

1. Assert: F has a [[Capability]] internal slot whose value is a PromiseCapability Record.
2. Let promiseCapability be the value of F's [[Capability]] internal slot.
3. If promiseCapability.[[Resolve]] is not undefined, then throw a TypeError exception.
4. If promiseCapability.[[Reject]] is not undefined, then throw a TypeError exception.
5. Set promiseCapability.[[Resolve]] to resolve.
6. Set promiseCapability.[[Reject]] to reject.
7. Return undefined.

RejectPromise ( promise, reason )

1. Assert: the value of promise's [[PromiseState]] internal slot is "pending".
2. Let reactions be the value of promise's [[PromiseRejectReactions]] internal slot.
3. Set the value of promise's [[PromiseResult]] internal slot to reason.
4. Set the value of promise's [[PromiseFulfillReactions]] internal slot to undefined.
5. Set the value of promise's [[PromiseRejectReactions]] internal slot to undefined.
6. Set the value of promise's [[PromiseState]] internal slot to "rejected".
7. Return TriggerPromiseReactions(reactions, reason).

IsPromise ( x )

The abstract operation IsPromise checks for the promise brand on an object.

1. If Type(x) is not Object, return false.
2. If x does not have a [[PromiseState]] internal slot, return false.
3. If the value of x's [[PromiseState]] internal slot is undefined, return false.
4. Return true.

TriggerPromiseReactions ( reactions, argument )

The abstract operation TriggerPromiseReactions takes a collection of functions to trigger in the next Task, and calls them, passing each the given argument. Typically, these reactions will modify a previously-returned promise, possibly calling in to a user-supplied handler before doing so.

1. Repeat for each reaction in reactions, in original insertion order
   1. Perform EnqueueTask("PromiseTasks", PromiseReactionTask, (reaction, argument)).
2. Return undefined.

Promise Tasks

PromiseReactionTask ( reaction, argument )

The task PromiseReactionTask with parameters reaction and argument applies the appropriate handler to the incoming value, and uses the handler's return value to resolve or reject the derived promise associated with that handler.

1. Assert: reaction is a PromiseReaction Record.
2. Let promiseCapability be reaction.[[Capabilities]].
3. Let handler be reaction.[[Handler]].
4. If handler is "Identity", then let handlerResult be NormalCompletion(argument).
5. Else if handler is "Thrower", then let handlerResult be Completion{ [[type]]: throw, [[value]]: argument, [[target]]: empty }.
6. Else, let handlerResult be the result of calling the [[Call]] internal method of handler passing undefined as thisArgument and (argument) as argumentsList.
7. If handlerResult is an abrupt completion, then
   1. Let status be the result of calling the [[Call]] internal method of promiseCapability.[[Reject]] passing undefined as thisArgument and (handlerResult.[[value]]) as argumentsList.
   2. NextTask status.
8. Let handlerResult be handlerResult.[[value]].
9. Let status be the result of calling the [[Call]] internal method of promiseCapability.[[Resolve]] passing undefined as thisArgument and (handlerResult) as argumentsList.
10. NextTask status.

ResolvePromiseViaThenableTask ( promiseToResolve, thenable, then )

The task ResolvePromiseViaThenableTask with parameters promiseToResolve, thenable, and then uses the supplied thenable and its then method to resolve the given promise. This process must take place in an enqueued task to ensure that code inside the then method cannot disrupt the invariants of surrounding code.

1. Let resolvingFunctions be CreateResolvingFunctions(promiseToResolve).
2. Let thenCallResult be the result of calling the [[Call]] internal method of then passing thenable as thisArgument and (resolvingFunctions.[[Resolve]], resolvingFunctions.[[Reject]]) as argumentsList.
3. If thenCallResult is an abrupt completion,
   1. Let status be the result of calling the [[Call]] internal method of resolvingFunctions.[[Reject]] passing undefined as thisArgument and (thenCallResult.[[value]]) as argumentsList.
   2. NextTask status.
4. NextTask thenCallResult.

The Promise Constructor

The Promise constructor is the %Promise% intrinsic object and the initial value of the Promise property of the global object. When Promise is called as a function rather than as a constructor, it initialises its this value with the internal state necessary to support the Promise.prototype methods.

The Promise constructor is designed to be subclassable. It may be used as the value in an extends clause of a class definition. Subclass constructors that intend to inherit the specified Promise behaviour must include a super call to Promise.

Promise ( executor )

When the Promise function is called with argument executor the following steps are taken:

1. Let promise be the this value.
2. If Type(promise) is not Object, then throw a TypeError exception.
3. If promise does not have a [[PromiseState]] internal slot, then throw a TypeError exception.
4. If promise's [[PromiseState]] internal slot is not undefined, then throw a TypeError exception.
5. If IsCallable(executor) is false, then throw a TypeError exception.
6. Return InitialisePromise(promise, executor).

NOTE

The executor argument must be a function object. It is called for initiating and reporting completion of the possibly deferred action represented by this Promise object. The executor is called with two arguments: resolve and reject. These are functions that may be used by the executor function to report eventual completion or failure of the deferred computation. Returning from the executor function does not mean that the deferred action has been completed but only that the request to eventually perform the deferred action has been accepted.

The resolve function that is passed to an executor function accepts a single argument. The executor code may eventually call the resolve function to indicate that it wishes to resolve the associated Promise object. The argument passed to the resolve function represents the eventual value of the deferred action and can be either the actual fulfillment value or another Promise object which will provide the value if it is fullfilled.

The reject function that is passed to an executor function accepts a single argument. The executor code may eventually call the reject function to indicate that the associated Promise is rejected and will never be fulfilled. The argument passed to the reject function is used as the rejection value of the promise. Typically it will be an Error object.

The resolve and reject functions passed to an executor function by the Promise constructor have the capability to actually resolve and reject the associated promise. Subclasses may have different constructor behaviour that passes in customized values for resolve and reject.

InitialisePromise ( promise, executor )

The abstract operation InitialisePromise initialises a newly allocated promise object using an executor function.

1. Assert: promise has a [[PromiseState]] internal slot and its value is undefined.
2. Assert: IsCallable(executor) is true.
3. Set promise's [[PromiseState]] internal slot to "pending".
4. Set promise's [[PromiseFulfillReactions]] internal slot to a new empty List.
5. Set promise's [[PromiseRejectReactions]] internal slot to a new empty List.
6. Let resolvingFunctions be CreateResolvingFunctions(promise).
7. Let completion be the result of calling the [[Call]] internal method of executor with undefined as thisArgument and (resolvingFunctions.[[Resolve]], resolvingFunctions.[[Reject]]) as argumentsList.
8. If completion is an abrupt completion, then
   1. Let status be the result of calling the [[Call]] internal method of resolvingFunctions.[[Reject]] with undefined as thisArgument and (completion.[[value]]) as argumentsList.
   2. ReturnIfAbrupt(status).
9. Return promise.

new Promise ( ... argumentsList )

When Promise is called as part of a new expression it is a constructor: it initialises a newly created object.

Promise called as part of a new expression with argument list argumentsList performs the following steps:

1. Let F be the Promise function object on which the new operator was applied.
2. Let argumentsList be the argumentsList argument of the [[Construct]] internal method that was invoked by the new operator.
3. Return Construct(F, argumentsList).

If Promise is implemented as an ECMAScript function object, its [[Construct]] internal method will perform the above steps.

Properties of the Promise Constructor

The value of the [[Prototype]] internal slot of the Promise constructor is the Function prototype object.

Besides the length property (whose value is 1), the Promise constructor has the following properties:

Promise.all ( iterable )

The all function returns a new promise which is fulfilled with an array of fulfillment values for the passed promises, or rejects with the reason of the first passed promise that rejects. It resolves all elements of the passed iterable to promises as it runs this algorithm.

1. Let C be the this value.
2. Let promiseCapability be NewPromiseCapability(C).
3. ReturnIfAbrupt(promiseCapability).
4. Let iterator be GetIterator(iterable).
5. IfAbruptRejectPromise(iterator, promiseCapability).
6. Let values be ArrayCreate(0).
7. Let remainingElementsCount be a new Record { [[value]]: 1 }.
8. Let index be 0.
9. Repeat
   1. Let next be IteratorStep(iterator).
   2. IfAbruptRejectPromise(next, promiseCapability).
   3. If next is false,
      1. Set remainingElementsCount.[[value]] to remainingElementsCount.[[value]] - 1.
      2. If remainingElementsCount.[[value]] is 0,
         1. Let resolveResult be the result of calling the [[Call]] internal method of promiseCapability.[[Resolve]] with undefined as thisArgument and (values) as argumentsList.
         2. ReturnIfAbrupt(resolveResult).
      3. Return promiseCapability.[[Promise]].
   4. Let nextValue be IteratorValue(next).
   5. IfAbruptRejectPromise(nextValue, promiseCapability).
   6. Let nextPromise be Invoke(C, "resolve", (nextValue)).
   7. IfAbruptRejectPromise(nextPromise, promiseCapability).
   8. Let resolveElement be a new built-in function object as defined in Promise.all Resolve Element Functions.
   9. Set the [[AlreadyCalled]] internal slot of resolveElement to false.
   10. Set the [[Index]] internal slot of resolveElement to index.
   11. Set the [[Values]] internal slot of resolveElement to values.
   12. Set the [[Capabilities]] internal slot of resolveElement to promiseCapabilities.
   13. Set the [[RemainingElements]] internal slot of resolveElement to remainingElementsCount.
   14. Set remainingElementsCount.[[value]] to remainingElementsCount.[[value]] + 1.
   15. Let result be Invoke(nextPromise, "then", (resolveElement, promiseCapability.[[Reject]])).
   16. IfAbruptRejectPromise(result, promiseCapability).
   17. Set index to index + 1.

Note: The all function requires its this value to be a constructor function that supports the parameter conventions of the Promise constructor.

Promise.all Resolve Element Functions

A Promise.all resolve element function is an anonymous built-in function that is used to resolve a specific Promise.all element. Each Promise.all resolve element function has [[Index]], [[Values]], [[Capabilities]], [[RemainingElements]], and [[AlreadyCalled]] internal slots.

When a Promise.all resolve element function F is called with argument x, the following steps are taken:

1. If the value of F's [[AlreadyCalled]] internal slot is true, then return undefined.
2. Set the [[AlreadyCalled]] internal slot of F to true.
3. Let index be the value of F's [[Index]] internal slot.
4. Let values be the value of F's [[Values]] internal slot.
5. Let promiseCapability be the value of F's [[Capabilities]] internal slot.
6. Let remainingElementsCount be the value of F's [[RemainingElements]] internal slot.
7. Let result be CreateDataProperty(values, ToString(index), x).
8. IfAbruptRejectPromise(result, promiseCapability).
9. Set remainingElementsCount.[[value]] to remainingElementsCount.[[value]] - 1.
10. If remainingElementsCount.[[value]] is 0,
    1. Return the result of calling the [[Call]] internal method of promiseCapability.[[Resolve]] with undefined as thisArgument and (values) as argumentsList.
11. Return undefined.

Promise.prototype

The initial value of Promise.prototype is the Promise prototype object.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

Promise.race ( iterable )

The race function returns a new promise which is settled in the same way as the first passed promise to settle. It resolves all elements of the passed iterable to promises as it runs this algorithm.

1. Let C be the this value.
2. Let promiseCapability be NewPromiseCapability(C).
3. ReturnIfAbrupt(promiseCapability).
4. Let iterator be GetIterator(iterable).
5. IfAbruptRejectPromise(iterator, promiseCapability).
6. Repeat
   1. Let next be IteratorStep(iterator).
   2. IfAbruptRejectPromise(next, promiseCapability).
   3. If next is false, return promiseCapability.[[Promise]].
   4. Let nextValue be IteratorValue(next).
   5. IfAbruptRejectPromise(nextValue, promiseCapability).
   6. Let nextPromise be Invoke(C, "resolve", (nextValue)).
   7. IfAbruptRejectPromise(nextPromise, promiseCapability).
   8. Let result be Invoke(nextPromise, "then", (promiseCapability.[[Resolve]], promiseCapability.[[Reject]])).
   9. IfAbruptRejectPromise(result, promiseCapability).

Note: The race function requires its this value to be a constructor function that supports the parameter conventions of the Promise constructor. It also requires that its this value provides a resolve method.

Promise.reject ( r )

The reject function returns a new promise rejected with the passed argument.

1. Let C be the this value.
2. Let promiseCapability be NewPromiseCapability(C).
3. ReturnIfAbrupt(promiseCapability).
4. Let rejectResult be the result of calling the [[Call]] internal method of promiseCapability.[[Reject]] with undefined as thisArgument and (r) as argumentsList.
5. ReturnIfAbrupt(rejectResult).
6. Return promiseCapability.[[Promise]].

Note: The reject function requires its this value to be a constructor function that supports the parameter conventions of the Promise constructor.

Promise.resolve ( x )

The resolve function returns a new promise resolved with the passed argument, or returns the argument if it is already a promise branded with the correct type.

1. Let C be the this value.
2. If IsPromise(x) is true,
   1. Let constructor be the value of x's [[PromiseConstructor]] internal slot.
   2. If SameValue(constructor, C) is true, return x.
3. Let promiseCapability be NewPromiseCapability(C).
4. ReturnIfAbrupt(promiseCapability).
5. Let resolveResult be the result of calling the [[Call]] internal method of promiseCapability.[[Resolve]] with undefined as thisArgument and (x) as argumentsList.
6. ReturnIfAbrupt(resolveResult).
7. Return promiseCapability.[[Promise]].

Note: The resolve function requires its this value to be a constructor function that supports the parameter conventions of the Promise constructor.

Promise [ @@create ] ( )

The @@create method of a Promise function object F performs the following steps:

1. Let F be the this value.
2. Return AllocatePromise(F).

The value of the name property of this function is "[Symbol.create]".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

AllocatePromise ( constructor )

The abstract operation AllocatePromise allocates a new promise object using the constructor argument.

1. Let obj be OrdinaryCreateFromConstructor(constructor, "%PromisePrototype%", ([[PromiseState]], [[PromiseConstructor]], [[PromiseResult]], [[PromiseFulfillReactions]], [[PromiseRejectReactions]])).
2. Set obj's [[PromiseConstructor]] internal slot to constructor.
3. Return obj.

Properties of the Promise Prototype Object

The value of the [[Prototype]] internal slot of the Promise prototype object is the standard built-in Object prototype object. The Promise prototype object is an ordinary object. It does not have a [[PromiseState]] internal slot or any of the other internal slots of Promise instances.

Promise.prototype.catch ( onRejected )

When the catch method is called with argument onRejected the following steps are taken:

1. Let promise be the this value.
2. Return Invoke(promise, "then", (undefined, onRejected)).

Promise.prototype.constructor

The initial value of Promise.prototype.constructor is the standard built-in Promise constructor.

Promise.prototype.then ( onFulfilled , onRejected )

When the then method is called with arguments onFulfilled and onRejected the following steps are taken:

1. Let promise be the this value.
2. If IsPromise(promise) is false, throw a TypeError exception.
3. If IsCallable(onFulfilled) is false, then
   1. Let onFulfilled be "Identity".
4. If IsCallable(onRejected) is false, then
   1. Let onRejected be "Thrower".
5. Let C be Get(promise, "constructor").
6. ReturnIfAbrupt(C).
7. Let promiseCapability be NewPromiseCapability(C).
8. ReturnIfAbrupt(promiseCapability).
9. Let fulfillReaction be the PromiseReaction { [[Capabilities]]: promiseCapability, [[Handler]]: onFulfilled }.
10. Let rejectReaction be the PromiseReaction { [[Capabilities]]: promiseCapability, [[Handler]]: onRejected }.
11. If the value of promise's [[PromiseState]] internal slot is "pending",
    1. Append fulfillReaction as the last element of the List that is the value of promise's [[PromiseFulfillReactions]] internal slot.
    2. Append rejectReaction as the last element of the List that is the value of promise's [[PromiseRejectReactions]] internal slot.
12. Else if the value of promise's [[PromiseState]] internal slot is "fulfilled",
    1. Let value be the value of promise's [[PromiseResult]] internal slot.
    2. Call EnqueueTask("PromiseTasks", PromiseReactionTask, (fulfillReaction, value)).
13. Else if the value of promise's [[PromiseState]] internal slot is "rejected",
    1. Let reason be the value of promise's [[PromiseResult]] internal slot.
    2. Call EnqueueTask("PromiseTasks", (rejectReaction, reason)).
14. Return promiseCapability.[[Promise]].

Promise.prototype [ @@toStringTag ]

The initial value of the @@toStringTag property is the string value "Promise".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

Properties of Promise Instances

Promise instances are ordinary objects that inherit properties from the Promise prototype object (the intrinsic, %PromisePrototype%). Promise instances are initially created with the internal slots described in this table.

Deltas to Other Areas of the Spec

Well-Known Intrinsic Objects Table

Add the following rows:

To the extent possible under law, Domenic Denicola has waived all copyright and related or neighboring rights to promises-unwrapping.

This work is published from:
<span property="vcard:Country" datatype="dct:ISO3166" content="US" about="http://domenicdenicola.com">
  United States
</span>.