Example: Wrapping async transactions with promises

Creating a Cache

A cache is an object that keeps track of which operations have already been performed, stores the results and returns the stored result if the operation was already performed. In this case, since we are fetching content with JSONP, the operations are asynchronous so we will store promises representing them.

// We create a simple module with a private cache object
var GitHub = (function () {

    var cache = {};

    return {
        getUser: function (name) {
            // This method will return a promise
        }
    };
}());

Given a certain function that takes a user name and returns the corresponding GitHub API URL, then a method that caches the user data will simply check the private cache object or fetch the result.

getUser: function (name) {
    var url = getUserURL(name);

    if (cache[url]) {
        // If we have already stored the promise in the cache we just return it
        return cache[url];
    } else {
        // fetch() will make a JSONP request, cache the promise and return it
        return fetch(url);
    }
}

Resolving and Returning Promises

Our fetch() function will create a promise and fulfill it or reject it based on the result of the JSONP request. Following the steps described in the User Guide, we create a promise and call Y.jsonp inside its initialization function.

// Fetches a URL, stores a promise in the cache and returns it
function fetch(url) {
    var promise = new Y.Promise(function (fulfill, reject) {
        Y.jsonp(url, function (res) {
            var meta = res.meta,
                data = res.data;

            // Check for a successful response, otherwise reject the
            // promise with the message returned by the GitHub API.
            if (meta.status >= 200 && meta.status < 300) {
                fulfill(data);
            } else {
                reject(new Error(data.message));
            }
        });

        // Add a timeout in case the URL is completely wrong
        // or GitHub is too busy
        setTimeout(function () {
            // Once a promise has been fulfilled or rejected it will never
            // change its state again, so we can safely call reject() after
            // some time. If it was already fulfilled or rejected, nothing will
            // happen
            reject(new Error('Timeout'));
        }, 10000);
    });

    // store the promise in the cache object
    cache[url] = promise;

    return promise;
}

Wiring It All Together

Here is the complete code for this example. You will notice that it contains a request for a user called "y u i" which likely does not exist. This illustrates how promises help you handle errors. While it may be tempting to skip adding an error callback, it is highly recommended that you add one and provide feedback to your users when things go wrong.

HTML

<div id="demo"></div>

CSS

<style>
    #demo div {
        padding: 5px;
        margin: 2px;
    }
    .success {
        background: #BBE599;
    }
    .error {
        background: #ffc5c4;
    }
</style>

JavaScript

<script>
YUI().use('node', 'jsonp', 'promise', 'escape', function (Y) {

// A cache for GitHub user data
var GitHub = (function () {

    var cache = {},
        githubURL = 'https://api.github.com/users/{user}?callback={callback}';

    function getUserURL(name) {
        return Y.Lang.sub(githubURL, {
            user: name
        });
    }

    // Fetches a URL, stores a promise in the cache and returns it
    function fetch(url) {
        var promise = new Y.Promise(function (fulfill, reject) {
            Y.jsonp(url, function (res) {
                var meta = res.meta,
                    data = res.data;

                // Check for a successful response, otherwise reject the
                // promise with the message returned by the GitHub API.
                if (meta.status >= 200 && meta.status < 300) {
                    fulfill(data);
                } else {
                    reject(new Error(data.message));
                }
            });

            // Add a timeout in case the URL is completely wrong
            // or GitHub is too busy
            setTimeout(function () {
                // Once a promise has been fulfilled or rejected it will never
                // change its state again, so we can safely call reject() after
                // some time. If it was already fulfilled or rejected, nothing will
                // happen
                reject(new Error('Timeout'));
            }, 10000);
        });

        // store the promise in the cache object
        cache[url] = promise;

        return promise;
    }

    return {
        getUser: function (name) {
            var url = getUserURL(name);

            if (cache[url]) {
                // If we have already stored the promise in the cache we just return it
                return cache[url];
            } else {
                // fetch() will make a JSONP request, cache the promise and return it
                return fetch(url);
            }
        }
    };
}());


var demo = Y.one('#demo'),
    SUCCESS_TEMPLATE = '<div class="success">Loaded {name}\'s data! ' +
                        '<a href="{link}">Link to profile</a></div>',
    FAILURE_TEMPLATE = '<div class="error">{message}</div>';

function renderUser(user) {
    demo.setHTML(Y.Lang.sub(SUCCESS_TEMPLATE, {
        // escape the values gotten from the GitHub API to avoid unexpected
        // HTML injection which could be an XSS vulnerability
        name: Y.Escape.html(user.login),
        link: Y.Escape.html(user.html_url)
    }));
}

function showError(err) {
    demo.setHTML(
        'Looks like the service might be down - would you like to <a href="?mock=true">try this example with mock data</a>?'
    );
}

GitHub.getUser('yui').then(renderUser, showError);

});
</script>