Radix Router

A fast, simple path router that is optimized for consistently fast lookups. This router has support for placeholders and wildcards.

Installation

npm install --save radix-router

Usage

Creating a new Router

new RadixRouter(options) - Creates a new instance of a router. The options object is optional.

Possible parameters for the options object:

• routes - The routes to insert into the router.
• strict - Setting this option to true will force lookups to match exact paths (trailing slashes will not be ignored). Defaults to false.

const RadixRouter = require('radix-router')

const router = new RadixRouter({
  strict: true,
  routes: [
    {
      path: '/my/api/route/a', // "path" is a required field
      // any other fields will also be stored by the router
      extraRouteData: {},
      description: 'this is a route'
    },
    {
      path: '/my/api/route/b',
      extraRouteData: {},
      description: 'this is a different route',
      routeBSpecificData: {}
    }
  ]
})

Router methods

insert(routeData)

Adds the given data to the router. The object passed in must contain a path attribute that is a string. The path will be used by the router to know where to place the route.

Example input:

router.insert({
  path: '/api/route/c', // required
  // any additional data goes here
  extraData: 'anything can be added',
  handler: function (req, res) {
    // ...
  }
})

lookup(path)

Performs a lookup of the path. If there is a match, the data associated with the route is returned, otherwise this will return null.

Usage:

const routeThatExists = router.lookup('/api/route/c')

Example output:

{
  path: '/api/route/c',
  extraData: 'anything can be added',
  handler: function (req, res) {
    // ...
  }
}

remove(path)

Removes the path from the router. Returns true if the route was found and removed.

Usage:

const routeRemoved = router.remove('/some/route')

startsWith(path)

Returns a map of all routes starting with the given prefix and the data associated with them.

Usage:

const apiRoutes = router.startsWith('/api')

Example output:

[
  {
    path:'/api/v1/route',
    much: 'data'
  },
  {
    path: '/api/v1/other-route/:id',
    so: 'placeholder',
    much: 'wow'
  }
]

Wildcard and placeholder matching

Wildcards can be added by to the end of routes by adding /** to the end of your route.

Example:

router.insert(
  path: '/api/v2/**',
  such: 'wildcard'
})

Output of router.lookup('/api/v2/some/random/route'):

{
  path: '/api/v2/**',
  sucn: 'wildcard'
}

Placeholders can be used in routes by starting a segment of the route with a colon :. Whatever content fills the position of the placeholder will be added to the lookup result under the params attribute. The results within params is sorted by its occurrence in the route.

Note: Route placeholder params are placed into an array as an optimization. Your route handlers should be aware of the order placeholders are defined in the routes.

Example:

router.insert(
  path: '/api/v2/:myPlaceholder/route',
  very: 'placeholder'
})

router.insert(
  path: '/api/v3/:organizations/directory/:groupId',
  very: 'placeholder'
})

Output of router.lookup('/api/v2/application/route'):

{
  path: '/api/v2/:myPlaceholder/route',
  very: 'placeholder',
  params: [ 'application' ]
}

Output of router.lookup('/api/v3/test-org/directory/test-group-id'):

{
  path: '/api/v3/:organizations/directory/:groupId',
  very: 'placeholder',
  params: [ 'test-org', 'test-group-id' ]
}