Robust Callbacks

Makes JavaScript callback APIs robust

Callback APIs are the most natural way to implement asynchronous control flow. Improper use of such APIs is, however, hard to debug. The callback function might get called

• not at all: leading to a sudden stop in the middle of applications, without an error or stack trace.
• several times: leading to hard to track down repetitions of your business logic
• too late: making slowness hard to track down

This library fixes this. It wraps callbacks that your code expects to be called by client code.

• the callback isn't called --> the wrapper returns the callback with an error after a timeouj
• the callback is called too late (after the timeout) --> the wrapper has already returned an error and ignores the late call
• the callback is called multiple times --> the wrapper throws an exception on the second call
• all other cases (single calls on time with success or errors) are passed through

Usage

Let's say you create a unit testing library like MochaJS. Users can use it to define tests like this:

it "requires me to call the asynchronous return method at the end of my test", (done) ->
  # Test something here...

  # Now finish the test by calling the async return method
  done()

A simple implementation of your libary, with the problems mentioned above, would look something like this:

it = (name, test_function) ->
  test_function (err) ->
    # the test is finished here

Hardening this implementation through robust-callbacks requires very minimal adjustments:

roca = require 'robust-callbacks'

it = (name, test_function) ->
  test_function roca (err) ->
    # the test is finished here

Now if your pesky users forget to call done, or call it multiple times, they'll get a proper error message telling them exactly what they did wrong!

Development

See the developer guidelines