phuu is Tom Ashworth

casper: helpers and handlers for Express

24 Apr 2013

Hot on the heels of distra, here’s another little something for your toolbox! Watch the intro video, or check out the documentation. Either way, enjoy…

</param></param></param></embed>

casper is a set of helpers and handlers for building JSONP APIs in Express.

All casper’s methods return a function that can be used in the Express callback chain, or as callbacks for methods that retrieve data, which would typically be a database.

Install

Install casper using npm:

npm install casper

Example usage

The following examples assume that you’ve got the following set up:

// an instance of express() (app) is available
var app = express();

// Grab casper
var casper = require('casper');

Basic handlers

Send an empty object:

// res.jsonp({}) is sent
app.get('/', casper.noop());

Or return some custom data:

// res.jsonp({ hello: 'world' }) is sent
app.get('/',
  casper.noop({
    hello: 'world'
  }));

Database callbacks

casper.db

casper.db returns a function to be used as a database callback. It assumes the first argument is an err and the second is the data is has to send – an array or an object.

It takes Express’ req and res as arguments:

casper.db(req, res)

For example:

app.get('/',
  function (req, res) {
    YourModel
      .find()
      .exec(casper.db(req, res));
  });

It can also take a callback which, if present, is called instead of sending data directly back to the client.

With a callback:

app.get('/',
  function (req, res) {
    YourModel
      .find()
      .exec(casper.db(req, res, function (err, data) {
        // Do something with data
      }));
  });

If it is passed an error, it will pass that on to the client with a 500 status code. If it recieves no data, or an empty array, it will return the data it recieved with a 404 status.

Checks & filters

Casper also has some useful checks & filters to help you ensure the data you’re recieving is what you’re expecting.

capser.check.body

Check for the presence of data in the body using a key:

For the following, assume the body is { testKey: "Hello" }

// calls next() becuase present
app.get('/',
  casper.check.body('testKey'),
  casper.noop());

If the data is missing from the body it sends a 400 error, detailing the missing parameter:

app.get('/',
  casper.check.body('nonExistantKey'),
  casper.noop());

// results in
res.jsonp(400, { error: 'Missing nonExistantKey from body.' });

capser.rm.body

Remove a key from the body:

// body is { testKey: "Hello", otherKey: "World" }
app.get('/',
  casper.rm('testKey'),
  casper.noop());

// afterwards body is { otherKey: "World" }

casper.allow.body

Whitelist a key or array of keys allowed on the body.

// body is { testKey: "Hello", otherKey: "World" }
app.get('/',
  casper.allow.body('otherKey'),
  casper.noop());

// afterwards body is { test: "Hello" }

With an array:

// body is { testKey: "Hello", otherKey: "World", unwantedKey: "World" }
app.get('/',
  casper.allow.body(['testKey', 'otherKey']),
  casper.noop());

// afterwards body is { testKey: "Hello", otherKey: "World" }

Feedback welcome!

As ever, I hope casper is useful to you! If you’ve got any feedback, bugs or ideas then let me know on Twitter or, even better, on GitHub.