robojerk/codeql-action

Update checked-in dependencies

Browse source
This commit is contained in:
github-actions[bot] 2024-09-16 17:29:58 +00:00
parent 1afca056e3
commit 6989ba7bd2
3942 changed files with 55190 additions and 132206 deletions
Download patch file Download diff file Expand all files Collapse all files

385
node_modules/path-to-regexp/Readme.md generated vendored
View file

@ -16,323 +16,188 @@ npm install path-to-regexp --save
## Usage
```javascript
const { pathToRegexp, match, parse, compile } = require("path-to-regexp");
// pathToRegexp(path, keys?, options?)
// match(path)
// parse(path)
// compile(path)
```js
const {
match,
pathToRegexp,
compile,
parse,
stringify,
} = require("path-to-regexp");
```
### Path to regexp
The `pathToRegexp` function will return a regular expression object based on the provided `path` argument. It accepts the following arguments:
- **path** A string, array of strings, or a regular expression.
- **keys** _(optional)_ An array to populate with keys found in the path.
- **options** _(optional)_
- **sensitive** When `true` the regexp will be case sensitive. (default: `false`)
- **strict** When `true` the regexp won't allow an optional trailing delimiter to match. (default: `false`)
- **end** When `true` the regexp will match to the end of the string. (default: `true`)
- **start** When `true` the regexp will match from the beginning of the string. (default: `true`)
- **delimiter** The default delimiter for segments, e.g. `[^/#?]` for `:named` patterns. (default: `'/#?'`)
- **endsWith** Optional character, or list of characters, to treat as "end" characters.
- **encode** A function to encode strings before inserting into `RegExp`. (default: `x => x`)
- **prefixes** List of characters to automatically consider prefixes when parsing. (default: `./`)
```javascript
const keys = [];
const regexp = pathToRegexp("/foo/:bar", keys);
// regexp = /^\/foo(?:\/([^\/#\?]+?))[\/#\?]?$/i
// keys = [{ name: 'bar', prefix: '/', suffix: '', pattern: '[^\\/#\\?]+?', modifier: '' }]
```
**Please note:** The `RegExp` returned by `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). When using paths that contain query strings, you need to escape the question mark (`?`) to ensure it does not flag the parameter as [optional](#optional).
### Parameters
The path argument is used to define parameters and populate keys.
#### Named Parameters
Named parameters are defined by prefixing a colon to the parameter name (`:foo`).
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"`).
```js
const regexp = pathToRegexp("/:foo/:bar");
// keys = [{ name: 'foo', prefix: '/', ... }, { name: 'bar', prefix: '/', ... }]
const fn = match("/:foo/:bar");
regexp.exec("/test/route");
//=> [ '/test/route', 'test', 'route', index: 0, input: '/test/route', groups: undefined ]
fn("/test/route");
//=> { path: '/test/route', params: { foo: 'test', bar: 'route' } }
```
**Please note:** Parameter names must use "word characters" (`[A-Za-z0-9_]`).
### Wildcard
##### Custom Matching Parameters
Parameters can have a custom regexp, which overrides the default match (`[^/]+`). For example, you can match digits or names in a path:
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`).
```js
const regexpNumbers = pathToRegexp("/icon-:foo(\\d+).png");
// keys = [{ name: 'foo', ... }]
const fn = match("/*splat");
regexpNumbers.exec("/icon-123.png");
//=> ['/icon-123.png', '123']
regexpNumbers.exec("/icon-abc.png");
//=> null
const regexpWord = pathToRegexp("/(user|u)");
// keys = [{ name: 0, ... }]
regexpWord.exec("/u");
//=> ['/u', 'u']
regexpWord.exec("/users");
//=> null
fn("/bar/baz");
//=> { path: '/bar/baz', params: { splat: [ 'bar', 'baz' ] } }
```
**Tip:** Backslashes need to be escaped with another backslash in JavaScript strings.
### Optional
##### Custom Prefix and Suffix
Parameters can be wrapped in `{}` to create custom prefixes or suffixes for your segment:
Braces can be used to define parts of the path that are optional.
```js
const regexp = pathToRegexp("/:attr1?{-:attr2}?{-:attr3}?");
const fn = match("/users{/:id}/delete");
regexp.exec("/test");
// => ['/test', 'test', undefined, undefined]
fn("/users/delete");
//=> { path: '/users/delete', params: {} }
regexp.exec("/test-test");
// => ['/test', 'test', 'test', undefined]
fn("/users/123/delete");
//=> { path: '/users/123/delete', params: { id: '123' } }
```
#### Unnamed Parameters
## Match
It is possible to write an unnamed parameter that only consists of a regexp. It works the same the named parameter, except it will be numerically indexed:
The `match` function returns a function for matching strings against a path:
- **path** String or array of strings.
- **options** _(optional)_ (Extends [pathToRegexp](#pathToRegexp) options)
- **decode** Function for decoding strings to params, or `false` to disable all processing. (default: `decodeURIComponent`)
```js
const regexp = pathToRegexp("/:foo/(.*)");
// keys = [{ name: 'foo', ... }, { name: 0, ... }]
regexp.exec("/test/route");
//=> [ '/test/route', 'test', 'route', index: 0, input: '/test/route', groups: undefined ]
const fn = match("/foo/:bar");
```
#### Modifiers
**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).
Modifiers must be placed after the parameter (e.g. `/:foo?`, `/(test)?`, `/:foo(test)?`, or `{-:foo(test)}?`).
## PathToRegexp
##### Optional
The `pathToRegexp` function returns a regular expression for matching strings against paths. It
Parameters can be suffixed with a question mark (`?`) to make the parameter optional.
- **path** String or array of strings.
- **options** _(optional)_ (See [parse](#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`)
```js
const regexp = pathToRegexp("/:foo/:bar?");
// keys = [{ name: 'foo', ... }, { name: 'bar', prefix: '/', modifier: '?' }]
regexp.exec("/test");
//=> [ '/test', 'test', undefined, index: 0, input: '/test', groups: undefined ]
regexp.exec("/test/route");
//=> [ '/test/route', 'test', 'route', index: 0, input: '/test/route', groups: undefined ]
const { regexp, keys } = pathToRegexp("/foo/:bar");
```
**Tip:** The prefix is also optional, escape the prefix `\/` to make it required.
When dealing with query strings, escape the question mark (`?`) so it doesn't mark the parameter as optional. Handling unordered data is outside the scope of this library.
```js
const regexp = pathToRegexp("/search/:tableName\\?useIndex=true&term=amazing");
regexp.exec("/search/people?useIndex=true&term=amazing");
//=> [ '/search/people?useIndex=true&term=amazing', 'people', index: 0, input: '/search/people?useIndex=true&term=amazing', groups: undefined ]
// This library does not handle query strings in different orders
regexp.exec("/search/people?term=amazing&useIndex=true");
//=> null
```
##### Zero or more
Parameters can be suffixed with an asterisk (`*`) to denote a zero or more parameter matches.
```js
const regexp = pathToRegexp("/:foo*");
// keys = [{ name: 'foo', prefix: '/', modifier: '*' }]
regexp.exec("/");
//=> [ '/', undefined, index: 0, input: '/', groups: undefined ]
regexp.exec("/bar/baz");
//=> [ '/bar/baz', 'bar/baz', index: 0, input: '/bar/baz', groups: undefined ]
```
##### One or more
Parameters can be suffixed with a plus sign (`+`) to denote a one or more parameter matches.
```js
const regexp = pathToRegexp("/:foo+");
// keys = [{ name: 'foo', prefix: '/', modifier: '+' }]
regexp.exec("/");
//=> null
regexp.exec("/bar/baz");
//=> [ '/bar/baz','bar/baz', index: 0, input: '/bar/baz', groups: undefined ]
```
### Match
The `match` function will return a function for transforming paths into parameters:
```js
// Make sure you consistently `decode` segments.
const fn = match("/user/:id", { decode: decodeURIComponent });
fn("/user/123"); //=> { path: '/user/123', index: 0, params: { id: '123' } }
fn("/invalid"); //=> false
fn("/user/caf%C3%A9"); //=> { path: '/user/caf%C3%A9', index: 0, params: { id: 'café' } }
```
The `match` function can be used to custom match named parameters. For example, this can be used to whitelist a small number of valid paths:
```js
const urlMatch = match("/users/:id/:tab(home|photos|bio)", {
decode: decodeURIComponent,
});
urlMatch("/users/1234/photos");
//=> { path: '/users/1234/photos', index: 0, params: { id: '1234', tab: 'photos' } }
urlMatch("/users/1234/bio");
//=> { path: '/users/1234/bio', index: 0, params: { id: '1234', tab: 'bio' } }
urlMatch("/users/1234/otherstuff");
//=> false
```
#### Process Pathname
You should make sure variations of the same path match the expected `path`. Here's one possible solution using `encode`:
```js
const fn = match("/café", { encode: encodeURI });
fn("/caf%C3%A9"); //=> { path: '/caf%C3%A9', index: 0, params: {} }
```
**Note:** [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) encodes paths, so `/café` would be normalized to `/caf%C3%A9` and match in the above example.
##### Alternative Using Normalize
Sometimes you won't have already normalized paths to use, so you could normalize it yourself before matching:
```js
/**
* Normalize a pathname for matching, replaces multiple slashes with a single
* slash and normalizes unicode characters to "NFC". When using this method,
* `decode` should be an identity function so you don't decode strings twice.
*/
function normalizePathname(pathname: string) {
return (
decodeURI(pathname)
// Replaces repeated slashes in the URL.
.replace(/\/+/g, "/")
// Reference: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize
// Note: Missing native IE support, may want to skip this step.
.normalize()
);
}
// Two possible ways of writing `/café`:
const re = pathToRegexp("/caf\u00E9");
const input = encodeURI("/cafe\u0301");
re.test(input); //=> false
re.test(normalizePathname(input)); //=> true
```
### Parse
The `parse` function will return a list of strings and keys from a path string:
```js
const tokens = parse("/route/:foo/(.*)");
console.log(tokens[0]);
//=> "/route"
console.log(tokens[1]);
//=> { name: 'foo', prefix: '/', suffix: '', pattern: '[^\\/#\\?]+?', modifier: '' }
console.log(tokens[2]);
//=> { name: 0, prefix: '/', suffix: '', pattern: '.*', modifier: '' }
```
**Note:** This method only works with strings.
### Compile ("Reverse" Path-To-RegExp)
## Compile ("Reverse" Path-To-RegExp)
The `compile` function will return a function for transforming parameters into a valid path:
- **path** A string.
- **options** (See [parse](#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`)
```js
// Make sure you encode your path segments consistently.
const toPath = compile("/user/:id", { encode: encodeURIComponent });
const toPath = compile("/user/:id");
toPath({ id: 123 }); //=> "/user/123"
toPath({ id: "name" }); //=> "/user/name"
toPath({ id: "café" }); //=> "/user/caf%C3%A9"
toPath({ id: ":/" }); //=> "/user/%3A%2F"
// Without `encode`, you need to make sure inputs are encoded correctly.
// (Note: You can use `validate: false` to create an invalid paths.)
const toPathRaw = compile("/user/:id", { validate: false });
const toPathRepeated = compile("/*segment");
toPathRaw({ id: "%3A%2F" }); //=> "/user/%3A%2F"
toPathRaw({ id: ":/" }); //=> "/user/:/"
const toPathRepeated = compile("/:segment+");
toPathRepeated({ segment: "foo" }); //=> "/foo"
toPathRepeated({ segment: ["foo"] }); //=> "/foo"
toPathRepeated({ segment: ["a", "b", "c"] }); //=> "/a/b/c"
const toPathRegexp = compile("/user/:id(\\d+)");
// When disabling `encode`, you need to make sure inputs are encoded correctly. No arrays are accepted.
const toPathRaw = compile("/user/:id", { encode: false });
toPathRegexp({ id: 123 }); //=> "/user/123"
toPathRegexp({ id: "123" }); //=> "/user/123"
toPathRaw({ id: "%3A%2F" }); //=> "/user/%3A%2F"
```
**Note:** The generated function will throw on invalid input.
## Stringify
### Working with Tokens
Transform `TokenData` (a sequence of tokens) back into a Path-to-RegExp string.
Path-To-RegExp exposes the two functions used internally that accept an array of tokens:
- **data** A `TokenData` instance
- `tokensToRegexp(tokens, keys?, options?)` Transform an array of tokens into a matching regular expression.
- `tokensToFunction(tokens)` Transform an array of tokens into a path generator function.
```js
const data = new TokenData([
{ type: "text", value: "/" },
{ type: "param", name: "foo" },
]);
#### Token Information
const path = stringify(data); //=> "/:foo"
```
- `name` The name of the token (`string` for named or `number` for unnamed index)
- `prefix` The prefix string for the segment (e.g. `"/"`)
- `suffix` The suffix string for the segment (e.g. `""`)
- `pattern` The RegExp used to match this token (`string`)
- `modifier` The modifier character used for the segment (e.g. `?`)
## Developers
## Compatibility with Express <= 4.x
- If you are rewriting paths with match and compile, consider using `encode: false` and `decode: false` to keep raw paths passed around.
- To ensure matches work on paths containing characters usually encoded, such as emoji, consider using [encodeurl](https://github.com/pillarjs/encodeurl) for `encodePath`.
Path-To-RegExp breaks compatibility with Express <= `4.x`:
### Parse
- RegExp special characters can only be used in a parameter
- Express.js 4.x supported `RegExp` special characters regardless of position - this is considered a bug
- Parameters have suffixes that augment meaning - `*`, `+` and `?`. E.g. `/:user*`
- No wildcard asterisk (`*`) - use parameters instead (`(.*)` or `:splat*`)
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`.
## Live Demo
- **path** A string.
- **options** _(optional)_
- **encodePath** A function for encoding input strings. (default: `x => x`, recommended: [`encodeurl`](https://github.com/pillarjs/encodeurl))
You can see a live demo of this library in use at [express-route-tester](http://forbeslindesay.github.io/express-route-tester/).
### Tokens
`TokenData` is a sequence of tokens, currently of types `text`, `parameter`, `wildcard`, or `group`.
### Custom path
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:
```js
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' } }
```
## Errors
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.
### Unexpected `?` or `+`
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}`.
### Unexpected `(`, `)`, `[`, `]`, 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 use these characters literally, escape them with a backslash, e.g. `"\\("`.
### Missing parameter name
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"`.
### Unterminated quote
Parameter names can be wrapped in double quote characters, and this error means you forgot to close the quote character.
### Express <= 4.x
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]`.
## License