Description of the native JavaScript promises API with examples

Native JavaScript promises API

// Current browser support for native promises: http://kangax.github.io/compat-table/es6/#Promise
// Article: http://www.html5rocks.com/en/tutorials/es6/promises/
// Polyfills:
//  https://github.com/getify/native-promise-only
//  https://github.com/jakearchibald/es6-promise
 
/*------------------------------ GET PROMISE ------------------------------*/
// N.B.: Promises pass only first argument to resolve/reject callbacks, others are ignored
function doSomething(){
    return new Promise(function(resolve, reject) {
        setTimeout(function(){
            if(Math.random()>0.5){// toBeOrNotToBe :)
                resolve("promise resolved");
            }else{
                reject('promise rejected');
            }
        });
    });
}
 
//---------- Add "done" and "fail" actions ----------
doSomething()
.then(function(res){
    console.log('done', res);
},function(res){
    console.log('fail', res);
});
 
//---------- Add only "fail" action ----------
doSomething()
.then(undefined, function(res){
    console.log('fail', res);
});
 
//---------- Add "always" ----------
// there isn't "finally" callback https://github.com/domenic/promises-unwrapping/issues/18
doSomething()
.then(function(res){
    console.log('always', res);
},function(res){
    console.log('always', res);
});
 
/*------------------------------ RESOLVE PROMISE OUTSIDE ------------------------------*/
// but *...it's useful to do all your promise-related work inside the promise constructor callback*
function doSomething() {
    var wrappedPromise = {},
        promise = new Promise(function (resolve, reject) {
            wrappedPromise.resolve = resolve;
            wrappedPromise.reject = reject;
        });
    wrappedPromise.then = promise.then.bind(promise);
    wrappedPromise.catch = promise.catch.bind(promise);
    wrappedPromise.promise = promise;// e.g. if you want to provide somewhere only promise, without resolve/reject methods

    return wrappedPromise;
}

var wrappedPromise = doSomething();
wrappedPromise
    .then(function (res) {
        console.log('done', res);
    }, function (res) {
        console.log('fail', res);
    });

wrappedPromise.resolve('trigerred resolve');
 
/*------------------------------ CATCH ------------------------------*/
// N.B.: if an error is thrown in the constructor callback-> it triggers "reject"
doSomething()
    .then(f1)
    .then(f2)
    .catch(r1)
    .then(f3)
    .catch(r2);
    
// is analogous to:
try {
  try {
    doSomething();
    f1();
    f2();
  } catch (e) {
    r1(e);
  }
  
  f3();
} catch (e) {
  r2(e);
}

/*------------------------------ JQUERY DEFERRED TO NATIVE PROMISE ------------------------------*/
var jQueryPromise = $.ajax('/data.json');// or $.Deferred();

var nativePromise = Promise.resolve(jQueryPromise);
// or
var nativePromise = new Promise(function (resolve, reject) {
  jQueryPromise.then(resolve, reject);
});

/*------------------------------ GET RESOLVED/REJECTED PROMISES ------------------------------*/
// RESOLVED
var resolvedPromise = Promise.resolve('Resolved');
// or
var resolvedPromise = new Promise(function (resolve) {
  resolve('Resolved');
});

// REJECTED
var rejectedPromise = Promise.reject(new Error('Rejected'));
// or
var rejectedPromise = new Promise(function (resolve, reject) {
  reject(new Error('Rejected'));
});

// N.B.: RESOLVE/REJECT ARE ALWAYS CALLED ASYNCHRONOUSLY
var test = 'Empty';
resolvedPromise.then(function(res){
 test = 'Changed';
});

console.log(test);// 'Empty';
setTimeout(function(){
 console.log(test);// 'Changed'
}, 0);