Add native match function to library

Author: blakeembrey

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')

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;

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-lock.json

@@ -41,6 +41,6 @@
     "nyc": "^14.1.1",
     "standard": "^14.1.0",
     "ts-node": "^8.3.0",
-    "typescript": "^3.0.1"
+    "typescript": "^3.7.2"
   }
 }

package.json

@@ -10,7 +10,7 @@ type Test = [
   pathToRegexp.Path,
   pathToRegexp.RegExpOptions & pathToRegexp.ParseOptions,
   pathToRegexp.Token[],
-  Array<[string, string[]]>,
+  Array<[string, string[], pathToRegexp.Match?]>,
   Array<[any, string] | [any, string, pathToRegexp.PathFunctionOptions]>
 ]
 
@@ -30,8 +30,8 @@ var TESTS: Test[] = [
       '/'
     ],
     [
-      ['/', ['/']],
-      ['/route', null]
+      ['/', ['/'], { path: '/', index: 0, params: {} }],
+      ['/route', null, false]
     ],
     [
       [null, '/'],
@@ -46,10 +46,10 @@ var TESTS: Test[] = [
       '/test'
     ],
     [
-      ['/test', ['/test']],
-      ['/route', null],
-      ['/test/route', null],
-      ['/test/', ['/test/']]
+      ['/test', ['/test'], { path: '/test', index: 0, params: {} }],
+      ['/route', null, false],
+      ['/test/route', null, false],
+      ['/test/', ['/test/'], { path: '/test/', index: 0, params: {} }]
     ],
     [
       [null, '/test'],
@@ -201,7 +201,7 @@ var TESTS: Test[] = [
       }
     ],
     [
-      ['/route', ['/route', 'route']]
+      ['/route', ['/route', 'route'], { path: '/route', index: 0, params: { test: 'route' } }]
     ],
     [
       [{}, null],
@@ -734,9 +734,9 @@ var TESTS: Test[] = [
       }
     ],
     [
-      ['/route', ['/route', 'route']],
-      ['/route/nested', null],
-      ['/', ['/', undefined]],
+      ['/route', ['/route', 'route'], { path: '/route', index: 0, params: { test: 'route' } }],
+      ['/route/nested', null, false],
+      ['/', ['/', undefined], { path: '/', index: 0, params: {} }],
       ['//', null]
     ],
     [
@@ -885,10 +885,10 @@ var TESTS: Test[] = [
       }
     ],
     [
-      ['/', null],
-      ['/route', ['/route', 'route']],
-      ['/some/basic/route', ['/some/basic/route', 'some/basic/route']],
-      ['//', null]
+      ['/', null, false],
+      ['/route', ['/route', 'route'], { path: '/route', index: 0, params: { test: ['route'] } }],
+      ['/some/basic/route', ['/some/basic/route', 'some/basic/route'], { path: '/some/basic/route', index: 0, params: { test: ['some', 'basic', 'route'] } }],
+      ['//', null, false]
     ],
     [
       [{}, null],
@@ -988,13 +988,14 @@ var TESTS: Test[] = [
       }
     ],
     [
-      ['/', ['/', undefined]],
-      ['//', null],
-      ['/route', ['/route', 'route']],
-      ['/some/basic/route', ['/some/basic/route', 'some/basic/route']]
+      ['/', ['/', undefined], { path: '/', index: 0, params: {} }],
+      ['//', null, false],
+      ['/route', ['/route', 'route'], { path: '/route', index: 0, params: { test: ['route'] } }],
+      ['/some/basic/route', ['/some/basic/route', 'some/basic/route'], { path: '/some/basic/route', index: 0, params: { test: ['some', 'basic', 'route'] } }]
     ],
     [
       [{}, ''],
+      [{ test: [] }, ''],
       [{ test: 'foobar' }, '/foobar'],
       [{ test: ['foo', 'bar'] }, '/foo/bar']
     ]
@@ -2782,18 +2783,18 @@ describe('path-to-regexp', function () {
             var toPath = pathToRegexp.compile(path as string, opts)
 
             compileCases.forEach(function (io) {
-              var input = io[0]
-              var output = io[1]
+              var params = io[0]
+              var path = io[1]
               var options = io[2]
 
-              if (output != null) {
-                it('should compile using ' + util.inspect(input), function () {
-                  expect(toPath(input, options)).to.equal(output)
+              if (path != null) {
+                it('should compile using ' + util.inspect(params), function () {
+                  expect(toPath(params, options)).to.equal(path)
                 })
               } else {
-                it('should not compile using ' + util.inspect(input), function () {
+                it('should not compile using ' + util.inspect(params), function () {
                   expect(function () {
-                    toPath(input, options)
+                    toPath(params, options)
                   }).to.throw(TypeError)
                 })
               }
@@ -2809,13 +2810,22 @@ describe('path-to-regexp', function () {
 
         describe('match' + (opts ? ' using ' + util.inspect(opts) : ''), function () {
           matchCases.forEach(function (io) {
-            var input = io[0]
-            var output = io[1]
-            var message = 'should' + (output ? ' ' : ' not ') + 'match ' + util.inspect(input)
+            var pathname = io[0]
+            var matches = io[1]
+            var params = io[2]
+            var message = 'should' + (matches ? ' ' : ' not ') + 'match ' + util.inspect(pathname)
 
             it(message, function () {
-              expect(exec(re, input)).to.deep.equal(output)
+              expect(exec(re, pathname)).to.deep.equal(matches)
             })
+
+            if (typeof path === "string" && params !== undefined) {
+              var match = pathToRegexp.match(path)
+
+              it(message + ' params', function () {
+                expect(match(pathname)).to.deep.equal(params)
+              })
+            }
           })
         })
       })