Turn a path string such as
/user/:nameinto a regular expression.
npm install path-to-regexp --save
const {
match,
pathToRegexp,
compile,
parse,
stringify,
} = require("path-to-regexp");
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:
TokenData object, or array of strings and TokenData objects.false to disable all processing. (default: decodeURIComponent)const fn = match("/foo/:bar");
Please note: path-to-regexp is intended for ordered data (e.g. paths, hosts). It can not handle arbitrarily ordered data (e.g. query strings, URL fragments, JSON, etc).
The pathToRegexp function returns the regexp for matching strings against paths, and an array of keys for understanding the RegExp#exec matches.
TokenData object, or array of strings and TokenData objects.false)true)[^/] for :named parameters. (default: '/')true)const { regexp, keys } = pathToRegexp("/foo/:bar");
regexp.exec("/foo/123"); //=> ["/foo/123", "123"]
The compile function will return a function for transforming parameters into a valid path:
TokenData object.[^/] for :named parameters. (default: '/')false to disable entirely. (default: encodeURIComponent)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"
Transform a TokenData object to a Path-to-RegExp string.
TokenData object.const data = {
tokens: [
{ type: "text", value: "/" },
{ type: "param", name: "foo" },
],
};
const path = stringify(data); //=> "/:foo"
encode: false and decode: false to keep raw paths passed around.encodePath.The parse function accepts a string and returns TokenData, which can be used with match and compile.
x => x, recommended: encodeurl)TokenData has two properties:
text, parameter, wildcard, or group.parse, shown in error messages to assist debugging.In some applications you may not be able to use the path-to-regexp syntax, but you still want to use this library for match and compile. For example:
import { match } from "path-to-regexp";
const tokens = [
{ type: "text", value: "/" },
{ type: "parameter", name: "foo" },
];
const originalPath = "/[foo]"; // To help debug error messages.
const path = { tokens, originalPath };
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.
Parameter names must be provided after : or *, for example /*path. They can be valid JavaScript identifiers (e.g. :myName) or JSON strings (:"my-name").
? or +In past releases, ?, *, and + were used to denote optional or repeating parameters. As an alternative, try these:
?), use braces: /file{.:ext}.+), use a wildcard: /*path.*), use both: /files{/*path}.(, ), [, ], etc.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 match these characters literally, escape them with a backslash, e.g. "\\(".
Parameter names can be wrapped in double quote characters, and this error means you forgot to close the quote character. For example, :"foo.
Path-To-RegExp breaks compatibility with Express <= 4.x in the following ways:
* must have a name and matches the behavior of parameters :.? is no longer supported, use braces instead: /:file{.:ext}.()[]?+!).:"this".MIT