find-my-way
Advanced tools
The find-my-way npm package is a fast HTTP router for Node.js. It is designed to help developers create routing systems for web applications and APIs. It supports dynamic and static routing, HTTP methods, middleware, hooks, and versioning.
Static Routing
Static routing allows you to define routes for specific paths. When a request matches the path, the associated handler is called.
const findMyWay = require('find-my-way')({ defaultRoute: (req, res) => { res.end('Not Found') } });
findMyWay.on('GET', '/example', (req, res, params) => { res.end('This is a static route example'); });Dynamic Routing
Dynamic routing supports path parameters, enabling you to capture values from the URL path and pass them to your handler function.
findMyWay.on('GET', '/example/:param', (req, res, params) => { res.end(`Parameter value: ${params.param}`); });HTTP Methods
The package supports various HTTP methods, allowing you to define different handlers for GET, POST, PUT, DELETE, etc.
findMyWay.on('POST', '/example', (req, res, params) => { res.end('This is a POST method example'); });Middleware Support
Middleware functions can be used to perform actions before the final handler is executed.
findMyWay.use('/example', (req, res, params, next) => { console.log('Middleware executed'); next(); });Versioned Routes
Versioning allows you to define different handlers for different versions of your API.
findMyWay.on('GET', '/example', { version: '1.0.0' }, (req, res, params) => { res.end('This is version 1.0.0'); });Express is a widely-used web application framework for Node.js. It provides a robust set of features for web and mobile applications, including routing, middleware, and template engines. Compared to find-my-way, Express offers a more comprehensive solution with additional features beyond routing.
Koa-router is a router middleware for Koa, another Node.js web framework. It offers similar functionalities to find-my-way, such as HTTP method support and dynamic routing, but is specifically designed to work within the Koa ecosystem.
Hapi is a rich framework for building applications and services, which includes powerful plugin capabilities. It provides a more extensive set of features than find-my-way, including input validation, caching, authentication, and more.
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.
npm i find-my-way --save
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://localost:3000')
})
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()
}
})
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')
}
// maps "/foo/" and "/foo" to `handler`
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-regex).
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 lowercased before routing, including
parametric and regexp-matched values. You can turn off case sensitivity
with:
const router = require('find-my-way')({
caseSensitive: false
})
Register a new route.
router.on('GET', '/example', (req, res, params) => {
// your code
})
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' })
If needed you can provide a version option, which will allow you to declare multiple versions of the same route. The versioning should follow 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!')
})
// The 'Accept-Version' header could be '1.2.0' as well as '*', '2.x' or '2.4.x'
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.
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) => {
// your code
})
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.
// parametric
router.on('GET', '/example/:userId', (req, res, params) => {}))
router.on('GET', '/example/:userId/:secretToken', (req, res, params) => {}))
// wildcard
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.
// parametric with regexp
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.
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:
So if you declare the following routes
/:userId/foo/bar/33/:a(^.*$)/:band 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.
The router is able to route all HTTP methods defined by http core module.
Deregister a route.
router.off('GET', '/example')
// => { handler: Function, params: Object, store: Object}
// => null
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')
// => [{ handler: Function, params: Object, store: Object}]
// => null
Empty router.
router.reset()
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) => {})
// Method 'GET' already declared for route ':'
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])
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!' })
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, which should be conform to the semver specification.
router.find('GET', '/example')
// => { handler: Function, params: Object, store: Object}
// => null
router.find('GET', '/example', '1.x')
// => { handler: Function, params: Object, store: Object}
// => null
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())
// └── /
// ├── test (GET)
// │ └── /hello (GET)
// └── hello/world (GET)
It is inspired by the echo router, some parts have been extracted from trekjs router.
find-my-way - MIT
trekjs/router - MIT
Copyright © 2017 Tomas Della Vedova
FAQs
Crazy fast http radix based router
The npm package find-my-way receives a total of 1,619,173 weekly downloads. As such, find-my-way popularity was classified as popular.
We found that find-my-way demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.