Two way URL <==> route(params) converter with mapper.

npm install url-mapper --save

The main purpose of url-mapper is to match given URL to one of the routes. It will return the matched route (key and associated value) and parsed parameters. You can associate anything you want with route: function, React component or just plain object.

url-mapper is helpful when creating router packages for frameworks or can be used as router itself. It allows you to outsource working with a url (mapping, parsing, stringifying) and concentrate on wiring up things related to your favorite framework.

import React from 'react'
import ReactDOM from 'react-dom'
import Mapper from 'url-mapper'
import { CoreApp, ComponentA, ComponentB, Component404 } from './components'

const urlMapper = Mapper()

// routable part of url as first argument
var matchedRoute = urlMapper.map('/bar/baz/:42', {
  '/foo/:id': ComponentA,
  '/bar/:list/:itemId': ComponentB,
  '*': Component404,
})

if (matchedRoute) {
  const Component = matchedRoute.match // ComponentB
  const props = matchedRoute.values // { list: 'baz', itemId: 42 }

  ReactDOM.render(
    <CoreApp>
      <Component {...props} />
    </CoreApp>
  )
}

See @cerebral/router as an example of building your own router solution on top of url-mapper. Also see example at Runkit Sandbox to try it right in your browser.

At top level the url-mapper module exports a factory which returns default implementation of an URL <==> route(params) converter.

var urlMapper = require('url-mapper')
var mapper = urlMapper(options)

Object - Object with parse, stringify and map methods.

Returned methods deals with Express-style route definitions and cleaned routable part of url (without origin, base path, leading hash symbol).

Params defined in route are mapped to the same named properties in the values Object with help of path-to-regexp module. It is safe to pass Numbers and Booleans as well as Strings as path parameteres. The original type would be preserved while parsing back stringified one.

By default, the query part is ignored. Query part params are mapped to the same named properties in values Object if { query: true } option was passed to factory. Conversion of the query part is made with help of URLON module. Therefore, it can accept any JSON serializable value.

Hash part is ignored at all if any present. You still can manage your routes in location.hash but don't provide # symbol before routable part.

mapper.parse(route, url)

Object - values parsed from url with given route.

Path parsed using path-to-regexp module, tweaked to support Boolean and Number. Query part parsed with URLON module if { query: true } option was passed to factory.

mapper.stringify(route, values)

String - values stringified to url with given route.

Properties defined in route are stringified to path part using path-to-regexp module, tweaked to support Boolean and Number. Properties not defined in route are stringified to query part using URLON module if { query: true } option was passed to factory.

mapper.map(url, routes)

Object - Object representing matched route with properties:

Custom converting algoritms could be implemented by providing a custom compile function. If you don't like default route definition format or converting algorithms, feel free to make your own.

var urlMapper = require('url-mapper/mapper')
var mapper = urlMapper(compileFn, options)

For each route mapper would call compileFn(route, options) and cache result internally. compileFn should return parse(url) and stringify(values) methods for any given route. See default implementation for reference.

Object - Object with parse(route, url), stringify(route, values) and map(url, routes) methods.

These methods will use cached methods returned by compileFn for given routes.