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('{"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])

router.on('GET', '/', (req, res, params) => {
  // your code
})

// with store
router.on('GET', '/store', (req, res, params, store) => {
  // the store can be updated
  assert.equal(store, { hello: 'world' })
}, { hello: 'world' })

If you want to register a parametric path, just use the colon before the parameter name, if you need a wildcard use the star.
Remember that static routes are always inserted before parametric and wildcard.

// parametric
router.on('GET', '/example/:name', () => {}))
// wildcard
router.on('GET', '/other-example/*', () => {}))

Regex routes are supported as well, but pay attention, regex are very expensive!

// parametric with regex
router.on('GET', '/test/:file(^\\d+).png', () => {}))

You can also pass an array of methods if you need to declare multiple routes with the same handler but different method.

router.on(['GET', 'POST'], '/', (req, res, params) => {
  // your code
})

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

wqa/find-my-way