Promises

MDN docs

quoting from there:

A Promise is in one of these states:

• pending: initial state, not fulfilled or rejected.

• fulfilled: meaning that the operation completed successfully.

• rejected: meaning that the operation failed.

A promise that is not pending is “settled”.

You can create a Promise with new, passing it an executor function:

let p = new Promise((resolve, reject) => {
     if (things go well) {
       resolve(resulting_value)
     } else {
        reject(error)
     }
})

At any time after the promise is created, you can call then on it and pass in a success handler, a failure handler, or both:

p.then(on_success) p.then(undefined, on_failure) p.then(on_success, on_failure)

If the promise is still pending, the appropriate handler will be called once it is settled. If it’s settled already, the handler will be calleed immediately (or ASAP, anyway).

The on_success handler is called with the resolved value from the promise, while the on_failure handler is called with the error value from the promise.

then() returns a new promise, so you can chain calls:

p.then(on_success).then(another_on_success).then(a_third_on_success)

If the on_success handler returns a new promise, that promise will be the return value from then() (or an equivalent promise, anyway).

The handlers will be called in order. If one fails, then the promise returned by that then() call will be rejected. “Fail” can mean raises an exception.

Many async functions nowadays return promises.

Pausing

Here’s a way of doing something after a delay:

let p = new Promise((resolve) => {
    setTimeout(resolve, 100)
}).then(()=>{
    do stuff
})

Some notes I made a while ago

Here are some examples:

// Return a new promise.
return new Promise(function(resolve, reject) {
   // do stuff.  if it works:
   resolve(result);
   // but if it fails:
   reject(Error(error text));
});

// USE a promise
promise.then(function(result) {
   // use result here
}, function(error) {
   // do something with error here
});

// CHAINING
// Note that 'then' returns a new promise

promise.then(function(val1) {
   return val1 + 2;
}).then(function(val2) {
   val2 is here val1 + 2!!!
});

// MORE CHAINING
promise.then(function(result){
  // do something, then return a new promise
  return promise2;
}).then(function(result2) {
  // this isn't invoked until promise2 resolves, and it gets promise2's result.
  ...
}