Part of the Overlook framework.
Plugin which delegates handling of requests either to this route, or children, based on matching the request path.
Similar to express's routing.
Extend routes with this plugin and then define the "path part" for each route via [PATH_PART]
property or [GET_PATH_PART]()
method. If neither is defined, .name
is taken as path part.
Each route's path is its parent's path + the new path part. /user
+ login
-> /user/login
.
const Route = require('@overlook/route');
const pathPlugin = require('@overlook/plugin-path');
const { PATH_PART } = pathPlugin;
const PathRoute = Route.extend( pathPlugin );
// URL: /
const root = new PathRoute();
// URL: /bands
const bands = new PathRoute( { name: 'bands' } );
root.attachChild( bands );
// URL: /bands/:bandId
const band = new PathRoute( {
name: 'band',
[PATH_PART]: ':bandId'
} );
bands.attachChild( band );
// URL: /bands/:bandId/albums
const albums = new PathRoute( { name: 'albums' } );
band.attachChild( albums );
// URL: /bands/:bandId/albums/:albumId
const album = new PathRoute( {
name: 'album',
[PATH_PART]: ':albumId'
} );
albums.attachChild( album );
A request for http://example.com/bands/the-cure/albums/wish
will be routed to the album
route.
Routes can be added in any order, and the plugin will order them by priority automatically. Static matches (e.g. bands
) take priority over parameterized matches (e.g. :id
). The lowest priority is wildcard matches (*
).
To handle requests, define/extend the [HANDLE_ROUTE]()
method.
If a route matches exactly, [HANDLE_ROUTE]()
will be called with the request. If it only matches in part, the request will be forwarded on to the route's children to match.
[HANDLE_ROUTE]
symbol is re-exported from @overlook/plugin-match (which this plugin extends).
const Route = require('@overlook/route');
const pathPlugin = require('@overlook/plugin-path');
const { GET_PATH_PART, HANDLE_ROUTE } = pathPlugin;
const PathRoute = Route.extend( pathPlugin );
class BandsRoute extends PathRoute {
[GET_PATH_PART]() {
return 'bands';
}
[HANDLE_ROUTE]( req ) {
// Handle the request
// `req` = request object
}
}
For parameterized routes (i.e. :something
), the parameters can be accessed as req[PARAMS]
.
const { GET_PATH_PART, PARAMS } = require('@overlook/plugin-path');
class BandRoute extends PathRoute {
[GET_PATH_PART]() {
return ':bandId';
}
[HANDLE_ROUTE]( req ) {
const params = req[PARAMS];
// If URL = '/bands/the-cure'
// params = { bandId: 'the-cure' }
}
}
For a wildcard match (i.e. match entire rest of path) use either:
[PATH_PART] = '*'
: Param will be called*
[PART_PATH] = '*something'
: Param will be calledsomething
This module follows semver. Breaking changes will only be made in major version updates.
All active NodeJS release lines are supported (v10+ at time of writing). After a release line of NodeJS reaches end of life according to Node's LTS schedule, support for that version of Node may be dropped at any time, and this will not be considered a breaking change. Dropping support for a Node version will be made in a minor version update (e.g. 1.2.0 to 1.3.0). If you are using a Node version which is approaching end of life, pin your dependency of this module to patch updates only using tilde (~
) e.g. ~1.2.3
to avoid breakages.
Use npm test
to run the tests. Use npm run cover
to check coverage.
See changelog.md
If you discover a bug, please raise an issue on Github. https://github.com/overlookjs/plugin-path/issues
Pull requests are very welcome. Please:
- ensure all tests pass before submitting PR
- add tests for new features
- document new functionality/API additions in README
- do not add an entry to Changelog (Changelog is created when cutting releases)