detour


Detour is a router for node.js web applications.

Detour is different from sinatra-style routers (like express's router) because you route urls to objects (that have http methods) instead of to http methods.

Rationale: If you have multiple http methods implemented for a given url (like a lot of APIs do), this style of routing will be much more natural and will vastly improve your code organization and re-use. With object routing, it's much simpler to keep the related handlers together, but separated from unrelated handlers (often even in another file/module).

It works for node.js' standard HTTP server, as well as express and connect applications.

Examples:

$3

``javascript
var detour = require('detour');
var http = require('http');
var router = detour();

router.route('/', {
GET : function(req, res){
res.end("GET works!");
},
POST : function(req, res){
res.end("POST works too!");
}
});

http.createServer(function(req, res){
router.middleware(req, res);
}).listen(9999);
`

$3


`javascript
var detour = require('detour');
var express = require('express');
var app = express();
var router = detour();
app.use(router.middleware);

router.route('/', {
GET : function(req, res){
res.end("GET works!");
},
POST : function(req, res){
res.end("POST works too!");
}
});

`


$3

A simple example:

`javascript
router.route('/test/:test_id', {
GET : function(req, res){
res.end("GET works: " + req.pathVar.test_id);
// a request to /test/1234 will have output like this:
// GET works: 1234

// req.pathVar is a hash of all name value pairs pull from the
// request url
},
});

`
In the example above, you can see that the path string sent to the router (/test/:test_id) uses the same format as express. Regular expressions are also allowed.


You can also see from the example that within a route handler, req.pathVar will have all the variables collected from your route.

$3


Detour supports connect-style middleware like most node.js
frameworks (including express). Example:
`javascript
var detour = require('detour');
var router = detour();
router.use(someMiddleware);
`

The middleware stack for detour runs after the route has been
determined, but before any other processing. The entire routed resource
object will be available at req.detourHandler if you want to do any
special handling in your middleware that are related to its contents.

This makes Detour extremely extensible on a resource-by-resource basis. For example, if you write a resource object like this:

`javascript
router.route('/test/:test_id', {
mustBeAuthenticated : true, // <-- NB: non-standard property
GET : function(req, res){
res.end("GET works: " + req.pathVar.test_id);
},
});

`

...you can write a middleware that acts according to that data before the handler
for GET is called.




$3

In addition to regular object routing, For the sake of convenience, Detour also supports collection-routing where two resource objects can be routed in a
collection-member relationship at the same time.

Here's an example:

`javascript
var router = new Router();
router.collection('/test/:testid', {
collection : {
GET : function(req, res){
res.end('collection here!');
}
},
member : {
GET : function(req, res){
res.end('member here! ' + JSON.stringify(req.pathVar));
}
}
});
`

Note: the object being routed has two properties: collection and
member, with each being a resource object on its own. The member
resource object will be routed to the given path (/test/:testid in this
case), and the collection resource object will be routed to the parent
path (/test in this case).

This feature can be useful if you have resources that follow this
pattern and you want to keep these two similar resources together in the same file.




$3

#### OPTIONS handling:
There is a default OPTIONS response for any route but you can over-ride it like this:
`javascript
router.on('OPTIONS', function(req, res, resource){
// resource is the object you routed. You can loop through the methods on it here if you want!
res.writeHead(200);
res.end("options, options, options!");
});
`

#### HEAD handling:
There is a default HEAD response for any route with a GET, but you can over-ride it like this:
`javascript
router.on('HEAD', function(req, res, resource){
// resource is the object you routed. You can call resource.GET() from here if you want!
res.writeHead(200);
res.end("doesn't matter what I type here. node will not send output on a HEAD request")
});
`

$3

#### 405 handling:
The correct http response for a method that an existing url doesn't support is a 405. You can over-ride the default like this:
`javascript
router.on(405, function(req, res, resource){
// resource is the object you routed. You can loop through the methods on it here if you want!
res.writeHead(405);
res.end("this resource doesn't support that method! ");
});
`

#### 404 handling:
There is a default 404 response for any route that doesn't match, but you can over-ride it like this:
`javascript
router.on(404, function(req, res){
res.writeHead(404);
res.end("nope. couldn't find that!")
});
`
(NOTE: this only works if the middleware doesn't get a third parameter -- typically called next() -- passed to it,
otherwise next()` is used for 404s as you'd expect from a middleware.)