Node's Pastoral Musicians

    rouxter

    0.1.0 • Public • Published

    rouxter

    Build Status NPM version

    A simple URL router for the client or server. Supports case sensitivity, route value constraints and wildcards.

    Smallish (~1.3KB gzipped) with no dependencies.

    rouxter is pronounced ROOTER. Yelling is optional. roux was already taken and I'm not very clever.

    Installation

    Server

    npm install rouxter

    Client

    The client version is built using browserify. It is located at dist/rouxter.js. If you want to minify it, clone the repo and run npm run minify, or use your own favored flavor of minification.

    <script src="/path/to/rouxter.js"></script>

    Usage

    Note that on the client, there is a global Rouxter variable attached to the window.

    const Route = require('rouxter').Route; //window.Rouxter.Route on the client
     
    //configuring routes
    const myRoutes = {
        home: new Route('home', '/'),
        about: new Route('about', '/about'),
        post: new Route('post', '/article/:id', {
            constraints: {
                id: /^\d{1,5}$/
            }
        }),
        api: new Route('api', '/api/v:version/:method*.:format', {
            constraints: {
                version: /^[12]$/,
                format: /^(xml|json|html|txt)$/
            },
            coercions: {
                version: 'int'
            }
        })
    };
     
    //using routes
    const match = myRoutes.api.getMatch('/api/v2/users/all.json');
    if (match) {
        console.log(match);
    /*
    { version: { position: 0, name: 'version', value: 2 },
      method: { position: 1, name: 'method', value: 'users/all' },
      format: { position: 2, name: 'format', value: 'json' } }    
     */
    }

    Variables

    Route variables are created by prefixing the variable name with a colon. They will be keyed by name with their value in the return value of getMatch.

    Wildcards

    By default, forward slashes act as delimiters for variables. So the URL /foo/:bar/baz will match /foo/hello/baz but not /foo/hello/world/baz.

    To match things with a forward slash, append a * to the variable name: /foo/:bar*/baz will now match both /foo/hello/baz and /foo/hello/world/baz.

    Other Route Parsing Details

    • A regular expression is generated from the URL you provide, and those regular expressions are always greedy. For example, /foo/:bar*/baz/bat will set bar to baz/bat/baz/bat if you pass it /foo/bar/baz/bat/baz/bat/baz/bat.
    • All route URLs are anchored at the start and end: /foo/bar will match /foo/bar but not /foo/bar/baz or /hello/foo/bar
    • To match a literal : or a literal * in a route, prefix it with a backslash \
    • Variable names can be any combination of alphanumeric characters and the underscore
    • The route URL must start with a forward slash

    Options

    caseInsensitive

    const myRoute = new Route('/foo/:bar', { 
        caseInsensitive: true
    });

    This makes the regular expression match case insensitive. So the above will match both /foo/bar and /FoO/BAr.

    constraints

    const myRoute = new Route('/foo/:bar', { 
        constraints: {
            bar: /^\d+$/
        }
    });

    This option enforces constrains the route values. In the above example, the route parameter bar must be an integer. So /foo/123 would match but /foo/bar would not.

    Constraints can be regular expressions or a function, or an arbitrarily nested array of both. If you use an array, ALL constraints within the array must be satisfied for the route to match (this is helpful for reusing constraints in multiple routes).

    More complicated example that requires bar to be a positive integer less than 100:

    const myRoute = new Route('/foo/:bar', { 
        constraints: {
            bar: [
                /^\d+$/,
                function(param) {
                    var int = parseInt(param.value);
                    return int > 0 && int < 100;
                }
            ]
        }
    });

    coercions

    const myRoute = new Route('/foo/:bar', { 
        coercions: {
            bar: 'int'
        }
    });

    This option coerces the route parameter value into something else. The above example would run parseInt on the value of bar. So if you match /foo/3 you would get 3 instead of "3" for the value of bar.

    Possible builtin coercions are int, boolean and number. Alternatively, you can also provide a function to perform a custom coercion. For example:

    const myRoute = new Route('/foo/:bar', {
        constraints: {
            bar: /^\d+$/
        },
        coercions: {
            bar: function(value, params) {
                var bar = parseInt(value);
                if (bar < 0) {
                    return 'negative';
                }
                if (bar < 100) {
                    return 'small';
                }
                
                return 'large';
            }
        }
    });

    This will coerce bar into either "negative", "small" or "large" depending on its integral value.

    Development

    • Run tests with npm test
    • Build client library with npm run compile
    • Minify client library with npm run minify
    • Build and minify the client library with npm run build

    Keywords

    Install

    npm i rouxter

    DownloadsWeekly Downloads

    0

    Version

    0.1.0

    License

    MIT

    Last publish

    Collaborators

    • tmont