path-to-regexp 2.2.1 → 3.1.0

package/History.md

@@ -1,3 +1,24 @@
+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
+==================
+
+  * Support `start` option to disable anchoring from beginning of the string
+
+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
+==================
+
+  * Allow empty string with `end: false` to match both relative and absolute paths
+
 2.2.0 / 2018-03-06
 ==================
 

package/Readme.md

@@ -18,7 +18,7 @@ npm install path-to-regexp --save
 ## Usage
 
 ```javascript
-var pathToRegexp = require('path-to-regexp')
+const pathToRegexp = require('path-to-regexp')
 
 // pathToRegexp(path, keys?, options?)
 // pathToRegexp.parse(path)
@@ -26,24 +26,24 @@ var pathToRegexp = require('path-to-regexp')
 ```
 
 - **path** A string, array of strings, or a regular expression.
-- **keys** An array to be populated with the keys found in the path.
+- **keys** An array to populate with keys found in the path.
 - **options**
-  - **sensitive** When `true` the route will be case sensitive. (default: `false`)
-  - **strict** When `false` the trailing slash is optional. (default: `false`)
-  - **end** When `false` the path will match at the beginning. (default: `true`)
-  - Advanced options (use for non-pathname strings, e.g. host names):
-    - **delimiter** The default delimiter for segments. (default: `'/'`)
-    - **endsWith** Optional character, or list of characters, to treat as "end" characters.
-    - **delimiters** List of characters to consider delimiters when parsing. (default: `'./'`)
+  - **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`)
+  - **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: `'/'`)
+  - **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)
 
 ```javascript
-var keys = []
-var re = pathToRegexp('/foo/:bar', keys)
-// re = /^\/foo\/([^\/]+?)\/?$/i
+const keys = []
+const regexp = pathToRegexp('/foo/:bar', keys)
+// regexp = /^\/foo\/([^\/]+?)\/?$/i
 // keys = [{ name: 'bar', prefix: '/', delimiter: '/', optional: false, repeat: false, pattern: '[^\\/]+?' }]
 ```
 
-**Please note:** The `RegExp` returned by `path-to-regexp` is intended for ordered data (e.g. pathnames, hostnames). It does not handle arbitrary 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).
 
 ### Parameters
 
@@ -51,17 +51,17 @@ The path argument is used to define parameters and populate the list of keys.
 
 #### Named Parameters
 
-Named parameters are defined by prefixing a colon to the parameter name (`:foo`). By default, the parameter will match until the following path segment.
+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. `[^/]+`).
 
 ```js
-var re = pathToRegexp('/:foo/:bar')
+const regexp = pathToRegexp('/:foo/:bar')
 // keys = [{ name: 'foo', prefix: '/', ... }, { name: 'bar', prefix: '/', ... }]
 
-re.exec('/test/route')
-//=> ['/test/route', 'test', 'route']
+regexp.exec('/test/route')
+//=> [ '/test/route', 'test', 'route', index: 0, input: '/test/route', groups: undefined ]
 ```
 
-**Please note:** Parameter names must be made up of "word characters" (`[A-Za-z0-9_]`).
+**Please note:** Parameter names must use "word characters" (`[A-Za-z0-9_]`).
 
 #### Parameter Modifiers
 
@@ -70,83 +70,92 @@ re.exec('/test/route')
 Parameters can be suffixed with a question mark (`?`) to make the parameter optional.
 
 ```js
-var re = pathToRegexp('/:foo/:bar?')
+const regexp = pathToRegexp('/:foo/:bar?')
 // keys = [{ name: 'foo', ... }, { name: 'bar', delimiter: '/', optional: true, repeat: false }]
 
-re.exec('/test')
-//=> ['/test', 'test', undefined]
+regexp.exec('/test')
+//=> [ '/test', 'test', undefined, index: 0, input: '/test', groups: undefined ]
 
-re.exec('/test/route')
-//=> ['/test', 'test', 'route']
+regexp.exec('/test/route')
+//=> [ '/test/route', 'test', 'route', index: 0, input: '/test/route', groups: undefined ]
 ```
 
-**Tip:** If the parameter is the _only_ value in the segment, the prefix is also optional.
+**Tip:** The prefix is also optional, escape the prefix `\/` to make it required.
 
 ##### Zero or more
 
-Parameters can be suffixed with an asterisk (`*`) to denote a zero or more parameter matches. The prefix is taken into account for each match.
+Parameters can be suffixed with an asterisk (`*`) to denote a zero or more parameter matches. The prefix is used for each match.
 
 ```js
-var re = pathToRegexp('/:foo*')
+const regexp = pathToRegexp('/:foo*')
 // keys = [{ name: 'foo', delimiter: '/', optional: true, repeat: true }]
 
-re.exec('/')
-//=> ['/', undefined]
+regexp.exec('/')
+//=> [ '/', undefined, index: 0, input: '/', groups: undefined ]
 
-re.exec('/bar/baz')
-//=> ['/bar/baz', 'bar/baz']
+regexp.exec('/bar/baz')
+//=> [ '/bar/baz', 'bar/baz', index: 0, input: '/bar/baz', groups: undefined ]
 ```
 
 ##### One or more
 
-Parameters can be suffixed with a plus sign (`+`) to denote a one or more parameter matches. The prefix is taken into account for each match.
+Parameters can be suffixed with a plus sign (`+`) to denote a one or more parameter matches. The prefix is used for each match.
 
 ```js
-var re = pathToRegexp('/:foo+')
+const regexp = pathToRegexp('/:foo+')
 // keys = [{ name: 'foo', delimiter: '/', optional: false, repeat: true }]
 
-re.exec('/')
+regexp.exec('/')
 //=> null
 
-re.exec('/bar/baz')
-//=> ['/bar/baz', 'bar/baz']
+regexp.exec('/bar/baz')
+//=> [ '/bar/baz','bar/baz', index: 0, input: '/bar/baz', groups: undefined ]
+```
+
+#### Unnamed Parameters
+
+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.
+
+```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 ]
 ```
 
 #### Custom Matching Parameters
 
-All parameters can be provided a custom regexp, which overrides the default match (`[^\/]+`). For example, you can match digits in the path:
+All parameters can have a custom regexp, which overrides the default match (`[^/]+`). For example, you can match digits or names in a path:
 
 ```js
-var re = pathToRegexp('/icon-:foo(\\d+).png')
+const regexpNumbers = pathToRegexp('/icon-:foo(\\d+).png')
 // keys = [{ name: 'foo', ... }]
 
-re.exec('/icon-123.png')
+regexpNumbers.exec('/icon-123.png')
 //=> ['/icon-123.png', '123']
 
-re.exec('/icon-abc.png')
+regexpNumbers.exec('/icon-abc.png')
 //=> null
-```
 
-**Please note:** Backslashes need to be escaped with another backslash in strings.
+const regexpWord = pathToRegexp('/(user|u)')
+// keys = [{ name: 0, ... }]
 
-#### Unnamed Parameters
+regexpWord.exec('/u')
+//=> ['/u', 'u']
 
-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.
-
-```js
-var re = pathToRegexp('/:foo/(.*)')
-// keys = [{ name: 'foo', ... }, { name: 0, ... }]
-
-re.exec('/test/route')
-//=> ['/test/route', 'test', 'route']
+regexpWord.exec('/users')
+//=> null
 ```
 
+**Tip:** Backslashes need to be escaped with another backslash in JavaScript strings.
+
 ### Parse
 
 The parse function is exposed via `pathToRegexp.parse`. This will return an array of strings and keys.
 
 ```js
-var tokens = pathToRegexp.parse('/route/:foo/(.*)')
+const tokens = pathToRegexp.parse('/route/:foo/(.*)')
 
 console.log(tokens[0])
 //=> "/route"
@@ -165,7 +174,7 @@ console.log(tokens[2])
 Path-To-RegExp exposes a compile function for transforming a string into a valid path.
 
 ```js
-var toPath = pathToRegexp.compile('/user/:id')
+const toPath = pathToRegexp.compile('/user/:id')
 
 toPath({ id: 123 }) //=> "/user/123"
 toPath({ id: 'café' }) //=> "/user/caf%C3%A9"
@@ -174,16 +183,17 @@ toPath({ id: '/' }) //=> "/user/%2F"
 toPath({ id: ':/' }) //=> "/user/%3A%2F"
 toPath({ id: ':/' }, { encode: (value, token) => value }) //=> "/user/:/"
 
-var toPathRepeated = pathToRegexp.compile('/:segment+')
+const toPathRepeated = pathToRegexp.compile('/:segment+')
 
 toPathRepeated({ segment: 'foo' }) //=> "/foo"
 toPathRepeated({ segment: ['a', 'b', 'c'] }) //=> "/a/b/c"
 
-var toPathRegexp = pathToRegexp.compile('/user/:id(\\d+)')
+const toPathRegexp = pathToRegexp.compile('/user/:id(\\d+)')
 
 toPathRegexp({ id: 123 }) //=> "/user/123"
 toPathRegexp({ id: '123' }) //=> "/user/123"
 toPathRegexp({ id: 'abc' }) //=> Throws `TypeError`.
+toPathRegexp({ id: 'abc' }, { validate: true }) //=> "/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.
@@ -198,11 +208,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 index)
-* `prefix` The prefix character for the segment (`/` or `.`)
-* `delimiter` The delimiter for the segment (same as prefix or `/`)
+* `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`)
-* `partial` Indicates this token is a partial path segment (`boolean`)
 * `pattern` The RegExp used to match this token (`string`)
 
 ## Compatibility with Express <= 4.x

package/index.d.ts

@@ -3,17 +3,21 @@ declare function pathToRegexp (path: pathToRegexp.Path, keys?: pathToRegexp.Key[
 declare namespace pathToRegexp {
   export interface RegExpOptions {
     /**
-     * When `true` the route will be case sensitive. (default: `false`)
+     * When `true` the regexp will be case sensitive. (default: `false`)
      */
     sensitive?: boolean;
     /**
-     * When `false` the trailing slash is optional. (default: `false`)
+     * When `true` the regexp allows an optional trailing delimiter to match. (default: `false`)
      */
     strict?: boolean;
     /**
-     * When `false` the path will match at the beginning. (default: `true`)
+     * When `true` the regexp will match to the end of the string. (default: `true`)
      */
     end?: boolean;
+    /**
+     * When `true` the regexp will match from the beginning of the string. (default: `true`)
+     */
+    start?: boolean;
     /**
      * Sets the final character for non-ending optimistic matches. (default: `/`)
      */
@@ -22,6 +26,10 @@ declare namespace pathToRegexp {
      * List of characters that can also be "end" characters.
      */
     endsWith?: string | string[];
+    /**
+     * List of characters to consider delimiters when parsing. (default: `undefined`, any character)
+     */
+    whitelist?: string | string[];
   }
 
   export interface ParseOptions {
@@ -29,10 +37,13 @@ declare namespace pathToRegexp {
      * Set the default delimiter for repeat parameters. (default: `'/'`)
      */
     delimiter?: string;
+  }
+
+  export interface TokensToFunctionOptions {
     /**
-     * List of valid delimiter characters. (default: `'./'`)
+     * When `true` the regexp will be case sensitive. (default: `false`)
      */
-    delimiters?: string | string[];
+    sensitive?: boolean;
   }
 
   /**
@@ -43,12 +54,12 @@ declare namespace pathToRegexp {
   /**
    * Transforming an Express-style path into a valid path.
    */
-  export function compile (path: string, options?: ParseOptions): PathFunction;
+  export function compile <P extends object = object> (path: string, options?: ParseOptions & TokensToFunctionOptions): PathFunction<P>;
 
   /**
    * Transform an array of tokens into a path generator function.
    */
-  export function tokensToFunction (tokens: Token[]): PathFunction;
+  export function tokensToFunction <P extends object = object> (tokens: Token[], options?: TokensToFunctionOptions): PathFunction<P>;
 
   /**
    * Transform an array of tokens into a matching regular expression.
@@ -62,7 +73,6 @@ declare namespace pathToRegexp {
     optional: boolean;
     repeat: boolean;
     pattern: string;
-    partial: boolean;
   }
 
   interface PathFunctionOptions {
@@ -70,11 +80,15 @@ declare namespace pathToRegexp {
      * Function for encoding input strings for output.
      */
     encode?: (value: string, token: Key) => string;
+    /**
+     * When `false` the function can produce an invalid (unmatched) path. (default: `true`)
+     */
+    validate?: boolean;
   }
 
   export type Token = string | Key;
   export type Path = string | RegExp | Array<string | RegExp>;
-  export type PathFunction = (data?: Object, options?: PathFunctionOptions) => string;
+  export type PathFunction <P extends object = object> = (data?: P, options?: PathFunctionOptions) => string;
 }
 
 export = pathToRegexp;

package/index.js

@@ -11,7 +11,6 @@ module.exports.tokensToRegExp = tokensToRegExp
  * Default configs.
  */
 var DEFAULT_DELIMITER = '/'
-var DEFAULT_DELIMITERS = './'
 
 /**
  * The main path matching regexp utility.
@@ -25,8 +24,8 @@ var PATH_REGEXP = new RegExp([
   // Match Express-style parameters and un-named parameters with a prefix
   // and optional suffixes. Matches appear as:
   //
-  // "/:test(\\d+)?" => ["/", "test", "\d+", undefined, "?"]
-  // "/route(\\d+)"  => [undefined, undefined, undefined, "\d+", undefined]
+  // ":test(\\d+)?" => ["test", "\d+", undefined, "?"]
+  // "(\\d+)"  => [undefined, undefined, "\d+", undefined]
   '(?:\\:(\\w+)(?:\\(((?:\\\\.|[^\\\\()])+)\\))?|\\(((?:\\\\.|[^\\\\()])+)\\))([+*?])?'
 ].join('|'), 'g')
 
@@ -43,7 +42,7 @@ function parse (str, options) {
   var index = 0
   var path = ''
   var defaultDelimiter = (options && options.delimiter) || DEFAULT_DELIMITER
-  var delimiters = (options && options.delimiters) || DEFAULT_DELIMITERS
+  var whitelist = (options && options.whitelist) || undefined
   var pathEscaped = false
   var res
 
@@ -62,7 +61,6 @@ function parse (str, options) {
     }
 
     var prev = ''
-    var next = str[index]
     var name = res[2]
     var capture = res[3]
     var group = res[4]
@@ -70,9 +68,11 @@ function parse (str, options) {
 
     if (!pathEscaped && path.length) {
       var k = path.length - 1
+      var c = path[k]
+      var matches = whitelist ? whitelist.indexOf(c) > -1 : true
 
-      if (delimiters.indexOf(path[k]) > -1) {
-        prev = path[k]
+      if (matches) {
+        prev = c
         path = path.slice(0, k)
       }
     }
@@ -84,11 +84,10 @@ function parse (str, options) {
       pathEscaped = false
     }
 
-    var partial = prev !== '' && next !== undefined && next !== prev
     var repeat = modifier === '+' || modifier === '*'
     var optional = modifier === '?' || modifier === '*'
-    var delimiter = prev || defaultDelimiter
     var pattern = capture || group
+    var delimiter = prev || defaultDelimiter
 
     tokens.push({
       name: name || key++,
@@ -96,8 +95,9 @@ function parse (str, options) {
       delimiter: delimiter,
       optional: optional,
       repeat: repeat,
-      partial: partial,
-      pattern: pattern ? escapeGroup(pattern) : '[^' + escapeString(delimiter) + ']+?'
+      pattern: pattern
+        ? escapeGroup(pattern)
+        : '[^' + escapeString(delimiter === defaultDelimiter ? delimiter : (delimiter + defaultDelimiter)) + ']+?'
     })
   }
 
@@ -117,26 +117,27 @@ function parse (str, options) {
  * @return {!function(Object=, Object=)}
  */
 function compile (str, options) {
-  return tokensToFunction(parse(str, options))
+  return tokensToFunction(parse(str, options), options)
 }
 
 /**
  * Expose a method for transforming tokens into the path function.
  */
-function tokensToFunction (tokens) {
+function tokensToFunction (tokens, options) {
   // Compile all the tokens into regexps.
   var matches = new Array(tokens.length)
 
   // Compile all the patterns before compilation.
   for (var i = 0; i < tokens.length; i++) {
     if (typeof tokens[i] === 'object') {
-      matches[i] = new RegExp('^(?:' + tokens[i].pattern + ')$')
+      matches[i] = new RegExp('^(?:' + tokens[i].pattern + ')$', flags(options))
     }
   }
 
   return function (data, options) {
     var path = ''
     var encode = (options && options.encode) || encodeURIComponent
+    var validate = options ? options.validate !== false : true
 
     for (var i = 0; i < tokens.length; i++) {
       var token = tokens[i]
@@ -163,7 +164,7 @@ function tokensToFunction (tokens) {
         for (var j = 0; j < value.length; j++) {
           segment = encode(value[j], token)
 
-          if (!matches[i].test(segment)) {
+          if (validate && !matches[i].test(segment)) {
             throw new TypeError('Expected all "' + token.name + '" to match "' + token.pattern + '"')
           }
 
@@ -176,7 +177,7 @@ function tokensToFunction (tokens) {
       if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
         segment = encode(String(value), token)
 
-        if (!matches[i].test(segment)) {
+        if (validate && !matches[i].test(segment)) {
           throw new TypeError('Expected "' + token.name + '" to match "' + token.pattern + '", but got "' + segment + '"')
         }
 
@@ -184,12 +185,7 @@ function tokensToFunction (tokens) {
         continue
       }
 
-      if (token.optional) {
-        // Prepend partial segment prefixes.
-        if (token.partial) path += token.prefix
-
-        continue
-      }
+      if (token.optional) continue
 
       throw new TypeError('Expected "' + token.name + '" to be ' + (token.repeat ? 'an array' : 'a string'))
     }
@@ -249,7 +245,6 @@ function regexpToRegexp (path, keys) {
         delimiter: null,
         optional: false,
         repeat: false,
-        partial: false,
         pattern: null
       })
     }
@@ -300,12 +295,11 @@ function tokensToRegExp (tokens, keys, options) {
   options = options || {}
 
   var strict = options.strict
+  var start = options.start !== false
   var end = options.end !== false
-  var delimiter = escapeString(options.delimiter || DEFAULT_DELIMITER)
-  var delimiters = options.delimiters || DEFAULT_DELIMITERS
+  var delimiter = options.delimiter || DEFAULT_DELIMITER
   var endsWith = [].concat(options.endsWith || []).map(escapeString).concat('$').join('|')
-  var route = ''
-  var isEndDelimited = tokens.length === 0
+  var route = start ? '^' : ''
 
   // Iterate over the tokens and create our regexp string.
   for (var i = 0; i < tokens.length; i++) {
@@ -313,37 +307,40 @@ function tokensToRegExp (tokens, keys, options) {
 
     if (typeof token === 'string') {
       route += escapeString(token)
-      isEndDelimited = i === tokens.length - 1 && delimiters.indexOf(token[token.length - 1]) > -1
     } else {
-      var prefix = escapeString(token.prefix)
       var capture = token.repeat
-        ? '(?:' + token.pattern + ')(?:' + prefix + '(?:' + token.pattern + '))*'
+        ? '(?:' + token.pattern + ')(?:' + escapeString(token.delimiter) + '(?:' + token.pattern + '))*'
         : token.pattern
 
       if (keys) keys.push(token)
 
       if (token.optional) {
-        if (token.partial) {
-          route += prefix + '(' + capture + ')?'
+        if (!token.prefix) {
+          route += '(' + capture + ')?'
         } else {
-          route += '(?:' + prefix + '(' + capture + '))?'
+          route += '(?:' + escapeString(token.prefix) + '(' + capture + '))?'
         }
       } else {
-        route += prefix + '(' + capture + ')'
+        route += escapeString(token.prefix) + '(' + capture + ')'
       }
     }
   }
 
   if (end) {
-    if (!strict) route += '(?:' + delimiter + ')?'
+    if (!strict) route += '(?:' + escapeString(delimiter) + ')?'
 
     route += endsWith === '$' ? '$' : '(?=' + endsWith + ')'
   } else {
-    if (!strict) route += '(?:' + delimiter + '(?=' + endsWith + '))?'
-    if (!isEndDelimited) route += '(?=' + delimiter + '|' + endsWith + ')'
+    var endToken = tokens[tokens.length - 1]
+    var isEndDelimited = typeof endToken === 'string'
+      ? endToken[endToken.length - 1] === delimiter
+      : endToken === undefined
+
+    if (!strict) route += '(?:' + escapeString(delimiter) + '(?=' + endsWith + '))?'
+    if (!isEndDelimited) route += '(?=' + escapeString(delimiter) + '|' + endsWith + ')'
   }
 
-  return new RegExp('^' + route, flags(options))
+  return new RegExp(route, flags(options))
 }
 
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "path-to-regexp",
   "description": "Express style path to RegExp utility",
-  "version": "2.2.1",
+  "version": "3.1.0",
   "main": "index.js",
   "typings": "index.d.ts",
   "files": [
@@ -33,13 +33,13 @@
   },
   "devDependencies": {
     "@types/chai": "^4.0.4",
-    "@types/mocha": "^2.2.42",
-    "@types/node": "^8.0.24",
+    "@types/mocha": "^5.2.5",
+    "@types/node": "^12.7.3",
     "chai": "^4.1.1",
     "istanbul": "^0.4.5",
-    "mocha": "^3.5.0",
-    "standard": "^10.0.3",
-    "ts-node": "^3.3.0",
-    "typescript": "^2.4.2"
+    "mocha": "^6.2.0",
+    "standard": "^14.1.0",
+    "ts-node": "^8.3.0",
+    "typescript": "^3.0.1"
   }
 }