Promises/B

STATUS: PROPOSAL

Implementations

[[Implementations/Narwhal|]] (0.5), [[Implementations/node.js|]] (http://github.com/kriskowal/q)

Specification

1. How to send messages to a promise object is beyond the scope of this specification.
2. How to detect whether a value is a promise object is beyond the scope of this specification.
3. These behaviors are an exercise left to implementors.
4. Users of promises must not depend on any particular implementation's behavior.

(See Promises/D for a specification that illuminates all of the above details, or Promises/A for a syntactically convenient subset of this API)

The "promise" (provisionally "promise-b") module exports the following API:

when(value, callback, errback_opt)

1. Arranges for callback to be called:
   1. with the fully resolved value of the given value
   2. in a future turn of the event loop
   3. if and when the value is or becomes a fully resolved value accessible to the caller.
2. Arranges for errback to be called:
   1. with a value representing the reason why the value will never be fully resolved
   2. in a future turn of the event loop
   3. if the value is a promise and
   4. if that promise is resolved with a rejection ("reject").
3. Returns a promise that may be eventually resolved with the value returned by either the callback or the errback.
4. The value may be any value.
5. If the value is a promise, sends a "when" message to that promise with a callback and an errback that intercept the resolution of that promise and resolve the promise returned by "when":
   1. with the value received by the callback
   2. or with a rejection ("reject") with the reason given to the errback.
6. Callback must not be called before when returns.
7. Errback must not be called before when returns.
8. Callback must only be called once.
9. Errback must only be called once.
10. If callback is called, errback must never be called.
11. If errback is called, callback must never be called.
12. "when" does not guarantee that callback or errback will ever be called.

asap(value, callback, errback_opt)

1. Arranges for callback to be called with the fully resolved value of the given value when the value is or becomes a fully resolved value accessible to the caller.
2. The value may be any value.
3. If the value is a promise, "asap" sends a "when" message to that promise with a callback and an errback that intercept the resolution of that promise and resolve the promise returned by "asap":
   1. with the value given to the callback
   2. or with a rejection ("reject") with the reason given to the errback.
4. If the value is not a promise, "asap" must call the callback immediately.
   1. If the callback does not return a promise, "asap" returns the value returned by "callback".
   2. If the callback returns a promise, "asap" sends a a "when" message to that promise with a callback and errback that intercept the resolution of that promise and resolve the promise returned by "asap":
      1. with the value given to the callback
      2. or with a rejection ("reject") with the reason given to the errback.
5. "asap" does not guarantee that callback or errback will ever be called.
6. Callback must only be called once.
7. Errback must only be called once.
8. If callback is called, errback must never be called.
9. If errback is called, callback must never be called.
10. Callback and errback may never be called.

enqueue(task Function)

1. causes a function to be called as soon as possible in a future turn.

get(object, name)

1. Returns a promise for a property of the given object.

post(object, name, args)

1. Returns a promise for the return value of calling a member function of the given object with the given arguments.
2. args are not variadic.

put(object, name, value)

1. returns a promise to set the value of a named property of the object and to forward the value when that has been completed.

del(object, name)

1. Returns a promise to delete the named property of the object and to forward undefined when that has been completed.

makePromise(descriptor Object, fallback Function)

1. Returns a Promise object
2. Must be callable as a function
3. May be instantiable as a constructor
4. Accepts a descriptor Object that maps message names to handler functions, particularly:
   1. when(errback)
   2. get(name)
   3. put(name, value)
   4. post(name, args)
   5. del(name)
5. Each of the above handler functions must return a more resolved value or promise.
6. Accepts a fallback(message, ...args) function that receives all messages that are not handled by the promise descriptor and must return a more resolved value or promise.
7. Returns a promise.

defer()

1. Returns an Object with a "resolve(value)" property function, and a "promise" property.
2. The first time that "resolve(value)" is called, the state of the "promise" advances to "resolved" and all previous and future promises observing the "promise" are resolved.
   1. If the "value" is not a promise, the resolved value of the "promise" becomes a reference ("ref") to the given value.
3. All subsequent calls to resolve must be silently ignored.

reject(reason String)

1. Returns a rejected promise with the given reason.
2. A rejected promise handles the "when(errback)" message in one of two ways:
   1. If an errback is provided, the errback is called with the reason as its argument, and the "when" message handler must return the value returned by the errback.
   2. If no errback is provided, the "when" message handler must return a new rejection ("reject") with the same reason.
3. Rejects all other messages.

ref(value)

1. If value is a promise, returns that promise.
2. If the value is not a promise, returns a resolved promise that handles the following messages:
   1. when(errback) ignores the errback and forwards the resolved value.
   2. get(name) forwards the named property of the resolved value.
   3. put(name, value) sets the named property to the given value of the resolved value and forwards the value.
   4. del(name) deletes the named property of the resolved value and forwards undefined
   5. post(name, args) calls the named method of the value and forwards the returned value.
   6. all other messages forward a rejection ("reject") with the reason "Promise does not handle NAME" where NAME is the name of the message.

isPromise(value) Boolean

returns whether the given value is a promise.

method(name String)

1. returns a function like "get", "put", "del", and "post" except with the given name that must forward a message to a promise in a future turn.

Discussions

• CommonJS Promises and the Q API
• A more differenter approach to promises
• Duck-type Promises
• Issues with a current promises specification.
• Unify promises