Noodles, Poodles and More!

    blue-router

    1.2.10 • Public • Published

    Blue Router

    Blue Router is router powered by Bluebird promises. Routing is process that determines which function will be executed on the fly. Decision depends on URI. For example: context.uri = '/user/register' will execute user registration function.

    Blue Router can be used in NodeJS HTTP server, TCP server, UDP server, Redis PUB/SUB, browser side ...etc.

    It's really universal and very fast.

    Installation

    npm install blue-router --save

    Dependencies

    The only dependency is Bluebird package. The advantage is in rich Bluebird API methods.

    const Promise = require('bluebird') //NodeJS or Browserify
    <script src="bluebird.min.js"></script> //Browser (client side)

    Integration

    //NodeJS or browserify (client side)
    const br = require('blue-router');
     
    //Browser (client side)
    <script src="bluebird.min.js"></script>
    <script src="/blue-router/index.js"></script>

    Methods

    • br(context).when(route) when 'context.uri' is matched against 'route' function in then() is executed
    • br(context).when(route1).redirect(route2) will redirect from 'route1' to 'route2'
    • br(context).notfound() 404 not found. Always put this method after all when() methods.
    • br(context).do() will be executed on each request

    All methods when(), redirect(), notfound(), do() return bluebird promise and after that you can use any of bluebird methods (then, spread, catch, delay ...)

    Slashes

    Trailing and ending slashes can be ignored so all of these URIs will be valid:

    /cli/register/john/23/true?x=123&y=abc&z=false
    /cli/register/john/23/true/?x=123&y=abc&z=false
    cli/register/john/23/true?x=123&y=abc&z=false
    cli/register/john/23/true/?x=123&y=abc&z=false
    

    Case Insensitive URIs

    URIs are case insensitive so all of these URIs will work:

    /register/john
    /Register/John
    /REGISTER/John

    Regular Expressions in route definition

    RegExp syntax is allowed in route definition.

    • . any character
    • * match 0 or more times
    • + match 1 or more times
    • ? match 0 or 1 time
    • | alternative
    • () grouping
    • [] set of chars
    • {m, n} repetition modifier (at least m but at most n)
    • \\w word
    • \\W non-word
    • \\d digit
    • \\D non-digit
    • ... and others
    br(context).when('/cli/get.+/[0-9]+').then(require('./cli/match_exact.js').getname).catch(errLog);
    br(context).when('/cli/shop(s)?/w{3}/:name/:year').then(require('./cli/match_param.js').shop).catch(errLog);
    br(context).when('/cli/shop/\\d+/:name/:year/:color').then(require('./cli/match_param.js').shop).catch(errLog);
    

    Parameters

    Variables in Blue Router are named simmilar to ExpressJS:

    • ctx.req.body for example context.req.body = {name: 'Peter'}
    • ctx.req.params for example /user/:id and /user/23 will return {id: 23}
    • ctx.req.query for example ?username=john&password=as1234 will return {username: 'john', password: 'as1234'}

    Chaining

    Use Bluebird then() to serially connect functions. This will make your code more readable and error handling easier. br(context).when(route).then(func11).then(func12).then(func13).catch(logErr)

    Error 404: Not Found

    Method notfound() must be placed after all when() methods.

    br(context).notfound().then(function (ctx) {console.log('Error 404: ROUTE ' + ctx.uri + ' NOT FOUND');}).catch(errLog)

    Debugging

    To activate Blue Router debugging set context.opts.debug: true

    Usage

    NodeJS server (HTTP, TCP, UDP, Redis channel)

    /*
     * TCP server example
     */
    const br = require('blue-router');
     
    //cmd value can be changed dynamically by TCP server
    var input = {cmd: '/register/john/45', data: {company: 'Cloud LLC', employers: 257}};
     
    var context = {
        uri: input.cmd,
        req: {
            body: input.data
        },
        res: {
            socket: socket
        }
    };
     
    // br(context).when() is Bluebird promise
    // 'ctx' is 'context' object with added req.query and req.params properties
    br(context).when('/register/:name/:age')
        .then(function (ctx) {
            console.log('ctx.req.query: ', ctx.req.query); //undefined
            console.log('ctx.req.params: ', ctx.req.params); //{name: 'John', age: 45}
            console.log('ctx.req.body: ', ctx.req.body); //{company: 'Cloud LLC', employers: 257}
     
            ctx.res.socket.write('Message to TCP client.');
        })
        .catch(function (err) {
            console.error(err);
        });
     

    Explanation: br(context).when() makes Bluebird promise and after that you can use all bluebird's API methods. URI 'context.uri' can be fetched dynamically from browser's URL, HTTP/TCP/UDP server request or from command line (CLI).

    Examples

    const br = require('blue-router');
    var errLog = require('./cli/errLog.js');
     
    //input from console - cli input ($node cli.js {"cmd":"/cli/register/john/23/true","data":{}})
    var input = process.argv[2];
     
    //converting a string to object
    try {
        input = JSON.parse(input); //convert string to object
    } catch (err) {
        console.log(err.stack);
    }
     
    //context object which define router behaviour
    var context = {
        uri: input.cmd,
        req: {
            body: input.data
        },
        res: {
            cl: console.log
        },
        opts: {
            debug: false
        }
    };
     
     
     
     
    ///////////// R O U T E S /////////////////////
     
     
    ///// EXACT MATCH
     
    //node cli.js '{"cmd": "/cli/list", "data": [{"id": 12}, {"id": 13}, {"id": 14}]}'  --> run this in Linux terminal
    //node cli.js '{"cmd": "/cli/list/", "data": [{"id": 12}, {"id": 13}, {"id": 14}]}'
    //node cli.js '{"cmd": "cli/list", "data": [{"id": 12}, {"id": 13}, {"id": 14}]}'
    //node cli.js '{"cmd": "cli/list/", "data": [{"id": 12}, {"id": 13}, {"id": 14}]}'
    br(context).when('/cli/list').then(require('./cli/match_exact.js').list).catch(errLog);
     
    /// redirection
    //node cli.js '{"cmd": "/cli/listall", "data": [{"id": 12}, {"id": 13}, {"id": 14}]}'
    //node cli.js '{"cmd": "/cli/listall/", "data": [{"id": 12}, {"id": 13}, {"id": 14}]}'
    //node cli.js '{"cmd": "cli/listall", "data": [{"id": 12}, {"id": 13}, {"id": 14}]}'
    //node cli.js '{"cmd": "cli/listall/", "data": [{"id": 12}, {"id": 13}, {"id": 14}]}'
    br(context).when('/cli/listall').redirect('/cli/list').then(require('./cli/match_exact.js').list).catch(errLog);
     
    //node cli.js '{"cmd": "/cli/getname/firstname", "data": {"name": "Sasa"}}'
    //node cli.js '{"cmd": "/cli/getname/firstname/", "data": {"name": "Sasa"}}'
    //node cli.js '{"cmd": "cli/getname/firstname", "data": {"name": "Sasa"}}'
    //node cli.js '{"cmd": "cli/getname/firstname/", "data": {"name": "Sasa"}}'
    br(context).when('/cli/getname/firstname/').then(require('./cli/match_exact.js').getname).catch(errLog);
     
     
    ////examples with uri query string
    //node cli.js '{"cmd": "/cli/login?username=peter&password=pan", "data": {}}'
    //node cli.js '{"cmd": "/cli/login/?username=peter&password=pan", "data": {}}'
    //node cli.js '{"cmd": "cli/login?username=peter&password=pan", "data": {}}'
    //node cli.js '{"cmd": "cli/login/?username=peter&password=pan", "data": {}}'
    br(context).when('/cli/login').then(require('./cli/match_exact.js').login).catch(errLog);
     
     
    ////examples with regular expression
    //node cli.js '{"cmd": "/cli/getnames/12345", "data": {"name": "McCloud"}}'
    //node cli.js '{"cmd": "/cli/getnames/12345/", "data": {"name": "McCloud"}}'
    //node cli.js '{"cmd": "cli/getnames/12345", "data": {"name": "McCloud"}}'
    //node cli.js '{"cmd": "cli/getnames/12345/", "data": {"name": "McCloud"}}'
    //node cli.js '{"cmd": "/cli/getname/12/", "data": {"name": "McCloud"}}'
    br(context).when('/cli/get.+/[0-9]+').then(require('./cli/match_exact.js').getname).catch(errLog);
     
     
     
     
     
     
    ///// PARAM MATCH
     
    //node cli.js '{"cmd": "/cli/users/55", "data": [{"id": 33, "name": "Peter"}, {"id": 55, "name": "Dean"}]}'
    //node cli.js '{"cmd": "/cli/users/55/", "data": [{"id": 33, "name": "Peter"}, {"id": 55, "name": "Dean"}]}'
    //node cli.js '{"cmd": "cli/users/55", "data": [{"id": 33, "name": "Peter"}, {"id": 55, "name": "Dean"}]}'
    //node cli.js '{"cmd": "cli/users/55/", "data": [{"id": 33, "name": "Peter"}, {"id": 55, "name": "Dean"}]}'
    br(context).when('/cli/users/:id').then(require('./cli/match_param.js').get_user_by_id).catch(errLog);
     
    //node cli.js '{"cmd": "/cli/register/john/23/true", "data": {"nick": "johnny"}}'
    //node cli.js '{"cmd": "/cli/register/john/23/true/", "data": {"nick": "johnny"}}'
    //node cli.js '{"cmd": "cli/register/john/23/true", "data": {"nick": "johnny"}}'
    //node cli.js '{"cmd": "cli/register/john/23/true/", "data": {"nick": "johnny"}}'
    //
    //examples with uri query string
    //node cli.js '{"cmd": "/cli/register/john/23/true?x=123&y=abc&z=false", "data": {"nick": "johnny"}}'
    //node cli.js '{"cmd": "/cli/register/john/23/true/?x=123&y=abc&z=false", "data": {"nick": "johnny"}}'
    //node cli.js '{"cmd": "cli/register/john/23/true?x=123&y=abc&z=false", "data": {"nick": "johnny"}}'
    //node cli.js '{"cmd": "cli/register/john/23/true/?x=123&y=abc&z=false", "data": {"nick": "johnny"}}'
    br(context).when('/cli/register/:name/:year/:employed').then(require('./cli/match_param.js').register).catch(errLog);
     
     
    ///examples with regular expression
     
    //node cli.js '{"cmd": "/cli/shops/www/CloudShop/1971", "data": {}}'
    //node cli.js '{"cmd": "/cli/shop/www/CloudShop/1971", "data": {}}'
    br(context).when('/cli/shop(s)?/w{3}/:name/:year').then(require('./cli/match_param.js').shop).catch(errLog);
     
    //\\d+ replaces one or more digits (integer numbers)
    //node cli.js '{"cmd": "/cli/shop/5/BetaShop/1978/red", "data": {}}'
    //node cli.js '{"cmd": "/cli/shop/567/BetaShop/1978/red", "data": {}}'
    br(context).when('/cli/shop/\\d+/:name/:year/:color').then(require('./cli/match_param.js').shop).catch(errLog);
     
     
     
     
     
    ///// NO MATCH (bad uri - Error 404)
     
    //node cli.js '{"cmd": "", "data": {}}'
    //node cli.js '{"cmd": "/", "data": {}}'
    //node cli.js '{"cmd": "/cli", "data": {}}'
    //node cli.js '{"cmd": "/cli/", "data": {}}'
    //node cli.js '{"cmd": "/cli/lis", "data": {}}'
    //node cli.js '{"cmd": "/cli/lista", "data": {}}'
    //node cli.js '{"cmd": "/cli/list/bad", "data": {}}'
    br(context).notfound().then(require('./cli/notfound.js')).catch(errLog); //put this after all when() methods
     
     
     
    //always will be executed on each URI
    br(context).do().then(require('./cli/do.js')).catch(errLog);

    Error Handling

    ========= errLog.js ==========
    ==============================
    // print only messages where err.message is not empty string
    module.exports = (err) => {
      if (!!err && !!err.message) {
        console.log('errLog: ', err.stack);
      }
    };
    

    Licence

    Copyright (c) 2017 Saša Mikodanić Licensed under MIT .

    Install

    npm i blue-router

    DownloadsWeekly Downloads

    2

    Version

    1.2.10

    License

    MIT

    Unpacked Size

    32.2 kB

    Total Files

    11

    Last publish

    Collaborators

    • smikodanic