The Promise
constructor is primarily used to wrap functions that do not already support promises.
Promise() constructor
Try it
Syntax
new Promise(executor)
Parameters
-
executor
-
A
function
to be executed by the constructor, during the process of constructing the newPromise
object. Theexecutor
is custom code that ties an outcome to a promise. You, the programmer, write theexecutor
. Its signature is expected to be:function(resolutionFunc, rejectionFunc){ // typically, some asynchronous operation. }
resolutionFunc
andrejectionFunc
are also functions, and you can give them whatever actual names you want. Their signatures are simple: they accept a single parameter of any type.resolutionFunc(value) // call on resolved rejectionFunc(reason) // call on rejected
The
resolutionFunc
value
parameter can be another promise object, in which case the promise gets dynamically inserted into the promise chain.About the
executor
, it's important to understand the following:- The
executor
return value is ignored. - If an error is thrown in the
executor
, the promise is rejected.
So the mechanism by which the code within the
executor
has effect is as follows:- At the time when the constructor generates the new
Promise
object, it also generates a corresponding pair of functions forresolutionFunc
andrejectionFunc
; these are "tethered" to thePromise
object. - The code within the
executor
has the opportunity to perform some operation and then reflect the operation's outcome (if the value is not another Promise object) as either "resolved" or "rejected", by terminating with an invocation of either theresolutionFunc
or therejectionFunc
, respectively. - In other words, the code within the
executor
communicates via the side effect caused byresolutionFunc
orrejectionFunc
. The side effect is that thePromise
object either becomes "resolved", or "rejected".
And so, given all the above, here's a summary of the typical flow:
- The operation within
executor
is asynchronous and provides a callback. - The callback is defined within the
executor
code. - The callback terminates by invoking
resolutionFunc
. - The invocation of
resolutionFunc
includes avalue
parameter. - The
value
is passed back to the tetheredPromise
object. - The
Promise
object (asynchronously) invokes any associated.then(handleResolved)
. - The
value
received by.then(handleResolved)
is passed to the invocation ofhandleResolved
as an input parameter (see Chained Promises).
- The
Return value
When called via new
, the Promise
constructor returns a promise object. The promise object will become "resolved" when either of the functions resolutionFunc
or rejectionFunc
are invoked. Note that if you call resolutionFunc
or rejectionFunc
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
Browser compatibility
Desktop | Mobile | Server | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | WebView Android | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | Deno | Node.js | |
Promise |
32
|
12
|
29
Constructor requires a new operator since version 37.
|
No
|
19
|
8
Constructor requires a new operator since version 10.
|
4.4.3
|
32
|
29
Constructor requires a new operator since version 37.
|
19
|
8
Constructor requires a new operator since version 10.
|
2.0
|
1.0
|
0.12.0
Constructor requires a new operator since version 4.
|
See also
© 2005–2022 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/Promise