Quickly parse & match URLs
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bench chore: add “regexparam” to bench Nov 23, 2018
src fix: remove destructuring (#11) Dec 10, 2018
test fix(test): remove only Dec 10, 2018
.editorconfig initial commit Nov 2, 2017
.gitignore fix: remove destructuring (#11) Dec 10, 2018
.travis.yml set node 6 as minimum; move on 🏃🏽 Nov 5, 2017
builder.js add super simple builder Feb 14, 2018
license.md initial commit Nov 2, 2017
package.json 1.0.7 Dec 10, 2018
readme.md update benchmarks~! May 19, 2018

readme.md

matchit Build Status

Quickly parse & match URLs

Install

$ npm install --save matchit

Usage

const { exec, match, parse } = require('matchit');

parse('/foo/:bar/:baz?');
//=> [
//=>   { old:'/foo/:bar', type:0, val:'foo' },
//=>   { old:'/foo/:bar', type:1, val:'bar' },
//=>   { old:'/foo/:bar', type:3, val:'baz' }
//=> ]

const routes = ['/', '/foo', 'bar', '/baz', '/baz/:title','/bat/*'].map(parse);

match('/', routes);
//=> [{ old:'/', type:0, val:'/' }]

match('/foo', routes);
//=> [{ old:'/foo', type:0, val:'foo' }]

match('/bar', routes);
//=> [{ old:'bar', type:0, val:'bar' }]

match('/baz', routes);
//=> [{ old:'/baz', type:0, val:'baz' }]

let a = match('/baz/hello', routes);
//=> [{...}, {...}]
let b = exec('/baz/hello', a);
//=> { title:'hello' }

match('/bat/quz/qut', routes);
//=> [
//=>   { old:'/bat/*', type:0, val:'bat' },
//=>   { old:'/bat/*', type:2, val:'*' }
//=> ]

API

matchit.parse(route)

Returns: Array

The route is split and parsed into a "definition" array of objects. Each object ("segment") contains a val, type, and old key:

  • old — The route's original value
  • type — An numerical representation of the segment type.
    • 0 - static
    • 1 - parameter
    • 2 - any/wildcard
    • 3 - optional param
  • val — The current segment's value. This is either a static value of the name of a parameter

route

Type: String

A single URL pattern.

Note: Input will be stripped of all leading & trailing / characters, so there's no need to normalize your own URLs before passing it to parse!

matchit.match(url, routes)

Returns: Array

Returns the route's encoded definition. See matchit.parse.

url

Type: String

The true URL you want to be matched.

routes

Type: Array

All "parsed" route definitions, via matchit.parse.

Important: Multiple routes will require an Array of matchit.parse outputs.

matchit.exec(url, match)

Returns: Object

Returns an object an object of key:val pairs, as defined by your route pattern.

url

Type: String

The URL (pathname) to evaluate.

Important: This should be pathnames only as any querystrings will be included the response.

match

Type: Array

The route definition to use, via matchit.match.

Benchmarks

Running Node 6.11.1

matchit.parse
  --> 311,463 ops/sec ±0.39% (96 runs sampled)
path-to-regexp
  --> 63,187 ops/sec ±0.78% (95 runs sampled)
path-to-regexp.parse
  --> 194,130 ops/sec ±0.50% (97 runs sampled)

matchit.match (index)
  --> 19,015,297 ops/sec ±0.48% (95 runs sampled)
path-to-regexp.exec (index)
  --> 994,152 ops/sec ±0.50% (92 runs sampled)
path-to-regexp.tokens (index)
  --> 68,463 ops/sec ±0.41% (96 runs sampled)

matchit.match (param)
  --> 2,569,858 ops/sec ±0.98% (91 runs sampled)
path-to-regexp.exec (param)
  --> 903,529 ops/sec ±0.55% (90 runs sampled)
path-to-regexp.tokens (param)
  --> 68,158 ops/sec ±0.45% (93 runs sampled)

matchit.match (optional)
  --> 3,012,451 ops/sec ±1.57% (90 runs sampled)
path-to-regexp.exec (optional)
  --> 1,780,864 ops/sec ±0.48% (93 runs sampled)
path-to-regexp.tokens (optional)
  --> 71,376 ops/sec ±0.50% (93 runs sampled)

matchit.match (wildcard)
  --> 2,996,976 ops/sec ±1.18% (89 runs sampled)
path-to-regexp.exec (wildcard)
  --> 1,776,872 ops/sec ±0.52% (90 runs sampled)
path-to-regexp.tokens (wildcard)
  --> 70,687 ops/sec ±0.43% (95 runs sampled)

matchit.exec (params)
  --> 1,171,416 ops/sec ±0.66% (96 runs sampled)
path-to-regexp.exec (params)
  --> 71,773 ops/sec ±0.47% (96 runs sampled)

License

MIT © Luke Edwards