Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Yet another CPS helper

branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.rst

wrapas

The wrapas function is a simple helper to use with continuation passing style libraries. It helps to resolve some common pattern and problems brought by this convention and helps the developer to have a better vision of the control flow of his program.

A lot of alternatives already exist, I did not check them all. There is probably some solutions much more accurate to your needs, but here is mine.

Features

  • provides a simple way to aggregate results, in a predictable order
  • handles errors at one unique place
  • prevents multiple calls of a callback
  • guarantees that the final callback will be asynchronous
  • binds the callback to a given context
  • ≈576 bytes minified, ≈370 bytes gzipped, nodejs and browser compliant

Examples

Compile a template:

function compileTemplate(templatePath, dataPath, callback) {
  var as = wrapas(function (error, template, data) {
    if (error) {
      callback(error);
    }
    else {
      template.render(data);
    }
  });

  fs.readFile(templatePath, as(function (content) {
    return new Template(content);
  }));

  fs.readFile(dataPath, as(function (content) {
    return JSON.stringify(content);
  }));
}

Fetch multiple ressources:

{

  // getAllIds: function(callback) { .... },
  // getUser: function(id, callback) { .... },

  getUserNames: function (callback) {
    var as = wrapas(function (error) {
      // Transform the arguments to an array
      callback(error, [].splice.call(arguments, 1));
    }, this);

    this.getAllIds(as(function (ids) {
      ids.forEach(function (id) {
          this.getUser(id, as());
      }, this);
    }));
  }
}

Dependency

In order to work with callbacks that could be synchronous, we have to use a function that will do an asynchronous call just after all synchronous code is run. setTimeout(..., 0) could be used but it is very slow: the minimum delay is bound to a few milliseconds, depending on the environment.

We use the setImmediate(...) alternative, which is only on Internet Explorer 10 but that can be implemented on other environments as well with postMessage (recent browsers), nextTick (nodejs) or setTimeout (as a fallback).

Include immediate.js if you don't have any better polyfill for this function (and its counterpart, clearImmediate).

API

The wrapas function will create a ‘callback registry’. It will returns a function that, when called, registers a new callback, and return a wrapper function to be used as a callback in continuation passing style APIs like the nodejs standard library.

wrapas(function(error, args...), ?object)

Create a new ‘callback registry’ in order to track callbacks. The first argument is a function to call when all callbacks are executed, or if a callback receive an error. The error argument is the first error to be passed to any callback, and the other arguments are values returned by the functions you register.

The second argument is optional and is passed as context for all callbacks.

‘callback registry’(function(args...))

Register a new callback. If the resulting function is called with a truthy value as first argument, this callback will be called with the other arguments. Else, the final callback will be called with the first argument and all future call on functions from the registry will be ignored.

When all resulting function are called and there was no error, the final callback is called with the defined values returned by the registered callbacks as arguments.

Random thoughts

Wrap this library yourself! Chose the best wrapper that covers your needs.

Something went wrong with that request. Please try again.