promises-unwrapping

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.

PromiseCapability Record Fields

    

        Field Name
        Value
        Meaning
    



    

        [[Promise]]
        An object
        An object that is usable as a promise.
    

    

        [[Resolve]]
        A function object
        The function that is used to resolve the given promise object.
    

    

        [[Reject]]
        A function object
        The function that is used to reject the given promise object.

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.

PromiseReaction Record Fields

    

        Field Name
        Value
        Meaning
    



    

        [[Capabilities]]
        A PromiseCapability record
        The capabilities of the promise for which this record provides a reaction handler.
    

    

        [[Handler]]
        A function object, or a String
        The function that should be applied to the incoming value, and whose return value will govern what happens to the derived promise. If [[Handled]] is "Identity" it is equivalent to a function that simply returns its first argument. If [[Handler]] is "Thrower" it is equivalent to a function that throws its first argument as an exception.

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, (_reactio