cbax

CBAX Library

Cbax is a simple library for creating callback streams that operate like connect middleware. It works for callbacks that expect to called with (error, data).

Install with npm install cbax@git+ssh://[e-mail]:uhray/cbax.git.

Simple Example

var cbax = require('./cbax'),
    fs = require('fs');

// Middleware that ensures no error and there is data
cbax.use(cbax.clean);

fs.readFile('file.txt', cbax(function(e, d) {
  console.log('got data:', d);
}));

API

# cbax.use(callback, [cb2, cb3...])

Adds callback and all other arguments to the middleware chain.

# cbax.copy()

Creates a copy of the cbax object with the same middleware. This allows you to create a new cbax object from the original, add a bunch of middleware, and use it multiple times. I suggest adding middleware that you want globally, and then create a copy for each page or module to use with additional middleware.

# cbax.fresh([callback, cb2, cb3...])

Create a new cbax object with no middleware other than the optional callback values provided as arguments here.

# cbax([callback, cb2, cb3...])

Returns a function with all the preset middleware plus the provided callbacks here. This is the callback function that should be passed to functions expecting a callback.

Callback format

Callbacks should expect three arguments: (error, data, next, context)

The error and data will be preserved from the caller of cbax. The next function will continue down the middleware chain. The context is the context of the cbax object. This context most notably has the get method to retrieve values associated with this cbax instance.

If you call the next object with values, they will override the original error and data. next('error') will override the error. next('error', 'data') will override both error and data.

The context of the callback will the context set by the function caller.

NEW: you can now change the callback format if your callback does not expect only two arguments, you can change the default. Do cbax.config.num_args = 7 to set the number of arguments to 7. This means that the next and context arguments will be the 8th and 9th arguments, respecively.

Middleware

CBax comes packaged with some useful middleware that you can add to your middleware chains if you desire.

# cbax.log()

Logs the error and data values and then calls next.

# cbax.estop()

If there is an error, it stops the middleware chain.

# cbax.dstop()

If there is no data, it stops the middleware chain.

# cbax.clean()

Stops the chain unless there is data and is no error. This the same as using both estop and dstop.

Events

The cbax object is and event emitter. This means you can listen for the following events.

# cbax.on('start', callback)

This is called with an callback chain is first called. It is called with the (error, data) values and the context is the cbax context.

# cbax.on('stop', callback)

This is called with an callback chain is done. It is called with the first argument as the array of arguments that would be passed down the middleware chain.

SetGet

The cbax object has setters and getters. This offers two api methods:

# cbax.set(key, value)

Set's the key-value pair on the object so that callback functions can be configured with more information than just the value in the argument array.

# cbax.get(key)

Retrieves the value associate with this key (values set using the set method).

Future Work

• More prepackaged middleware
• More events of use