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 = canal = ; var app = ;app;app; var routes = // GET / { return res; } login: // GET /login { return res } // POST /login { // login logic return res; } user: checkLogin // Translated into a placeholder $username: { } ; ; app;
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.
; Canal.options = { registrar: CanalExpressregistrar idenfifierPreprocessor: CanalExpressidentifierPreprocessor 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;Canal; var result = Canal; 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 = { } user: { } { } ;
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 = { } $username: { } { } ;
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 = { } admin: ensureLogin { } pages: get: populatePages { } ;
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.
{ var args = route; args; if!appverb throw 'The requested routing verb "' + verb + '" wasn\'t available for the route "' + route + '"'; appverb;}; { ifidentifier0 == '$' return ':' + identifier; return identifier;}