Briskly-router NPM

Briskly-Router

Route handling for Node with types!

Types???

See: Routing
Types annotations are allowed in route parameters to define more granular routes.
For example: Given the routes /users/{id: number} and /users/{id: string}
A request to /users/123 will only match the {id: number} route.
A request to /users/seikho will only match the {id: string} route.
Since we have no route that matches an array or object, /users/[1,2,3] will not match either route.

Building and Contributing

See CONTRIBUTING guide

Installation

npm install briskly-router --save

Basic Usage

Basic demo

import BR = require('briskly-router');

var router = new BR.Router({
    port: 2189,
    host: 'localhost'
});

router.route({
    method: 'GET',
    path: '/',
    handler: {
        file: 'front/index.html'
    }
});

router.route({
    method: 'GET',
    path: '/users/{id: number}',
    handler: (request, reply) => getUserById(request.params.id).then(reply)
});

router.start();

// some time later

router.stop();

Configuration

See connection(...)

Routing

A route is defined by its parts which are separated by a forward slash (/).
Routes do not need to be defined in order and will always use the most specific route An example route table:

/
/{...} -- A catch all route that will match where everything else does not
/scripts/{...} -- Will match /scripts/[anything here]/[and here...]/so on..
/users/{id: number} -- Will match /users/42
/users/{name: string} -- Will match /users/seikho
/users -- Will only /users

Allowed parts:

Literal: An exact string. E.g. /my-home
Mixed Exact values (prefix and suffix) with parameters. E.g.:
/prefix{param}suffix
/prefix{param: string}suffix
/prefix{param: number}suffix
Parameter:
{myparam}: E.g. /{myparams}
Typed Parameter:
string: /{someWord: string}
number: /{anumber: number}
array: /{myArray: array}
object: /{myObj: object}
any: {someParam: any}
Wildcard
Must be at the end of a route path
E.g.: /{...}
Another: /scripts/{...}

API

route

Adds a route to the route table See: Routing RouteOptions

function route(options: RouteOptions)

Examples

route({ method: 'get', path: '/scripts/{...}', handler: directory: { 'front/scripts' } });

route({ method: 'get', path: '/api/users', handler: (req, reply) => getUsers.then(reply) });

route({ method: 'get', path: '/api/user/{id: number}', handler: (req, reply) => getUser(req.params.id).then(reply) });

route({ method: 'get', path: '/api/user/{name: string}', handler: (req, reply) => getUserByName(req.params.name).then(reply) });

route({ method: 'get', path: '/', handler: { file: 'front/index.html' } });

Router

See: ServerOptions

class Router {
    constructor(options: ServerOptions);
    start(callback: (error?: any) => void): Promise<void>;
    stop(callback: () => void): Promise<void>;
    connection(options: ServerOptions): void;
    route(options: RouteOptions): void;
}

connection

See: ServerOptions
Set the listening port and/or host

function connection(options: ServerOptions): void;

start

Starts the web server listener.
This will parse briskly.json and use the port key

function start(callback: () => void): Promise<void>;

stop

Stops the web server listener.

function stop(callback: () => void): Promise<void>;

ServerOptions

interface ServerOptions {
    port?: number;
    host?: string;
}

RouteOptions

See: RouteHandler DirectoryHandler FileHandler

interface RouteOptions {
    method: string; // GET, POST, PUT, DELETE, etc...
    path: string;
    handler: RouteHandler|DirectoryHandler|FileHandler
}

RouteHandler

See: Response Reply

function(response: Response, reply: Reply)

DirectoryHandler

interface DirectoryHandler {
    // The base directory to append the request file path to
    directory: string;
}

FileHandler

interface FileHandler {
    // The relative path of the file
    file: string;
}

Response

The object provided to the RouteHandler function

interface Response {
    query?: any;
    body?: any;
    params?: any;
    path: string;
    wildcard?: string;
}

Reply

The function use to send a response to the client

interface Reply {
    (data: any, statusCode?: number)
    file: (filePath: string) => void;
}

TODOS

Convert codebase to ES6
~~Disallow ambiguous routes~~ DONE v0.7.0
Allow catch/error handlers
Provide a default catch handler
Provide specific catch folders for routes
Consider optional parameters
~~Restrict parameter names to valid JavaScript object names~~ DONE v0.6.0
~~Consider prefix and suffix values on route parameter parts. E.g.:~~ DONE v0.6.0
~~/scripts/{name: string}.js~~
~~/prefix-{param}-suffix~~
Create API for middleware
Add parameter name for wildcard. E.g. /{...myparam}