Turn a path string such as
/user/:name
into a regular expression.
npm install path-to-regexp --save
const { match, compile, parse } = require("path-to-regexp");
// match(path, options?)
// compile(path, options?)
// parse(path, options?)
Parameters match arbitrary strings in a path by matching up to the end of the segment, or up to any proceeding tokens. They are defined by prefixing a colon to the parameter name (:foo
). Parameter names can use any valid JavaScript identifier, or be double quoted to use other characters (:"param-name"
).
const fn = match("/:foo/:bar");
fn("/test/route");
//=> { path: '/test/route', params: { foo: 'test', bar: 'route' } }
Wildcard parameters match one or more characters across multiple segments. They are defined the same way as regular parameters, but are prefixed with an asterisk (*foo
).
const fn = match("/*splat");
fn("/bar/baz");
//=> { path: '/bar/baz', params: { splat: [ 'bar', 'baz' ] } }
Braces can be used to define parts of the path that are optional.
const fn = match("/users{/:id}/delete");
fn("/users/delete");
//=> { path: '/users/delete', params: {} }
fn("/users/123/delete");
//=> { path: '/users/123/delete', params: { id: '123' } }
The match
function returns a function for matching strings against a path:
- path String or array of strings.
- options (optional) (See parse for more options)
- sensitive Regexp will be case sensitive. (default:
false
) - end Validate the match reaches the end of the string. (default:
true
) - delimiter The default delimiter for segments, e.g.
[^/]
for:named
parameters. (default:'/'
) - trailing Allows optional trailing delimiter to match. (default:
true
) - decode Function for decoding strings to params, or
false
to disable all processing. (default:decodeURIComponent
)
- sensitive Regexp will be case sensitive. (default:
const fn = match("/foo/:bar");
Please note: path-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 compile
function will return a function for transforming parameters into a valid path:
- path A string.
- options (See parse for more options)
- delimiter The default delimiter for segments, e.g.
[^/]
for:named
parameters. (default:'/'
) - encode Function for encoding input strings for output into the path, or
false
to disable entirely. (default:encodeURIComponent
)
- delimiter The default delimiter for segments, e.g.
const toPath = compile("/user/:id");
toPath({ id: "name" }); //=> "/user/name"
toPath({ id: "café" }); //=> "/user/caf%C3%A9"
const toPathRepeated = compile("/*segment");
toPathRepeated({ segment: ["foo"] }); //=> "/foo"
toPathRepeated({ segment: ["a", "b", "c"] }); //=> "/a/b/c"
// When disabling `encode`, you need to make sure inputs are encoded correctly. No arrays are accepted.
const toPathRaw = compile("/user/:id", { encode: false });
toPathRaw({ id: "%3A%2F" }); //=> "/user/%3A%2F"
- If you are rewriting paths with match and compile, consider using
encode: false
anddecode: false
to keep raw paths passed around. - To ensure matches work on paths containing characters usually encoded, such as emoji, consider using encodeurl for
encodePath
.
The parse
function accepts a string and returns TokenData
, the set of tokens and other metadata parsed from the input string. TokenData
is can used with match
and compile
.
- path A string.
- options (optional)
- encodePath A function for encoding input strings. (default:
x => x
, recommended:encodeurl
)
- encodePath A function for encoding input strings. (default:
TokenData
is a sequence of tokens, currently of types text
, parameter
, wildcard
, or group
.
In some applications, you may not be able to use the path-to-regexp
syntax, but still want to use this library for match
and compile
. For example:
import { TokenData, match } from "path-to-regexp";
const tokens = [
{ type: "text", value: "/" },
{ type: "parameter", name: "foo" },
];
const path = new TokenData(tokens);
const fn = 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 past releases, ?
, *
, and +
were used to denote optional or repeating parameters. As an alternative, try these:
- For optional (
?
), use an empty segment in a group such as/:file{.:ext}
. - For repeating (
+
), only wildcard matching is supported, such as/*path
. - For optional repeating (
*
), use a group and a wildcard parameter such as/files{/*path}
.
Previous versions of Path-to-RegExp used these for RegExp features. This version no longer supports them so they've been reserved to avoid ambiguity. To use these characters literally, escape them with a backslash, e.g. "\\("
.
Parameter names, the part after :
or *
, must be a valid JavaScript identifier. For example, it cannot start with a number or contain a dash. If you want a parameter name that uses these characters you can wrap the name in quotes, e.g. :"my-name"
.
Parameter names can be wrapped in double quote characters, and this error means you forgot to close the quote character.
Path-To-RegExp breaks compatibility with Express <= 4.x
in the following ways:
- Regexp characters can no longer be provided.
- The optional character
?
is no longer supported, use braces instead:/:file{.:ext}
. - Some characters have new meaning or have been reserved (
{}?*+@!;
). - The parameter name now supports all JavaScript identifier characters, previously it was only
[a-z0-9]
.
MIT