Promises, Promises

function getUserInfo(id, callback) {
    $.ajax({
        url: "/user/" + id,
        type: 'GET',
        dataType: 'html',
        success: function(data, textStatus, xhr) {
            callback(null, data);
        },
        error: function(xhr, textStatus, errorThrown) {
            callback(new Error(textStatus), errorThrown);
        }
    });
}
function getUserComments(id, callback) {
    $.ajax({
        url: "/user/" + id + "/comments",
        type: 'GET',
        dataType: 'html',
        success: function(data, textStatus, xhr) {
            callback(null, data);
        },
        error: function(xhr, textStatus, errorThrown) {
            callback(new Error(textStatus), errorThrown);
        }
    });
}

// Get the user info
getUserInfo(1, function(err, userDoc) {
    if (!err) {
        // get the user comments
        getUserComments(1, function(err, commentArray) {
            if (!err) {
                DisplayUserInfoWithComments(userDoc, commentArray);
            } else {
                // Do something to handle errors
            }
        });
    } else {
        // Do something to handle errors
    }
}

Let's try that

// Get the user info
var userDoc = null;
var commentArray = null;
var wasError = false
getUserInfo(1, function(err, inDoc) {
    if (!err) {
        userDoc = inDoc;
        if (commentArray) {
            DisplayUserInfoWithComments(userDoc, commentArray);
        }
    } else {
        wasError = err;
        wasError.errThrown = arguments[1];
    }
});
getUserComments(1, function(err, inArray) {
    if (!err) {
        commentArray = inArray;
        if (userDoc) {
            DisplayUserInfoWithComments(userDoc, commentArray);
        }
    } else {
        wasError = err;
        wasError.errThrown = arguments[1];
    }
});

// Deferred method
function getUserInfo(id) {
    return $.ajax({
        url: "/user/" + id,
        type: 'GET',
        dataType: 'html',
    }).then(function(data, textStatus, xhr) { return data; });
}
function getUserComments(id, callback) {
    $.ajax({
        url: "/user/" + id + "/comments",
        type: 'GET',
        dataType: 'html'
    }).then(function(data, textStatus, xhr) { return data; });
}

// Get the user info; deferred method
var userDfd = getUserInfo(1);
var commentsDfd = getUserComments(1);
DisplayUserInfoWithComments(userDfd, commentsDfd);

function DisplayUserInfoWithComments(userDfd, clistDfd) {
        $.when(userDfd, clistDfd).then(function(user, clist){
// Previous contents of DisplayUserInfoWithComments in here
        }, function(err) {
// Handle the error
        });
    }
    

Traditional Callback:

• Operations that do something asynchronously and return a result

• Operations that take data and do something with it

Which of these should care about program flow?

function cleanDatabase() {
    var waitFor = [];

    console.log("Cleaning database");
    waitFor.push(dropCollection('users'));
    waitFor.push(dropCollection('comments'));

    return Q.all(waitFor);
}

Most Promise libraries have something like Q.all -- jQuery has $.when, other libraries call it something different.  It accepts multiple Promises and resolves once all input Promises are resolve to an array containing the resolved value of each promise.

If any of those Promises reject then the Promise returned by Q.all will immediately reject to the error that Promise rejected with.

• Don't make a promise you don't intend to keep.
  
  
• Trust, but verify!
  
  
• For every promise, there is price to pay. ~Jim Rohn
  
  
• Empty promises.
  
  
• Instant Gratification

A promise should eventually settle!

Always Always Always handle the error case!

// Wrong way!
GetDBRecord().then(function(result) {
    // Do something cool with the result
});

// Right way!
GetDBRecord().then(function(result) {
    // Do something cool with the result
}, function(err) {
    // Panic!
});

Always handling the error case does not mean you must always handle it right away -- if you return the Promise (or return the result of .then) then a calling method might handle it.

A Promise whose reject case isn't handled will fail silently!

Sometimes a Promise is just used to mark success or failure

function displayLoadingIndicator(promise) {
    showLoadingIndicator();
    var hide = function() { hideLoadingIndicator(); };
    Promise.when(promise).then(hide, hide);
}

Some libraries, such as jQuery Deferred, have a .always() shortcut for this

function changeTheUser(user) {
    return Promise.when(user).then(function(user) {
        // The user is resolved!
    });
}

When a function returns a promise, arguments can be a promise or a value. 

The when function accepts a Promise or a value and return a Promise.

If the input is not a Promise it immediately resolves to the value.

• Still in development -- last updated in the draft April 3, 2015
• Not final, but implemented in Chrome, Firefox, and node 0.12
  
• Terminology: "fulfilled", "rejected", "pending".
• "settled" means not pending.  "resolved" if it is either settled or "locked in" to match another promise.
• Functions
• Promise.all - accepts an array one or more Promises or values and  returns a promise that is fulfilled when all passed promises are fulfilled. Fulfills to an array of those promises or rejects to the reason of the first promise that is rejected.
• Promise.race - accepts one or more values and returns a promise that is settled in the same way as the first promise to settle of the passed promises.
• Promise.reject / Promise.resolve - Resolves or rejects the promise

function doSomethingAmazing(someValue) {
    return new Promise(function(resolve, reject) {
        CallAwesomeThing(someValue, function(err, result) {            if (err) { reject(err); }
            else { resolve(result); }
        });
    });
}

• Most widely accepted standard for Javascript Promises
• To fully support, must pass 872 unit test
• At least partially supported by most Promise libraries
• thennable just requires a then method
• Three states: 'pending', 'fulfilled', 'rejected'
• The then method must accept two arguments, onFulfilled and onRejected
• Any Promise library supporting the Promises/A+ standard will be interoperable by nature of common support for the then method.

The ECMAScript 6 is not Promises/A+ compliant, but is close.

• Comes free with jQuery, already used by all jQuery async methods
  
  
• jQuery 1.8 made Deferred objects thenable , so mostly (but not completely) interoperable with Promise/A+ libraries
  
  
• Besides resolve and rejected states, supports an additional "progress" callback that can be triggered multiple times to give progress updates before it is settled.