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}

License

MIT