path-to-regexp 3.1.0 → 3.3.0

package/Readme.md

@@ -21,6 +21,7 @@ npm install path-to-regexp --save
 const pathToRegexp = require('path-to-regexp')
 
 // pathToRegexp(path, keys?, options?)
+// pathToRegexp.match(path)
 // pathToRegexp.parse(path)
 // pathToRegexp.compile(path)
 ```
@@ -150,9 +151,20 @@ regexpWord.exec('/users')
 
 **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 = pathToRegexp.match('/user/:id')
+
+match('/user/123') //=> { path: '/user/123', index: 0, params: { id: '123' } }
+match('/invalid') //=> false
+```
+
 ### Parse
 
-The parse function is exposed via `pathToRegexp.parse`. This will return an array of strings and keys.
+The `parse` function will return a list of strings and keys from a path string:
 
 ```js
 const tokens = pathToRegexp.parse('/route/:foo/(.*)')
@@ -171,7 +183,7 @@ console.log(tokens[2])
 
 ### Compile ("Reverse" Path-To-RegExp)
 
-Path-To-RegExp exposes a compile function for transforming a string into a valid path.
+The `compile` function will return a function for transforming parameters into a valid path:
 
 ```js
 const toPath = pathToRegexp.compile('/user/:id')
@@ -181,7 +193,7 @@ toPath({ id: 'café' }) //=> "/user/caf%C3%A9"
 toPath({ id: '/' }) //=> "/user/%2F"
 
 toPath({ id: ':/' }) //=> "/user/%3A%2F"
-toPath({ id: ':/' }, { encode: (value, token) => value }) //=> "/user/:/"
+toPath({ id: ':/' }, { encode: (value, token) => value, validate: false }) //=> "/user/:/"
 
 const toPathRepeated = pathToRegexp.compile('/:segment+')
 
@@ -193,7 +205,7 @@ 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"
+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.

package/index.d.ts

@@ -51,6 +51,16 @@ declare namespace pathToRegexp {
    */
   export function parse (path: string, options?: ParseOptions): Token[];
 
+  /**
+   * Create path match function from `path-to-regexp` spec.
+   */
+  export function match <P extends object = object> (path: string, options?: ParseOptions): MatchFunction<P>;
+
+  /**
+   * Create a path match function from `path-to-regexp` output.
+   */
+  export function regexpToFunction <P extends object = object> (re: RegExp, keys: Key[]): MatchFunction<P>;
+
   /**
    * Transforming an Express-style path into a valid path.
    */
@@ -86,9 +96,25 @@ declare namespace pathToRegexp {
     validate?: boolean;
   }
 
+  interface MatchFunctionOptions {
+    /**
+     * Function for decoding strings for params.
+     */
+    decode?: (value: string, token: Key) => string;
+  }
+
+  interface MatchResult <P extends object = object> {
+    path: string;
+    index: number;
+    params: P;
+  }
+
+  type Match <P extends object = object> = false | MatchResult<P>;
+
   export type Token = string | Key;
   export type Path = string | RegExp | Array<string | RegExp>;
   export type PathFunction <P extends object = object> = (data?: P, options?: PathFunctionOptions) => string;
+  export type MatchFunction <P extends object = object> = (path: string, options?: MatchFunctionOptions) => Match<P>;
 }
 
 export = pathToRegexp;

package/index.js

@@ -2,6 +2,8 @@
  * Expose `pathToRegexp`.
  */
 module.exports = pathToRegexp
+module.exports.match = match
+module.exports.regexpToFunction = regexpToFunction
 module.exports.parse = parse
 module.exports.compile = compile
 module.exports.tokensToFunction = tokensToFunction
@@ -88,6 +90,7 @@ function parse (str, options) {
     var optional = modifier === '?' || modifier === '*'
     var pattern = capture || group
     var delimiter = prev || defaultDelimiter
+    var prevText = prev || (typeof tokens[tokens.length - 1] === 'string' ? tokens[tokens.length - 1] : '')
 
     tokens.push({
       name: name || key++,
@@ -97,7 +100,7 @@ function parse (str, options) {
       repeat: repeat,
       pattern: pattern
         ? escapeGroup(pattern)
-        : '[^' + escapeString(delimiter === defaultDelimiter ? delimiter : (delimiter + defaultDelimiter)) + ']+?'
+        : restrictBacktrack(delimiter, defaultDelimiter, prevText)
     })
   }
 
@@ -109,6 +112,16 @@ function parse (str, options) {
   return tokens
 }
 
+function restrictBacktrack (delimiter, defaultDelimiter, prevText) {
+  var charGroup = '[^' + escapeString(delimiter === defaultDelimiter ? delimiter : (delimiter + defaultDelimiter)) + ']'
+
+  if (!prevText || prevText.indexOf(delimiter) > -1 || prevText.indexOf(defaultDelimiter) > -1) {
+    return charGroup + '+?'
+  }
+
+  return escapeString(prevText) + '|(?:(?!' + escapeString(prevText) + ')' + charGroup + ')+?'
+}
+
 /**
  * Compile a string to a template function for the path.
  *
@@ -120,6 +133,46 @@ function compile (str, options) {
   return tokensToFunction(parse(str, options), options)
 }
 
+/**
+ * Create path match function from `path-to-regexp` spec.
+ */
+function match (str, options) {
+  var keys = []
+  var re = pathToRegexp(str, keys, options)
+  return regexpToFunction(re, keys)
+}
+
+/**
+ * Create a path match function from `path-to-regexp` output.
+ */
+function regexpToFunction (re, keys) {
+  return function (pathname, options) {
+    var m = re.exec(pathname)
+    if (!m) return false
+
+    var path = m[0]
+    var index = m.index
+    var params = {}
+    var decode = (options && options.decode) || decodeURIComponent
+
+    for (var i = 1; i < m.length; i++) {
+      if (m[i] === undefined) continue
+
+      var key = keys[i - 1]
+
+      if (key.repeat) {
+        params[key.name] = m[i].split(key.delimiter).map(function (value) {
+          return decode(value, key)
+        })
+      } else {
+        params[key.name] = decode(m[i], key)
+      }
+    }
+
+    return { path: path, index: index, params: params }
+  }
+}
+
 /**
  * Expose a method for transforming tokens into the path function.
  */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "path-to-regexp",
   "description": "Express style path to RegExp utility",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "main": "index.js",
   "typings": "index.d.ts",
   "files": [
@@ -12,7 +12,8 @@
   "scripts": {
     "lint": "standard",
     "test-spec": "mocha --require ts-node/register -R spec --bail test.ts",
-    "test-cov": "istanbul cover node_modules/mocha/bin/_mocha -- --require ts-node/register -R spec test.ts",
+    "test-cov": "nyc --reporter=lcov mocha -- --require ts-node/register -R spec test.ts",
+    "coverage": "nyc report --reporter=text-lcov",
     "test": "npm run lint && npm run test-cov"
   },
   "keywords": [
@@ -36,10 +37,10 @@
     "@types/mocha": "^5.2.5",
     "@types/node": "^12.7.3",
     "chai": "^4.1.1",
-    "istanbul": "^0.4.5",
     "mocha": "^6.2.0",
+    "nyc": "^14.1.1",
     "standard": "^14.1.0",
     "ts-node": "^8.3.0",
-    "typescript": "^3.0.1"
+    "typescript": "^3.7.2"
   }
 }

package/History.md

@@ -1,202 +0,0 @@
-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
-==================
-
-  * Pass `token` as second argument to `encode` option (e.g. `encode(value, token)`)
-
-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
-==================
-
-  * 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`)
-  * Remove `isarray` dependency
-  * Explicitly handle trailing delimiters instead of trimming them (e.g. `/test/` is now treated as `/test/` instead of `/test` when matching)
-  * Remove overloaded `keys` argument that accepted `options`
-  * Remove `keys` list attached to the `RegExp` output
-  * 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
-==================
-
-  * 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
-==================
-
-  * 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
-==================
-
-  * Add `\\` to the ignore character group to avoid backtracking on mismatched parens
-
-1.5.2 / 2016-06-15
-==================
-
-  * Escape `\\` in string segments of regexp
-
-1.5.1 / 2016-06-08
-==================
-
-  * Add `index.d.ts` to NPM package
-
-1.5.0 / 2016-05-20
-==================
-
-  * Handle partial token segments (better)
-  * Allow compile to handle asterisk token segments
-
-1.4.0 / 2016-05-18
-==================
-
-  * Handle RegExp unions in path matching groups
-
-1.3.0 / 2016-05-08
-==================
-
-  * Clarify README language and named parameter token support
-  * Support advanced Closure Compiler with type annotations
-  * Add pretty paths options to compiled function output
-  * Add TypeScript definition to project
-  * Improved prefix handling with non-complete segment parameters (E.g. `/:foo?-bar`)
-
-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
-==================
-
-  * Add support for matching an asterisk (`*`) as an unnamed match everything group (`(.*)`)
-
-1.1.1 / 2015-05-11
-==================
-
-  * Expose methods for working with path tokens
-
-1.1.0 / 2015-05-09
-==================
-
-  * Expose the parser implementation to consumers
-  * Implement a compiler function to generate valid strings
-  * Huge refactor of tests to be more DRY and cover new parse and compile functions
-  * Use chai in tests
-  * Add .editorconfig
-
-1.0.3 / 2015-01-17
-==================
-
-  * Optimised function runtime
-  * Added `files` to `package.json`
-
-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
-==================
-
-  * Ensure installation works correctly on 0.8
-
-1.0.0 / 2014-08-17
-==================
-
-  * No more API changes
-
-0.2.5 / 2014-08-07
-==================
-
-  * Allow keys parameter to be omitted
-
-0.2.4 / 2014-08-02
-==================
-
-  * Code coverage badge
-  * Updated readme
-  * Attach keys to the generated regexp
-
-0.2.3 / 2014-07-09
-==================
-
-  * Add MIT license
-
-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
-==================
-
-  * Fixed a major capturing group regexp regression
-
-0.2.0 / 2014-06-09
-==================
-
-  * Improved support for arrays
-  * Improved support for regexps
-  * Better support for non-ending strict mode matches with a trailing slash
-  * Travis CI support
-  * Block using regexp special characters in the path
-  * Removed support for the asterisk to match all
-  * New support for parameter suffixes - `*`, `+` and `?`
-  * Updated readme
-  * Provide delimiter information with keys array
-
-0.1.2 / 2014-03-10
-==================
-
-  * Move testing dependencies to `devDependencies`
-
-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
-==================
-
-  * Add `options.end`
-
-0.0.2 / 2013-02-10
-==================
-
-  * Update to match current express
-  * Add .license property to component.json