node package manager
Stop writing boring code. Discover, share, and reuse within your team. Create a free org »

koa-trail

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

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