Package Exports

url-router

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (url-router) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

url-router

A non-opinionated cross-platform URL routing library.

Installing

npm install url-router

Examples

Browser:

import Router from 'url-router'

const router = new Router([
  ['/', () => import('./views/Homepage')],
  ['/user/:id/profile', () => import('./views/UserProfile')],
  [/^\/article\/(\d+)$/, () => import('./views/Article')],

  // es2018 named capture groups
  [/^\/post\/(?<id>\d+)$/, () => import('./views/Post')]
])

const route = router.find(location.pathname)
route.handler(route)

node.js:

const http = require('http')
const Router = require('url-router')
const { URL } = require('url')

const article = require('./controllers/article')

const router = new Router([
  ['GET','/article/:id', article.get],
  ['POST', '/article', article.create],
  ['PUT', '/article/:id', article.update],
  ['DELETE', '/article/:id', article.remove],
])

http.createServer((req, res) => {
  const url = new URL(req.url)
  const route = router.find(req.method, url.pathname)
  route.handler({ req, res, route })
}).listen(8080)

API

new Router(routes)

Creates a router instance.

Params:
routes: Array. An array of routes.

route signature:

new Router([
  [method?, path, handler, test?],
  ...
])

method

String. Optional. HTTP method. GET, POST, PUT, DELETE, HEAD, CONNECT, OPTIONS, TRACE, PATCH.
If method is omitted, it defaults to GET.

path

String | Regexp. The path to match against the request path.

You could define route params in path, for example:

const router = new Router([
  ['/people/:username/articles/:articleId', handler]
])

router.find('/people/johnsmith/articles/123')

/*
result:
{
  method: 'GET',
  path: '/people/johnsmith/articles/123',
  handler: handler
  params: { username: 'johnsmith', articleId: '123' }
}
*/

* is wildcard, e.g., route path /foo*bar can match /foowwsdfbar.

If you need more power, use Regexp. Capture groups will be set as route params, keys are $1, $2, ....

const router = new Router([
  [/^\/article\/(\d+)$/, handler]
])

router.find('/article/123')

/*
result:
{
  method: 'GET',
  path: '/article/123',
  handler: handler
  params: { $1: '123' }
}
*/

You can use named capture groups introduced in ES2018:

const router = new Router([
  [/^\/article\/(?<id>\d+)$/, handler]
])

router.find('/article/123')

/*
result:
{
  method: 'GET',
  path: '/article/123',
  handler: handler
  params: { id: '123' }
}
*/

handler

Any type. The handler you wish to handle the request. Based on your framework design, the handler can be a function to handle the request, or the file path to your controller file, or an object (such as Vue component), etc.

If handler is a string and contains $ character, and path is a regexp (string with route params and wildcard will be converted to regexp underlying), the handler will be rewitten. For example:

const router = new Router([
  ['/people/:username/:page', '/people/$2']
])

router.find('/people/johnsmith/articles')

/*
result:
{
  method: 'GET',
  path: '/people/johnsmith/articles',
  handler: '/people/articles',
  params: { username: 'johnsmith', page: 'articles' }
}
*/

The rewrite formula is

routeHandler = requestPath.replace(routePath, routeHandler)

The route params will be converted to capture groups, so can be accessed by $1, $2, ....

Use ES2018 named capture groups:

const router = new Router([
  [/\/member\/(?<id>\d+)\/(?<page>[^/]+)$/, '/member/$<page>']
])

router.find('/member/234/profile')

/*
result:
{
  method: 'GET',
  path: '/member/234/profile',
  handler: '/member/profile',
  params: { id: '234', page: 'profile' }
}
*/

test

Function. Optional. Your custom test function to test against the request. If test function is defined, the route will be matched only if:

The request path is matched with route's path
The test function is passed (returns true)

Function signature:

function test(matchedRoute, testArg) {
  // should return true or false
}

matchedRoute: Object.

{
  method,
  path,
  handler,
  params
}

testArg: Arguments passed by router.find(method?, path, testArg?).

router.add(method?, path, handler, test?)

Adds a route to route table.

method is optional, it defaults to GET.

Every HTTP method has a shortcut alias:

router.get(path, handler, test)
router.post(path, handler, test)
router.put(path, handler, test)
router.delete(path, handler, test)
router.head(path, handler, test)
router.connect(path, handler, test)
router.options(path, handler, test)
router.trace(path, handler, test)
router.patch(path, handler, test)

router.find(method?, path, testArg?)

Finds the route which matches the method and path, and passes the test function if thers is one, or null if no route matches.

Params:
method: String. Optional. The request method. If omitted, defaults to GET.
path: String. The request method.
testArg: Any. Optional. Argument provides to route test function.

Returns:

{
  method,
  path,
  handler,
  params
}

License

MIT