file structure based router for micro/express

Installation

$ npm i micro-r

About

micro-r is a small and opinionated routing library utilizing file/folder of the application. Routes are not dynamic and are bound at runtime, rendering "Directory Traversal Attacks" not applicable.

Middlewares can be defined by use() or by dropping index.js files in the desired folders. These must export either a plain middleware function or an array of functions.

Functions

configure(object)

Provides the possibility to change the following defaults.

• ext: string extension of middleware files e.g..ts; default: .js
• entry: string name of middleware files e.g.middleware; default: index

on(method, path, handler)

Register custom handlers to specific paths.

• method: string one of: *, get, post, put, patch, delete, head, options
• path: string pathname to match
• handler: Function callback function receiving req and res as parameters

use(middleware)

Register a middleware function.

• middleware: Function e.g.(req, res, next) => next()

has(method, path)

Returns true of the requested route exists.

• method: string one of: *, get, post, put, patch, delete, head, options
• path: string pathname

chain(middlewares)

Transforms an array of middleware functions into a single middleware function.

• middlewares: Array<Function> similar to use() but with arrays

register(basepath, onDone)

Recursively register the given path and its subfolders.

• basepath: string path to folder
• onDone: Function optional; called if registration done

route(req, res)

Handle the incoming requests.

• req: IncomingMessage server request object
• res: ServerResponse server response object

listener

listener Instance exposes three functions to bind, unbind and emit events.

Events

Following Events are available:

• Ready if micro-r is done with register()
• Error if an uncatched error in middleware, route or register call occurred

on(event, handler)

Register an event handler.

• event: string name of the event
• handler: function event handler

off(event, handler)

Unregister an event handler.

• event: string name of the event
• handler: function event handler

emit(event, req, res, payload)

Emit an event with payload.

• event: string name of the event
• req: IncomingMessage server request object
• res: ServerResponse server response object
• payload: any any kind of data

Example

Following folder/file structure with default configuration

routes
|
├───api
|       index.js
|       get.js
|
├───photo
|   |   index.js
│   │   get.js
│   │   post.js
│   │   delete.js
│   │
│   └───vacation
|           index.js
│           get.js
│           post.js
│
└───user
        post.js

registers the following routes

• GET: example.com/api
• GET: example.com/photo
• POST: example.com/photo
• DELETE: example.com/photo
• GET: example.com/photo/vacation
• POST: example.com/photo/vacation
• POST: example.com/user

Vanilla

const {default: router, Event} = require('micro-r');
const {send} = require('micro');

const fallback = (req, res) => {
    send(res, '404', 'WOOPS');
};

const {on, use, chain, register, route, listener} = router(fallback);

listener.on(Event.READY, () => console.info('I\'m ready'));
listener.on(Event.ERROR, (req, res, error) => console.error(req, res, error));

register('./routes');

on('get', '/foo', async (req, res) => {
    send(res, 200);
});

const middlewares = [
    (req, res, next) => {
        res.data = [];
        next();
    },
    (req, res, next) => {
        res.data.push('foobar');
        next();
    },
];
 
on('get', '/custom', chain(middlewares)(async (req, res) => {
    // res.data === ['foobar']
    send(res, 200);
}));

module.exports = route;

Express

const {default: router, Event} = require('micro-r');
const express = require('express');

const app = express();

const fallback = (req, res) => {
    send(res, '404', 'WOOPS');
};

const {register, route, listener} = router(fallback);

register('./routes', () => console.info('I\'m ready'));

app.use(route);
app.listen(3000);

Licence

MIT License

Copyright (c) 2019 Oleg Kamlowski

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.