find-my-way
A crazy fast HTTP router, internally uses an highly performant Radix Tree (aka compact Prefix Tree), supports route params, wildcards, and it's framework independent.
If you want to see a benchmark comparison with the most commonly used routers, see here.
Do you need a real-world example that uses this router? Check out Fastify or Restify.
Install
npm i find-my-way --save
Usage
const http = require('http')
const router = require('find-my-way')()
router.on('GET', '/', (req, res, params) => {
res.end('{"message":"hello world"}')
})
const server = http.createServer((req, res) => {
router.lookup(req, res)
})
server.listen(3000, err => {
if (err) throw err
console.log('Server listening on: http://localhost:3000')
})
API
FindMyway([options])
Instance a new router.
You can pass a default route with the option defaultRoute
.
const router = require('find-my-way')({
defaultRoute: (req, res) => {
res.statusCode = 404
res.end()
}
})
In case of a badly formatted url (eg: /hello/%world
), by default find-my-way
will invoke the defaultRoute
, unless you specify the onBadUrl
option:
const router = require('find-my-way')({
onBadUrl: (path, req, res) => {
res.statusCode = 400
res.end(`Bad path: ${path}`)
}
})
Trailing slashes can be ignored by supplying the ignoreTrailingSlash
option:
const router = require('find-my-way')({
ignoreTrailingSlash: true
})
function handler (req, res, params) {
res.end('foo')
}
router.on('GET', '/foo/', handler)
You can set a custom length for parameters in parametric (standard, regex and multi) routes by using maxParamLength
option, the default value is 100 characters.
If the maximum length limit is reached, the default route will be invoked.
const router = require('find-my-way')({
maxParamLength: 500
})
If you are using a regex based route, find-my-way
will throw an error if detects potentially catastrophic exponential-time regular expressions (internally uses safe-regex2
).
If you want to disable this behavior, pass the option allowUnsafeRegex
.
const router = require('find-my-way')({
allowUnsafeRegex: true
})
According to RFC3986, find-my-way is case sensitive by default.
You can disable this by setting the caseSensitive
option to false
:
in that case, all paths will be matched as lowercase, but the route parameters or wildcards will maintain their original letter casing. You can turn off case sensitivity with:
const router = require('find-my-way')({
caseSensitive: false
})
By default find-my-way
uses accept-version strategy to match requests with different versions of the handlers. The matching logic of that strategy is explained below. It is possible to define the alternative strategy:
const customVersioning = {
storage: function () {
let versions = {}
return {
get: (version) => { return versions[version] || null },
set: (version, store) => { versions[version] = store },
del: (version) => { delete versions[version] },
empty: () => { versions = {} }
}
},
deriveVersion: (req, ctx) => {
return req.headers['accept']
}
}
const router = FindMyWay({ versioning: customVersioning });
The custom strategy object should contain next properties:
storage
- the factory function for the Storage of the handlers based on their version.deriveVersion
- the function to determine the version based on the request
The signature of the functions and objects must match the one from the example above.
Please, be aware, if you use custom versioning strategy - you use it on your own risk. This can lead both to the performance degradation and bugs which are not related to find-my-way
itself
on(method, path, [opts], handler, [store])
Register a new route.
router.on('GET', '/example', (req, res, params) => {
})
Last argument, store
is used to pass an object that you can access later inside the handler function. If needed, store
can be updated.
router.on('GET', '/example', (req, res, params, store) => {
assert.equal(store, { message: 'hello world' })
}, { message: 'hello world' })
Versioned routes
If needed you can provide a version
option, which will allow you to declare multiple versions of the same route. If you never configure a versioned route, the 'Accept-Version'
header will be ignored.
Remember to set a Vary header in your responses with the value you are using for deifning the versioning (e.g.: 'Accept-Version'), to prevent cache poisoning attacks. You can also configure this as part your Proxy/CDN.
default
Default versioning strategy is called accept-version
and it follows the semver specification.
When using lookup
, find-my-way
will automatically detect the Accept-Version
header and route the request accordingly.
Internally find-my-way
uses the semver-store
to get the correct version of the route; advanced ranges and pre-releases currently are not supported.
Be aware that using this feature will cause a degradation of the overall performances of the router.
router.on('GET', '/example', { version: '1.2.0' }, (req, res, params) => {
res.end('Hello from 1.2.0!')
})
router.on('GET', '/example', { version: '2.4.0' }, (req, res, params) => {
res.end('Hello from 2.4.0!')
})
If you declare multiple versions with the same major or minor find-my-way
will always choose the highest compatible with the Accept-Version
header value.
custom
It's also possible to define a custom versioning strategy during the find-my-way
initialization. In this case the logic of matching the request to the specific handler depends on the versioning strategy you use.
on(methods[], path, [opts], handler, [store])
Register a new route for each method specified in the methods
array.
It comes handy when you need to declare multiple routes with the same handler but different methods.
router.on(['GET', 'POST'], '/example', (req, res, params) => {
})
Supported path formats
To register a parametric path, use the colon before the parameter name. For wildcard use the star.
Remember that static routes are always inserted before parametric and wildcard.
router.on('GET', '/example/:userId', (req, res, params) => {}))
router.on('GET', '/example/:userId/:secretToken', (req, res, params) => {}))
router.on('GET', '/example/*', (req, res, params) => {}))
Regular expression routes are supported as well, but pay attention, RegExp are very expensive in term of performance!
If you want to declare a regular expression route, you must put the regular expression inside round parenthesis after the parameter name.
router.on('GET', '/example/:file(^\\d+).png', () => {}))
It's possible to define more than one parameter within the same couple of slash ("/"). Such as:
router.on('GET', '/example/near/:lat-:lng/radius/:r', (req, res, params) => {}))
Remember in this case to use the dash ("-") as parameters separator.
Finally it's possible to have multiple parameters with RegExp.
router.on('GET', '/example/at/:hour(^\\d{2})h:minute(^\\d{2})m', (req, res, params) => {}))
In this case as parameter separator it's possible to use whatever character is not matched by the regular expression.
Having a route with multiple parameters may affect negatively the performance, so prefer single parameter approach whenever possible, especially on routes which are on the hot path of your application.
Match order
The routing algorithm matches one chunk at a time (where the chunk is a string between two slashes),
this means that it cannot know if a route is static or dynamic until it finishes to match the URL.
The chunks are matched in the following order:
- static
- parametric
- wildcards
- parametric(regex)
- multi parametric(regex)
So if you declare the following routes
/:userId/foo/bar
/33/:a(^.*$)/:b
and the URL of the incoming request is /33/foo/bar,
the second route will be matched because the first chunk (33) matches the static chunk.
If the URL would have been /32/foo/bar, the first route would have been matched.
Supported methods
The router is able to route all HTTP methods defined by http
core module.
off(method, path)
Deregister a route.
router.off('GET', '/example')
off(methods[], path, handler, [store])
Deregister a route for each method specified in the methods
array.
It comes handy when you need to deregister multiple routes with the same path but different methods.
router.off(['GET', 'POST'], '/example')
reset()
Empty router.
router.reset()
Caveats
- It's not possible to register two routes which differs only for their parameters, because internally they would be seen as the same route. In a such case you'll get an early error during the route registration phase. An example is worth thousand words:
const findMyWay = FindMyWay({
defaultRoute: (req, res) => {}
})
findMyWay.on('GET', '/user/:userId(^\\d+)', (req, res, params) => {})
findMyWay.on('GET', '/user/:username(^[a-z]+)', (req, res, params) => {})
Shorthand methods
If you want an even nicer api, you can also use the shorthand methods to declare your routes.
For each HTTP supported method, there's the shorthand method. For example:
router.get(path, handler [, store])
router.delete(path, handler [, store])
router.head(path, handler [, store])
router.patch(path, handler [, store])
router.post(path, handler [, store])
router.put(path, handler [, store])
router.options(path, handler [, store])
If you need a route that supports all methods you can use the all
api.
router.all(path, handler [, store])
lookup(request, response, [context])
Start a new search, request
and response
are the server req/res objects.
If a route is found it will automatically call the handler, otherwise the default route will be called.
The url is sanitized internally, all the parameters and wildcards are decoded automatically.
router.lookup(req, res)
lookup
accepts an optional context which will be the value of this
when executing a handler
router.on('GET', '*', function(req, res) {
res.end(this.greeting);
})
router.lookup(req, res, { greeting: 'Hello, World!' })
find(method, path [, version])
Return (if present) the route registered in method:path.
The path must be sanitized, all the parameters and wildcards are decoded automatically.
You can also pass an optional version string. In case of the default versioning strategy it should be conform to the semver specification.
router.find('GET', '/example')
router.find('GET', '/example', '1.x')
prettyPrint()
Prints the representation of the internal radix tree, useful for debugging.
findMyWay.on('GET', '/test', () => {})
findMyWay.on('GET', '/test/hello', () => {})
findMyWay.on('GET', '/hello/world', () => {})
console.log(findMyWay.prettyPrint())
routes
Return the all routes registered at moment, useful for debugging.
const findMyWay = require('find-my-way')()
findMyWay.on('GET', '/test', () => {})
findMyWay.on('GET', '/test/hello', () => {})
console.log(findMyWay.routes)
Acknowledgements
It is inspired by the echo router, some parts have been extracted from trekjs router.
License
find-my-way - MIT
trekjs/router - MIT
Copyright © 2017-2019 Tomas Della Vedova