JavaScript
Failed to load latest commit information.
.gitignore revival Aug 29, 2014
.travis.yml revival Aug 29, 2014
History.md revival Aug 29, 2014
LICENSE revival Aug 29, 2014
Readme.md revival Aug 29, 2014
component.json add DEPRECATED into description Aug 29, 2014
index.js add DEPRECATED console.log Aug 29, 2014
package.json revival Aug 29, 2014
test.js revival Aug 29, 2014

Readme.md

Path-to-RegExp

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

NPM version Build status Test coverage

Installation

npm install path-to-regexp --save

Usage

var pathToRegexp = require('path-to-regexp');

// pathToRegexp(path, keys, options);
  • 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', delimiter: '/', repeat: false, optional: false }]

Parameters

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

Named Parameters

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', ... }]

re.exec('/test/route');
//=> ['/test/route', 'test', 'route']

Suffixed Parameters

Optional

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 }]

re.exec('/test');
//=> ['/test', 'test', undefined]

re.exec('/test/route');
//=> ['/test', 'test', 'route']
Zero or more

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 }]

re.exec('/');
//=> ['/', undefined]

re.exec('/bar/baz');
//=> ['/bar/baz', 'bar/baz']
One or more

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 }]

re.exec('/');
//=> null

re.exec('/bar/baz');
//=> ['/bar/baz', 'bar/baz']

Custom Match Parameters

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', ... }]

re.exec('/123');
//=> ['/123', '123']

re.exec('/abc');
//=> null

Unnamed Parameters

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', ... }]

re.exec('/test/route');
//=> ['/test/route', 'test', 'route']

Compatibility with Express <= 4.x

Path-To-RegExp breaks compatibility with Express <= 4.x in a few ways:

  • RegExp special characters can now be used in the regular path. E.g. /user[(\\d+)]
  • All RegExp special characters can now be used inside the custom match. E.g. /:user(.*)
  • No more support for asterisk matching - use an explicit parameter instead. E.g. /(.*)
  • Parameters can have suffixes that augment meaning - *, + and ?. E.g. /:user*
  • Strings aren't interpreted as literal regexp strings - no more non-capturing groups, lookaheads, lookbehinds or nested matching groups (but you can still pass a regexp manually)

Live Demo

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

License

MIT