Router for functional rendering UIs
sour is a standalone functional router that works in Node and the browser. It provides the state management and lifecycle hooks you'll use in your application. Sour is designed for composition. You should build your own application-specific routing layer that uses sour internally. Routing is handled by routington.
$ npm install --save sour
var Sour = require('sour')
var state = Sour()
console.log(state.path())
//=> /the/current/path
var hello = Sour.route(state, {
path: '/the/route/path',
render: function () {
return 'Hello world!'
}
})
Sour.beforeEnter(state, hello, function (params, callback) {
//=> I run before the "hello" route is rendered
callback(null)
})
Sour.watch(state)
//=> Observe path changes and update the active route
state(function (state) {
console.log(Sour.render(state))
})
Returns an observable representation of the state.
Type: string
Default: document.location.pathname
The initial path to use. In the browser, this defaults to the current page path. In Node, it defaults to ''
. Passing data.hash = true
will synchronize the path with location.hash
instead of location.pathname
.
Watches for path changes to update the active route. Returns an unwatch function.
Type: function
Arguments: none
An optional callback that will be called when the router is ready, meanin either:
- No matching route was found
- A match was located and the route transition was successful
Defines a new route, returning the route key that can later be referenced to create hooks or change routes.
Required
Type: string
A path string provided to routington.
Required
Type: function
The render function for the route.
Transitions the router to the specified route returned by Sour.route
.
Required
The router state.
Required
Type: object
A route returned from Sour.route
.
Required
Type: object
Parameters for the route. These are passed to any registered route hooks.
Type: function
Default: noop
Arguments: err
A callback that will be called after the transition completes. A route transition is complete when:
beforeLeave
hooks finishafterLeave
hooks finishbeforeEnter
hooks finish- the active route is updated
The afterEnter
hook for the destination route will be run after the transition completes.
Runs the render
function defined via Sour.route
for the active route and returns its result.
Required
Type: object
The current state of the router. If no active route is found, undefined
is returned.
A variadic set of arguments. These arguments are passed to your active render
function.
Hooks provide a way to add custom behavior that runs at different points in the routing lifecycle.
Enter and leave hooks run asynchronously when moving between valid routes. Each hook method returns an unlisten function that will unregister the hook.
The router state.
The route key object returned by Sour.route
. If no route is provided, the hook will run for every route.
Required
Type: function
Arguments: params, callback
A callback that will be called when the specified route is activated. Hooks are called in the order in which they were registered with the arguments params, callback
, where:
params
are path parameters defined by the path definition string.callback
: a function oferr
that can halt the route transition and must be called to continue route activation.
Required
Type: function
Arguments: {path}
Called when the current path does not match any routes. Returns an unlisten function.
Required
Type: function
Arguments: err
Called when any hook errors during a transition. Returns an unlisten function.
Given a route and its path params, return a string representing the route's path.
Required
Type: object
A route returned from Sour.route
Optional
Type: object
Params to match against the params in the path of the given route.
MIT © Ben Drucker