path-to-regexp 4.0.4 → 6.1.0

package/Readme.md

@@ -18,19 +18,12 @@ npm install path-to-regexp --save
 ## Usage
 
 ```javascript
-const {
-  pathToRegexp,
-  match,
-  parse,
-  compile,
-  normalizePathname
-} = require("path-to-regexp");
+const { pathToRegexp, match, parse, compile } = require("path-to-regexp");
 
 // pathToRegexp(path, keys?, options?)
 // match(path)
 // parse(path)
 // compile(path)
-// normalizePathname(path)
 ```
 
 - **path** A string, array of strings, or a regular expression.
@@ -40,26 +33,27 @@ const {
   - **strict** When `true` the regexp allows an optional trailing delimiter to match. (default: `false`)
   - **end** When `true` the regexp will match to the end of the string. (default: `true`)
   - **start** When `true` the regexp will match from the beginning of the string. (default: `true`)
-  - **delimiter** The default delimiter for segments. (default: `'/'`)
+  - **delimiter** The default delimiter for segments, e.g. `[^/#?]` for `:named` patterns. (default: `'/#?'`)
   - **endsWith** Optional character, or list of characters, to treat as "end" characters.
-  - **whitelist** List of characters to consider delimiters when parsing. (default: `undefined`, any character)
+  - **encode** A function to encode strings before inserting into `RegExp`. (default: `x => x`)
+  - **prefixes** List of characters to automatically consider prefixes when parsing. (default: `./`)
 
 ```javascript
 const keys = [];
 const regexp = pathToRegexp("/foo/:bar", keys);
 // regexp = /^\/foo\/([^\/]+?)\/?$/i
-// keys = [{ name: 'bar', prefix: '/', delimiter: '/', optional: false, repeat: false, pattern: '[^\\/]+?' }]
+// keys = [{ name: 'bar', prefix: '/', suffix: '', pattern: '[^\\/#\\?]+?', modifier: '' }]
 ```
 
-**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).
+**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). When using paths that contain query strings, you need to escape the question mark (`?`) to ensure it does not flag the parameter as [optional](#optional).
 
 ### Parameters
 
-The path argument is used to define parameters and populate the list of keys.
+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`). By default, the parameter will match until the next prefix (e.g. `[^/]+`).
+Named parameters are defined by prefixing a colon to the parameter name (`:foo`).
 
 ```js
 const regexp = pathToRegexp("/:foo/:bar");
@@ -71,7 +65,61 @@ regexp.exec("/test/route");
 
 **Please note:** Parameter names must use "word characters" (`[A-Za-z0-9_]`).
 
-#### Parameter Modifiers
+##### 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.
+
+##### 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]
+
+regexp.exec("/test-test");
+// => ['/test', 'test', 'test', undefined]
+```
+
+#### Unnamed Parameters
+
+It is possible to write an unnamed parameter that only consists of a regexp. It works the same the named parameter, except it will be numerically indexed:
+
+```js
+const regexp = pathToRegexp("/:foo/(.*)");
+// keys = [{ name: 'foo', ... }, { name: 0, ... }]
+
+regexp.exec("/test/route");
+//=> [ '/test/route', 'test', 'route', index: 0, input: '/test/route', groups: undefined ]
+```
+
+#### Modifiers
+
+Modifiers must be placed after the parameter (e.g. `/:foo?`, `/(test)?`, or `/:foo(test)?`).
 
 ##### Optional
 
@@ -79,7 +127,7 @@ Parameters can be suffixed with a question mark (`?`) to make the parameter opti
 
 ```js
 const regexp = pathToRegexp("/:foo/:bar?");
-// keys = [{ name: 'foo', ... }, { name: 'bar', delimiter: '/', optional: true, repeat: false }]
+// keys = [{ name: 'foo', ... }, { name: 'bar', prefix: '/', modifier: '?' }]
 
 regexp.exec("/test");
 //=> [ '/test', 'test', undefined, index: 0, input: '/test', groups: undefined ]
@@ -90,13 +138,26 @@ regexp.exec("/test/route");
 
 **Tip:** The prefix is also optional, escape the prefix `\/` to make it required.
 
+When dealing with query strings, escape the question mark (`?`) so it doesn't mark the parameter as optional. Handling unordered data is outside the scope of this library.
+
+```js
+const regexp = pathToRegexp("/search/:tableName\\?useIndex=true&term=amazing");
+
+regexp.exec("/search/people?useIndex=true&term=amazing");
+//=> [ '/search/people?useIndex=true&term=amazing', 'people', index: 0, input: '/search/people?useIndex=true&term=amazing', groups: undefined ]
+
+// This library does not handle query strings in different orders
+regexp.exec("/search/people?term=amazing&useIndex=true");
+//=> null
+```
+
 ##### Zero or more
 
-Parameters can be suffixed with an asterisk (`*`) to denote a zero or more parameter matches. The prefix is used for each match.
+Parameters can be suffixed with an asterisk (`*`) to denote a zero or more parameter matches.
 
 ```js
 const regexp = pathToRegexp("/:foo*");
-// keys = [{ name: 'foo', delimiter: '/', optional: true, repeat: true }]
+// keys = [{ name: 'foo', prefix: '/', modifier: '*' }]
 
 regexp.exec("/");
 //=> [ '/', undefined, index: 0, input: '/', groups: undefined ]
@@ -107,11 +168,11 @@ regexp.exec("/bar/baz");
 
 ##### One or more
 
-Parameters can be suffixed with a plus sign (`+`) to denote a one or more parameter matches. The prefix is used for each match.
+Parameters can be suffixed with a plus sign (`+`) to denote a one or more parameter matches.
 
 ```js
 const regexp = pathToRegexp("/:foo+");
-// keys = [{ name: 'foo', delimiter: '/', optional: false, repeat: true }]
+// keys = [{ name: 'foo', prefix: '/', modifier: '+' }]
 
 regexp.exec("/");
 //=> null
@@ -120,60 +181,53 @@ regexp.exec("/bar/baz");
 //=> [ '/bar/baz','bar/baz', index: 0, input: '/bar/baz', groups: undefined ]
 ```
 
-#### Unnamed Parameters
+### Match
 
-It is possible to write an unnamed parameter that only consists of a matching group. It works the same as a named parameter, except it will be numerically indexed.
+The `match` function will return a function for transforming paths into parameters:
 
 ```js
-const regexp = pathToRegexp("/:foo/(.*)");
-// keys = [{ name: 'foo', ... }, { name: 0, ... }]
+// Make sure you consistently `decode` segments.
+const match = match("/user/:id", { decode: decodeURIComponent });
 
-regexp.exec("/test/route");
-//=> [ '/test/route', 'test', 'route', index: 0, input: '/test/route', groups: undefined ]
+match("/user/123"); //=> { path: '/user/123', index: 0, params: { id: '123' } }
+match("/invalid"); //=> false
+match("/user/caf%C3%A9"); //=> { path: '/user/caf%C3%A9', index: 0, params: { id: 'café' } }
 ```
 
-#### Custom Matching Parameters
+#### Process Pathname
 
-All parameters can have a custom regexp, which overrides the default match (`[^/]+`). For example, you can match digits or names in a path:
+You should make sure variations of the same path match the expected `path`. Here's one possible solution using `encode`:
 
 ```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, ... }]
+const match = match("/café", { encode: encodeURI, decode: decodeURIComponent });
 
-regexpWord.exec("/u");
-//=> ['/u', 'u']
-
-regexpWord.exec("/users");
-//=> null
+match("/user/caf%C3%A9"); //=> { path: '/user/caf%C3%A9', index: 0, params: { id: 'café' } }
 ```
 
-**Tip:** Backslashes need to be escaped with another backslash in JavaScript strings.
-
-### Match
+**Note:** [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) automatically encodes pathnames for you.
 
-The `match` function will return a function for transforming paths into parameters:
+##### Alternative Using Normalize
 
-```js
-const match = match("/user/:id");
-
-match("/user/123"); //=> { path: '/user/123', index: 0, params: { id: '123' } }
-match("/invalid"); //=> false
-```
-
-### Normalize Pathname
-
-The `normalizePathname` function will return a normalized string for matching with `pathToRegexp`.
+Sometimes you won't have an already normalized pathname. You can normalize it yourself before processing:
 
 ```js
+/**
+ * Normalize a pathname for matching, replaces multiple slashes with a single
+ * slash and normalizes unicode characters to "NFC". When using this method,
+ * `decode` should be an identity function so you don't decode strings twice.
+ */
+function normalizePathname(pathname: string) {
+  return (
+    decodeURI(pathname)
+      // Replaces repeated slashes in the URL.
+      .replace(/\/+/g, "/")
+      // Reference: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize
+      // Note: Missing native IE support, may want to skip this step.
+      .normalize()
+  );
+}
+
+// Two possible ways of writing `/café`:
 const re = pathToRegexp("/caf\u00E9");
 const input = encodeURI("/cafe\u0301");
 
@@ -192,10 +246,10 @@ console.log(tokens[0]);
 //=> "/route"
 
 console.log(tokens[1]);
-//=> { name: 'foo', prefix: '/', delimiter: '/', optional: false, repeat: false, pattern: '[^\\/]+?' }
+//=> { name: 'foo', prefix: '/', suffix: '', pattern: '[^\\/#\\?]+?', modifier: '' }
 
 console.log(tokens[2]);
-//=> { name: 0, prefix: '/', delimiter: '/', optional: false, repeat: false, pattern: '.*' }
+//=> { name: 0, prefix: '/', suffix: '', pattern: '.*', modifier: '' }
 ```
 
 **Note:** This method only works with strings.
@@ -205,14 +259,20 @@ console.log(tokens[2]);
 The `compile` function will return a function for transforming parameters into a valid path:
 
 ```js
-const toPath = compile("/user/:id");
+// Make sure you encode your path segments consistently.
+const toPath = compile("/user/:id", { encode: encodeURIComponent });
 
 toPath({ id: 123 }); //=> "/user/123"
 toPath({ id: "café" }); //=> "/user/caf%C3%A9"
 toPath({ id: "/" }); //=> "/user/%2F"
 
 toPath({ id: ":/" }); //=> "/user/%3A%2F"
-toPath({ id: ":/" }, { encode: (value, token) => value, validate: false }); //=> "/user/:/"
+
+// Without `encode`, you need to make sure inputs are encoded correctly.
+const toPathRaw = compile("/user/:id");
+
+toPathRaw({ id: "%3A%2F" }); //=> "/user/%3A%2F"
+toPathRaw({ id: ":/" }, { validate: false }); //=> "/user/:/"
 
 const toPathRepeated = compile("/:segment+");
 
@@ -227,11 +287,11 @@ toPathRegexp({ id: "abc" }); //=> Throws `TypeError`.
 toPathRegexp({ id: "abc" }, { validate: false }); //=> "/user/abc"
 ```
 
-**Note:** The generated function will throw on invalid input. It will do all necessary checks to ensure the generated path is valid. This method only works with strings.
+**Note:** The generated function will throw on invalid input.
 
 ### Working with Tokens
 
-Path-To-RegExp exposes the two functions used internally that accept an array of tokens.
+Path-To-RegExp exposes the two functions used internally that accept an array of tokens:
 
 - `tokensToRegexp(tokens, keys?, options?)` Transform an array of tokens into a matching regular expression.
 - `tokensToFunction(tokens)` Transform an array of tokens into a path generator function.
@@ -239,11 +299,10 @@ Path-To-RegExp exposes the two functions used internally that accept an array of
 #### Token Information
 
 - `name` The name of the token (`string` for named or `number` for unnamed index)
-- `prefix` The prefix character for the segment (e.g. `/`)
-- `delimiter` The delimiter for the segment (same as prefix or default delimiter)
-- `optional` Indicates the token is optional (`boolean`)
-- `repeat` Indicates the token is repeated (`boolean`)
+- `prefix` The prefix string for the segment (e.g. `"/"`)
+- `suffix` The suffix string for the segment (e.g. `""`)
 - `pattern` The RegExp used to match this token (`string`)
+- `modifier` The modifier character used for the segment (e.g. `?`)
 
 ## Compatibility with Express <= 4.x
 

package/dist/index.d.ts

@@ -4,16 +4,10 @@ export interface ParseOptions {
      */
     delimiter?: string;
     /**
-     * List of characters to consider delimiters when parsing. (default: `undefined`, any character)
+     * List of characters to automatically consider prefixes when parsing.
      */
-    whitelist?: string | string[];
+    prefixes?: string;
 }
-/**
- * Normalize a pathname for matching, replaces multiple slashes with a single
- * slash and normalizes unicode characters to "NFC". When using this method,
- * `decode` should be an identity function so you don't decode strings twice.
- */
-export declare function normalizePathname(pathname: string, whitelist?: string | string[]): string;
 /**
  * Parse a string for the raw tokens.
  */
@@ -66,7 +60,7 @@ export declare type MatchFunction<P extends object = object> = (path: string) =>
 /**
  * Create path match function from `path-to-regexp` spec.
  */
-export declare function match<P extends object = object>(str: Path, options?: ParseOptions & RegexpOptions & RegexpToFunctionOptions): MatchFunction<P>;
+export declare function match<P extends object = object>(str: Path, options?: ParseOptions & TokensToRegexpOptions & RegexpToFunctionOptions): MatchFunction<P>;
 /**
  * Create a path match function from `path-to-regexp` output.
  */
@@ -77,20 +71,15 @@ export declare function regexpToFunction<P extends object = object>(re: RegExp,
 export interface Key {
     name: string | number;
     prefix: string;
-    delimiter: string;
-    optional: boolean;
-    repeat: boolean;
+    suffix: string;
     pattern: string;
+    modifier: string;
 }
 /**
  * A token is a string (nothing special) or key metadata (capture group).
  */
 export declare type Token = string | Key;
-/**
- * Expose a function for taking tokens and returning a RegExp.
- */
-export declare function tokensToRegexp(tokens: Token[], keys?: Key[], options?: RegexpOptions): RegExp;
-export interface RegexpOptions {
+export interface TokensToRegexpOptions {
     /**
      * When `true` the regexp will be case sensitive. (default: `false`)
      */
@@ -114,14 +103,16 @@ export interface RegexpOptions {
     /**
      * List of characters that can also be "end" characters.
      */
-    endsWith?: string | string[];
-}
-export interface ParseOptions {
+    endsWith?: string;
     /**
-     * Set the default delimiter for repeat parameters. (default: `'/'`)
+     * Encode path tokens for use in the `RegExp`.
      */
-    delimiter?: string;
+    encode?: (value: string) => string;
 }
+/**
+ * Expose a function for taking tokens and returning a RegExp.
+ */
+export declare function tokensToRegexp(tokens: Token[], keys?: Key[], options?: TokensToRegexpOptions): RegExp;
 /**
  * Supported `path-to-regexp` input types.
  */
@@ -133,4 +124,4 @@ export declare type Path = string | RegExp | Array<string | RegExp>;
  * placeholder key descriptions. For example, using `/user/:id`, `keys` will
  * contain `[{ name: 'id', delimiter: '/', optional: false, repeat: false }]`.
  */
-export declare function pathToRegexp(path: Path, keys?: Key[], options?: RegexpOptions & ParseOptions): RegExp;
+export declare function pathToRegexp(path: Path, keys?: Key[], options?: TokensToRegexpOptions & ParseOptions): RegExp;