tgvashworth

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…

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.