canal

Canal

A structured routing toolkit for Express

Canal was designed to make structuring routes in Express as easy as possible by relying on JavaScript objects to design your routes. It allows you to easily manage complex routing strategies while ensuring that the code remains readable and navigatable.

Install

Using Canal is extremely simple, just add a dependency to your package.json file or run npm install canal from the terminal.

Example

var express = require('express'),
	canal = require('canal');

var app = express();
app.use(express.bodyParser());
app.use(app.router);

var routes = {
	// GET /
	get: function(req, res) {
		return res.render('index');
	},

	login: {
		// GET /login
		get: function(req, res) {
			return res.render('login')
		},
		// POST /login
		post: function(req, res) {
			// login logic
			return res.redirect('/');
		}
	},
	user: [checkLogin, {
		// Translated into a placeholder
		$username: {
			get: function(req, res) {

			}
		}
	}]
};

canal(app, routes);

app.listen(process.env.port || 3000);

Features

• Structured Route Design Canal allows you to design your routes by following a proven set of guides which ensure that your routes are easy to understand, extend and modify.
• Tree Based Structure Your routes are tree-based, so why should you be forced to use a linear design approach? Embrace the power of JavaScript's object maps and realize just how easily complex routes can be designed and managed.
• Powerful Syntax Canal allows for complex routing paradigms, including the use of Express' chained route handling while still keeping the syntax as simple as possible. Don't believe us? Try it out for yourself.

API

Canal's API consists of a single function which allows you to register routes with an application.

function Canal(app, routes, options = Canal.options);

Canal.options = {
	registrar: Canal.Express.registrar,
	idenfifierPreprocessor: Canal.Express.identifierPreprocessor,
	basePath: '/',
	pathSeparator: '/'
};

Routes List

Sometimes it's handy to get a list of all the routes which will be generated by Canal for access control systems, or indexes. This can easily be achieved by using Canal's routes method, which returns a layout of the routes generated by a routing table.

Canal.routes(routes);
Canal.routes(routes, options);

var result = Canal.routes({
	get: function(req, res) {},

	user: {
		get: function(req, res) {},
		post: function(req, res) {}
	}
});

result = {
	get: ['/', '/user'],
	post: ['/user']
};

Routes Syntax

The routes used by Canal are formed by creating a nested JavaScript map object describing the different path branches. Each laef represents the path component at the depth of the branch it is linked to, so the path /user/login would be represented by the object { user: { login: {} } }. Each leaf can specify functions to handle different verbs (get, post, delete etc.).

Basic Routes

Basic routes are defined by creating an object like the following. Canal will attempt to register functions as route handlers, using their property name as the verb.

var routes = {
	get: function(req, res) { },

	user: {
		get: function(req, res) { },
		post: function(req, res) { }
	}
};

Placeholders

To further extend the power of routes, placeholders can be used, indicated by the presence of a $ sign before the name of the placeholder. These placeholders should be registered with Express using the app.param() function before they will work.

var routes = {
	get: function(req, res) { },

	$username: {
		get: function(req, res) { },
		post: function(req, res) { }
	}
};

Cascading Routes

Sometimes it's necessary to include request preprocessors on specific routes. For example, the ability to ensure that a user is signed in for any administrative routes is a common use case, and one that can be handled by a route preprocessor. Canal allows these preprocessors to be implemented very easily through the use of arrays as leaves in the route tree.

var routes = {
	get: function(req, res) { },

	admin: [ensureLogin, {
		get: function(req, res) { },
		pages: {
			get: [populatePages, function(req, res) { }]
		}
	}]
};

Cascading handlers are applied to all child routes when they appear with an Object as the last element, while they are implemented only for the given handler if the last element in the array is a function.

Customization

By default, Canal comes with support for Express out of the box, but it has been designed to allow you to easily modify its behaviour to work with different frameworks. The core of Canal's framework behaviour are the identifierPreprocessor and registrar methods in Canal.options. These methods are responsible for handling the conversion of placeholders into the syntax expected by the web framework, and registering new routes with the framework respectively.

function Express_Registrar(app, verb, route, handlers) { 
	var args = [route];
	args.push(handlers);

	if(!app[verb]) 
		throw new Error('The requested routing verb "' + verb + '" wasn\'t available for the route "' + route + '"');

	app[verb].apply(this, args);
};

function identifierPreprocessor(identifier) {
	if(identifier[0] == '$')
		return ':' + identifier.substr(1);
	return identifier;
}