cerebral / url-mapper

Take a URL and map to functions, parsing params

url-mapper

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

Installation

npm install url-mapper --save

Usage

Overview

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.

Example

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.

API

Main module

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

Factory

Usage

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

Arguments

Param	Type	Details
options	Object	Options passed to converter. Property Type Details query Boolean Enables converting values not defined in route as query in URL Object Notation querySeparator String String used to separate query from routable part. Default '?'.

Returns

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.

parse method

Usage

mapper.parse(route, url)

Arguments

Param	Type	Details
route	String	Express style route definition
url	String	Routable part of url

Returns

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.

stringify method

Usage

mapper.stringify(route, values)

Arguments

Param	Type	Details
route	String	Express style route definition
values	Object	Object used to populate parameters in route definition

Returns

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.

map method

Usage

mapper.map(url, routes)

Arguments

Param	Type	Details
url	String	Routable part of url
routes	Object	Routes to map url with

Returns

Object - Object representing matched route with properties:

Property	Type	Details
route	String	Matched route defined as key in routes
match	Any	Value from routes associated with matched route
values	Object	Values parsed from given url with matched route

Matcher

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.

Factory

Usage

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

Arguments

Param	Type	Details
compileFn	Function	Function used by mapper to "compile" a route.
options	Any	Optional. Passed to compileFn as second argument.

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.

Returns

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.