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 fix 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; });
}

• Shorter methods
• Where did the error handling go?
• Why are we doing a no-op then function?
• jQuery normally resolves ajax to 3 parameters; we only care about the first.

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

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

• 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
• The power of empty promises.
• A promise made is a promise kept.
  

Don't make a promise you don't intend to keep
A promise should eventually settle (resolve or reject)!

Trust, but verify!
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.

The easiest way to get a hard-to-find error with Promises is having something fail when you aren't handling the error case.

The power of empty promises

There are times when the result of a promise is less important than whether or not the promise has settled -- or even whether it succeeded or failed!

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

A promise made is a promise kept

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

If you are willing to have a function return a promise, or if the output doesn't matter, you can easily make that function not care if it's a promise or not.

Most promise libraries have something similar to the ECMAScript when function, which will accept a Promise or a value and return a Promise that will settle the same way that Promise does.

In the case of a value it immediately resolves to the value.
This is extremely powerful!!

• Still in development -- last updated in the draft April 5, 2014
• Not final, but implemented in Chrome and Firefox (latest versions)
  
• 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
• Promise.defer() - returns a Deferred object with .reject(), .resolve(), and .promise
  
• Promise.defer().promise returns a Promise that will be settled by the Deferred object and is thenable

• Widely accepted as "The Standard" for Javascript Promises
• Implemented by the majority of javascript Promise libraries
• Partially supported by most other libraries
• Defines thenable as any object with a then method.
• Defines 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 standard seems to be Promises/A+ compliant.

• Comes free with jQuery, already used by all jQuery async methods
• jQuery 1.8 made Deferred objects thenable , so generally 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.