Rotunda is a modern promise-based isomorphic routing library for Node.js and the browser inspired by the express framework and Django.
Install
Note: Rotunda uses language features that were introduced in ES2015 (ES6). The code has been converted to ES5 syntax using Babel but expects certain globals like Promise
and Map
that may not be available in older JavaScript environments. If you plan to use Rotunda in older browsers or older versions of Node.js you should use a polyfill/shim library like core-js.
With NPM
npm install rotunda
From source
git clone https://github.com/foss-haas/rotunda.gitcd rotundanpm installnpm run dist
In order to run the automated type checks for development, you will need to have flow installed and available from the project folder. If flow is not available, the type checks will be skipped temporarily.
API
new Router
Creates a Router
instance.
Arguments
-
caseInsensitive: boolean (default:
false
)If enabled, routes and paths will be converted to lower case, emulating the behaviour of case-insensitive file systems. Parameter names are not affected and are always case-sensitive.
Examples
;let router = ;let caselessRouter = true; // ES5 equivalent: var Router = Router;var router = ;var caselessRouter = true;
Router#param
Defines a named parameter on the router. Returns the router instance itself to allow chaining.
Arguments
-
name: string
The parameter will be invoked by every route that matches its name. Parameter names are case-sensitive. If a route uses a parameter that was not defined, the value will be passed through to the route handler directly.
-
resolve: function (optional)
Optionally the parameter can be assigned a resolve function that should return a promise for the parameter's value. The function will be passed the current value of the parameter as well as an object mapping the names of other parameters for the route to promises for their values.
If the promise is rejected with a reason, the routing will be aborted and fail with the given reason. If the promise is rejected without a reason, the route will fail to match and the routing will continue with the next match or fail with an error indicating that the route could not be resolved if there are no other matches.
Otherwise the result the result of the promise will be passed to any parameters that depend on it. Once all parameters have resolved successfully, their values will be passed to the route handler matching the route.
Note that it is possible to create a dead-lock if two parameters on the same route depend on each other's values to resolve.
-
schema: any (optional)
Optionally the parameter can be assigned a schema to validate any matching values against. The schema can be a joi schema or any value that has a method named
validate
. The method must accept a string value as input and return an object with two properties:value
anderror
.A truthy
error
indicates that the schema validation has failed and will result in the router skipping the matched route and continuing with the next match or failing with an error indicating the route could not be resolved.If the value of
error
is non-truthy, the value of thevalue
property will be used as the value of the parameter for the resolve function or the current route handler if the parameter has no resolve function.
If you only want to assign a schema to the parameter, you can pass the schema as the second argument.
If neither resolve nor schema are specified, the method has no effect.
If both are defined, the value will first be validated against the schema and then passed to the resolve function.
Examples
// Let's use joi for our schemas; // Define a parameter that resolves immediatelyrouter; // Define a parameter that resolves asynchronouslyrouter; // Define a parameter that depends on another parameterrouter; // Define a parameter with only a resolve functionrouter; // Define a parameter with only a schemarouter; // This has no effectrouter;
Router#route
Defines a route on the router. Returns the router instance itself to allow chaining.
Arguments
-
route: string
The absolute path of the route to define. Leading, trailing and redundant slashes will be ignored. Parameters are segments starting with a colon followed by the parameter name, e.g.
/users/:userId/profile
contains the parameter "userId".If any of the parameters have been defined on the router, their values will be validated and resolved before being passed to the handler. If any parameter fails to validate or resolve, the route handler will be skipped.
Note that for any segment of the route any static matches will be preferred to parameters, e.g. for the path
/pages/manual
the route/pages/:pageName
(static, parameter) will be preferred over the route/:category/manual
(parameter, static) which in turn will be preferred over/:category/:section
(parameter, parameter). -
handler: function
A function that returns a promise for the result of the given route. If the route contains any parameters, the handler will be passed an object mapping the names of the parameters to their resolved values.
If the promise returned by the handler is rejected with an error, the routing will abort and fail with that error. If the promise is rejected without an error, the next route handler matching the route will be invoked. If no other handlers match the route, the routing will fail with an error indicating that the route could not be resolved.
If the handler returns any other value than a promise, it will be wrapped in a resolved promise automatically.
-
name: string (optional)
The route can optionally be registered using a given name. Only named routes can be reversed (see below).
Examples
router; // Non-promise return values will be wrapped automaticallyrouter; // Parameters will have been resolved before the route handler is invokedrouter;router; // The raw values of parameters are available, toorouter;
Router#reverse
Returns a path that would resolve to the route name and parameters.
Arguments
-
name: string
The name of a named route registered with this router. If no route with the given name has been registered with the router, an error will be thrown.
-
parameters: Object (optional)
An object mapping parameter names to parameter values. Any parameters not used by the route will be ignored. If any parameters are missing, an error will be thrown.
Parameter values should be strings or values with string representations that are supported by the parameter definitions.
Examples
router;router; // You can always pass in parameter values as stringsrouter;// -> "/articles/23" // You can also pass in non-string valuesrouter;// -> "/articles/42" // But be wary of passing in arbitrary objectsrouter;// -> "/articles/[object Object]" // You always have to pass in all parametersrouter;// -> Error: Failed to reverse article_detail. Missing param: articleId // Extra parameters will be ignoredrouter;// -> "/articles/23"
Router#resolve
Attempts to resolve a path. Returns a promise that is rejected if the path does not successfully match any routes or resolved with the matching route handler's result.
Arguments
-
path: string
The absolute path to resolve.
-
context: any (optional)
An additional argument that will be passed to the matching parameters' resolve functions and the route handler.
Examples
router;router; router;// -> This is the article page for Article #23 // Paths that don't match anything are rejectedrouter;// -> Error: 404 // Paths that match a route that is rejected with a reason are rejectedrouter;router;// -> Error: Out of order // Parameters that are rejected with a reason also result in rejectionrouter;router;router;// -> Error: Server error // Contexts can be used to pass run-time dependencies to a routerouter;router;router;
License
The MIT/Expat license. For more information, see http://foss-haas.mit-license.org/ or the accompanying LICENSE file.