path-to-regexp 3.1.0 → 3.2.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
@@ -120,6 +122,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.2.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"
   }
 }