Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
liberal JSON-only HTTP request routing for node.
JavaScript
Tag: v0.1.0

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
benchmark
example
lib
test
LICENSE
Makefile
README.md
TODO
package.json

README.md

journey

liberal JSON-only HTTP request routing for node.

introduction

Journey's goal is to provide a fast and flexible RFC 2616 compliant request router for JSON consuming clients.

synopsis

var journey = require('journey');

//
// Create a Router object with an associated routing table
//
var router = new(journey.Router)(function (map) {
    map.root.bind(function (res) { res.send("Welcome") });
    map.get(/^trolls\/([0-9]+)$/).bind(function (res, id) {
        database('trolls').get(id, function (doc) {
            res.send(200, {}, doc);
        });
    };
    map.post('/trolls').bind(function (res, data) {
        sys.puts(data.type); // "Cave-Troll"
        res.send(200);
    });
});

require('http').createServer(function (request, response) {
    var body = "";

    request.addListener('data', function (chunk) { body += chunk });
    request.addListener('end', function () {
        //
        // Dispatch the request to the router
        //
        router.route(request, body, function (result) {
            response.writeHead(result.status, result.headers);
            response.end(result.body);
        });
    });
}).listen(8080);

API

You create a router with the journey.Router constructor:

var router = new(journey.Router)(function (map) {
    // Define routes here
});

The returned object exposes a route method, which takes three arguments: an http.ServerRequest instance, a body, and a callback, as such:

function route(request, body, callback)

and asynchronously calls the callback with an object containing the response headers, status and body:

{ status: 200,
  headers: {"Content-Type":"application/json"},
  body: '{"journey":"Welcome"}'
}

Note that the response body will either be JSON data, or empty.

Routes

Here are a couple of example routes:

// HTTP methods                      // request
map.get('/users')                    // GET    /users
map.post('/users')                   // POST   /users
map.del(/^users\/(\d+)$/)            // DELETE /users/45
map.put(/^users\/(\d+)$/)            // PUT    /users/45

map.route('POST',          '/users') // POST        /users
map.route(['POST', 'PUT'], '/users') // POST or PUT /users

map.root                             // GET /
map.any                              // Matches all request
map.post('/', {                      // Only match POST requests to /
    assert: function (req) {         // with data in the body.
        return req.body.length > 0;
    }
});

Any of these routes can be bound to a function or object which responds to the apply method. We use bind for that:

map.get('/hello').bind(function (res) {});

If there is a match, the bound function is called, and passed the response object, as first argument. Calling the send method on this object will trigger the callback, passing the response to it:

map.get('/hello').bind(function (res) {
    res.send(200, {}, {hello: "world"});
});

The send method is pretty flexible, here are a couple of examples:

                            // status, headers, body
res.send(404);              // 404     {}       ''
res.send("Welcome");        // 200     {}       '{"journey":"Welcome"}'
res.send({hello:"world"});  // 200     {}       '{"hello":"world"}'

res.send(200, {"Server":"HAL/1.0"}, ["bob"]);

As you can see, the body is automatically converted to JSON, and if a string is passed, it acts as a message from journey. To send a raw string back, you can use the sendBody method:

res.sendBody(JSON.stringify({hello:"world"}));

This will bypass JSON conversion.

URL parameters

Consider a request such as GET /users?limit=5, I can get the url params like this:

map.get('/users').bind(function (res, params) {
    params.limit; // 5
});

How about a POST request, with form data, or JSON? Same thing, journey will parse the data, and pass it as the last argument to the bound function.

Capture groups

Any captured data on a matched route gets passed as arguments to the bound function, so let's say we have a request like GET /trolls/42, and the following route:

get(/^([a-z]+)\/([0-9]+)$/)

Here's how we can access the captures:

map.get(/^([a-z]+)\/([0-9]+)$/).bind(function (res, resource, id, params) {
    res;      // response object
    resource; // "trolls"
    id;       // 42
    params;   // {}
});

Summary

A bound function has the following template:

function (responder, [capture1, capture2, ...], data/params)

license

Released under the Apache License 2.0

See LICENSE file.

Copyright (c) 2010 Alexis Sellier

Something went wrong with that request. Please try again.