step-node-agent 3.20.2 → 3.21.0

package/node_modules/npm/node_modules/query-string/index.d.ts

@@ -12,6 +12,8 @@ export interface ParseOptions {
 	- `bracket`: Parse arrays with bracket representation:
 
 		```
+		import queryString = require('query-string');
+
 		queryString.parse('foo[]=1&foo[]=2&foo[]=3', {arrayFormat: 'bracket'});
 		//=> {foo: ['1', '2', '3']}
 		```
@@ -19,6 +21,8 @@ export interface ParseOptions {
 	- `index`: Parse arrays with index representation:
 
 		```
+		import queryString = require('query-string');
+
 		queryString.parse('foo[0]=1&foo[1]=2&foo[3]=3', {arrayFormat: 'index'});
 		//=> {foo: ['1', '2', '3']}
 		```
@@ -26,18 +30,38 @@ export interface ParseOptions {
 	- `comma`: Parse arrays with elements separated by comma:
 
 		```
+		import queryString = require('query-string');
+
 		queryString.parse('foo=1,2,3', {arrayFormat: 'comma'});
 		//=> {foo: ['1', '2', '3']}
 		```
 
+	- `separator`: Parse arrays with elements separated by a custom character:
+
+		```
+		import queryString = require('query-string');
+
+		queryString.parse('foo=1|2|3', {arrayFormat: 'separator', arrayFormatSeparator: '|'});
+		//=> {foo: ['1', '2', '3']}
+		```
+
 	- `none`: Parse arrays with elements using duplicate keys:
 
 		```
+		import queryString = require('query-string');
+
 		queryString.parse('foo=1&foo=2&foo=3');
 		//=> {foo: ['1', '2', '3']}
 		```
 	*/
-	readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'none';
+	readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'separator' | 'none';
+
+	/**
+	The character used to separate array elements when using `{arrayFormat: 'separator'}`.
+
+	@default ,
+	*/
+	readonly arrayFormatSeparator?: string;
 
 	/**
 	Supports both `Function` as a custom sorting function or `false` to disable sorting.
@@ -48,16 +72,22 @@ export interface ParseOptions {
 
 	@example
 	```
+	import queryString = require('query-string');
+
 	const order = ['c', 'a', 'b'];
 
 	queryString.parse('?a=one&b=two&c=three', {
 		sort: (itemLeft, itemRight) => order.indexOf(itemLeft) - order.indexOf(itemRight)
 	});
-	// => {c: 'three', a: 'one', b: 'two'}
+	//=> {c: 'three', a: 'one', b: 'two'}
 	```
 
+	@example
+	```
+	import queryString = require('query-string');
+
 	queryString.parse('?a=one&c=three&b=two', {sort: false});
-	// => {a: 'one', c: 'three', b: 'two'}
+	//=> {a: 'one', c: 'three', b: 'two'}
 	```
 	*/
 	readonly sort?: ((itemLeft: string, itemRight: string) => number) | false;
@@ -68,7 +98,9 @@ export interface ParseOptions {
 	@default false
 
 	@example
-	```js
+	```
+	import queryString = require('query-string');
+
 	queryString.parse('foo=1', {parseNumbers: true});
 	//=> {foo: 1}
 	```
@@ -82,15 +114,32 @@ export interface ParseOptions {
 
 	@example
 	```
+	import queryString = require('query-string');
+
 	queryString.parse('foo=true', {parseBooleans: true});
 	//=> {foo: true}
 	```
 	*/
 	readonly parseBooleans?: boolean;
+
+	/**
+	Parse the fragment identifier from the URL and add it to result object.
+
+	@default false
+
+	@example
+	```
+	import queryString = require('query-string');
+
+	queryString.parseUrl('https://foo.bar?foo=bar#xyz', {parseFragmentIdentifier: true});
+	//=> {url: 'https://foo.bar', query: {foo: 'bar'}, fragmentIdentifier: 'xyz'}
+	```
+	*/
+	readonly parseFragmentIdentifier?: boolean;
 }
 
 export interface ParsedQuery<T = string> {
-	[key: string]: T | T[] | null | undefined;
+	[key: string]: T | T[] | null;
 }
 
 /**
@@ -108,17 +157,31 @@ export function parse(query: string, options?: ParseOptions): ParsedQuery;
 export interface ParsedUrl {
 	readonly url: string;
 	readonly query: ParsedQuery;
+
+	/**
+	The fragment identifier of the URL.
+
+	Present when the `parseFragmentIdentifier` option is `true`.
+	*/
+	readonly fragmentIdentifier?: string;
 }
 
 /**
 Extract the URL and the query string as an object.
 
+If the `parseFragmentIdentifier` option is `true`, the object will also contain a `fragmentIdentifier` property.
+
 @param url - The URL to parse.
 
 @example
 ```
+import queryString = require('query-string');
+
 queryString.parseUrl('https://foo.bar?foo=bar');
 //=> {url: 'https://foo.bar', query: {foo: 'bar'}}
+
+queryString.parseUrl('https://foo.bar?foo=bar#xyz', {parseFragmentIdentifier: true});
+//=> {url: 'https://foo.bar', query: {foo: 'bar'}, fragmentIdentifier: 'xyz'}
 ```
 */
 export function parseUrl(url: string, options?: ParseOptions): ParsedUrl;
@@ -144,6 +207,8 @@ export interface StringifyOptions {
 	- `bracket`: Serialize arrays using bracket representation:
 
 		```
+		import queryString = require('query-string');
+
 		queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket'});
 		//=> 'foo[]=1&foo[]=2&foo[]=3'
 		```
@@ -151,6 +216,8 @@ export interface StringifyOptions {
 	- `index`: Serialize arrays using index representation:
 
 		```
+		import queryString = require('query-string');
+
 		queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'index'});
 		//=> 'foo[0]=1&foo[1]=2&foo[2]=3'
 		```
@@ -158,18 +225,38 @@ export interface StringifyOptions {
 	- `comma`: Serialize arrays by separating elements with comma:
 
 		```
+		import queryString = require('query-string');
+
 		queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'comma'});
 		//=> 'foo=1,2,3'
 		```
 
+  - `separator`: Serialize arrays by separating elements with character:
+
+		```
+		import queryString = require('query-string');
+
+		queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'separator', arrayFormatSeparator: '|'});
+		//=> 'foo=1|2|3'
+		```
+
 	- `none`: Serialize arrays by using duplicate keys:
 
 		```
+		import queryString = require('query-string');
+
 		queryString.stringify({foo: [1, 2, 3]});
 		//=> 'foo=1&foo=2&foo=3'
 		```
 	*/
-	readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'none';
+	readonly arrayFormat?: 'bracket' | 'index' | 'comma' | 'separator' | 'none';
+
+	/**
+	The character used to separate array elements when using `{arrayFormat: 'separator'}`.
+
+	@default ,
+	*/
+	readonly arrayFormatSeparator?: string;
 
 	/**
 	Supports both `Function` as a custom sorting function or `false` to disable sorting.
@@ -180,29 +267,223 @@ export interface StringifyOptions {
 
 	@example
 	```
+	import queryString = require('query-string');
+
 	const order = ['c', 'a', 'b'];
 
 	queryString.stringify({a: 1, b: 2, c: 3}, {
 		sort: (itemLeft, itemRight) => order.indexOf(itemLeft) - order.indexOf(itemRight)
 	});
-	// => 'c=3&a=1&b=2'
+	//=> 'c=3&a=1&b=2'
+	```
+
+	@example
+	```
+	import queryString = require('query-string');
 
 	queryString.stringify({b: 1, c: 2, a: 3}, {sort: false});
-	// => 'b=1&c=2&a=3'
+	//=> 'b=1&c=2&a=3'
 	```
 	*/
 	readonly sort?: ((itemLeft: string, itemRight: string) => number) | false;
+
+	/**
+	Skip keys with `null` as the value.
+
+	Note that keys with `undefined` as the value are always skipped.
+
+	@default false
+
+	@example
+	```
+	import queryString = require('query-string');
+
+	queryString.stringify({a: 1, b: undefined, c: null, d: 4}, {
+		skipNull: true
+	});
+	//=> 'a=1&d=4'
+
+	queryString.stringify({a: undefined, b: null}, {
+		skipNull: true
+	});
+	//=> ''
+	```
+	*/
+	readonly skipNull?: boolean;
+
+	/**
+	Skip keys with an empty string as the value.
+
+	@default false
+
+	@example
+	```
+	import queryString = require('query-string');
+
+	queryString.stringify({a: 1, b: '', c: '', d: 4}, {
+		skipEmptyString: true
+	});
+	//=> 'a=1&d=4'
+	```
+
+	@example
+	```
+	import queryString = require('query-string');
+
+	queryString.stringify({a: '', b: ''}, {
+		skipEmptyString: true
+	});
+	//=> ''
+	```
+	*/
+	readonly skipEmptyString?: boolean;
 }
 
+export type Stringifiable = string | boolean | number | null | undefined;
+
+export type StringifiableRecord = Record<
+	string,
+	Stringifiable | readonly Stringifiable[]
+>;
+
 /**
 Stringify an object into a query string and sort the keys.
 */
 export function stringify(
-	object: {[key: string]: any},
+	// TODO: Use the below instead when the following TS issues are fixed:
+	// - https://github.com/microsoft/TypeScript/issues/15300
+	// - https://github.com/microsoft/TypeScript/issues/42021
+	// Context: https://github.com/sindresorhus/query-string/issues/298
+	// object: StringifiableRecord,
+	object: Record<string, any>,
 	options?: StringifyOptions
 ): string;
 
 /**
 Extract a query string from a URL that can be passed into `.parse()`.
+
+Note: This behaviour can be changed with the `skipNull` option.
 */
 export function extract(url: string): string;
+
+export interface UrlObject {
+	readonly url: string;
+
+	/**
+	Overrides queries in the `url` property.
+	*/
+	readonly query?: StringifiableRecord;
+
+	/**
+	Overrides the fragment identifier in the `url` property.
+	*/
+	readonly fragmentIdentifier?: string;
+}
+
+/**
+Stringify an object into a URL with a query string and sorting the keys. The inverse of [`.parseUrl()`](https://github.com/sindresorhus/query-string#parseurlstring-options)
+
+Query items in the `query` property overrides queries in the `url` property.
+
+The `fragmentIdentifier` property overrides the fragment identifier in the `url` property.
+
+@example
+```
+queryString.stringifyUrl({url: 'https://foo.bar', query: {foo: 'bar'}});
+//=> 'https://foo.bar?foo=bar'
+
+queryString.stringifyUrl({url: 'https://foo.bar?foo=baz', query: {foo: 'bar'}});
+//=> 'https://foo.bar?foo=bar'
+
+queryString.stringifyUrl({
+	url: 'https://foo.bar',
+	query: {
+		top: 'foo'
+	},
+	fragmentIdentifier: 'bar'
+});
+//=> 'https://foo.bar?top=foo#bar'
+```
+*/
+export function stringifyUrl(
+	object: UrlObject,
+	options?: StringifyOptions
+): string;
+
+/**
+Pick query parameters from a URL.
+
+@param url - The URL containing the query parameters to pick.
+@param keys - The names of the query parameters to keep. All other query parameters will be removed from the URL.
+@param filter - A filter predicate that will be provided the name of each query parameter and its value. The `parseNumbers` and `parseBooleans` options also affect `value`.
+
+@returns The URL with the picked query parameters.
+
+@example
+```
+queryString.pick('https://foo.bar?foo=1&bar=2#hello', ['foo']);
+//=> 'https://foo.bar?foo=1#hello'
+
+queryString.pick('https://foo.bar?foo=1&bar=2#hello', (name, value) => value === 2, {parseNumbers: true});
+//=> 'https://foo.bar?bar=2#hello'
+```
+*/
+export function pick(
+	url: string,
+	keys: readonly string[],
+	options?: ParseOptions & StringifyOptions
+): string
+export function pick(
+	url: string,
+	filter: (key: string, value: string | boolean | number) => boolean,
+	options?: {parseBooleans: true, parseNumbers: true} & ParseOptions & StringifyOptions
+): string
+export function pick(
+	url: string,
+	filter: (key: string, value: string | boolean) => boolean,
+	options?: {parseBooleans: true} & ParseOptions & StringifyOptions
+): string
+export function pick(
+	url: string,
+	filter: (key: string, value: string | number) => boolean,
+	options?: {parseNumbers: true} & ParseOptions & StringifyOptions
+): string
+
+/**
+Exclude query parameters from a URL. Like `.pick()` but reversed.
+
+@param url - The URL containing the query parameters to exclude.
+@param keys - The names of the query parameters to remove. All other query parameters will remain in the URL.
+@param filter - A filter predicate that will be provided the name of each query parameter and its value. The `parseNumbers` and `parseBooleans` options also affect `value`.
+
+@returns The URL without the excluded the query parameters.
+
+@example
+```
+queryString.exclude('https://foo.bar?foo=1&bar=2#hello', ['foo']);
+//=> 'https://foo.bar?bar=2#hello'
+
+queryString.exclude('https://foo.bar?foo=1&bar=2#hello', (name, value) => value === 2, {parseNumbers: true});
+//=> 'https://foo.bar?foo=1#hello'
+```
+*/
+export function exclude(
+	url: string,
+	keys: readonly string[],
+	options?: ParseOptions & StringifyOptions
+): string
+export function exclude(
+	url: string,
+	filter: (key: string, value: string | boolean | number) => boolean,
+	options?: {parseBooleans: true, parseNumbers: true} & ParseOptions & StringifyOptions
+): string
+export function exclude(
+	url: string,
+	filter: (key: string, value: string | boolean) => boolean,
+	options?: {parseBooleans: true} & ParseOptions & StringifyOptions
+): string
+export function exclude(
+	url: string,
+	filter: (key: string, value: string | number) => boolean,
+	options?: {parseNumbers: true} & ParseOptions & StringifyOptions
+): string