Promises/A+ Extension: Synchronous Inspection

This proposal extends the Promises/A+ specification to cover synchronous inspection of a promise's fulfillment value or rejection reason.

It is not expected that all Promises/A+ implementations will include this extension. If the features of this extension are desired, you should test for them:

if (typeof promise.inspect === "function") {
  // Use the `inspect` method, assuming it conforms to the contract below.
}

Motivation

TODO

Requirements: the inspect method

A promise implementing this specification must have an inspect method, which returns an object.

1. When the promise is pending, the object returned by inspect
   1. must not have a property named fulfillmentValue.
   2. must not have a property named rejectionReason.
2. When the promise is fulfilled, the object returned by inspect
   1. must have a property named fulfillmentValue, whose value is equal to the promise's fulfillment value.
   2. must not have a property named rejectionReason.
3. When the promise is rejected, the object returned by inspect
   1. must not have a property named fulfillmentValue.
   2. must have a property named rejectionReason, whose value is equal to the promise's rejection reason.

Note

Since fulfillment values and rejection reasons can be any valid JavaScript value, including undefined, this specification hinges on the difference between a property being present and it being absent. That is, the proper way to synchronously test for a promise being fulfilled is not if (promise.inspect().fulfillmentValue) or even if (promise.inspect().fulfillmentValue !== undefined), but instead if ("fulfillmentValue" in promise.inspect()).

I was about to commit this for discussion, before I realized a potentially fatal flaw that made me contemplate Draft B (#2).

Promises/A+ Extension: Synchronous Inspection

This proposal extends the Promises/A+ specification to cover synchronous inspection of a promise's fulfillment value or rejection reason.

It is not expected that all Promises/A+ implementors will implement this extension. If the features of this extension are desired, you should test for them as in the "Branding" section below.

Motivation

TODO

Requirements

Branding

An implementation of the synchronous inspection extension must signal that synchronous inspection is available by adding a truthy synchronousInspection property to every then method:

if (promise.then.synchronousInspection) {
  // Proceed to use the properties described below.
}

Synchronous Inspection Properties

1. When pending, a promise
   1. must not have a property named fulfillmentValue.
   2. must not have a property named rejectionReason.
2. When fulfilled, a promise
   1. must have a property named fulfillmentValue, whose value is equal to the promise's fulfillment value.
   2. must not have a property named rejectionReason.
3. When rejected, a promise
   1. must not have a property named fulfillmentValue.
   2. must have a property named rejectionReason, whose value is equal to the promise's rejection reason.
4. If a promise consumer sets a property named fulfillmentValue or rejectionReason, this must not have any impact on the promise's state.

Suggestions

If feasible, an implementation is encouraged to make fulfillmentValue and rejectionReason properties non-writable, to discourage attempts to set them.

Note

Since fulfillment values and rejection reasons can be any valid JavaScript value, including undefined, this specification hinges on the difference between a property being present and it being absent. That is, the proper way to synchronously test for a promise being fulfilled is not if (promise.fulfillmentValue) or even if (promise.fulfillmentValue !== undefined), but instead if ("fulfillmentValue" in promise).

I've left the motivation sections as TODOs.

I think the templating use case, as explained by @ForbesLindesay here, is a good one.

I also think that assimilation could benefit. Currently, you can only assimilate by waiting a turn. Thus, there are usually at least two turns in consuming an assimilated promise: foreignPromise.then(deferred.resolve, deferred.reject) and nativePromise.then(...). With synchronous inspection available, the first step could be made synchronous while not losing the guaranteed asynchronicity of the second.

Promieses/A+ Extension: Synchronous Inspection

This proposal extends the Promises/A+ specification to cover synchronous inspection of a promise's fulfillment value or rejection reason.

It is not expected that all Promises/A+ implementations will include this extension. If the features of this extension are desired, you should test for them:

if (typeof promise.asap === 'function') {
  // Use the `asap` method, assuming it conforms to the contract below.
}

Motivation

TODO

Requirements: the asap method

A promise implementing this specification must have an asap method.

A promises asap method accepts two arguments

promise.asap(onFulfilled, onRejected)

promise.asap must behave in the same way as then as described in http://promises-aplus.github.com/promises-spec/#the__method But for the purposes of asap 3.2.4 and Notes 4.1 can be ignored as asap is permitted to call onFulfilled and onRejected synchronously.

Note

This deliberately makes the API for synchronous inspection similar to that of asynchronous inspection to discourage anti-patterns like polling for completion. It is also optimized for the common use case of a promise that may or may not be completed already.

Promieses/A+ Extension: Synchronous Inspection

This proposal extends the Promises/A+ specification to cover synchronous inspection of a promise's fulfillment value or rejection reason.

It is not expected that all Promises/A+ implementations will include this extension. If the features of this extension are desired, you should test for them:

if (typeof promise.asap === 'function') {
  // Use the `asap` method, assuming it conforms to the contract below.
}

Motivation

TODO

Requirements: the asap method

A promise's asap method accepts two arguments:

promise.asap(onFulfilled, onRejected)

1. Both onFulfilled and onRejected are optional arguments:
   1. If onFulfilled is not a function, it must be ignored.
   2. If onRejected is not a function, it must be ignored.
2. If onFulfilled is a function:
   1. it must be called after promise is fulfilled, with promise's fulfillment value as its first argument.
   2. it must not be called more than once.
   3. it must not be called if onRejected has been called.
3. If onRejected is a function,
   1. it must be called after promise is rejected, with promise's rejection reason as its first argument.
   2. it must not be called more than once.
   3. it must not be called if onFulfilled has been called.
4. asap may be called multiple times on the same promise.
   1. If/when promise is fulfilled, respective onFulfilled callbacks must execute in the order of their originating calls to asap.
   2. If/when promise is rejected, respective onRejected callbacks must execute in the order of their originating calls to asap.
5. asap returns undefined and allows errors to be thrown synchronously.

Note

This deliberately makes the API for synchronous inspection similar to that of asynchronous inspection to discourage anti-patterns like polling for completion. It is also optimized for the common use case of a promise that may or may not be completed already.

Promises/A+ Extension: Synchronous Inspection

This proposal extends the Promises/A+ specification to cover synchronous inspection of a promise's fulfillment value or rejection reason.

It is not expected that all Promises/A+ implementations will include this extension. If the features of this extension are desired, you should test for them:

if (typeof promise.inspectState === "function") {
  // Use the `inspectState` method, assuming it conforms to the contract below.
}

Motivation

TODO

Requirements: the inspectState method

A promise implementing this specification must have an inspectState method, which returns an object.

1. When the promise is pending, the object returned by inspectState
   1. must have a property named isFulfilled with a value of false
   2. must have a property named isRejected with a value of false
   3. must not have a property named fulfillmentValue
   4. must not have a property named rejectionReason
2. When the promise is fulfilled, the object returned by inspectState
   1. must have a property named fulfillmentValue, whose value is equal to the promise's fulfillment value.
   2. must have a property named isFulfilled with a value of true
   3. must have a property named isRejected with a value of false
   4. must not have a property named rejectionReason
3. When the promise is rejected, the object returned by inspectState
   1. must have a property named rejectionReason, whose value is equal to the promise's rejection reason.
   2. must have a property named isFulfilled with a value of false
   3. must have a property named isRejected with a value of true
   4. must not have a property named fulfillmentValue
4. Adding to or modifying properties of the object returned by inspectState must not impact the state, fulfillment value, or rejection reason of the promise in any way. (note 2)

Notes

1. Since fulfillment values and rejection reasons can be any valid JavaScript value, including undefined, you must check isFulfilled and isRejected. That is, the proper way to synchronously test for a promise being fulfilled is not if (promise.inspectState().fulfillmentValue) or even if (promise.inspectState().fulfillmentValue !== undefined), but instead if (promise.inspectState().isFulfilled).
2. Implementations may, if they choose, freeze the returned object in order to make this more obvious.