The Promise
constructor is primarily used to wrap functions that do not already support promises.
The source for this interactive demo is stored in a GitHub repository. If you'd like to contribute to the interactive demo project, please clone https://github.com/mdn/interactive-examples and send us a pull request.
Syntax
new Promise(executor)
-
Parameters
executor
- A
function
to be executed by the constructor, during the process of constructing thepromiseObj
. Theexecutor
is custom code that ties an outcome to a promise. You, the programmer, write theexecutor
. The signature of this function is expected to be: -
function(resolutionFunc, rejectionFunc){ // typically, some asynchronous operation. }
- At the time when the constructor generates the new
promiseObj
, it also generates a corresponding pair of functions forresolutionFunc
andrejectionFunc;
these are "tethered" to thepromiseObj
. Therefore, the code within theexecutor
has the opportunity to perform some operation and then reflect the operation's outcome(If the value is not another Promise object) as either "fulfilled" or "rejected" by terminating with an invocation of either theresolutionFunc
or therejectionFunc
, respectively. - The
executor
has no meaningful return value. It communicates via the side-effect caused byresolutionFunc
orrejectionFunc
. The side-effect is that thepromiseObj
becomes "resolved." - Typically, it works like this: The operation within
executor
is asynchronous and provides a callback. The callback is defined within theexecutor
code. The callback terminates by invokingresolutionFunc
. The invocation ofresolutionFunc
includes avalue
parameter. Thevalue
is passed back to the tetheredpromiseObj
. ThepromiseObj
(asynchronously) invokes any.then()
associated with it. Thevalue
received bypromiseObj.then()
is passed to the invocation ofhandleFulfilled
as an input parameter (See "Chained Promises" section). - The
executor
might also include atry{} catch()
block that invokesrejectionFunc
upon error. - The signatures of these two functions are simple, they accept a single parameter of any type. Of course, the actual names of these functions can be whatever is desired, i.e. they are named as the parameters of
executor
. Each function is used by simply calling it when appropriate.
-
resolutionFunc(value) // call on fulfilled rejectionFunc(reason) // call on rejected
The returned
value
can be another promise object, in which case the promise gets dynamically inserted into the chain. -
Return value
promiseObj
- When called via
new
, thePromise
constructor returns a promise object. The promise object will become "resolved" when either of the functionsresolutionFunc
orrejectionFunc
are invoked. Note that if you callresolutionFunc
orrejectionFunc
and pass another Promise object as an argument, you can say that it is "resolved", but still cannot be said to be "settled".
Examples
Creating a new Promise
A Promise
object is created using the new
keyword and its constructor. This constructor takes a function, called the "executor function", as its parameter. This function should take two functions as parameters. The first of these functions (resolve
) is called when the asynchronous task completes successfully and returns the results of the task as a value. The second (reject
) is called when the task fails, and returns the reason for failure, which is typically an error object.
const myFirstPromise = new Promise((resolve, reject) => { // do something asynchronous which eventually calls either: // // resolve(someValue) // fulfilled // or // reject("failure reason") // rejected });
Making functions return a Promise
To provide a function with promise functionality, have it return a promise:
function myAsyncFunction(url) { return new Promise((resolve, reject) => { const xhr = new XMLHttpRequest() xhr.open("GET", url) xhr.onload = () => resolve(xhr.responseText) xhr.onerror = () => reject(xhr.statusText) xhr.send() }); }
Specifications
Specification |
---|
ECMAScript (ECMA-262) The definition of 'Promise constructor' in that specification. |
Browser compatibility
Desktop | Mobile | Server | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Promise() constructor | Chrome Full support 32 | Edge Full support 12 | Firefox
Full support
29
| IE No support No | Opera Full support 19 | Safari
Full support
8
| WebView Android Full support 4.4.3 | Chrome Android Full support 32 | Firefox Android
Full support
29
| Opera Android Full support 19 | Safari iOS
Full support
8
| Samsung Internet Android Full support 2.0 | nodejs
Full support
0.12
|
Legend
- Full support
- Full support
- No support
- No support
- See implementation notes.
- See implementation notes.