phylum

Koa extension with focus on efficient routing and modern technologies.

Requirements

Please note that phylum requires nodejs >= 10 to support latest features such as named regexp groups for parsing route paths.

Installation

npm i phylum

Changelog

The changelog documents all major changes made between releases.

Quick Start

const Phylum = require('phylum');
 
// app works the same as a koa application expect of additional routing:
const app = new Phylum();
 
// Add handlers with routes:
app.get('/', ctx => {
    ctx.body = 'Hello World!';
});

API

class Phylum

A Phylum instance is a Koa application that works as documented here.
In addition to the koa api, a phylum instance exposes all routing functions as documented below.

const Phylum = require('phylum');
 
const app = new Phylum();

class Router

A Router instance is just routes requests and is not a Koa application itself.

const Koa = require('koa');
const {Router} = require('phylum');
 
const router = new Router();
 
const app = new Koa();
app.use(router.handler());

app/router.use([path, ][options, ]handler)

Register routed middleware or handler functions.

app.use('/foo', {rewrite: 1}, (ctx, next) => {
    // Do something.
});

• path <route> - The route path as explained below.
• options <object> - Route options as explained below.

app/router.METHOD([path, ][options, ]handler)

Register routed handler functions.
The handler is called only if the request method matches
the specified one and there is no unrouted rest path:

app.get('/foo', ctx => {
    ctx.body = 'Bar!';
});

• METHOD - One of the following: get post put head delete options
• path <route> - The route path as explained below.
• options <object> - Route options as explained below (without method option).

router.handler(options)

Get a function that handles a context using the router.
Useful for embedding the router into an existing koa application or another routing library.

app.use(router.handler());

• options <object> - An optional object with the following options:
  • cleanRestPath <any> - If truthy, the context's restPath property will be deleted before passing the context to the router and will be added again before calling the next function. This is useful for nesting the router into another routing library.
  • cleanParams <any> - If truthy, the context's params property will be deleted before passing the context to the router and will be added again before calling the next function.

Options

rewrite

If truthy, path and url will be rewritten to match the unrouted rest path.
Trailing slashes will be preserved.

app.use('/foo', {rewrite: 1}, ctx => {
    // Request paths will be rewritten:
    //  - /foo/bar  -> /bar
    //  - /foo/bar/ -> /bar/
});

method

If set, the handler is called only if the request method matches
the specified one and there is no unrouted rest path:

app.use('/foo', {method: 'get'}, ctx => {
    // The handler will be called for the following paths:
    //  - /foo
    //  - /foo/
});

Routes

Routes can be strings, regular expressions or a combination of both using array.
The following are valid routes:

'/foo/bar'
['foo', 'bar/']
['foo', /bar/]
[['/foo'], '/bar']

• Duplicate, leading and trailing slashes are ignored.
• Regular expressions are only matched against a single part of a path.

Route Parameters

Route parameters can be defined using named regular expression capturing groups:

app.get(['greet', /(?<name>.+)/], ctx => {
    // Parameters are exposed by the 'ctx.params' object:
    ctx.body = `Hello ${ctx.params.name}!`;
});

Rest Path

While routing, phylum keeps track of the rest path and stores it on the context so routers can be nested in each other. The rest path is an array containing unrouted path segments:

app.use('/foo', ctx => {
    // If the request path was '/foo/bar/123'
    ctx.restPath // -> ['bar', '123']
});

Contributing

Suggestions to improve this package are always welcome.
Feel free to file issues and to submit pull requests.

Tests

npm install
 
# Run linter & tests: 
npm test
# Run tests and watch for changes: 
npm run watch