Promises are an abstraction of the flow of program execution which can be summed up as follows:

Asker: Whenever you're done doing what you're doing, would you call me back?
Answerer: Sure thing, I promise

A JavaScript Promise can be:

fulfilled - the action relating to the promise succeeded
rejected - the action relating to the promise failed
pending - hasn't been fulfilled or rejected yet
settled - has fulfilled or rejected

Simple Promise

Click here to expand...

function simple_promise(random_message) {
  return new Promise(function(resolve, reject) {
	if (confirm("press a button! random message: " + random_message)) {
  		resolve("okay clicked");
	} else {
  		reject(Error("cancel clicked"));
	}
  });
}

using it

simple_promise('hello marcus').then(function(response) {
    console.log("PROMISE SUCCESS!", response);
}, function(error) {
    console.error("PROMISE FAILED!", error);
});

Complex Promise - Promisfying an XMLHttpRequest

Click here to expand...

function get(url) {
  // Return a new promise.
  return new Promise(function(resolve, reject) {
    // Do the usual XHR stuff
    var req = new XMLHttpRequest();
    req.open('GET', url);

    req.onload = function() {
      // This is called even on 404 etc
      // so check the status
      if (req.status == 200) {
        // Resolve the promise with the response text
        resolve(req.response);
      }
      else {
        // Otherwise reject with the status text
        // which will hopefully be a meaningful error
        reject(Error(req.statusText));
      }
    };

    // Handle network errors
    req.onerror = function() {
      reject(Error("Network Error"));
    };

    // Make the request
    req.send();
  });
}

using it

get('/web/fundamentals/primers/promises').then(function(response) {
    console.log("SUCCESS!", response);
}, function(error) {
    console.error("FAILED!", error);
});

Sugar Coating Error Handling

Click here to expand...

instead of

simple_promise('hello marcus').then(function(response) {
    console.log("PROMISE SUCCESS!", response);
}, function(error) {
    console.error("PROMISE FAILED!", error);
});

you can do this

simple_promise('hello marcus').then(function(response) {
    console.log("PROMISE SUCCESS!", response);
}).catch(function(error) {
    console.error("PROMISE FAILED!", error);
});

Chaining then()'s

transforming values

var promise = new Promise(function(resolve, reject) {
  resolve(1);
});

promise.then(function(val) {
  console.log(val); // 1
  return val + 2;
}).then(function(val) {
  console.log(val); // 3
})

chaining multiple async things back-to-back

asyncThing1().then(function() {
  return asyncThing2();
}).then(function() {
  return asyncThing3();
}).catch(function(err) {
  return asyncRecovery1();
}).then(function() {
  return asyncThing4();
}, function(err) {
  return asyncRecovery2();
}).catch(function(err) {
  console.log("Don't worry about it");
}).then(function() {
  console.log("All done!");
})

flow chart

JavaScript - Promise

Simple Promise

Complex Promise - Promisfying an XMLHttpRequest

Sugar Coating Error Handling

Chaining then()'s