From CommonJS Spec Wiki
Jump to: navigation, search

STATUS: Proposal by KrisZyp


A promise represents the eventual value returned from the single completion of an operation. A promise may be in one of the three states, unfulfilled, fulfilled, and failed. The promise may only move from unfulfilled to fulfilled, or unfulfilled to failed. Once a promise is fulfilled or failed, the promise's value MUST not be changed, just as a values in JavaScript, primitives and object identities, can not change (although objects themselves may always be mutable even if their identity isn't). The immutable characteristic of promises are important for avoiding side-effects from listeners that can create unanticipated changes in behavior and allows promises to be passed to other functions without affecting the caller, in same way that primitives can be passed to functions without any concern that the caller's variable will be modified by the callee.

This API does not define how promises are created, but only defines the necessary interface that a promise must provide for promise consumers to interact with it. Implementors are free to define how promises are generated. Some promises may be provide their own functions to fulfill the promise, and other promises may be fulfilled by mechanisms that are not visible to the promise consumer. See the [Promise Manager] API for a proposal for useful convenience functions. Promises itself may include other additional convenience methods as well. For example, one could implement Dojo's Deferred functions on promises such as addCallback and addBoth.

A promise is defined as an object that has a function as the value for the property 'then':

then(fulfilledHandler, errorHandler, progressHandler)
Adds a fulfilledHandler, errorHandler, and progressHandler to be called for completion of a promise. The fulfilledHandler is called when the promise is fulfilled. The errorHandler is called when a promise fails. The progressHandler is called for progress events. All arguments are optional and non-function values are ignored. The progressHandler is not only an optional argument, but progress events are purely optional. Promise implementors are not required to ever call a progressHandler (the progressHandler may be ignored), this parameter exists so that implementors may call it if they have progress events to report.

This function should return a new promise that is fulfilled when the given fulfilledHandler or errorHandler callback is finished. This allows promise operations to be chained together. The value returned from the callback handler is the fulfillment value for the returned promise. If the callback throws an error, the returned promise will be moved to failed state.

An example of using a CommonJS compliant promise:

    then(printResult, onError);

An interactive-promise is an extended promise that supports the following additional functions:

Requests the given property from the target of this promise. Returns a promise to provide the value of the stated property from this promise's target.
call(functionName, arg1, arg2, ...)
Request to call the given method/function on the target of this promise. Returns a promise to provide the return value of the requested function call.

Open Issues

Should calls to the callback handlers be put on the event queue or executed immediately? - Currently unspecified, and I don't know for sure what is best.





  • Q-IO Interfaces for IO using Q promises in JavaScript on Node
  • Q-Connection A JavaScript library for communicating asynchronously with remote objects using promises.
  • Promised-IO Promised I/O for multiple platforms (developed as a dependency of Perstore)
  • WebDriverJs JavaScript bindings for WebDriver, uses promises.
  • mocha-as-promised Adds “thenable” promise support to the Mocha test runner.
  • dynamo-as-promised A promise-based client for Amazon's DynamoDB.
  • chai-as-promised Extends Chai with assertions about promises.
  • Joey An HTTP content negotiation client and server JavaScript library, inspired by Sinatra and JSGI, and using Q promises.
  • Mr A CommonJS module system for front-end web application development


Related Discussions