Note: A preliminary promise module is also available starting from Gecko 17, though it didn't conform to the Promises/A+ proposal until Gecko 25:
resource://gre/modules/commonjs/promise/core.js"); // Gecko 17 to 20 Components.utils.import(" resource://gre/modules/commonjs/sdk/core/promise.js"); // Gecko 21 to 24
This implementation also includes helper functions that are specific to the Add-on SDK. While you may still import this module from the above paths, the recommended way for loading it is through the Add-on SDK loader.
For an introduction to promises, you may start from the Add-on SDK documentation, keeping in mind that only the core subset is implemented in this module.
A promise is an object representing a value that may not be available yet. Internally, a promise can be in one of three states:
- Pending, when the final value is not available yet. This is the only state that may transition to one of the other two states.
- Fulfilled, when and if the final value becomes available. A fulfillment value becomes permanently associated with the promise. This may be any value, including
- Rejected, if an error prevented the final value from being determined. A rejection reason becomes permanently associated with the promise. This may be any value, including
undefined, though it is generally an
Errorobject, like in exception handling.
A reference to an existing promise may be received by different means, for example as the return value of a call into an asynchronous API. In this case, the state of the promise can be observed but not directly controlled.
To observe the state of a promise, its
then method must be used. This method registers callback functions that are called as soon as the promise is either fulfilled or rejected. The method returns a new promise, that in turn is fulfilled or rejected depending on the state of the original promise and on the behavior of the callbacks. For example, unhandled exceptions in the callbacks cause the new promise to be rejected, even if the original promise is fulfilled. See the documentation of the
then method for details.
Promises may also be created using the
new Promise() constructor.
Creates a new pending promise and provides methods to resolve or reject it.
Deferred defer(); Obsolete since Gecko 30
A new object, containing the new promise in the
promise property, and the methods to change its state in the
reject properties. See the
Deferred documentation for details.
Creates a new promise fulfilled with the specified value, or propagates the state of an existing promise.
Promise resolve( aValue );
- If this value is not a promise, including
undefined, it becomes the fulfillment value of the returned promise. If this value is a promise, then the returned promise will be resolved with the value, i.e. it will eventually assume the same state as the provided promise.
A promise that can be pending, fulfilled, or rejected.
Creates a new promise rejected with the specified reason.
Promise reject( aReason );
The rejection reason for the returned promise. Although the reason can be
undefined, it is generally an
Errorobject, like in exception handling.Note: This argument should not be a promise. Specifying a rejected promise would make the rejection reason equal to the rejected promise itself, and not its rejection reason.
A rejected promise.
See the examples page.