Rewrite and simplify API

Author: blakeembrey

Readme.md

@@ -24,29 +24,9 @@ const { match, compile, parse } = require("path-to-regexp");
 // parse(path, options?)
 ```
 
-### Match
-
-The `match` function returns a function for transforming paths into parameters:
-
-- **path** A string.
-- **options** _(optional)_ (See [parse](#parse) for more options)
-  - **sensitive** Regexp will be case sensitive. (default: `false`)
-  - **end** Validate the match reaches the end of the string. (default: `true`)
-  - **decode** Function for decoding strings to params, or `false` to disable all processing. (default: `decodeURIComponent`)
-
-```js
-const fn = match("/foo/:bar");
-```
-
-**Please note:** `path-to-regexp` is intended for ordered data (e.g. pathnames, hostnames). It can not handle arbitrarily ordered data (e.g. query strings, URL fragments, JSON, etc).
-
 ### Parameters
 
-Parameters match arbitrary strings in a path by matching up to the end of the segment, or up to any proceeding tokens.
-
-#### Named parameters
-
-Named parameters are defined by prefixing a colon to the parameter name (`:foo`). Parameter names can use any valid unicode identifier characters, similar to JavaScript.
+Parameters match arbitrary strings in a path by matching up to the end of the segment, or up to any proceeding tokens. They are defined by prefixing a colon to the parameter name (`:foo`). Parameter names can use any valid JavaScript identifier, or be double quoted to use other characters (`:"param-name"`).
 
 ```js
 const fn = match("/:foo/:bar");
@@ -55,137 +35,54 @@ fn("/test/route");
 //=> { path: '/test/route', params: { foo: 'test', bar: 'route' } }
 ```
 
-##### Custom matching parameters
-
-Parameters can have a custom regexp, which overrides the default match (`[^/]+`). For example, you can match digits or names in a path:
-
-```js
-const exampleNumbers = match("/icon-:foo(\\d+).png");
-
-exampleNumbers("/icon-123.png");
-//=> { path: '/icon-123.png', params: { foo: '123' } }
-
-exampleNumbers("/icon-abc.png");
-//=> false
-
-const exampleWord = pathToRegexp("/(user|u)");
-
-exampleWord("/u");
-//=> { path: '/u', params: { '0': 'u' } }
-
-exampleWord("/users");
-//=> false
-```
-
-**Tip:** Backslashes need to be escaped with another backslash in JavaScript strings.
-
-#### Unnamed parameters
-
-It is possible to define a parameter without a name. The name will be numerically indexed:
-
-```js
-const fn = match("/:foo/(.*)");
-
-fn("/test/route");
-//=> { path: '/test/route', params: { '0': 'route', foo: 'test' } }
-```
-
-#### Custom prefix and suffix
-
-Parameters can be wrapped in `{}` to create custom prefixes or suffixes for your segment:
-
-```js
-const fn = match("{/:attr1}?{-:attr2}?{-:attr3}?");
-
-fn("/test");
-//=> { path: '/test', params: { attr1: 'test' } }
-
-fn("/test-test");
-//=> { path: '/test-test', params: { attr1: 'test', attr2: 'test' } }
-```
-
-#### Modifiers
-
-Modifiers are used after parameters with custom prefixes and suffixes (`{}`).
-
-##### Optional
-
-Parameters can be suffixed with a question mark (`?`) to make the parameter optional.
-
-```js
-const fn = match("/:foo{/:bar}?");
-
-fn("/test");
-//=> { path: '/test', params: { foo: 'test' } }
-
-fn("/test/route");
-//=> { path: '/test/route', params: { foo: 'test', bar: 'route' } }
-```
-
-##### Zero or more
+### Wildcard
 
-Parameters can be suffixed with an asterisk (`*`) to denote a zero or more parameter matches.
+Wildcard parameters match one or more characters across multiple segments. They are defined the same way as regular parameters, but are prefixed with an asterisk (`*foo`).
 
 ```js
-const fn = match("{/:foo}*");
-
-fn("/foo");
-//=> { path: '/foo', params: { foo: [ 'foo' ] } }
+const fn = match("/*splat");
 
 fn("/bar/baz");
-//=> { path: '/bar/baz', params: { foo: [ 'bar', 'baz' ] } }
+//=> { path: '/bar/baz', params: { splat: [ 'bar', 'baz' ] } }
 ```
 
-##### One or more
+### Optional
 
-Parameters can be suffixed with a plus sign (`+`) to denote a one or more parameter matches.
+Braces can be used to define parts of the path that are optional.
 
 ```js
-const fn = match("{/:foo}+");
+const fn = match("/users{/:id}/delete");
 
-fn("/");
-//=> false
+fn("/users/delete");
+//=> { path: '/users/delete', params: {} }
 
-fn("/bar/baz");
-//=> { path: '/bar/baz', params: { foo: [ 'bar', 'baz' ] } }
+fn("/users/123/delete");
+//=> { path: '/users/123/delete', params: { id: '123' } }
 ```
 
-##### Custom separator
-
-By default, parameters set the separator as the `prefix + suffix` of the token. Using `;` you can modify this:
-
-```js
-const fn = match("/name{/:parts;-}+");
+## Match
 
-fn("/name");
-//=> false
+The `match` function returns a function for matching strings against a path:
 
-fn("/bar/1-2-3");
-//=> { path: '/name/1-2-3', params: { parts: [ '1', '2', '3' ] } }
-```
-
-#### Wildcard
-
-A wildcard is also supported. It is roughly equivalent to `(.*)`.
+- **path** String or array of strings.
+- **options** _(optional)_ (See [parse](#parse) for more options)
+  - **sensitive** Regexp will be case sensitive. (default: `false`)
+  - **end** Validate the match reaches the end of the string. (default: `true`)
+  - **trailing** Allows optional trailing delimiter to match. (default: `true`)
+  - **decode** Function for decoding strings to params, or `false` to disable all processing. (default: `decodeURIComponent`)
 
 ```js
-const fn = match("/*");
-
-fn("/");
-//=> { path: '/', params: {} }
-
-fn("/bar/baz");
-//=> { path: '/bar/baz', params: { '0': [ 'bar', 'baz' ] } }
+const fn = match("/foo/:bar");
 ```
 
-### Compile ("Reverse" Path-To-RegExp)
+**Please note:** `path-to-regexp` is intended for ordered data (e.g. pathnames, hostnames). It can not handle arbitrarily ordered data (e.g. query strings, URL fragments, JSON, etc).
+
+## Compile ("Reverse" Path-To-RegExp)
 
 The `compile` function will return a function for transforming parameters into a valid path:
 
 - **path** A string.
 - **options** (See [parse](#parse) for more options)
-  - **sensitive** Regexp will be case sensitive. (default: `false`)
-  - **validate** When `false` the function can produce an invalid (unmatched) path. (default: `true`)
   - **encode** Function for encoding input strings for output into the path, or `false` to disable entirely. (default: `encodeURIComponent`)
 
 ```js
@@ -194,46 +91,34 @@ const toPath = compile("/user/:id");
 toPath({ id: "name" }); //=> "/user/name"
 toPath({ id: "café" }); //=> "/user/caf%C3%A9"
 
-// When disabling `encode`, you need to make sure inputs are encoded correctly. No arrays are accepted.
-const toPathRaw = compile("/user/:id", { encode: false });
-
-toPathRaw({ id: "%3A%2F" }); //=> "/user/%3A%2F"
-toPathRaw({ id: ":/" }); //=> Throws, "/user/:/" when `validate` is `false`.
-
-const toPathRepeated = compile("{/:segment}+");
+const toPathRepeated = compile("/*segment");
 
 toPathRepeated({ segment: ["foo"] }); //=> "/foo"
 toPathRepeated({ segment: ["a", "b", "c"] }); //=> "/a/b/c"
 
-const toPathRegexp = compile("/user/:id(\\d+)");
+// When disabling `encode`, you need to make sure inputs are encoded correctly. No arrays are accepted.
+const toPathRaw = compile("/user/:id", { encode: false });
 
-toPathRegexp({ id: "123" }); //=> "/user/123"
+toPathRaw({ id: "%3A%2F" }); //=> "/user/%3A%2F"
 ```
 
 ## Developers
 
 - If you are rewriting paths with match and compile, consider using `encode: false` and `decode: false` to keep raw paths passed around.
-- To ensure matches work on paths containing characters usually encoded, consider using [encodeurl](https://github.com/pillarjs/encodeurl) for `encodePath`.
+- To ensure matches work on paths containing characters usually encoded, such as emoji, consider using [encodeurl](https://github.com/pillarjs/encodeurl) for `encodePath`.
 
 ### Parse
 
-The `parse` function accepts a string and returns `TokenData`, the set of tokens and other metadata parsed from the input string. `TokenData` is can used with `$match` and `$compile`.
+The `parse` function accepts a string and returns `TokenData`, the set of tokens and other metadata parsed from the input string. `TokenData` is can used with `match` and `compile`.
 
 - **path** A string.
 - **options** _(optional)_
   - **delimiter** The default delimiter for segments, e.g. `[^/]` for `:named` parameters. (default: `'/'`)
-  - **encodePath** A function for encoding input strings. (default: `x => x`, recommended: [`encodeurl`](https://github.com/pillarjs/encodeurl) for unicode encoding)
+  - **encodePath** A function for encoding input strings. (default: `x => x`, recommended: [`encodeurl`](https://github.com/pillarjs/encodeurl))
 
 ### Tokens
 
-The `tokens` returned by `TokenData` is an array of strings or keys, represented as objects, with the following properties:
-
-- `name` The name of the token
-- `prefix` _(optional)_ The prefix string for the segment (e.g. `"/"`)
-- `suffix` _(optional)_ The suffix string for the segment (e.g. `""`)
-- `pattern` _(optional)_ The pattern defined to match this token
-- `modifier` _(optional)_ The modifier character used for the segment (e.g. `?`)
-- `separator` _(optional)_ The string used to separate repeated parameters
+`TokenData` is a sequence of tokens, currently of types `text`, `parameter`, `wildcard`, or `group`.
 
 ### Custom path
 
@@ -242,9 +127,12 @@ In some applications, you may not be able to use the `path-to-regexp` syntax, bu
 ```js
 import { TokenData, match } from "path-to-regexp";
 
-const tokens = ["/", { name: "foo" }];
-const path = new TokenData(tokens, "/");
-const fn = $match(path);
+const tokens = [
+  { type: "text", value: "/" },
+  { type: "parameter", name: "foo" },
+];
+const path = new TokenData(tokens);
+const fn = match(path);
 
 fn("/test"); //=> { path: '/test', index: 0, params: { foo: 'test' } }
 ```
@@ -253,55 +141,34 @@ fn("/test"); //=> { path: '/test', index: 0, params: { foo: 'test' } }
 
 An effort has been made to ensure ambiguous paths from previous releases throw an error. This means you might be seeing an error when things worked before.
 
-### Unexpected `?`, `*`, or `+`
-
-In previous major versions `/` and `.` were used as implicit prefixes of parameters. So `/:key?` was implicitly `{/:key}?`. For example:
-
-- `/:key?` → `{/:key}?` or `/:key*` → `{/:key}*` or `/:key+` → `{/:key}+`
-- `.:key?` → `{.:key}?` or `.:key*` → `{.:key}*` or `.:key+` → `{.:key}+`
-- `:key?` → `{:key}?` or `:key*` → `{:key}*` or `:key+` → `{:key}+`
+### Unexpected `?` or `+`
 
-### Unexpected `;`
+In past releases, `?`, `*`, and `+` were used to denote optional or repeating parameters. As an alternative, try these:
 
-Used as a [custom separator](#custom-separator) for repeated parameters.
+- For optional (`?`), use an empty segment in a group such as `/:file{.:ext}`.
+- For repeating (`+`), only wildcard matching is supported, such as `/*path`.
+- For optional repeating (`*`), use a group and a wildcard parameter such as `/files{/*path}`.
 
-### Unexpected `!`, `@`, or `,`
+### Unexpected `(`, `)`, `[`, `]`, etc.
 
-These characters have been reserved for future use.
-
-### Missing separator
-
-Repeated parameters must have a separator to be valid. For example, `{:foo}*` can't be used. Separators can be defined manually, such as `{:foo;/}*`, or they default to the suffix and prefix with the parameter, such as `{/:foo}*`.
+Previous versions of Path-to-RegExp used these for RegExp features. This version no longer supports them so they've been reserved to avoid ambiguity. To use these characters literally, escape them with a backslash, e.g. `"\\("`.
 
 ### Missing parameter name
 
-Parameter names, the part after `:`, must be a valid JavaScript identifier. For example, it cannot start with a number or dash. If you want a parameter name that uses these characters you can wrap the name in quotes, e.g. `:"my-name"`.
+Parameter names, the part after `:` or `*`, must be a valid JavaScript identifier. For example, it cannot start with a number or contain a dash. If you want a parameter name that uses these characters you can wrap the name in quotes, e.g. `:"my-name"`.
 
 ### Unterminated quote
 
 Parameter names can be wrapped in double quote characters, and this error means you forgot to close the quote character.
 
-### Pattern cannot start with "?"
-
-Parameters in `path-to-regexp` must be basic groups. However, you can use features that require the `?` nested within the pattern. For example, `:foo((?!login)[^/]+)` is valid, but `:foo(?!login)` is not.
-
-### Capturing groups are not allowed
-
-A parameter pattern can not contain nested capturing groups.
-
-### Unbalanced or missing pattern
-
-A parameter pattern must have the expected number of parentheses. An unbalanced amount, such as `((?!login)` implies something has been written that is invalid. Check you didn't forget any parentheses.
-
 ### Express <= 4.x
 
 Path-To-RegExp breaks compatibility with Express <= `4.x` in the following ways:
 
-- The only part of the string that is a regex is within `()`.
-  - In Express.js 4.x, everything was passed as-is after a simple replacement, so you could write `/[a-z]+` to match `/test`.
-- The `?` optional character must be used after `{}`.
+- Regexp characters can no longer be provided.
+- The optional character `?` is no longer supported, use braces instead: `/:file{.:ext}`.
 - Some characters have new meaning or have been reserved (`{}?*+@!;`).
-- The parameter name now supports all unicode identifier characters, previously it was only `[a-z0-9]`.
+- The parameter name now supports all JavaScript identifier characters, previously it was only `[a-z0-9]`.
 
 ## License
 

package.json

@@ -20,6 +20,7 @@
     "dist/"
   ],
   "scripts": {
+    "bench": "vitest bench",
     "build": "ts-scripts build",
     "format": "ts-scripts format",
     "lint": "ts-scripts lint",

scripts/redos.ts

@@ -5,13 +5,7 @@ import { MATCH_TESTS } from "../src/cases.spec.js";
 let safe = 0;
 let fail = 0;
 
-const TESTS = new Set(MATCH_TESTS.map((test) => test.path));
-// const TESTS = [
-//   ":path([^\\.]+).:ext",
-//   ":path.:ext(\\w+)",
-//   ":path{.:ext([^\\.]+)}",
-//   "/:path.:ext(\\\\w+)",
-// ];
+const TESTS = MATCH_TESTS.map((x) => x.path);
 
 for (const path of TESTS) {
   const { re } = match(path) as any;

src/cases.spec.ts

@@ -0,0 +1,42 @@
+import { bench } from "vitest";
+import { match } from "./index.js";
+
+const PATHS: string[] = [
+  "/xyz",
+  "/user",
+  "/user/123",
+  "/" + "a".repeat(32_000),
+  "/-" + "-a".repeat(8_000) + "/-",
+  "/||||\x00|" + "||".repeat(27387) + "|\x00".repeat(27387) + "/||/",
+];
+
+const STATIC_PATH_MATCH = match("/user");
+const SIMPLE_PATH_MATCH = match("/user/:id");
+const MULTI_SEGMENT_MATCH = match("/:x/:y");
+const MULTI_PATTERN_MATCH = match("/:x-:y");
+const TRICKY_PATTERN_MATCH = match("/:foo|:bar|");
+const ASTERISK_MATCH = match("/*foo");
+
+bench("static path", () => {
+  for (const path of PATHS) STATIC_PATH_MATCH(path);
+});
+
+bench("simple path", () => {
+  for (const path of PATHS) SIMPLE_PATH_MATCH(path);
+});
+
+bench("multi segment", () => {
+  for (const path of PATHS) MULTI_SEGMENT_MATCH(path);
+});
+
+bench("multi pattern", () => {
+  for (const path of PATHS) MULTI_PATTERN_MATCH(path);
+});
+
+bench("tricky pattern", () => {
+  for (const path of PATHS) TRICKY_PATTERN_MATCH(path);
+});
+
+bench("asterisk", () => {
+  for (const path of PATHS) ASTERISK_MATCH(path);
+});

src/index.bench.ts

@@ -6,89 +6,86 @@ import { PARSER_TESTS, COMPILE_TESTS, MATCH_TESTS } from "./cases.spec.js";
  * Dynamically generate the entire test suite.
  */
 describe("path-to-regexp", () => {
-  describe("arguments", () => {
-    it("should throw on non-capturing pattern", () => {
-      expect(() => match("/:foo(?:\\d+(\\.\\d+)?)")).toThrow(
+  describe("parse errors", () => {
+    it("should throw on unbalanced group", () => {
+      expect(() => parse("/{:foo,")).toThrow(
         new TypeError(
-          'Pattern cannot start with "?" at 6: https://git.new/pathToRegexpError',
+          "Unexpected END at 7, expected }: https://git.new/pathToRegexpError",
         ),
       );
     });
-
-    it("should throw on nested capturing group", () => {
-      expect(() => match("/:foo(\\d+(\\.\\d+)?)")).toThrow(
+    it("should throw on nested unbalanced group", () => {
+      expect(() => parse("/{:foo/{x,y}")).toThrow(
         new TypeError(
-          "Capturing groups are not allowed at 9: https://git.new/pathToRegexpError",
+          "Unexpected END at 12, expected }: https://git.new/pathToRegexpError",
         ),
       );
     });
 
-    it("should throw on unbalanced pattern", () => {
-      expect(() => match("/:foo(abc")).toThrow(
+    it("should throw on missing param name", () => {
+      expect(() => parse("/:/")).toThrow(
         new TypeError(
-          "Unbalanced pattern at 5: https://git.new/pathToRegexpError",
+          "Missing parameter name at 2: https://git.new/pathToRegexpError",
         ),
       );
     });
 
-    it("should throw on unmatched )", function () {
-      expect(() => match("/:fooab)c")).toThrow(
-        new TypeError("Unmatched ) at 7: https://git.new/pathToRegexpError"),
-      );
-    });
-
-    it("should throw on unmatched ) after other patterns", function () {
-      expect(() => match("/:test(\\w+)/:foo(\\d+))")).toThrow(
-        new TypeError("Unmatched ) at 21: https://git.new/pathToRegexpError"),
-      );
-    });
-
-    it("should throw on missing pattern", () => {
-      expect(() => match("/:foo()")).toThrow(
+    it("should throw on missing wildcard name", () => {
+      expect(() => parse("/*/")).toThrow(
         new TypeError(
-          "Missing pattern at 5: https://git.new/pathToRegexpError",
+          "Missing parameter name at 2: https://git.new/pathToRegexpError",
         ),
       );
     });
 
-    it("should throw on missing name", () => {
-      expect(() => match("/:(test)")).toThrow(
+    it("should throw on unterminated quote", () => {
+      expect(() => parse('/:"foo')).toThrow(
         new TypeError(
-          "Missing parameter name at 2: https://git.new/pathToRegexpError",
+          "Unterminated quote at 2: https://git.new/pathToRegexpError",
         ),
       );
     });
+  });
 
-    it("should throw on nested groups", () => {
-      expect(() => match("/{a{b:foo}}")).toThrow(
-        new TypeError(
-          "Unexpected { at 3, expected }: https://git.new/pathToRegexpError",
-        ),
-      );
+  describe("compile errors", () => {
+    it("should throw when a param is missing", () => {
+      const toPath = compile("/a/:b/c");
+
+      expect(() => {
+        toPath();
+      }).toThrow(new TypeError("Missing parameters: b"));
     });
 
-    it("should throw on repeat parameters without a separator", () => {
-      expect(() => match("{:x}*")).toThrow(
-        new TypeError(
-          `Missing separator for "x": https://git.new/pathToRegexpError`,
-        ),
-      );
+    it("should throw when expecting a repeated value", () => {
+      const toPath = compile("/*foo");
+
+      expect(() => {
+        toPath({ foo: [] });
+      }).toThrow(new TypeError('Expected "foo" to be a non-empty array'));
     });
 
-    it("should throw on unterminated quote", () => {
-      expect(() => match('/:"foo')).toThrow(
-        new TypeError(
-          "Unterminated quote at 2: https://git.new/pathToRegexpError",
-        ),
-      );
+    it("should throw when param gets an array", () => {
+      const toPath = compile("/:foo");
+
+      expect(() => {
+        toPath({ foo: [] });
+      }).toThrow(new TypeError('Expected "foo" to be a string'));
     });
 
-    it("should throw on invalid *", () => {
-      expect(() => match("/:foo*")).toThrow(
-        new TypeError(
-          "Unexpected * at 5, you probably want `/*` or `{/:foo}*`: https://git.new/pathToRegexpError",
-        ),
-      );
+    it("should throw when a wildcard is not an array", () => {
+      const toPath = compile("/*foo");
+
+      expect(() => {
+        toPath({ foo: "a" });
+      }).toThrow(new TypeError('Expected "foo" to be a non-empty array'));
+    });
+
+    it("should throw when a wildcard array value is not a string", () => {
+      const toPath = compile("/*foo");
+
+      expect(() => {
+        toPath({ foo: [1, "a"] as any });
+      }).toThrow(new TypeError('Expected "foo/0" to be a string'));
     });
   });
 
@@ -126,75 +123,4 @@ describe("path-to-regexp", () => {
       });
     },
   );
-
-  describe("compile errors", () => {
-    it("should throw when a required param is undefined", () => {
-      const toPath = compile("/a/:b/c");
-
-      expect(() => {
-        toPath();
-      }).toThrow(new TypeError('Expected "b" to be a string'));
-    });
-
-    it("should throw when it does not match the pattern", () => {
-      const toPath = compile("/:foo(\\d+)");
-
-      expect(() => {
-        toPath({ foo: "abc" });
-      }).toThrow(new TypeError('Invalid value for "foo": "abc"'));
-    });
-
-    it("should throw when expecting a repeated value", () => {
-      const toPath = compile("{/:foo}+");
-
-      expect(() => {
-        toPath({ foo: [] });
-      }).toThrow(new TypeError('Invalid value for "foo": ""'));
-    });
-
-    it("should throw when not expecting a repeated value", () => {
-      const toPath = compile("/:foo");
-
-      expect(() => {
-        toPath({ foo: [] });
-      }).toThrow(new TypeError('Expected "foo" to be a string'));
-    });
-
-    it("should throw when a repeated param is not an array", () => {
-      const toPath = compile("{/:foo}+");
-
-      expect(() => {
-        toPath({ foo: "a" });
-      }).toThrow(new TypeError('Expected "foo" to be an array'));
-    });
-
-    it("should throw when an array value is not a string", () => {
-      const toPath = compile("{/:foo}+");
-
-      expect(() => {
-        toPath({ foo: [1, "a"] as any });
-      }).toThrow(new TypeError('Expected "foo/0" to be a string'));
-    });
-
-    it("should throw when repeated value does not match", () => {
-      const toPath = compile("{/:foo(\\d+)}+");
-
-      expect(() => {
-        toPath({ foo: ["1", "2", "3", "a"] });
-      }).toThrow(new TypeError('Invalid value for "foo": "/1/2/3/a"'));
-    });
-  });
 });
-
-/**
- * Execute a regular expression and return a flat array for comparison.
- *
- * @param  {RegExp} re
- * @param  {String} str
- * @return {Array}
- */
-function exec(re: RegExp, str: string) {
-  const match = re.exec(str);
-
-  return match && Array.prototype.slice.call(match);
-}

src/index.spec.ts

@@ -3,5 +3,5 @@
   "compilerOptions": {
     "types": []
   },
-  "exclude": ["src/**/*.spec.ts"]
+  "exclude": ["src/**/*.spec.ts", "src/**/*.bench.ts"]
 }