path-to-regexp 7.2.0 → 8.1.0

package/Readme.md

@@ -17,208 +17,87 @@ npm install path-to-regexp --save
 ## Usage
 
 ```js
-const { pathToRegexp, match, parse, compile } = require("path-to-regexp");
-
-// pathToRegexp(path, options?)
-// match(path, options?)
-// parse(path, options?)
-// compile(path, options?)
-```
-
-### Path to regexp
-
-The `pathToRegexp` function returns a regular expression with `keys` as a property. It accepts the following arguments:
-
-- **path** A string.
-- **options** _(optional)_
-  - **sensitive** Regexp will be case sensitive. (default: `false`)
-  - **trailing** Allows optional trailing delimiter to match. (default: `true`)
-  - **strict** Verify patterns are valid and safe to use. (default: `false`, recommended: `true`)
-  - **end** Match to the end of the string. (default: `true`)
-  - **start** Match from the beginning of the string. (default: `true`)
-  - **loose** Allow the delimiter to be arbitrarily repeated, e.g. `/` or `///`. (default: `true`)
-  - **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)
-
-```js
-const regexp = pathToRegexp("/foo/:bar");
-// regexp = /^\/+foo(?:\/+([^\/]+?))(?:\/+)?$/i
-// keys = [{ name: 'bar', prefix: '', suffix: '', pattern: '', modifier: '' }]
+const {
+  match,
+  pathToRegexp,
+  compile,
+  parse,
+  stringify,
+} = require("path-to-regexp");
 ```
 
-**Please note:** The `RegExp` returned by `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
 
-The path argument is used to define parameters and populate keys.
-
-#### 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 regexp = pathToRegexp("/:foo/:bar");
-// keys = [{ name: 'foo', ... }, { name: 'bar', ... }]
-
-regexp.exec("/test/route");
-//=> [ '/test/route', 'test', 'route', index: 0 ]
-```
-
-##### 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 regexpNumbers = pathToRegexp("/icon-:foo(\\d+).png");
-// keys = [{ name: 'foo', ... }]
-
-regexpNumbers.exec("/icon-123.png");
-//=> ['/icon-123.png', '123']
-
-regexpNumbers.exec("/icon-abc.png");
-//=> null
-
-const regexpWord = pathToRegexp("/(user|u)");
-// keys = [{ name: 0, ... }]
-
-regexpWord.exec("/u");
-//=> ['/u', 'u']
-
-regexpWord.exec("/users");
-//=> null
-```
-
-**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 regexp = pathToRegexp("/:foo/(.*)");
-// keys = [{ name: 'foo', ... }, { name: '0', ... }]
-
-regexp.exec("/test/route");
-//=> [ '/test/route', 'test', 'route', index: 0 ]
-```
-
-##### Custom prefix and suffix
-
-Parameters can be wrapped in `{}` to create custom prefixes or suffixes for your segment:
-
-```js
-const regexp = pathToRegexp("{/:attr1}?{-:attr2}?{-:attr3}?");
-
-regexp.exec("/test");
-// => ['/test', 'test', undefined, undefined]
+const fn = match("/:foo/:bar");
 
-regexp.exec("/test-test");
-// => ['/test', 'test', 'test', undefined]
+fn("/test/route");
+//=> { path: '/test/route', params: { foo: 'test', bar: 'route' } }
 ```
 
-#### Modifiers
+### Wildcard
 
-Modifiers are used after parameters with custom prefixes and suffixes (`{}`).
-
-##### Optional
-
-Parameters can be suffixed with a question mark (`?`) to make the parameter optional.
+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 regexp = pathToRegexp("/:foo{/:bar}?");
-// keys = [{ name: 'foo', ... }, { name: 'bar', prefix: '/', modifier: '?' }]
-
-regexp.exec("/test");
-//=> [ '/test', 'test', undefined, index: 0 ]
+const fn = match("/*splat");
 
-regexp.exec("/test/route");
-//=> [ '/test/route', 'test', 'route', index: 0 ]
+fn("/bar/baz");
+//=> { path: '/bar/baz', params: { splat: [ 'bar', 'baz' ] } }
 ```
 
-##### Zero or more
+### Optional
 
-Parameters can be suffixed with an asterisk (`*`) to denote a zero or more parameter matches.
+Braces can be used to define parts of the path that are optional.
 
 ```js
-const regexp = pathToRegexp("{/:foo}*");
-// keys = [{ name: 'foo', prefix: '/', modifier: '*' }]
+const fn = match("/users{/:id}/delete");
 
-regexp.exec("/foo");
-//=> [ '/foo', "foo", index: 0 ]
+fn("/users/delete");
+//=> { path: '/users/delete', params: {} }
 
-regexp.exec("/bar/baz");
-//=> [ '/bar/baz', 'bar/baz', index: 0 ]
+fn("/users/123/delete");
+//=> { path: '/users/123/delete', params: { id: '123' } }
 ```
 
-##### One or more
-
-Parameters can be suffixed with a plus sign (`+`) to denote a one or more parameter matches.
-
-```js
-const regexp = pathToRegexp("{/:foo}+");
-// keys = [{ name: 'foo', prefix: '/', modifier: '+' }]
-
-regexp.exec("/");
-//=> null
+## Match
 
-regexp.exec("/bar/baz");
-//=> [ '/bar/baz', 'bar/baz', index: 0 ]
-```
+The `match` function returns a function for matching strings against a path:
 
-##### Custom separator
-
-By default, parameters set the separator as the `prefix + suffix` of the token. Using `;` you can modify this:
+- **path** String or array of strings.
+- **options** _(optional)_ (Extends [pathToRegexp](#pathToRegexp) options)
+  - **decode** Function for decoding strings to params, or `false` to disable all processing. (default: `decodeURIComponent`)
 
 ```js
-const regexp = pathToRegexp("/name{/:parts;-}+");
-
-regexp.exec("/name");
-//=> null
-
-regexp.exec("/bar/1-2-3");
-//=> [ '/name/1-2-3', '1-2-3', index: 0 ]
+const fn = match("/foo/:bar");
 ```
 
-#### Wildcard
-
-A wildcard can also be used. It is roughly equivalent to `(.*)`.
-
-```js
-const regexp = pathToRegexp("/*");
-// keys = [{ name: '0', pattern: '[^\\/]*', separator: '/', modifier: '*' }]
-
-regexp.exec("/");
-//=> [ '/', '', index: 0 ]
+**Please note:** `path-to-regexp` is intended for ordered data (e.g. paths, hosts). It can not handle arbitrarily ordered data (e.g. query strings, URL fragments, JSON, etc).
 
-regexp.exec("/bar/baz");
-//=> [ '/bar/baz', 'bar/baz', index: 0 ]
-```
-
-### Match
+## PathToRegexp
 
-The `match` function returns a function for transforming paths into parameters:
+The `pathToRegexp` function returns a regular expression for matching strings against paths. It
 
-- **path** A string.
-- **options** _(optional)_ The same options as `pathToRegexp`, plus:
-  - **decode** Function for decoding strings for params, or `false` to disable entirely. (default: `decodeURIComponent`)
+- **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`)
+  - **delimiter** The default delimiter for segments, e.g. `[^/]` for `:named` parameters. (default: `'/'`)
+  - **trailing** Allows optional trailing delimiter to match. (default: `true`)
 
 ```js
-const fn = match("/user/:id");
-
-fn("/user/123"); //=> { path: '/user/123', index: 0, params: { id: '123' } }
-fn("/invalid"); //=> false
-fn("/user/caf%C3%A9"); //=> { path: '/user/caf%C3%A9', index: 0, params: { id: 'café' } }
+const { regexp, keys } = pathToRegexp("/foo/:bar");
 ```
 
-**Note:** Setting `decode: false` disables the "splitting" behavior of repeated parameters, which is useful if you need the exactly matched parameter back.
-
-### Compile ("Reverse" Path-To-RegExp)
+## Compile ("Reverse" Path-To-RegExp)
 
 The `compile` function will return a function for transforming parameters into a valid path:
 
 - **path** A string.
-- **options** _(optional)_ Similar to `pathToRegexp` (`delimiter`, `encodePath`, `sensitive`, and `loose`), plus:
-  - **validate** When `false` the function can produce an invalid (unmatched) path. (default: `true`)
+- **options** (See [parse](#parse) for more options)
+  - **delimiter** The default delimiter for segments, e.g. `[^/]` for `:named` parameters. (default: `'/'`)
   - **encode** Function for encoding input strings for output into the path, or `false` to disable entirely. (default: `encodeURIComponent`)
 
 ```js
@@ -227,53 +106,61 @@ const toPath = compile("/user/:id");
 toPath({ id: "name" }); //=> "/user/name"
 toPath({ id: "café" }); //=> "/user/caf%C3%A9"
 
+const toPathRepeated = compile("/*segment");
+
+toPathRepeated({ segment: ["foo"] }); //=> "/foo"
+toPathRepeated({ segment: ["a", "b", "c"] }); //=> "/a/b/c"
+
 // 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}+");
+## Stringify
 
-toPathRepeated({ segment: ["foo"] }); //=> "/foo"
-toPathRepeated({ segment: ["a", "b", "c"] }); //=> "/a/b/c"
+Transform `TokenData` (a sequence of tokens) back into a Path-to-RegExp string.
+
+- **data** A `TokenData` instance
 
-const toPathRegexp = compile("/user/:id(\\d+)");
+```js
+const data = new TokenData([
+  { type: "text", value: "/" },
+  { type: "param", name: "foo" },
+]);
 
-toPathRegexp({ id: "123" }); //=> "/user/123"
+const path = stringify(data); //=> "/:foo"
 ```
 
 ## Developers
 
-- If you are rewriting paths with match and compiler, 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`.
-- If matches are intended to be exact, you need to set `loose: false`, `trailing: false`, and `sensitive: true`.
-- Enable `strict: true` to detect ReDOS issues.
+- 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, such as emoji, consider using [encodeurl](https://github.com/pillarjs/encodeurl) for `encodePath`.
 
 ### Parse
 
-A `parse` function is available and returns `TokenData`, the set of tokens and other metadata parsed from the input string. `TokenData` is can passed directly into `pathToRegexp`, `match`, and `compile`. It accepts only two options, `delimiter` and `encodePath`, which makes those options redundant in the above methods.
+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`.
 
-### Tokens
+- **path** A string.
+- **options** _(optional)_
+  - **encodePath** A function for encoding input strings. (default: `x => x`, recommended: [`encodeurl`](https://github.com/pillarjs/encodeurl))
 
-The `tokens` returned by `TokenData` is an array of strings or keys, represented as objects, with the following properties:
+### Tokens
 
-- `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
 
-In some applications, you may not be able to use the `path-to-regexp` syntax (e.g. file-based routing), but you can still use this library for `match`, `compile`, and `pathToRegexp` by building your own `TokenData` instance. For example:
+In some applications, you may not be able to use the `path-to-regexp` syntax, but still want to use this library for `match` and `compile`. For example:
 
 ```js
 import { TokenData, match } from "path-to-regexp";
 
-const tokens = ["/", { name: "foo" }];
-const path = new TokenData(tokens, "/");
+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' } }
@@ -283,31 +170,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 `+`
+### Unexpected `?` or `+`
+
+In past releases, `?`, `*`, and `+` were used to denote optional or repeating parameters. As an alternative, try these:
+
+- 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}`.
 
-In previous major versions `/` and `.` were used as implicit prefixes of parameters. So `/:key?` was implicitly `{/:key}?`. For example:
+### Unexpected `(`, `)`, `[`, `]`, etc.
 
-- `/:key?` → `{/:key}?` or `/:key*` → `{/:key}*` or `/:key+` → `{/:key}+`
-- `.:key?` → `{.:key}?` or `.:key*` → `{.:key}*` or `.:key+` → `{.:key}+`
-- `:key?` → `{:key}?` or `:key*` → `{:key}*` or `:key+` → `{:key}+`
+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. `"\\("`.
 
-### Unexpected `;`
+### Missing parameter name
 
-Used as a [custom separator](#custom-separator) for repeated parameters.
+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"`.
 
-### Unexpected `!`, `@`, or `,`
+### Unterminated quote
 
-These characters have been reserved for future use.
+Parameter names can be wrapped in double quote characters, and this error means you forgot to close the quote character.
 
 ### 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/dist/index.d.ts

@@ -7,40 +7,28 @@ export type Encode = (value: string) => string;
  */
 export type Decode = (value: string) => string;
 export interface ParseOptions {
-    /**
-     * The default delimiter for segments. (default: `'/'`)
-     */
-    delimiter?: string;
     /**
      * A function for encoding input strings.
      */
     encodePath?: Encode;
 }
-export interface PathToRegexpOptions extends ParseOptions {
+export interface PathToRegexpOptions {
     /**
-     * Regexp will be case sensitive. (default: `false`)
+     * Matches the path completely without trailing characters. (default: `true`)
      */
-    sensitive?: boolean;
-    /**
-     * Allow the delimiter to be arbitrarily repeated. (default: `true`)
-     */
-    loose?: boolean;
-    /**
-     * Verify patterns are valid and safe to use. (default: `false`)
-     */
-    strict?: boolean;
+    end?: boolean;
     /**
-     * Match from the beginning of the string. (default: `true`)
+     * Allows optional trailing delimiter to match. (default: `true`)
      */
-    start?: boolean;
+    trailing?: boolean;
     /**
-     * Match to the end of the string. (default: `true`)
+     * Match will be case sensitive. (default: `false`)
      */
-    end?: boolean;
+    sensitive?: boolean;
     /**
-     * Allow optional trailing delimiter to match. (default: `true`)
+     * The default delimiter for segments. (default: `'/'`)
      */
-    trailing?: boolean;
+    delimiter?: string;
 }
 export interface MatchOptions extends PathToRegexpOptions {
     /**
@@ -48,35 +36,62 @@ export interface MatchOptions extends PathToRegexpOptions {
      */
     decode?: Decode | false;
 }
-export interface CompileOptions extends ParseOptions {
-    /**
-     * Regexp will be case sensitive. (default: `false`)
-     */
-    sensitive?: boolean;
-    /**
-     * Allow the delimiter to be arbitrarily repeated. (default: `true`)
-     */
-    loose?: boolean;
-    /**
-     * Verify patterns are valid and safe to use. (default: `false`)
-     */
-    strict?: boolean;
-    /**
-     * Verifies the function is producing a valid path. (default: `true`)
-     */
-    validate?: boolean;
+export interface CompileOptions {
     /**
      * Function for encoding input strings for output into the path, or `false` to disable entirely. (default: `encodeURIComponent`)
      */
     encode?: Encode | false;
+    /**
+     * The default delimiter for segments. (default: `'/'`)
+     */
+    delimiter?: string;
 }
 /**
- * Tokenized path instance. Can we passed around instead of string.
+ * Plain text.
+ */
+export interface Text {
+    type: "text";
+    value: string;
+}
+/**
+ * A parameter designed to match arbitrary text within a segment.
+ */
+export interface Parameter {
+    type: "param";
+    name: string;
+}
+/**
+ * A wildcard parameter designed to match multiple segments.
+ */
+export interface Wildcard {
+    type: "wildcard";
+    name: string;
+}
+/**
+ * A set of possible tokens to expand when matching.
+ */
+export interface Group {
+    type: "group";
+    tokens: Token[];
+}
+/**
+ * A token that corresponds with a regexp capture.
+ */
+export type Key = Parameter | Wildcard;
+/**
+ * A sequence of `path-to-regexp` keys that match capturing groups.
+ */
+export type Keys = Array<Key>;
+/**
+ * A sequence of path match characters.
+ */
+export type Token = Text | Parameter | Wildcard | Group;
+/**
+ * Tokenized path instance.
  */
 export declare class TokenData {
     readonly tokens: Token[];
-    readonly delimiter: string;
-    constructor(tokens: Token[], delimiter: string);
+    constructor(tokens: Token[]);
 }
 /**
  * Parse a string for the raw tokens.
@@ -85,7 +100,7 @@ export declare function parse(str: string, options?: ParseOptions): TokenData;
 /**
  * Compile a string to a template function for the path.
  */
-export declare function compile<P extends ParamData = ParamData>(path: Path, options?: CompileOptions): PathFunction<P>;
+export declare function compile<P extends ParamData = ParamData>(path: Path, options?: CompileOptions & ParseOptions): (data?: P) => string;
 export type ParamData = Partial<Record<string, string | string[]>>;
 export type PathFunction<P extends ParamData> = (data?: P) => string;
 /**
@@ -93,7 +108,6 @@ export type PathFunction<P extends ParamData> = (data?: P) => string;
  */
 export interface MatchResult<P extends ParamData> {
     path: string;
-    index: number;
     params: P;
 }
 /**
@@ -105,35 +119,18 @@ export type Match<P extends ParamData> = false | MatchResult<P>;
  */
 export type MatchFunction<P extends ParamData> = (path: string) => Match<P>;
 /**
- * Create path match function from `path-to-regexp` spec.
- */
-export declare function match<P extends ParamData>(path: Path | Path[], options?: MatchOptions): MatchFunction<P>;
-/**
- * A key is a capture group in the regex.
- */
-export interface Key {
-    name: string;
-    prefix?: string;
-    suffix?: string;
-    pattern?: string;
-    modifier?: string;
-    separator?: string;
-}
-/**
- * A token is a string (nothing special) or key metadata (capture group).
- */
-export type Token = string | Key;
-/**
- * Repeated and simple input types.
+ * Supported path types.
  */
 export type Path = string | TokenData;
 /**
- * Normalize the given path string, returning a regular expression.
- *
- * An empty array can be passed in for the keys, which will hold the
- * placeholder key descriptions. For example, using `/user/:id`, `keys` will
- * contain `[{ name: 'id', delimiter: '/', optional: false, repeat: false }]`.
+ * Transform a path into a match function.
  */
-export declare function pathToRegexp(path: Path | Path[], options?: PathToRegexpOptions): RegExp & {
-    keys: Key[];
+export declare function match<P extends ParamData>(path: Path | Path[], options?: MatchOptions & ParseOptions): MatchFunction<P>;
+export declare function pathToRegexp(path: Path | Path[], options?: PathToRegexpOptions & ParseOptions): {
+    regexp: RegExp;
+    keys: Keys;
 };
+/**
+ * Stringify token data into a path string.
+ */
+export declare function stringify(data: TokenData): string;