lark-router

lark-router

Router for lark based on koa 2.0

Install

$ npm install --save lark-router

Get started

Lark-Router is a flexible and easy-to-use url router tool, compatible with native http apps, express apps and koa(v2) apps.

• http apps

const router = new LarkRouter();

router.get('/foo/bar', (req, res) => res.end("/foo/bra requested!"));
router.on('error', (error, req, res) => {
    res.statusCode = 500;
    res.end(error.message);
});

http.createServer(router.routes()).listen(3000);

• koa apps

const router = new LarkRouter();
const app    = new Koa();

router.get('/foo/bar', (ctx, next) => ctx.body = '/foo/bar requested!');
router.on('error', (error, ctx, next) => {
    ctx.statusCode = 500;
    ctx.body = error.message;
    return next();
});

app.use(router.routes()).listen(3000);

Params

See path-to-regexp. Params object is bind to the first argument of the app processor.

router.get('/:foo/:bar', (ctx, next) => { console.log(ctx.params); }); // ===> { foo: xxx, bar: xxx }
router.get(/^\/(\d+)\/(\w+)$/, (ctx, next) => { console.log(ctx.params); }); // ===> { 0: xxx, 1: xxx}

all, other, routed

Lark router has 3 special methods.

• all: match all requests

router.all('/foo/bar', handler);  // ===> response to GET/POST/DELETE/...  /foo/bar

• other: match all unmatched requests

router.other('*', response404notfound); // ===> response to GET/POST/DELETE/...  /foo/bar if no other route matched

• routed: match all matched requests

router.routed('/foo/bar', () => console.log('/foo/bar has been routed')); // ===> response to GET/POST/DELETE/...  /foo/bar if some routes matched

Nesting

You could nest routers together:

mainRouter.all('/api', apiRouter);

Note that Lark-Router uses a path param to pass the unmatched part of path. That param name can be configured, usually is subroutine, and a string '/:subroutine*' will be append to that expression automatically.

mainRouter.configure({
    'subroutine': 'sub',
    'nesting-path-auto-complete': false,
});

mainRouter.all('/api/:sub*', api); // equivalent to the example above.

Async processors

For async processors, return promises.

router.get('/', () => new Promise(...));
router.get('/foo', async () => { ... });

Loading files and directories to generate route rules

Use router.load(path) to load a file or a directory.

If the path is a file, it should export a function or an object.

• function The function accepts the router as parameter.

module.exports = router => {
    router.get('/foo/bar', (...args) => {...});
}

Or you can return a new one if you like, but this is not recommended since you may need to re-configure this sub-router, eg. setting a adapter for this router.

module.exports = () => {
    const router = new LarkRouter();
    router.get('/foo/bar', (...args) => {...});
    return router;
}

• Object If an object is exported, all the properties of the object with name in the router.methods should be a function and will be processed as router.route(key, value).

module.exports = {
    GET  (ctx, next) => {...}
    POST (ctx, next) => {...}
}

Some methods (eg. delete) are reserved words, so we recommend words capitalized or in upper case, like GET, Post

Loading directories with file name as param

You may still want to use routes like /:foo/:bar in loading directories model. We have provide an adapter to do this. router.adapter.parseFileName will parse all file/directory names(without extend name) in the loading process. We provid a default one:

/main.as.index.js              =>  /
/foo.as.param/bar.as.param.js  =>  /:foo/:bar
/foo/bar.as.asterisk.js        =>  /foo/:bar*