Express style path to RegExp utility


Turn an Express-style path string such as /user/:name into a regular expression.

npm install path-to-regexp --save
var pathToRegexp = require('path-to-regexp')
// pathToRegexp(path, keys, options) 
// pathToRegexp.parse(path) 
// pathToRegexp.compile(path) 
  • path A string in the express format, an array of strings, or a regular expression.
  • keys An array to be populated with the keys present in the url.
  • 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)
var keys = []
var re = pathToRegexp('/foo/:bar', keys)
// re = /^\/foo\/([^\/]+?)\/?$/i 
// keys = [{ name: 'bar', prefix: '/', delimiter: '/', optional: false, repeat: false, pattern: '[^\\/]+?' }] 

The path has the ability to define parameters and automatically populate the keys array.

Named parameters are defined by prefixing a colon to the parameter name (:foo). By default, this parameter will match up to the next path segment.

var re = pathToRegexp('/:foo/:bar', keys)
// keys = [{ name: 'foo', ... }, { name: 'bar', ... }] 
//=> ['/test/route', 'test', 'route'] 

Parameters can be suffixed with a question mark (?) to make the entire parameter optional. This will also make any prefixed path delimiter optional (/ or .).

var re = pathToRegexp('/:foo/:bar?', keys)
// keys = [{ name: 'foo', ... }, { name: 'bar', delimiter: '/', optional: true, repeat: false }] 
//=> ['/test', 'test', undefined] 
//=> ['/test', 'test', 'route'] 

Parameters can be suffixed with an asterisk (*) to denote a zero or more parameter match. The prefixed path delimiter is also taken into account for the match.

var re = pathToRegexp('/:foo*', keys)
// keys = [{ name: 'foo', delimiter: '/', optional: true, repeat: true }] 
//=> ['/', undefined] 
//=> ['/bar/baz', 'bar/baz'] 

Parameters can be suffixed with a plus sign (+) to denote a one or more parameters match. The prefixed path delimiter is included in the match.

var re = pathToRegexp('/:foo+', keys)
// keys = [{ name: 'foo', delimiter: '/', optional: false, repeat: true }] 
//=> null 
//=> ['/bar/baz', 'bar/baz'] 

All parameters can be provided a custom matching regexp and override the default. Please note: Backslashes need to be escaped in strings.

var re = pathToRegexp('/:foo(\\d+)', keys)
// keys = [{ name: 'foo', ... }] 
//=> ['/123', '123'] 
//=> null 

It is possible to write an unnamed parameter that is only a matching group. It works the same as a named parameter, except it will be numerically indexed.

var re = pathToRegexp('/:foo/(.*)', keys)
// keys = [{ name: 'foo', ... }, { name: '0', ... }] 
//=> ['/test/route', 'test', 'route'] 

An asterisk can be used for matching everything. It is equivalent to an unnamed matching group of (.*).

var re = pathToRegexp('/foo/*', keys)
// keys = [{ name: '0', ... }] 
//=> ['/foo/bar/baz', 'bar/baz'] 

The parse function is exposed via pathToRegexp.parse. This will yield an array of strings and keys.

var tokens = pathToRegexp.parse('/route/:foo/(.*)')
//=> "/route" 
//=> { name: 'foo', prefix: '/', delimiter: '/', optional: false, repeat: false, pattern: '[^\\/]+?' } 
//=> { name: 0, prefix: '/', delimiter: '/', optional: false, repeat: false, pattern: '.*' } 

Note: This method only works with strings.

Path-To-RegExp exposes a compile function for transforming an express path into valid path. Confusing enough? This example will straighten everything out for you.

var toPath = pathToRegexp.compile('/user/:id')
toPath({ id: 123 }) //=> "/user/123" 
toPath({ id: 'café' }) //=> "/user/caf%C3%A9" 
toPath({ id: '/' }) //=> "%2F" 
var toPathRepeated = pathToRegexp.compile('/:segment+')
toPathRepeated({ segment: 'foo' }) //=> "/foo" 
toPathRepeated({ segment: ['a', 'b', 'c'] }) //=> "/a/b/c" 
var toPathRegexp = pathToRegexp.compile('/user/:id(\\d+)')
toPathRegexp({ id: 123 }) //=> "/user/123" 
toPathRegexp({ id: '123' }) //=> "/user/123" 
toPathRegexp({ id: 'abc' }) //=> throws TypeError 

Note: The generated function will throw on any invalid input. It will execute all necessary checks to ensure the generated path is valid. This method only works with strings.

Path-To-RegExp exposes the two functions used internally that accept an array of tokens.

  • pathToRegexp.tokensToRegExp(tokens, options) Transform an array of tokens into a matching regular expression.
  • pathToRegexp.tokensToFunction(tokens) Transform an array of tokens into a path generator function.

Path-To-RegExp breaks compatibility with Express <= 4.x:

  • No longer a direct conversion to a RegExp with sugar on top - it's a path matcher with named and unnamed matching groups
    • It's unlikely you previously abused this feature, it's rare and you could always use a RegExp instead
  • All matching RegExp special characters can be used in a matching group. E.g. /:user(.*)
    • Other RegExp features are not support - no nested matching groups, non-capturing groups or look aheads
  • Parameters have suffixes that augment meaning - *, + and ?. E.g. /:user*

You can see a live demo of this library in use at express-route-tester.