Get unlimited public & private packages + package-based permissions with npm Pro.Get started »

@calmdownval/waltz-match

1.0.0 • Public • Published

waltz-match

This module uses the ES modules feature and requires Node v8.15.0+. Please refer to Node's documentation to read more on how to enable this functionality in your environment.

Matches path params. Utilizes a very fast parser and does not use regexes. This library performs well in comparison to other non-regex matchers, but gets dwarfed by regex matchers. See benchmarking below.

Installation

npm i --save @calmdownval/waltz-match

Usage

import * as Waltz from '@calmdownval/waltz-match';
 
// parse a pattern first, then use match with it
const pattern = Waltz.parse('/some/:param/in-my-path');
 
// it will return null for invalid paths
// -> null
Waltz.match('/some/wrong/path', pattern);
 
// and an array of matched params (indexed from 1) on success:
// -> [ 3, 'value' ]
const match = Waltz.match('/some/value/in-my-path', pattern);
 
// we can get get a key-value map of params
// -> { param : 'value' }
const params = Waltz.params(match, pattern);
 
// we can also reconstruct paths back from params
// -> '/some/value/in-my-path'
const path = Waltz.rebuild(params, pattern);

Syntax

Parameters

As seen above, parameters are denoted by a colon : followed by the parameter name until the next path separator / (or the end of string).

If ending with a question mark ?, such parameter is considered optional. Paths omitting this parameter will successfully match against the pattern. The parameter will be populated in the resulting array with null value.

Wildcards

Using a single wildcard * you can create a pattern that matches exactly one or no path segment at its position. It acts exactly the same as optional parameters except values matched under wildards will not appear in the resulting array with values.

Using a double wildcard ** you can create a pattern that matches zero or more path segments at its position. Although powerful, this can degrade performance of the matching process and should not be overused.

Benchmarks

Below are benchmarks of individual methods in comparison to other libraries. Libraries based on regular expressions typically perform badly when parsing the pattern itself, but offer great performance when actually matching paths. This library is therefore best suited for scenarios where you very often parse a new pattern and only use it once.

  parse:
  ------
  regexparam     x   930,642 ops/sec ±1.51% (86 runs sampled)
- path-to-regexp x   344,080 ops/sec ±1.43% (85 runs sampled)
+ waltz          x 3,881,128 ops/sec ±1.23% (88 runs sampled)
  matchit        x 2,143,504 ops/sec ±0.93% (82 runs sampled)
 
  match - test:
  -------------
  regexparam     x 13,484,800 ops/sec ±1.06% (89 runs sampled)
+ path-to-regexp x 14,250,364 ops/sec ±1.64% (87 runs sampled)
  waltz          x  1,572,177 ops/sec ±2.25% (88 runs sampled)
- matchit        x  1,091,833 ops/sec ±1.00% (94 runs sampled)
 
  match - exec:
  -------------
  regexparam     x 3,909,298 ops/sec ±2.08% (90 runs sampled)
+ path-to-regexp x 3,965,538 ops/sec ±1.63% (91 runs sampled)
  waltz          x 1,223,151 ops/sec ±1.87% (73 runs sampled)
- matchit        x   400,206 ops/sec ±1.01% (88 runs sampled)

Install

npm i @calmdownval/waltz-match

DownloadsWeekly Downloads

0

Version

1.0.0

License

GPL-3.0-or-later

Unpacked Size

47.2 kB

Total Files

7

Last publish

Collaborators

  • avatar