The Promise.jsm JavaScript code module implements the Promises/A+ proposal as known in April 2013.
This module was used before DOM Promises were made globally available in Gecko 29. Its usage is not suggested for new code.
If you just need a Promise, consider using a DOM Promise instead.
If you need a Deferred, because you want to create a Promise and manually resolve or reject it, consider using PromiseUtils.jsm instead.
To use it, you first need to import the code module into your JavaScript scope:
Components.utils.import("resource://gre/modules/Promise.jsm");
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:
Components.utils.import("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.
Introduction
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
undefined. - 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 Error object, 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.
Method overview
Deferred defer(); Obsolete since Gecko 30 |
Promise resolve([optional] aValue); |
Promise reject([optional] aReason); |
Methods
defer()
Creates a new pending promise and provides methods to resolve or reject it.
Deferred defer(); Obsolete since Gecko 30
Parameters
None.
Return value
A new object, containing the new promise in the promise property, and the methods to change its state in the resolve and reject properties. See the Deferred documentation for details.
resolve()
Creates a new promise fulfilled with the specified value, or propagates the state of an existing promise.
Promise resolve( aValue );
Parameters
aValueOptional- 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.
Return value
A promise that can be pending, fulfilled, or rejected.
reject()
Creates a new promise rejected with the specified reason.
Promise reject( aReason );
Parameters
aReasonOptional-
The rejection reason for the returned promise. Although the reason can be
undefined, it is generally anErrorobject, 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.
Return value
A rejected promise.
Examples
See the examples page.