An example of wrapping multiple dependent AJAX requests in a single promise using jQuery's Deferred object

promise-wrap-example.js

/**
 * Get a user's public GitHub activity using the GitHub API
 * Returns a promise
 */
function GitHubActivity(username) {
  var master, fetch, collectedData;

  collectedData = [];

  /**
   * Retrieve data from the API one page at a time, and update the status of the master Deferred
   */
  fetch = function(pageURL) {
    var request;

    pageURL = pageURL || 'https://api.github.com/users/'+username+'/events/public';

    // Make the AJAX request, which returns a promise
    request = $.ajax({
      url: pageURL,
      headers: {'Accept': 'application/vnd.github.v3+json'},
      dataType: 'json'
    });

    // Attach a function that will execute when data is returned
    request.done(function(data, status, xhr) {
      var matches;

      // Notify the master Deferred that we've received a page of data
      master.notify(data);

      // Append the page of data to our collection
      collectedData = collectedData.concat(data);

      // Parse Link header looking for a "next" URL
      matches = /<(\S+)>; rel="next"/.exec(xhr.getResponseHeader('Link'));

      if (matches) {
        // Fetch the next page
        fetch(matches[1]);
      } else {
        // No more pages to fetch, resolve the master Deferred with the collected page data
        master.resolve(collectedData);
      }
    });

    // Attach a function that will execute when an error occurs
    request.fail(function(xhr, status, error) {
      // Reject the master Deferred with the error object
      master.reject(error);
    });
  };

  // Create a master Deferred object to track the progress of the task
  master = new $.Deferred();

  // Start fetching data from the API
  fetch();

  // Return the Deferred's promise (basically a read-only version of the Deferred)
  return master.promise();
}

/*
 * Start Example
 */

// Create a new GitHubActivity object which returns a promise
var example = new GitHubActivity('TheBinaryPenguin');

// Attach a function that will execute when a page is retrieved
example.progress(function(data) {
  console.log('Received a Page ('+data.length+' items)');
});

// Attach a function that will execute when all pages have been retrieved
example.done(function(data) {
  console.log('Received All Pages ('+data.length+' items)');
});

// Attach a function that will execute when an error occurs
example.fail(function(data) {
  console.log('Error: '+data);
});

// Attach a function that will execute when the promise completes regardless of success or failure
example.always(function() {
  console.log('Example Complete');
});