path-to-regexp 4.0.5 → 6.2.0

package/History.md

@@ -1,30 +1,32 @@
-# 3.0.0 / 2019-01-13
+# Moved to [GitHub Releases](https://github.com/pillarjs/path-to-regexp/releases)
+
+## 3.0.0 / 2019-01-13
 
 - Always use prefix character as delimiter token, allowing any character to be a delimiter (e.g. `/:att1-:att2-:att3-:att4-:att5`)
 - Remove `partial` support, prefer escaping the prefix delimiter explicitly (e.g. `\\/(apple-)?icon-:res(\\d+).png`)
 
-# 2.4.0 / 2018-08-26
+## 2.4.0 / 2018-08-26
 
 - Support `start` option to disable anchoring from beginning of the string
 
-# 2.3.0 / 2018-08-20
+## 2.3.0 / 2018-08-20
 
 - Use `delimiter` when processing repeated matching groups (e.g. `foo/bar` has no prefix, but has a delimiter)
 
-# 2.2.1 / 2018-04-24
+## 2.2.1 / 2018-04-24
 
 - Allow empty string with `end: false` to match both relative and absolute paths
 
-# 2.2.0 / 2018-03-06
+## 2.2.0 / 2018-03-06
 
 - Pass `token` as second argument to `encode` option (e.g. `encode(value, token)`)
 
-# 2.1.0 / 2017-10-20
+## 2.1.0 / 2017-10-20
 
 - Handle non-ending paths where the final character is a delimiter
   - E.g. `/foo/` before required either `/foo/` or `/foo//` to match in non-ending mode
 
-# 2.0.0 / 2017-08-23
+## 2.0.0 / 2017-08-23
 
 - New option! Ability to set `endsWith` to match paths like `/test?query=string` up to the query string
 - New option! Set `delimiters` for specific characters to be treated as parameter prefixes (e.g. `/:test`)
@@ -35,38 +37,38 @@
 - Remove asterisk functionality (it's a real pain to properly encode)
 - Change `tokensToFunction` (e.g. `compile`) to accept an `encode` function for pretty encoding (e.g. pass your own implementation)
 
-# 1.7.0 / 2016-11-08
+## 1.7.0 / 2016-11-08
 
 - Allow a `delimiter` option to be passed in with `tokensToRegExp` which will be used for "non-ending" token match situations
 
-# 1.6.0 / 2016-10-03
+## 1.6.0 / 2016-10-03
 
 - Populate `RegExp.keys` when using the `tokensToRegExp` method (making it consistent with the main export)
 - Allow a `delimiter` option to be passed in with `parse`
 - Updated TypeScript definition with `Keys` and `Options` updated
 
-# 1.5.3 / 2016-06-15
+## 1.5.3 / 2016-06-15
 
 - Add `\\` to the ignore character group to avoid backtracking on mismatched parens
 
-# 1.5.2 / 2016-06-15
+## 1.5.2 / 2016-06-15
 
 - Escape `\\` in string segments of regexp
 
-# 1.5.1 / 2016-06-08
+## 1.5.1 / 2016-06-08
 
 - Add `index.d.ts` to NPM package
 
-# 1.5.0 / 2016-05-20
+## 1.5.0 / 2016-05-20
 
 - Handle partial token segments (better)
 - Allow compile to handle asterisk token segments
 
-# 1.4.0 / 2016-05-18
+## 1.4.0 / 2016-05-18
 
 - Handle RegExp unions in path matching groups
 
-# 1.3.0 / 2016-05-08
+## 1.3.0 / 2016-05-08
 
 - Clarify README language and named parameter token support
 - Support advanced Closure Compiler with type annotations
@@ -74,20 +76,20 @@
 - Add TypeScript definition to project
 - Improved prefix handling with non-complete segment parameters (E.g. `/:foo?-bar`)
 
-# 1.2.1 / 2015-08-17
+## 1.2.1 / 2015-08-17
 
 - Encode values before validation with path compilation function
 - More examples of using compilation in README
 
-# 1.2.0 / 2015-05-20
+## 1.2.0 / 2015-05-20
 
 - Add support for matching an asterisk (`*`) as an unnamed match everything group (`(.*)`)
 
-# 1.1.1 / 2015-05-11
+## 1.1.1 / 2015-05-11
 
 - Expose methods for working with path tokens
 
-# 1.1.0 / 2015-05-09
+## 1.1.0 / 2015-05-09
 
 - Expose the parser implementation to consumers
 - Implement a compiler function to generate valid strings
@@ -95,50 +97,50 @@
 - Use chai in tests
 - Add .editorconfig
 
-# 1.0.3 / 2015-01-17
+## 1.0.3 / 2015-01-17
 
 - Optimised function runtime
 - Added `files` to `package.json`
 
-# 1.0.2 / 2014-12-17
+## 1.0.2 / 2014-12-17
 
 - Use `Array.isArray` shim
 - Remove ES5 incompatible code
 - Fixed repository path
 - Added new readme badges
 
-# 1.0.1 / 2014-08-27
+## 1.0.1 / 2014-08-27
 
 - Ensure installation works correctly on 0.8
 
-# 1.0.0 / 2014-08-17
+## 1.0.0 / 2014-08-17
 
 - No more API changes
 
-# 0.2.5 / 2014-08-07
+## 0.2.5 / 2014-08-07
 
 - Allow keys parameter to be omitted
 
-# 0.2.4 / 2014-08-02
+## 0.2.4 / 2014-08-02
 
 - Code coverage badge
 - Updated readme
 - Attach keys to the generated regexp
 
-# 0.2.3 / 2014-07-09
+## 0.2.3 / 2014-07-09
 
 - Add MIT license
 
-# 0.2.2 / 2014-07-06
+## 0.2.2 / 2014-07-06
 
 - A passed in trailing slash in non-strict mode will become optional
 - In non-end mode, the optional trailing slash will only match at the end
 
-# 0.2.1 / 2014-06-11
+## 0.2.1 / 2014-06-11
 
 - Fixed a major capturing group regexp regression
 
-# 0.2.0 / 2014-06-09
+## 0.2.0 / 2014-06-09
 
 - Improved support for arrays
 - Improved support for regexps
@@ -150,20 +152,20 @@
 - Updated readme
 - Provide delimiter information with keys array
 
-# 0.1.2 / 2014-03-10
+## 0.1.2 / 2014-03-10
 
 - Move testing dependencies to `devDependencies`
 
-# 0.1.1 / 2014-03-10
+## 0.1.1 / 2014-03-10
 
 - Match entire substring with `options.end`
 - Properly handle ending and non-ending matches
 
-# 0.1.0 / 2014-03-06
+## 0.1.0 / 2014-03-06
 
 - Add `options.end`
 
-# 0.0.2 / 2013-02-10
+## 0.0.2 / 2013-02-10
 
 - Update to match current express
 - Add .license property to component.json

package/Readme.md

@@ -30,29 +30,30 @@ const { pathToRegexp, match, parse, compile } = require("path-to-regexp");
 - **keys** An array to populate with keys found in the path.
 - **options**
   - **sensitive** When `true` the regexp will be case sensitive. (default: `false`)
-  - **strict** When `true` the regexp allows an optional trailing delimiter to match. (default: `false`)
+  - **strict** When `true` the regexp won't allow 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: '[^\\/]+?' }]
+// regexp = /^\/foo(?:\/([^\/#\?]+?))[\/#\?]?$/i
+// 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");
@@ -64,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)?`, `/:foo(test)?`, or `{-:foo(test)}?`).
 
 ##### Optional
 
@@ -72,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 ]
@@ -83,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 ]
@@ -100,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
@@ -113,71 +181,60 @@ 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', ... }]
+const match = match("/café", { encode: encodeURI, decode: decodeURIComponent });
 
-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
+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
-
-The `match` function will return a function for transforming paths into parameters:
-
-```js
-const match = match("/user/:id");
+**Note:** [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) automatically encodes pathnames for you.
 
-match("/user/123"); //=> { path: '/user/123', index: 0, params: { id: '123' } }
-match("/invalid"); //=> false
-```
+##### Alternative Using Normalize
 
-### 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("/caf\u00E9");
+const input = encodeURI("/cafe\u0301");
 
 re.test(input); //=> false
 re.test(normalizePathname(input)); //=> true
 ```
 
-**Note:** It may be preferable to implement something in your own library that normalizes the pathname for matching. E.g. [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) automatically URI encodes paths for you, which would result in a consistent match.
-
-**Tip:** Consider using [`String.prototype.normalize`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize) to resolve unicode variants of the same string.
-
 ### Parse
 
 The `parse` function will return a list of strings and keys from a path string:
@@ -189,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.
@@ -202,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+");
 
@@ -224,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.
@@ -236,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): 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,26 +71,21 @@ 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`)
      */
     sensitive?: boolean;
     /**
-     * When `true` the regexp allows an optional trailing delimiter to match. (default: `false`)
+     * When `true` the regexp won't allow an optional trailing delimiter to match. (default: `false`)
      */
     strict?: boolean;
     /**
@@ -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;