#

Jump to Table of Contents

# Example: Wrapping async transactions with promises

This example shows how to create a cache for the GitHub Contributors API that returns promises representing the values you fetched. In order to access the API we use the JSONP module.

### 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 scoped>
        #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}</a>\'s data! ' +
                            '<a href="{link}">Link to profile</a></div>',
        FAILURE_TEMPLATE = '<div class="error">{message}</div>';

    function renderUser(user) {
        demo.append(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.append(Y.Lang.sub(FAILURE_TEMPLATE, {
            message: Y.Escape.html(err.message)
        }));
    }

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

    });
    </script>