Router middleware for koa
- REST routing using
app.get
, app.put
, app.post
, etc. - Rails-like resource routing, with nested resources.
- Named parameters.
- Multiple route middleware.
- Multiple routers.
Install
koa-router is available using npm:
npm install koa-router
Usage
Require the router and mount the middleware:
var koa = require('koa')
, router = require('koa-router')
, app = koa();
app.use(router(app));
After the router has been initialized, you can register routes or resources:
app.get('/users/:id', function *(next) {
var user = yield User.findOne(this.params.id);
this.body = user;
});
app.resource('forums', require('./controllers/forums'));
You can use multiple routers and sets of routes by omitting the app
argument. For example, separate routers for two versions of an API:
var APIv1 = new Router();
var APIv2 = new Router();
APIv1.get('/sign-in', function *() {
});
APIv2.get('/sign-in', function *() {
});
app.use(mount('/v1', APIv1.middleware()));
app.use(mount('/v2', APIv2.middleware()));
app.verb(path, middleware, [middleware...])
Match URL patterns to callback functions or controller actions using app.verb()
,
where verb is one of the HTTP verbs such as app.get()
or app.post()
.
app.get('/', function *(next) {
this.body = 'Hello World!';
});
Route paths will be translated to regular expressions used to match requests.
Query strings will not be considered when matching requests.
Multiple route callbacks / middleware
Multiple middleware may be given:
app.get(
'/users/:id',
function *(next) {
this.user = yield User.findOne(this.params.id);
yield next;
},
function *(next) {
console.log(this.user);
}
);
Named parameters / Capture groups
Named route parameters are captured and added to ctx.params
. Capture groups
from regular expression routes are also added to ctx.params
, which is an
array.
app.get('/:category/:title', function *(next) {
console.log(this.params);
});
Regular expressions
Control route matching exactly by specifying a regular expression instead of
a path string when creating the route. For example, it might be useful to match
date formats for a blog, such as /blog/2013-09-04
:
app.get(/^\/blog\/\d{4}-\d{2}-\d{2}\/?$/i, function *(next) {
});
Multiple methods
You can map routes to multiple HTTP methods using app.map()
:
app.map(['GET', 'POST'], '/', function *(next) {
});
You can map to all methods use app.all()
:
app.all('/', function *(next) {
});
app.resource(path, actions)
Resource routing is provided by the app.resource()
method. app.resource()
registers routes for corresponding controller actions, and returns a
Resource
object that can be used to further nest resources.
var app = require('koa')()
, router = require('koa-router')(app);
app.use(router);
app.resource('users', {
index: function *(next) {
},
new: function *(next) {
},
create: function *(next) {
},
show: function *(next) {
},
edit: function *(next) {
},
update: function *(next) {
},
destroy: function *(next) {
}
});
Action mapping
Actions are then mapped accordingly:
GET /users -> index
GET /users/new -> new
POST /users -> create
GET /users/:user -> show
GET /users/:user/edit -> edit
PUT /users/:user -> update
DELETE /users/:user -> destroy
Top-level resource
Omit the resource name to specify a top-level resource:
app.resource(require('./frontpage'));
Top-level controller actions are mapped as follows:
GET / -> index
GET /new -> new
POST / -> create
GET /:id -> show
GET /:id/edit -> edit
PUT /:id -> update
DELETE /:id -> destroy
Nesting
Resources can be nested using resource.add()
:
var forums = app.resource('forums', require('./forum'));
var threads = app.resource('threads', require('./threads'));
forums.add(threads);
app.redirect(path, destination, [code])
Redirect path
to destination
URL with optional 30x status code
.
app.redirect('/login', 'sign-in');
This is equivalent to:
app.all('/login', function *() {
this.redirect('/sign-in');
this.status = 301;
});
Tests
Tests use mocha and can be run
with npm:
npm test
License
The MIT License (MIT)
Copyright (c) 2013 Alexander C. Mingoia
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.