koa-trail

Trail is a router for koa with the option to explicitly execute multiple routes on a single request (similar to express routing).

For example, assume we have an authenticate middleware function which should run on every /api/* route. Instead of:

// chain the authenticate on every route 
app.get('/api/users', authenticate, apiController.getUsers);
app.get('/api/profile/:userId', authenticate, apiController.getProfile);
app.get('/api/page/:pageId', authenticate, apiController.getPage);
app.put('/api/:contentId/like', authenticate, apiController.likeContent);

We can simply apply the authentication handler once on a wildcard route:

app.all('/api/*', authenticate);

// the above route will be called before of any of the below routes matching /api/*
// therefore, we don't need to explicitly chain it on each route.

app.get('/api/users', apiController.getUsers);
app.get('/api/profile/:userId', apiController.getProfile);
app.get('/api/page/:pageId', apiController.getPage);
app.put('/api/:contentId/like', apiController.likeContent);

This reduces chaining on individual routes, and may improve security since there is less likelihood of a developer forgetting to add important security middleware on certain routes.

This middleware is largely inspired by koa-router. The reason for building a new router is that they explicitly decided not to allow the route chaining behavior outlined above.

• Usage
  • Installation
  • Setup
  • Setup
  • Route Chaining
  • Named Routes
  • Route Parameters
  • Wildcard Routes
  • Router Methods
    • register
    • VERB
    • all
    • url
    • finally
• License

Usage

Installation

npm install koa-trail

Setup

var koa = require('koa');
var trail = require('koa-trail');

var app = koa();
app.use(trail(app));

//now we can attach routes
app.get('/users', function *(next) {
  // ...
});

app.post('/users', function *(next) {
  // ...
});

When app is passed as a parameter to trail, it creates a method on the app for every http method (get, post, put, delete, etc), plus app.all, app.register, and app.url. If you would prefer not to "pollute" the app object with these methods, you may initialize a router object without passing the app parameter.

var koa = require('koa');
var trail = require('koa-trail');

var app = koa();
var router = new trail();

// pass the router.handler object, not the router object itself
app.use(router.handler); 

// now attach routes to the router object instead of app
router.get('/users', function *(next) {
  // ...
});

router.post('/users', function *(next) {
  // ...
});

Route Chaining

Named Routes

Routes can be named which makes them

Route Parameters

Wildcard Routes

Router Methods

register

VERB

all

url

finally

License

MIT