JavaScript tutorial

Promise

The Promise class allows you to execute code asynchronously.

Also you can wrap functions that do not already support promises.

// Will out "foo" in console after 3 seconds
new Promise((resolve, reject) => {
  setTimeout(() => resolve('foo'), 3000);
})
  .then(val => console.log(val));

A Promise is in one of these states:

  • pending - initial state, neither fulfilled nor rejected
  • fulfilled - operation was completed successfully
  • rejected - operation failed

Executor is a function that is used to create a Promise object:

function(resolutionFunc, rejectionFunc){
    // ... asynchronous code.
}

Within the async code, you must call resolutionFunc, otherwise the async code will never complete. Value passed to the resolutionFunc will be passed to the fulfilled callback.

The rejectionFunc usually invoked from try/catch statement. You can ignore this if you want to pass the raised exception to the error callback:

new Promise((resolve, reject) =>{
    throw new Error('Fail!');
})
  .catch(e => console.error(e)); // Fail!
constructor description
Promise(executor) Create promise from given executor.
method description
then( cbOk [,cbErr]) Appends fulfillment and rejection handlers to the promise, and returns a new promise resolving to the return value of the called handler, or to its original settled value if the promise was not handled.
catch(cbErr) Appends a rejection handler callback to the promise, and returns a new promise resolving to the return value of the callback if it is called, or to its original fulfillment value if the promise is instead fulfilled.
finally(cb) Appends a handler to the promise, and returns a new promise that is resolved when the original promise is resolved. The handler is called when the promise is settled, whether fulfilled or rejected.
static
method description
resolve(val) Returns a promisethat is resolved with the given value. If the value is a thenable, the returned promise will "follow" that thenable, adopting its eventual state; otherwise, the returned promise will be fulfilled with the value.
reject(reason) Returns promise, that is rejected with the given reason.
allSettled(iterable) Returns a promise that resolves after all of the given promises have either resolved or rejected.
any(iterable) Returns a promise that is awaiting fulfillment of one of the promises in an iterable and resolves with the value from that promise.
race(iterable) Returns a promise that is awaiting fulfillment or rejecting of one of the promises in an iterable and resolves with the value from that promise.

chaining

The then(), catch() and finally() methods return new Promise objects. You can use it to build chain of promises.

For example, the following code will print the numbers 2,3,4 to the console. The promise p will be fulfilled with a value 5. You won't see 5 in the console because nobody is using the result of last promise p. 

var p = new Promise((resolve)=>{
    resolve(2)
}).then(val=>{
    console.log(val);
    return 3;
}).then(val=>{
    console.log(val);
    return 4;
}).then(val=>{
    console.log(val);
    return 5;
}).catch((err)=>console.log(err));

console.log(p);