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.

Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your :heart: and support.

Install

Install with npm:

$ npm install --save en-route

How it works

en-route is a different, but similar concept to routes you might be familiar with, like express routes. The general idea is, you can:

Use middleware to modify file objects
Define routes, to determine whether or not a middleware function should run on a given file.
Define handlers for running specific middleware at specific points in your application or build.

See the examples folder for a number of different examples of how en-route works.

Usage

const Router = require('en-route');
const router = new Router();

API

Router

Create a new Router with the given options.

Params

options {object}

Example

// initialize a router with handler methdods
const router = new Router({ handlers: ['preWrite', 'postWrite'] });

.handlers

Register one or more middleware handler methods. Handler methods may also be added by passing an array of handler names to the constructor on the handlers option.

Params

methods {string}: Method names
options {object}
returns {object}: Returns the instance for chaining.

Example

router.handlers(['onLoad', 'preRender']);

.handler

Params

method {string}: Method name
options {object}
returns {object}: Returns the instance for chaining.

Example

router.handler('onLoad');

.route

Create a new router instance with all handler methods bound to the given pattern.

Params

pattern {string}
options {object}: Options to pass to new router.
returns {object}: Returns a new router instance with handler methods bound to the given pattern.

Example

const router = new Router({ handlers: ['before', 'after'] });
const file = { path: '/foo', content: '' };

router.route('/foo')
  .before(function(file) {
    file.content += 'foo';
  })
  .after(function(file) {
    file.content += 'bar';
  });

router.handle(file)
  .then(() => {
    assert.equal(file.content, 'foobar');
  });

.handle

Run a middleware methods on the given file.

Params

method {string|file}: The handler method to call on file. If the first argument is a file object, all handlers will be called on the file.
file {object}: File object
returns {Promise}

Example

// run a specific method
router.handle('onLoad', file)
  .then(file => console.log('File:', file))
  .catch(console.error);

// run multiple methods
router.handle('onLoad', file)
  .then(file => router.handle('preRender', file))
  .catch(console.error);

// run all methods
router.handle(file)
  .then(file => console.log('File:', file))
  .catch(console.error);

.all

Runs all handler methods on the given file, in series.

Params

file {object}: File object
returns {Promise}

Example

router.all(file => {
  file.data.title = 'Home';
});

.mixin

Mix router methods onto the given object.

Params

target {object}
returns {undefined}

Example

const router = new Router();
const obj = {};
router.handlers(['before', 'after']);
router.mixin(obj);
console.log(obj.before) //=> [function]

Route

Create a new Route with the given pattern, handler functions and options.

Params

pattern {string|regex}
fns {function|array}: One or more middleware functions.
options {object}

Example

const fn = file => file.count++;
const Route = require('en-route').Route;
const route = new Route('/(.*)', [fn, fn, fn]);
const file = { path: '/foo', count: 0 };

route.handle(file)
  .then(file => {
    console.log(file.count); // 3
  });

.all

Params

fns {function|array}: Handler function or array of handler functions.
returns {object}: Route instance for chaining

Example

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

.handle

Run a middleware stack on the given file.

Params

file {object}: File object
returns {object}: Callback that exposes err and file
returns {object}: Returns a promise with the file object.

Example

route.handle(file)
  .then(file => console.log('File:', file))
  .catch(console.error);

.layer

Push a layer onto the stack for a middleware functions.

Params

pattern {string|regex}: The pattern to use for matching files to determin if they should be handled.
fn {function|array}: Middleware functions
returns {object}: Route instance for chaining

Example

route.layer(/foo/, file => {
  // do stuff to file
  file.layout = 'default';
});

.layers

Push a layer onto the stack for one or more middleware functions.

Params

pattern {string|regex}
fns {function|array}: One or more middleware functions
returns {object}: Route instance for chaining

Example

route.layers(/foo/, function);
route.layers(/bar/, [function, function]);

Layer

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

Params

pattern {string}
handler {function}
options {object}

Example

const layer = new Layer('/', file => {
  // do stuff to file
  file.extname = '.html';
});

.handle

Calls the layer handler on the given file if the file.path matches the layer pattern.

Params

file {object}: File object
returns {Promise}

Example

layer.handle(file)
  .then(() => console.log('Done:', file))
  .then(console.error)

.match

Attempts to match a file path with the layer pattern. If the path matches, an object of params is returned (see path-to-regexp for details), otherwise null is returned.

Params

filepath {string}
returns {object|null}

Example

const layer = new Layer('/:name');
console.log(layer.match('/foo')) //=> { name: 'foo' }

Release history

v2.0.0

Breaking changes

en-route was completely refactored from the ground-up.

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

<summary>Contributing</summary>

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

<summary>Running Tests</summary>

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

<summary>Building docs</summary>

(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

Related projects

You might also be interested in these projects:

assemble: Get the rocks out of your socks! Assemble makes you fast at creating web projects… more | homepage
base-routes: Plugin for adding routes support to your base application. Requires templates support to work. | homepage
base: Framework for rapidly creating high quality, server-side node.js applications, using plugins like building blocks | homepage
gulp-routes: Add middleware to run for specified routes in your gulp pipeline. | homepage

Contributors

Commits	Contributor
101	jonschlinkert
35	doowb

Author

Brian Woodward

Jon Schlinkert

License

This file was generated by verb-generate-readme, v0.8.0, on November 11, 2018.

Current Tags

0.3.2 ... beta (10 years ago)
3.2.0 ... latest (6 years ago)

en-route

Install

How it works

Usage

API

Release history

v2.0.0

v1.0.0

About

Related projects

Contributors

Author

License

Current Tags

25 Versions