router-base

Base router for your JS framework or frameworkless app

It's abstract and knows nothing about http. It's just matches and generates urls.

How to include it in my app or framework?

Router supports:

1. node.js modules,
2. requirejs modules
3. and, of course, awesome ym modules.
4. You can just use the <script> tag also, RouterBase will export the global variable then.

You can install it with npm:

$ npm install router-base

or bower:

$ bower install router-base

How to use it?

Very basic example

At first, you need to create an instance:

var myRouter = new RouterBase({
 
    routes: myRoutes // routes config
 
});

Where routes config is an Array with objects, each object is a configuration for a route. For example:

var myRoutes = [{
    id: 'simplest_route',
    path: '/a/route'
}];
 
var myRouter = new RouterBase({
    routes: myRoutes
});
 
// You can generate routes by id:
myRouter.generate('simplest_route'); 
// returns '/a/route'
 
// You can find a route by path and method:
myRouter.match({path: '/a/route', method: 'GET'}); 
// returns {id: 'simplest_route', parameters: {}, definition: { id: 'simplest_route',
                                                                   path: '/a/route',
                                                                   defaults: {},
                                                                   requirements: {},
                                                                   host: undefined,
                                                                   methods: [ 'GET', 'POST', 'PUT', 'DELETE' ],
                                                                   schemes: [ 'http', 'https' ] } }
}
 
// You can get full info about a route by id:
myRouter.getRouteInfo('simplest_route');
// for answer see [tests](https://github.com/apsavin/router-base/blob/master/test/data/getRouteInfo-data.js#L4-L41)

You can use access to the definition if you want to set additional fields to the route. For example, you can mark route as secure specifying secure: true in the route config and then check this field like this:

var route = myRouter.match({path: '/a/route', method: 'GET'}); 
 
if (route && route.definition.secure) // do something
 

I will omit the definition field in the next examples.

Beautiful urls examples

You can use named parameters in paths of the routes.

var myRoutes = [{
    id: 'route_with_parameter_in_path',
    path: '/some/path/{parameter}'
}];
 
myRouter.generate('route_with_parameter_in_path'); 
// will throw an Error, because parameter is needed for the route
myRouter.generate('route_with_parameter_in_path', {parameter: 1}); 
// returns '/some/path/1'
myRouter.generate('route_with_parameter_in_path', {parameter: 'value'}); 
// returns '/some/path/value'
 
myRouter.match({path: '/some/path/', method: 'GET'}); 
// returns null
myRouter.match({path: '/some/path/to', method: 'GET'}); 
// returns {id: 'route_with_parameter_in_path', parameters: {parameter: 'to'}, definition: {...}}

Optional parameters in paths

var myRoutes = [{
    id: 'route_with_parameter_in_path',
    path: '/some/path/{parameter}',
    defaults: {parameter: 1}
}];
 
myRouter.generate('route_with_parameter_in_path'); 
// returns '/some/path'
myRouter.generate('route_with_parameter_in_path', {parameter: 1}); 
// returns '/some/path/1'
myRouter.generate('route_with_parameter_in_path', {parameter: 'value'}); 
// returns '/some/path/value'
 
myRouter.match({path: '/some/path', method: 'GET'}); 
// returns  {id: 'route_with_parameter_in_path', parameters: {parameter: 1}, definition: {...}}
myRouter.match({path: '/some/path/to', method: 'GET'}); 
// returns {id: 'route_with_parameter_in_path', parameters: {parameter: 'to'}, definition: {...}}

Restricted parameters in paths

var myRoutes = [{
    id: 'route_with_parameter_in_path',
    path: '/some/path/{parameter}',
    defaults: {parameter: 1},
    requirements: {parameter: '\\d+'}
}];
 
myRouter.generate('route_with_parameter_in_path'); 
// returns '/some/path'
myRouter.generate('route_with_parameter_in_path', {parameter: 1}); 
// returns '/some/path/1'
myRouter.generate('route_with_parameter_in_path', {parameter: 'value'}); 
// throws an Error, because parameter is not numeric
 
myRouter.match({path: '/some/path', method: 'GET'}); 
// returns {id: 'route_with_parameter_in_path', parameters: {parameter: 1}, definition: {...}}
myRouter.match({path: '/some/path/to', method: 'GET'}); 
// returns null

All possible routes parameters

1. id - String, required. You can use it to link a route to your controller.
2. path - String, required. Can include named parameters in {parameterName} form.
3. host - String, optional. Can include named parameters in {parameterName} form (For example, '{sub}.example.com').
4. defaults - Object, optional. Keys are parameters names, values are parameters default values.
5. requirements - Object, optional. You can use it to restrict parameters. Keys are parameters names, values are strings. Strings from values are for regular expressions, router uses it to test parameters.
6. methods - Array, optional. For example, ['GET'] to allow only GET methods.
7. schemes - Array, optional. For example, ['https'] to force https.

RouterBase parameters

1. routes - an Array of routes configs, the only required parameter
2. defaultMethods - what methods available for routes, ['GET', 'POST', 'PUT', 'DELETE'] by default
3. defaultSchemes - what schemes available for routes, ['http', 'https'] by default
4. symbols.parametersDelimiters. By default, . and / can be used as parameters delimiters in paths
5. symbols.parameterStart, default value is '{'
6. symbols.parameterMatcher, default value is '.*?'
7. symbols.parameterEnd, default value is '}'

Where is tests?

Of course, in test folder. Use npm test to run.