en-route

Routing for static site generators, build systems and task runners, heavily based on express.js routes but works with file objects. Used by Assemble, Verb, and Template.

Install

Install with npm:

$ npm install --save en-route

Thank you

This was highly inspired by express routes. Thank you, TJ. Our lives are easier because of your hard work.

Express is released under the MIT license. The code that inspired this library was Copyright (c) 2009-2014 TJ Holowaychuk tj@vision-media.ca.

API

Layer

Create a new Layer with the given path, options and handler function.

Params

• path {String}
• options {Object}
• handler {Function}
• returns {undefined}

Example

var layer = new Layer('/', function(file, next) {
  // do stuff to file
  next(null, file);
});

Route

Initialize Route with the given path,

Params

• path {String}

Example

var route = new Route('/', ['preRender', 'postRender']);

.dispatch

Dispatch a middleware stack over the given file.

Params

• file {Object}: File object
• returns {Function}: Callback that exposes err and file

Example

route.dispatch(file, function(err, res) {
  if (err) return console.log(err);
});

.all

Handler for all methods on the route.

Params

• handler {Function}
• returns {Object}: Route instance for chaining

Example

route.all(function(file, next) {
  file.data.title = 'Home';
  next();
});

.handler

Add a middleware handler method for the given name to the route instance.

Params

• method {String}: Name of the handler method to add to the route instance.

Example

route.handler('before');
route.handler('after');

.handlers

Add methods to the route instance for an array of middleware handlers.

Params

• methods {Array}: Method names to add to the route instance.

Example

route.handlers(['before', 'after']);

.match

Returns true if any layers in route.stack match the given path.

Params

• path {String}
• returns {Boolean}

.layer

Push a layer onto the stack for the given handler method and middleware fn.

Params

• name {String}: Layer name
• fn {Function}: Middleware function

Example

route.layer('before', {}, function(){});
route.layer('after', {}, [function(){}, function(){}]);
route.layer('other', [function(){}, function(){}]);

Router

Initialize a new Router with the given methods.

Params

• options {Object}
• returns {Function}: Returns a callable router function

Example

var router = new Router({methods: ['preRender', 'postRender']});

.route

Create a new Route for the given path. Each route contains a separate middleware stack.

Params

• path {String}
• returns {Object} Route: for chaining

Example

var router = new Router();
router.route('/foo')
  .all(function(file, next) {
    file.contents = new Buffer('foo');
    next();
  });

.method

Add additional methods to the current router instance.

Params

• methods {String|Array}: New methods to add to the router.
• returns {Object}: the router to enable chaining

Example

var router = new Router();
router.method('post');
router.post('.hbs', function(file, next) {
  next();
});

.handler

Add a middleware handler method to the instance.

Params

• method {String}: The name of the method to add
• returns {Object}: Returns the instance for chaining

Example

router.handler('before');
router.handler('after');

.handlers

Add an array of middleware handler methods to the instance.

Params

• methods {Array}: The method names to add
• returns {Object}: Returns the instance for chaining

Example

router.handlers(['before', 'after']);

.handle

Dispatch a file into the router.

Params

• file {Object}
• callback {Function}
• returns {undefined}

Example

router.dispatch(file, function(err) {
  if (err) console.log(err);
});

.use

Use the given middleware function, with optional path, defaulting to /. The other difference is that route path is stripped and not visible to the handler function. The main effect of this feature is that mounted handlers can operate without any code changes regardless of the prefix pathname.

Params

• fn {Function}: Middleware function
• returns {Object}: Router instance for chaining

Example

var router = new Router();
router.use(function(file, next) {
  // do stuff to "file"
  next();
});

.param

Map the given param placeholder name(s) to the given callback.

Parameter mapping is used to provide pre-conditions to routes which use normalized placeholders. For example a :user_id parameter could automatically load a user's information from the database without any additional code, The callback uses the same signature as middleware, the only difference being that the value of the placeholder is passed, in this case the id

of the user. Once the next() function is invoked, just like middleware it will continue on to execute the route, or subsequent parameter functions.

Params

• name {String}: Paramter name
• fn {Function}
• returns {Object}: Router instance for chaining

Example

app.param('user_id', function(file, next, id) {
  User.find(id, function(err, user) {
    if (err) {
      return next(err);
    } else if (!user) {
      return next(new Error('failed to load user'));
    }
    file.user = user;
    next();
  });
});

Release history

v1.0.0

Breaking changes

• en-route no longer supports error middleware (middleware with three arguments). This was done to simplify debugging, eliminate code debt that makes en-route harder to maintain and improve, to make en-route and middleware run faster, and to make certain that errors are always passed to the final done function.

About

Related projects

• assemble: Get the rocks out of your socks! Assemble makes you fast at creating web projects… more | homepage
• gulp-routes: Add middleware to run for specified routes in your gulp pipeline. | homepage
• template: Render templates using any engine. Supports, layouts, pages, partials and custom template types. Use template… more | homepage
• verb: Documentation generator for GitHub projects. Verb is extremely powerful, easy to use, and is used… more | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Contributors

Building docs

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

$ npm install -g verbose/verb#dev verb-generate-readme && verb

Running tests

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

$ npm install && npm test

Author

Brian Woodward

• github/doowb
• twitter/jonschlinkert

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2017, Jon Schlinkert. Released under the MIT License.

This file was generated by verb-generate-readme, v0.6.0, on July 08, 2017.