Repository files navigation

Turn a path string such as/user/:name into a regular expression.

npm install path-to-regexp --save

const{ pathToRegexp, match, parse, compile}=require("path-to-regexp");// pathToRegexp(path, options?)// match(path, options?)// parse(path, options?)// compile(path, options?)

ThepathToRegexp function returns a regular expression withkeys as a property. It accepts the following arguments:

• path A string.
• options(optional)
  • sensitive Regexp will be case sensitive. (default:false)
  • trailing Allows optional trailing delimiter to match. (default:true)
  • strict Verify patterns are valid and safe to use. (default:false, recommended:true)
  • end Match to the end of the string. (default:true)
  • start Match from the beginning of the string. (default:true)
  • loose Allow the delimiter to be arbitrarily repeated, e.g./ or///. (default:true)
  • delimiter The default delimiter for segments, e.g.[^/] for:named parameters. (default:'/')
  • encodePath A function for encoding input strings. (default:x => x, recommended:encodeurl for unicode encoding)

constregexp=pathToRegexp("/foo/:bar");// regexp = /^\/+foo(?:\/+([^\/]+?))(?:\/+)?$/i// keys = [{ name: 'bar', prefix: '', suffix: '', pattern: '', modifier: '' }]

Please note: TheRegExp returned bypath-to-regexp is intended for ordered data (e.g. pathnames, hostnames). It can not handle arbitrarily ordered data (e.g. query strings, URL fragments, JSON, etc).

The path argument is used to define parameters and populate keys.

Named parameters are defined by prefixing a colon to the parameter name (:foo). Parameter names can use any valid unicode identifier characters (similar to JavaScript).

constregexp=pathToRegexp("/:foo/:bar");// keys = [{ name: 'foo', ... }, { name: 'bar', ... }]regexp.exec("/test/route");//=> [ '/test/route', 'test', 'route', index: 0 ]

Parameters can have a custom regexp, which overrides the default match ([^/]+). For example, you can match digits or names in a path:

constregexpNumbers=pathToRegexp("/icon-:foo(\\d+).png");// keys = [{ name: 'foo', ... }]regexpNumbers.exec("/icon-123.png");//=> ['/icon-123.png', '123']regexpNumbers.exec("/icon-abc.png");//=> nullconstregexpWord=pathToRegexp("/(user|u)");// keys = [{ name: 0, ... }]regexpWord.exec("/u");//=> ['/u', 'u']regexpWord.exec("/users");//=> null

Tip: Backslashes need to be escaped with another backslash in JavaScript strings.

It is possible to define a parameter without a name. The name will be numerically indexed:

constregexp=pathToRegexp("/:foo/(.*)");// keys = [{ name: 'foo', ... }, { name: '0', ... }]regexp.exec("/test/route");//=> [ '/test/route', 'test', 'route', index: 0 ]

Parameters can be wrapped in{} to create custom prefixes or suffixes for your segment:

constregexp=pathToRegexp("{/:attr1}?{-:attr2}?{-:attr3}?");regexp.exec("/test");// => ['/test', 'test', undefined, undefined]regexp.exec("/test-test");// => ['/test', 'test', 'test', undefined]

Modifiers are used after parameters with custom prefixes and suffixes ({}).

Parameters can be suffixed with a question mark (?) to make the parameter optional.

constregexp=pathToRegexp("/:foo{/:bar}?");// keys = [{ name: 'foo', ... }, { name: 'bar', prefix: '/', modifier: '?' }]regexp.exec("/test");//=> [ '/test', 'test', undefined, index: 0 ]regexp.exec("/test/route");//=> [ '/test/route', 'test', 'route', index: 0 ]

Parameters can be suffixed with an asterisk (*) to denote a zero or more parameter matches.

constregexp=pathToRegexp("{/:foo}*");// keys = [{ name: 'foo', prefix: '/', modifier: '*' }]regexp.exec("/foo");//=> [ '/foo', "foo", index: 0 ]regexp.exec("/bar/baz");//=> [ '/bar/baz', 'bar/baz', index: 0 ]

Parameters can be suffixed with a plus sign (+) to denote a one or more parameter matches.

constregexp=pathToRegexp("{/:foo}+");// keys = [{ name: 'foo', prefix: '/', modifier: '+' }]regexp.exec("/");//=> nullregexp.exec("/bar/baz");//=> [ '/bar/baz', 'bar/baz', index: 0 ]

By default, parameters set the separator as theprefix + suffix of the token. Using; you can modify this:

constregexp=pathToRegexp("/name{/:parts;-}+");regexp.exec("/name");//=> nullregexp.exec("/bar/1-2-3");//=> [ '/name/1-2-3', '1-2-3', index: 0 ]

A wildcard can also be used. It is roughly equivalent to(.*).

constregexp=pathToRegexp("/*");// keys = [{ name: '0', pattern: '[^\\/]*', separator: '/', modifier: '*' }]regexp.exec("/");//=> [ '/', '', index: 0 ]regexp.exec("/bar/baz");//=> [ '/bar/baz', 'bar/baz', index: 0 ]

Thematch function returns a function for transforming paths into parameters:

• path A string.
• options(optional) The same options aspathToRegexp, plus:
  • decode Function for decoding strings for params, orfalse to disable entirely. (default:decodeURIComponent)

constfn=match("/user/:id");fn("/user/123");//=> { path: '/user/123', index: 0, params: { id: '123' }}fn("/invalid");//=> falsefn("/user/caf%C3%A9");//=> { path: '/user/caf%C3%A9', index: 0, params: { id: 'café' }}

Note: Settingdecode: false disables the "splitting" behavior of repeated parameters, which is useful if you need the exactly matched parameter back.

Thecompile function will return a function for transforming parameters into a valid path:

• path A string.
• options(optional) Similar topathToRegexp (delimiter,encodePath,sensitive, andloose), plus:
  • validate Whenfalse the function can produce an invalid (unmatched) path. (default:true)
  • encode Function for encoding input strings for output into the path, orfalse to disable entirely. (default:encodeURIComponent)

consttoPath=compile("/user/:id");toPath({id:"name"});//=> "/user/name"toPath({id:"café"});//=> "/user/caf%C3%A9"// When disabling `encode`, you need to make sure inputs are encoded correctly. No arrays are accepted.consttoPathRaw=compile("/user/:id",{encode:false});toPathRaw({id:"%3A%2F"});//=> "/user/%3A%2F"toPathRaw({id:":/"});//=> Throws, "/user/:/" when `validate` is `false`.consttoPathRepeated=compile("{/:segment}+");toPathRepeated({segment:["foo"]});//=> "/foo"toPathRepeated({segment:["a","b","c"]});//=> "/a/b/c"consttoPathRegexp=compile("/user/:id(\\d+)");toPathRegexp({id:"123"});//=> "/user/123"

• If you are rewriting paths with match and compiler, consider usingencode: false anddecode: false to keep raw paths passed around.
• To ensure matches work on paths containing characters usually encoded, consider usingencodeurl forencodePath.
• If matches are intended to be exact, you need to setloose: false,trailing: false, andsensitive: true.
• Enablestrict: true to detect ReDOS issues.

Aparse function is available and returnsTokenData, the set of tokens and other metadata parsed from the input string.TokenData is can passed directly intopathToRegexp,match, andcompile. It accepts only two options,delimiter andencodePath, which makes those options redundant in the above methods.

Thetokens returned byTokenData is an array of strings or keys, represented as objects, with the following properties:

• name The name of the token
• prefix(optional) The prefix string for the segment (e.g."/")
• suffix(optional) The suffix string for the segment (e.g."")
• pattern(optional) The pattern defined to match this token
• modifier(optional) The modifier character used for the segment (e.g.?)
• separator(optional) The string used to separate repeated parameters

In some applications, you may not be able to use thepath-to-regexp syntax (e.g. file-based routing), but you can still use this library formatch,compile, andpathToRegexp by building your ownTokenData instance. For example:

import{TokenData,match}from"path-to-regexp";consttokens=["/",{name:"foo"}];constpath=newTokenData(tokens,"/");constfn=match(path);fn("/test");//=> { path: '/test', index: 0, params: { foo: 'test' }}

An effort has been made to ensure ambiguous paths from previous releases throw an error. This means you might be seeing an error when things worked before.

In previous major versions/ and. were used as implicit prefixes of parameters. So/:key? was implicitly{/:key}?. For example:

• /:key? →{/:key}? or/:key* →{/:key}* or/:key+ →{/:key}+
• .:key? →{.:key}? or.:key* →{.:key}* or.:key+ →{.:key}+
• :key? →{:key}? or:key* →{:key}* or:key+ →{:key}+

Used as acustom separator for repeated parameters.

These characters have been reserved for future use.

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

• The only part of the string that is a regex is within().
  • In Express.js 4.x, everything was passed as-is after a simple replacement, so you could write/[a-z]+ to match/test.
• The? optional character must be used after{}.
• Some characters have new meaning or have been reserved ({}?*+@!;).
• The parameter name now supports all unicode identifier characters, previously it was only[a-z0-9].

MIT