Neverending Prototype Mode

    rsvp-tools

    0.1.0 • Public • Published

    rsvp-tools is a set of utility functions for wrapping event or callback based JavaScript APIs in RSVP promises. Both the browser and Node.js environments are supported.

    A simple example to get started. Here is a simple API call on the Facebook JavaScript SDK:

    FB.api('/platform', function(response){
      alert(response.company_overview);
    }, function(error){
      alert("Failed to fetch the platform summary");
    });

    With rsvp-tools:

    // Wrap the `api` function in promises
    var api = rsvpTools.callback.build(FB, 'api');
     
    api('/platform')
      .then(function(response){
        alert(response.company_overview);
      }, function(){
        alert("Failed to fetch the platform summary");
      });

    A simple example doesn't leverage promises very much- in this more complicated example we will find out which is more popular, my hometown or my current town.

    var errorHandler = function(){
      alert('Woops!');
    }
    FB.api('/me', function(response){
      var placesToCheck = 2,
          hometown,
          location;
          displayMorePopularItem = function(){
            var mostPopular = places.sort(function(a,b){ return b.likes <=> a.likes })[0];
            alert('Your most popular town is: '+mostPopular.name);
          };
      FB.api('/'+response.hometown.id, function(response){
        hometown = response;
        placesToCheck--;
        if (placesToCheck == 0) displayMorePopularItem();
      }, errorHandler);
      FB.api('/'+response.location.id, function(response){
        location = response;
        placesToCheck--;
        if (placesToCheck == 0) displayMorePopularItem();
      }, errorHandler);
    }, errorHandler);

    This amount of indirection can make following source code difficult. rsvp-tools can help you clean it up:

    var api = rsvpTools.callback.build(FB, 'api');
     
    api('/me')
      .then(function(response){
        return RSVP.all([
          api('/'+response.hometown.id),
          api('/'+response.location.id)
        ])
      }).then(function(places){
        return places.sort(function(a,b){ return b.likes <=> a.likes })[0];
      }).then(function(mostPopular){
        alert('Your most popular town is: '+mostPopular.name);
      }).fail(function(error){
        alert('Woops!');
      });

    Usage

    // callback.build
    //
    // Wrap async expecting a success and error callback after other
    // arguments. Use this wrapper for dealing with a context that will
    // never change.
    //
    var facebookApi = rsvpTools.callback.build(FB, 'api');
     
    // Always calling `api` on the `FB` context
    facebookApi("/platform").then(success, failure);
    // callback.contextPassed
    //
    // Wrap async expecting a success and error callback after other
    // arguments. Use this wrapper for dealing with a context that will
    // be decided at call-time.
    //
    var facebookApi = rsvpTools.callback.contextPassed('api');
     
    // Apply the promise-wrapped `api` method to the passed FB object.
    facebookApi(FB, "/platform").then(success, failure);
    // eventd.contextPassed
    //
    // Wrap async emitting success/failure events. This wrapper expects
    // the context to be provided at call-time.
    //
    var open = rsvpTools.evented.contextPassed('open');
     
    // Apply `open` to the XMLHTTPRequest instance.
    open(new XMLHTTPRequest(), "GET", "/api/foo.json").then(success, failure);
     
    // evented.contextPassed will try to attach handlers using several
    // standard functions:
    //
    //   addEventListener, attachEvent, on
    //
    // And will listen for the events "success" and "error". These can
    // be changed at setup-time.
    var readAsDataUrl = rsvpTools.evented.contextPassed('readAsDataUrl', 'load');
     
    // Promise resolves on the `load` event
    readAsDataUrl(new FileReader(), new Blob([])).then(success, failure)

    Building

    npm install
    bower install
    

    To build:

    grunt
    

    And to run tests start the server with:

    grunt server
    

    And visit http://localhost:8000/test/

    rsvp-tools is available under the MIT license. Cory Forsyth and Matthew Beale 2013

    Install

    npm i rsvp-tools

    DownloadsWeekly Downloads

    0

    Version

    0.1.0

    License

    MIT

    Last publish

    Collaborators

    • bantic
    • mixonic