matchit

What is matchit?

The 'matchit' npm package is a tiny, fast, and efficient routing library for matching URL patterns. It is designed to be minimalistic and highly performant, making it suitable for use in both client-side and server-side applications.

What are matchit's main functionalities?

Basic Route Matching

This feature allows you to define and match URL patterns. The `parse` function is used to define routes, and the `match` function is used to match a URL against these routes, returning the matched route and any parameters.

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

const routes = [
  parse('/users'),
  parse('/users/:id'),
  parse('/posts/:postId/comments/:commentId')
];

const matchRoute = (url) => {
  for (const route of routes) {
    const params = match(url, route);
    if (params) return { route, params };
  }
  return null;
};

console.log(matchRoute('/users/123')); // { route: { ... }, params: { id: '123' } }

Nested Route Matching

This feature allows for nested route matching, where you can define routes with multiple parameters and match URLs that include these nested parameters.

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

const routes = [
  parse('/users'),
  parse('/users/:id'),
  parse('/users/:id/posts/:postId')
];

const matchRoute = (url) => {
  for (const route of routes) {
    const params = match(url, route);
    if (params) return { route, params };
  }
  return null;
};

console.log(matchRoute('/users/123/posts/456')); // { route: { ... }, params: { id: '123', postId: '456' } }

Wildcard Route Matching

This feature allows for wildcard route matching, where you can define routes that match any sub-path. The wildcard parameter captures the rest of the URL.

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

const routes = [
  parse('/files/*'),
  parse('/files/images/*'),
  parse('/files/videos/*')
];

const matchRoute = (url) => {
  for (const route of routes) {
    const params = match(url, route);
    if (params) return { route, params };
  }
  return null;
};

console.log(matchRoute('/files/images/photo.jpg')); // { route: { ... }, params: { wildcard: 'photo.jpg' } }

Other packages similar to matchit

path-to-regexp

The 'path-to-regexp' package is a utility for converting a path string to a regular expression. It is commonly used in routing libraries to match URL patterns. Compared to 'matchit', 'path-to-regexp' is more flexible and powerful but also more complex and heavier.

route-parser

The 'route-parser' package is a lightweight library for parsing and matching URL patterns. It is similar to 'matchit' in terms of simplicity and performance but offers a different API and slightly different feature set.

url-pattern

The 'url-pattern' package is another library for matching URL patterns. It provides a simple and intuitive API for defining and matching routes. Compared to 'matchit', 'url-pattern' is more focused on ease of use and readability.

README

matchit

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 v10.13.0

# Parsing
  matchit               x 1,489,482 ops/sec ±2.89% (97 runs sampled)
  regexparam            x   406,824 ops/sec ±1.38% (96 runs sampled)
  path-to-regexp        x    83,439 ops/sec ±0.89% (96 runs sampled)
  path-to-regexp.parse  x   421,266 ops/sec ±0.13% (97 runs sampled)

# Match (index)
  matchit                x 132,338,546 ops/sec ±0.14% (96 runs sampled)
  regexparam             x  49,889,162 ops/sec ±0.21% (95 runs sampled)
  path-to-regexp.exec    x   7,176,721 ops/sec ±1.23% (94 runs sampled)
  path-to-regexp.tokens  x     102,021 ops/sec ±0.21% (96 runs sampled)

# Match (param)
  matchit                x 2,700,618 ops/sec ±0.92% (95 runs sampled)
  regexparam             x 6,924,653 ops/sec ±0.33% (94 runs sampled)
  path-to-regexp.exec    x 4,715,483 ops/sec ±0.28% (96 runs sampled)
  path-to-regexp.tokens  x    98,182 ops/sec ±0.45% (93 runs sampled)

# Match (optional)
  matchit                x 2,816,313 ops/sec ±0.64% (93 runs sampled)
  regexparam             x 8,437,064 ops/sec ±0.41% (93 runs sampled)
  path-to-regexp.exec    x 5,909,510 ops/sec ±0.22% (97 runs sampled)
  path-to-regexp.tokens  x   101,832 ops/sec ±0.43% (98 runs sampled)

# Match (wildcard)
  matchit                x 3,409,100 ops/sec ±0.34% (98 runs sampled)
  regexparam             x 9,740,429 ops/sec ±0.49% (95 runs sampled)
  path-to-regexp.exec    x 8,740,590 ops/sec ±0.43% (89 runs sampled)
  path-to-regexp.tokens  x   102,109 ops/sec ±0.35% (96 runs sampled)

# Exec
  matchit         x 1,558,321 ops/sec ±0.33% (96 runs sampled)
  regexparam      x 6,966,297 ops/sec ±0.21% (97 runs sampled)
  path-to-regexp  x   102,250 ops/sec ±0.45% (95 runs sampled)

Related

• regexparam - A similar (285B) utility, but relies on RegExp instead of String comparisons.

License

MIT © Luke Edwards