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.
It is inspired by the echo router, some parts have been extracted from trekjs router.

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])

Register a new route, store is an object that you can access later inside the handler function.

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.

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

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])

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.

License

find-my-way - MIT
trekjs/router - MIT

The software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and non infringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.

Copyright © 2017 Tomas Della Vedova