find-my-way

What is find-my-way?

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.

What are find-my-way's main functionalities?

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'); });

Other packages similar to find-my-way

express

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

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

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.

README

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.

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://localost: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()
  }
})

on(method, path, handler, [store])

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' })

on(methods[], path, 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) => {
  // your code
})

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.

// 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!

// 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.

Match order

The routes are matched in the following order:

static
parametric
wildcards
parametric(regex)
multi parametric(regex)

off(method, path)

Deregister a route.

router.off('GET', '/example')
// => { handler: Function, params: Object, store: Object}
// => null

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')
// => [{ handler: Function, params: Object, store: Object}]
// => null

reset()

Empty router.

router.reset()

Caveats

• Since static routes have greater priority than parametric routes, when you register a static route and a dynamic route, which have part of their path equal, the static route shadows the parametric route, that becomes not accessible. For example:

const assert = require('assert')
const router = require('find-my-way')({
  defaultRoute: (req, res) => {
    assert(req.url === '/example/shared/nested/oops')
  }
})

router.on('GET', '/example/shared/nested/test', (req, res, params) => {
  assert.fail('We should not be here')
})

router.on('GET', '/example/:param/nested/oops', (req, res, params) => {
  assert.fail('We should not be here')
})

router.lookup({ method: 'GET', url: '/example/shared/nested/oops' }, null)

• 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) => {})
// Method 'GET' already declared for route ':'

Shorthand methods

If you want an even nicer api, you can also use the shorthand methods to declare your routes.

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])
router.trace(path, handler [, store])
router.connect(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)

Start a new search, request and response are the server req/res objects.
If a route is found it will automatically called 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)

find(method, path)

Return (if present) the route registered in method:path.
The path must be sanitized, all the parameters and wildcards are decoded automatically.

router.find('GET', '/example')
// => { handler: Function, params: Object, store: Object}
// => null

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())
// └── /
//   ├── test (GET)
//   │   └── /hello (GET)
//   └── hello/world (GET)

Acknowledgements

This project is kindly sponsored by LetzDoIt.
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 Tomas Della Vedova