query-string

query-string

Version 9.3.0
Published 7 days ago
56.7 kB
3 dependencies
MIT license

Install

npm i query-string

yarn add query-string

pnpm add query-string

Overview

Parse and stringify URL query strings

Type Aliases

type ParsedQuery

type ParsedQuery<T = string> = Record<string, T | null | Array<T | null>>;

type ParsedUrl

type ParsedUrl = {
    readonly url: string;
    readonly query: ParsedQuery;

    /**
	The fragment identifier of the URL.

	Present when the `parseFragmentIdentifier` option is `true`.
	*/
    readonly fragmentIdentifier?: string;
};

type ParseOptions

type ParseOptions = {
    /**
	Decode the keys and values. URI components are decoded with [`decode-uri-component`](https://github.com/SamVerschueren/decode-uri-component).

	@default true
	*/
    readonly decode?: boolean;

    /**
	@default 'none'

	- `bracket`: Parse arrays with bracket representation:

		```
		import queryString from 'query-string';

		queryString.parse('foo[]=1&foo[]=2&foo[]=3', {arrayFormat: 'bracket'});
		//=> {foo: ['1', '2', '3']}
		```

	- `index`: Parse arrays with index representation:

		```
		import queryString from 'query-string';

		queryString.parse('foo[0]=1&foo[1]=2&foo[3]=3', {arrayFormat: 'index'});
		//=> {foo: ['1', '2', '3']}
		```

	- `comma`: Parse arrays with elements separated by comma:

		```
		import queryString from '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 from 'query-string';

		queryString.parse('foo=1|2|3', {arrayFormat: 'separator', arrayFormatSeparator: '|'});
		//=> {foo: ['1', '2', '3']}
		```

	- `bracket-separator`: Parse arrays (that are explicitly marked with brackets) with elements separated by a custom character:

		```
		import queryString from 'query-string';

		queryString.parse('foo[]', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> {foo: []}

		queryString.parse('foo[]=', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> {foo: ['']}

		queryString.parse('foo[]=1', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
	 	//=> {foo: ['1']}

		queryString.parse('foo[]=1|2|3', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> {foo: ['1', '2', '3']}

		queryString.parse('foo[]=1||3|||6', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> {foo: ['1', '', 3, '', '', '6']}

		queryString.parse('foo[]=1|2|3&bar=fluffy&baz[]=4', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> {foo: ['1', '2', '3'], bar: 'fluffy', baz:['4']}
		```

	- `colon-list-separator`: Parse arrays with parameter names that are explicitly marked with `:list`:

		```
		import queryString from 'query-string';

		queryString.parse('foo:list=one&foo:list=two', {arrayFormat: 'colon-list-separator'});
		//=> {foo: ['one', 'two']}
		```

	- `none`: Parse arrays with elements using duplicate keys:

		```
		import queryString from 'query-string';

		queryString.parse('foo=1&foo=2&foo=3');
		//=> {foo: ['1', '2', '3']}
		```
	*/
    readonly arrayFormat?:
        | 'bracket'
        | 'index'
        | 'comma'
        | 'separator'
        | 'bracket-separator'
        | 'colon-list-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.

	If omitted, keys are sorted using `Array#sort`, which means, converting them to strings and comparing strings in Unicode code point order.

	@default true

	@example
	```
	import queryString from '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'}
	```

	@example
	```
	import queryString from 'query-string';

	queryString.parse('?a=one&c=three&b=two', {sort: false});
	//=> {a: 'one', c: 'three', b: 'two'}
	```
	*/
    readonly sort?: ((itemLeft: string, itemRight: string) => number) | false;

    /**
	Parse the value as a number type instead of string type if it's a number.

	@default false

	@example
	```
	import queryString from 'query-string';

	queryString.parse('foo=1', {parseNumbers: true});
	//=> {foo: 1}
	```
	*/
    readonly parseNumbers?: boolean;

    /**
	Parse the value as a boolean type instead of string type if it's a boolean.

	@default false

	@example
	```
	import queryString from '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 from 'query-string';

	queryString.parseUrl('https://foo.bar?foo=bar#xyz', {parseFragmentIdentifier: true});
	//=> {url: 'https://foo.bar', query: {foo: 'bar'}, fragmentIdentifier: 'xyz'}
	```
	*/
    readonly parseFragmentIdentifier?: boolean;

    /**
	Specifies a schema for parsing query values with explicit type declarations. When defined, the types provided here take precedence over general parsing options such as `parseNumbers`, `parseBooleans`, and `arrayFormat`.

	Use this option to explicitly define the type of a specific parameter—particularly useful in cases where the type might otherwise be ambiguous (e.g., phone numbers or IDs).

	You can also provide a custom function to transform the value. The function will receive the raw string and should return the desired parsed result (see Example 4).

	NOTE: Array types (`string[]`, `number[]`) are ignored if `arrayFormat` is set to `'none'`.

	@default {}

	@example
	Parse `phoneNumber` as a string, overriding the `parseNumber` option:
	```
	import queryString from 'query-string';

	queryString.parse('?phoneNumber=%2B380951234567&id=1', {
		parseNumbers: true,
		types: {
			phoneNumber: 'string',
		}
	});
	//=> {phoneNumber: '+380951234567', id: 1}
	```

	@example
	Parse `items` as an array of strings, overriding the `parseNumber` option:
	```
	import queryString from 'query-string';

	queryString.parse('?age=20&items=1%2C2%2C3', {
		parseNumber: true,
		types: {
			items: 'string[]',
		}
	});
	//=> {age: 20, items: ['1', '2', '3']}
	```

	@example
	Force `age` to be parsed as a number even when `parseNumbers` is false:
	```
	import queryString from 'query-string';

	queryString.parse('?age=20&id=01234&zipcode=90210', {
		types: {
			age: 'number',
		}
	});
	//=> {age: 20, id: '01234', zipcode: '90210'}
	```

	@example
	Use a custom parser function to transform the value of `age`:
	```
	import queryString from 'query-string';

	queryString.parse('?age=20&id=01234&zipcode=90210', {
		types: {
			age: (value) => value * 2,
		}
	});
	//=> {age: 40, id: '01234', zipcode: '90210'}
	```

	@example
	Array types are ignored when `arrayFormat` is set to `'none'`:
	```
	queryString.parse('ids=001%2C002%2C003&foods=apple%2Corange%2Cmango', {
		arrayFormat: 'none',
		types: {
			ids: 'number[]',
			foods: 'string[]',
		},
	}
	//=> {ids:'001,002,003', foods:'apple,orange,mango'}
	```

	@example
	Parse a query using multiple type definitions:
	```
	import queryString from 'query-string';

	queryString.parse('?ids=001%2C002%2C003&items=1%2C2%2C3&price=22%2E00&numbers=1%2C2%2C3&double=5&number=20', {
		arrayFormat: 'comma',
		types: {
			ids: 'string',
			items: 'string[]',
			price: 'string',
			numbers: 'number[]',
			double: (value) => value * 2,
			number: 'number',
		},
	});
	//=> {ids: '001,002,003', items: ['1', '2', '3'], price: '22.00', numbers: [1, 2, 3], double: 10, number: 20}
	```

	@example
	Force `flagged` to be parsed as a boolean even when `parseBooleans` is false:
	```
	queryString.parse('?isAdmin=true&flagged=true&isOkay=0', {
			parseBooleans: false,
			types: {
					flagged: 'boolean',
					isOkay: 'boolean',
			},
	});
	//=> {isAdmin: 'true', flagged: true, isOkay: false}
	```

	Note: The `'boolean'` type also converts `'0'` and `'1'` to booleans, and treats valueless keys (e.g. `?flag`) as `true`.
	*/
    readonly types?: Record<
        string,
        | 'boolean'
        | 'number'
        | 'string'
        | 'string[]'
        | 'number[]'
        | ((value: string) => unknown)
    >;
};

type Stringifiable

type Stringifiable = string | boolean | number | bigint | null | undefined;

Supported value types for query string parameters.
Note: Symbol, functions, and objects (except arrays) are not supported and will throw an error when stringified.

type StringifiableRecord

type StringifiableRecord = Record<string, Stringifiable | readonly Stringifiable[]>;

A record of stringifiable values.

type StringifyOptions

type StringifyOptions = {
    /**
	Strictly encode URI components. It uses [`encodeURIComponent`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) if set to `false`. You probably [don't care](https://github.com/sindresorhus/query-string/issues/42) about this option.

	@default true
	*/
    readonly strict?: boolean;

    /**
	[URL encode](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) the keys and values.

	@default true
	*/
    readonly encode?: boolean;

    /**
	@default 'none'

	- `bracket`: Serialize arrays using bracket representation:

		```
		import queryString from 'query-string';

		queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket'});
		//=> 'foo[]=1&foo[]=2&foo[]=3'
		```

	- `index`: Serialize arrays using index representation:

		```
		import queryString from 'query-string';

		queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'index'});
		//=> 'foo[0]=1&foo[1]=2&foo[2]=3'
		```

	- `comma`: Serialize arrays by separating elements with comma:

		```
		import queryString from 'query-string';

		queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'comma'});
		//=> 'foo=1,2,3'

		queryString.stringify({foo: [1, null, '']}, {arrayFormat: 'comma'});
		//=> 'foo=1,,'
		// Note that typing information for null values is lost
		// and `.parse('foo=1,,')` would return `{foo: [1, '', '']}`.
		```

	- `separator`: Serialize arrays by separating elements with character:

		```
		import queryString from 'query-string';

		queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'separator', arrayFormatSeparator: '|'});
		//=> 'foo=1|2|3'
		```

	- `bracket-separator`: Serialize arrays by explicitly post-fixing array names with brackets and separating elements with a custom character:

		```
		import queryString from 'query-string';

		queryString.stringify({foo: []}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> 'foo[]'

		queryString.stringify({foo: ['']}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> 'foo[]='

		queryString.stringify({foo: [1]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> 'foo[]=1'

		queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> 'foo[]=1|2|3'

		queryString.stringify({foo: [1, '', 3, null, null, 6]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> 'foo[]=1||3|||6'

		queryString.stringify({foo: [1, '', 3, null, null, 6]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|', skipNull: true});
		//=> 'foo[]=1||3|6'

		queryString.stringify({foo: [1, 2, 3], bar: 'fluffy', baz: [4]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> 'foo[]=1|2|3&bar=fluffy&baz[]=4'
		```

	- `colon-list-separator`: Serialize arrays with parameter names that are explicitly marked with `:list`:

		```js
		import queryString from 'query-string';

		queryString.stringify({foo: ['one', 'two']}, {arrayFormat: 'colon-list-separator'});
		//=> 'foo:list=one&foo:list=two'
		```

	- `none`: Serialize arrays by using duplicate keys:

		```
		import queryString from 'query-string';

		queryString.stringify({foo: [1, 2, 3]});
		//=> 'foo=1&foo=2&foo=3'
		```
	*/
    readonly arrayFormat?:
        | 'bracket'
        | 'index'
        | 'comma'
        | 'separator'
        | 'bracket-separator'
        | 'colon-list-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.

	If omitted, keys are sorted using `Array#sort`, which means, converting them to strings and comparing strings in Unicode code point order.

	@default true

	@example
	```
	import queryString from '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'
	```

	@example
	```
	import queryString from 'query-string';

	queryString.stringify({b: 1, c: 2, a: 3}, {sort: false});
	//=> '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 from '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 from 'query-string';

	queryString.stringify({a: 1, b: '', c: '', d: 4}, {
		skipEmptyString: true
	});
	//=> 'a=1&d=4'
	```

	@example
	```
	import queryString from 'query-string';

	queryString.stringify({a: '', b: ''}, {
		skipEmptyString: true
	});
	//=> ''
	```
	*/
    readonly skipEmptyString?: boolean;

    /**
	A function that transforms key-value pairs before stringification.

	Similar to the `replacer` parameter of `JSON.stringify()`, this function is called for each key-value pair and can be used to transform values before they are stringified.

	The function receives the key and value, and should return the transformed value. Returning `undefined` will omit the key-value pair from the resulting query string.

	This is useful for custom serialization of non-primitive types like `Date`:

	@example
	```
	import queryString from 'query-string';

	queryString.stringify({
		date: new Date('2024-01-15T10:30:00Z'),
		name: 'John'
	}, {
		replacer: (key, value) => {
			if (value instanceof Date) {
				return value.toISOString();
			}

			return value;
		}
	});
	//=> 'date=2024-01-15T10%3A30%3A00.000Z&name=John'
	```

	@example
	```
	import queryString from 'query-string';

	// Omit keys with null values using replacer instead of skipNull
	queryString.stringify({
		a: 1,
		b: null,
		c: 3
	}, {
		replacer: (key, value) => value === null ? undefined : value
	});
	//=> 'a=1&c=3'
	```
	*/
    readonly replacer?: (key: string, value: unknown) => unknown;
};

type UrlObject

type UrlObject = {
    readonly url: string;

    /**
	Overrides queries in the `url` property.
	*/
    readonly query?: StringifiableRecord;

    /**
	Overrides the fragment identifier in the `url` property.
	*/
    readonly fragmentIdentifier?: string;
};

Namespaces

namespace default

module 'base.d.ts' {}

Decode the keys and values. URI components are decoded with [decode-uri-component](https://github.com/SamVerschueren/decode-uri-component).
true

function exclude

exclude: {
    (
        url: string,
        keys: readonly string[],
        options?: ParseOptions & StringifyOptions
    ): string;
    (
        url: string,
        filter: (key: string, value: string | number | boolean) => boolean,
        options?: { parseBooleans: true; parseNumbers: true } & ParseOptions &
            StringifyOptions
    ): string;
    (
        url: string,
        filter: (key: string, value: string | boolean) => boolean,
        options?: { parseBooleans: true } & ParseOptions & StringifyOptions
    ): string;
    (
        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.
Parameter url
The URL containing the query parameters to exclude.
Parameter keys
The names of the query parameters to remove. All other query parameters will remain in the URL.
Parameter 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 1
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'

function extract

extract: (url: string) => string;

Extract a query string from a URL that can be passed into .parse().

Example 1

import queryString from 'query-string';

queryString.extract('https://foo.bar?foo=bar');
//=> 'foo=bar'

function parse

parse: {
    (
        query: string,
        options: { parseBooleans: true; parseNumbers: true } & ParseOptions
    ): ParsedQuery<string | boolean | number>;
    (query: string, options: { parseBooleans: true } & ParseOptions): ParsedQuery<
        string | boolean
    >;
    (query: string, options: { parseNumbers: true } & ParseOptions): ParsedQuery<
        string | number
    >;
    (query: string, options?: ParseOptions): ParsedQuery<string>;
};

Parse a query string into an object. Leading ? or # are ignored, so you can pass location.search or location.hash directly.
The returned object is created with [Object.create(null)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/create) and thus does not have a prototype.
Parameter query
The query string to parse.

function parseUrl

parseUrl: (url: string, options?: ParseOptions) => ParsedUrl;

Extract the URL and the query string as an object.

Parameter url

The URL to parse.

Returns

An object with a url and query property.

If the parseFragmentIdentifier option is true, the object will also contain a fragmentIdentifier property.

Example 1

import queryString from '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'}

function pick

pick: {
    (
        url: string,
        keys: readonly string[],
        options?: ParseOptions & StringifyOptions
    ): string;
    (
        url: string,
        filter: (key: string, value: string | number | boolean) => boolean,
        options?: { parseBooleans: true; parseNumbers: true } & ParseOptions &
            StringifyOptions
    ): string;
    (
        url: string,
        filter: (key: string, value: string | boolean) => boolean,
        options?: { parseBooleans: true } & ParseOptions & StringifyOptions
    ): string;
    (
        url: string,
        filter: (key: string, value: string | number) => boolean,
        options?: { parseNumbers: true } & ParseOptions & StringifyOptions
    ): string;
};

Pick query parameters from a URL.
Parameter url
The URL containing the query parameters to pick.
Parameter keys
The names of the query parameters to keep. All other query parameters will be removed from the URL.
Parameter 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 1
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'

function stringify

stringify: (object: Record<string, any>, options?: StringifyOptions) => string;

Stringify an object into a query string and sorting the keys.
Parameter object
Object to stringify. Supported value types are: string, number, bigint, boolean, null, undefined, and arrays of these types. Other types like Symbol, functions, or objects (except arrays) will throw an error.
Example 1
import queryString from 'query-string'; queryString.stringify({foo: 'bar', baz: 42, qux: true}); //=> 'baz=42&foo=bar&qux=true'

function stringifyUrl

stringifyUrl: (object: UrlObject, options?: StringifyOptions) => 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)
The options are the same as for .stringify().
Returns
A string with the URL and a query string.
Query items in the query property overrides queries in the url property.
The fragmentIdentifier property overrides the fragment identifier in the url property.
Example 1
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'

type ParsedQuery

type ParsedQuery<T = string> = Record<string, T | null | Array<T | null>>;

type ParsedUrl

type ParsedUrl = {
    readonly url: string;
    readonly query: ParsedQuery;

    /**
	The fragment identifier of the URL.

	Present when the `parseFragmentIdentifier` option is `true`.
	*/
    readonly fragmentIdentifier?: string;
};

type ParseOptions

type ParseOptions = {
    /**
	Decode the keys and values. URI components are decoded with [`decode-uri-component`](https://github.com/SamVerschueren/decode-uri-component).

	@default true
	*/
    readonly decode?: boolean;

    /**
	@default 'none'

	- `bracket`: Parse arrays with bracket representation:

		```
		import queryString from 'query-string';

		queryString.parse('foo[]=1&foo[]=2&foo[]=3', {arrayFormat: 'bracket'});
		//=> {foo: ['1', '2', '3']}
		```

	- `index`: Parse arrays with index representation:

		```
		import queryString from 'query-string';

		queryString.parse('foo[0]=1&foo[1]=2&foo[3]=3', {arrayFormat: 'index'});
		//=> {foo: ['1', '2', '3']}
		```

	- `comma`: Parse arrays with elements separated by comma:

		```
		import queryString from '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 from 'query-string';

		queryString.parse('foo=1|2|3', {arrayFormat: 'separator', arrayFormatSeparator: '|'});
		//=> {foo: ['1', '2', '3']}
		```

	- `bracket-separator`: Parse arrays (that are explicitly marked with brackets) with elements separated by a custom character:

		```
		import queryString from 'query-string';

		queryString.parse('foo[]', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> {foo: []}

		queryString.parse('foo[]=', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> {foo: ['']}

		queryString.parse('foo[]=1', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
	 	//=> {foo: ['1']}

		queryString.parse('foo[]=1|2|3', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> {foo: ['1', '2', '3']}

		queryString.parse('foo[]=1||3|||6', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> {foo: ['1', '', 3, '', '', '6']}

		queryString.parse('foo[]=1|2|3&bar=fluffy&baz[]=4', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> {foo: ['1', '2', '3'], bar: 'fluffy', baz:['4']}
		```

	- `colon-list-separator`: Parse arrays with parameter names that are explicitly marked with `:list`:

		```
		import queryString from 'query-string';

		queryString.parse('foo:list=one&foo:list=two', {arrayFormat: 'colon-list-separator'});
		//=> {foo: ['one', 'two']}
		```

	- `none`: Parse arrays with elements using duplicate keys:

		```
		import queryString from 'query-string';

		queryString.parse('foo=1&foo=2&foo=3');
		//=> {foo: ['1', '2', '3']}
		```
	*/
    readonly arrayFormat?:
        | 'bracket'
        | 'index'
        | 'comma'
        | 'separator'
        | 'bracket-separator'
        | 'colon-list-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.

	If omitted, keys are sorted using `Array#sort`, which means, converting them to strings and comparing strings in Unicode code point order.

	@default true

	@example
	```
	import queryString from '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'}
	```

	@example
	```
	import queryString from 'query-string';

	queryString.parse('?a=one&c=three&b=two', {sort: false});
	//=> {a: 'one', c: 'three', b: 'two'}
	```
	*/
    readonly sort?: ((itemLeft: string, itemRight: string) => number) | false;

    /**
	Parse the value as a number type instead of string type if it's a number.

	@default false

	@example
	```
	import queryString from 'query-string';

	queryString.parse('foo=1', {parseNumbers: true});
	//=> {foo: 1}
	```
	*/
    readonly parseNumbers?: boolean;

    /**
	Parse the value as a boolean type instead of string type if it's a boolean.

	@default false

	@example
	```
	import queryString from '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 from 'query-string';

	queryString.parseUrl('https://foo.bar?foo=bar#xyz', {parseFragmentIdentifier: true});
	//=> {url: 'https://foo.bar', query: {foo: 'bar'}, fragmentIdentifier: 'xyz'}
	```
	*/
    readonly parseFragmentIdentifier?: boolean;

    /**
	Specifies a schema for parsing query values with explicit type declarations. When defined, the types provided here take precedence over general parsing options such as `parseNumbers`, `parseBooleans`, and `arrayFormat`.

	Use this option to explicitly define the type of a specific parameter—particularly useful in cases where the type might otherwise be ambiguous (e.g., phone numbers or IDs).

	You can also provide a custom function to transform the value. The function will receive the raw string and should return the desired parsed result (see Example 4).

	NOTE: Array types (`string[]`, `number[]`) are ignored if `arrayFormat` is set to `'none'`.

	@default {}

	@example
	Parse `phoneNumber` as a string, overriding the `parseNumber` option:
	```
	import queryString from 'query-string';

	queryString.parse('?phoneNumber=%2B380951234567&id=1', {
		parseNumbers: true,
		types: {
			phoneNumber: 'string',
		}
	});
	//=> {phoneNumber: '+380951234567', id: 1}
	```

	@example
	Parse `items` as an array of strings, overriding the `parseNumber` option:
	```
	import queryString from 'query-string';

	queryString.parse('?age=20&items=1%2C2%2C3', {
		parseNumber: true,
		types: {
			items: 'string[]',
		}
	});
	//=> {age: 20, items: ['1', '2', '3']}
	```

	@example
	Force `age` to be parsed as a number even when `parseNumbers` is false:
	```
	import queryString from 'query-string';

	queryString.parse('?age=20&id=01234&zipcode=90210', {
		types: {
			age: 'number',
		}
	});
	//=> {age: 20, id: '01234', zipcode: '90210'}
	```

	@example
	Use a custom parser function to transform the value of `age`:
	```
	import queryString from 'query-string';

	queryString.parse('?age=20&id=01234&zipcode=90210', {
		types: {
			age: (value) => value * 2,
		}
	});
	//=> {age: 40, id: '01234', zipcode: '90210'}
	```

	@example
	Array types are ignored when `arrayFormat` is set to `'none'`:
	```
	queryString.parse('ids=001%2C002%2C003&foods=apple%2Corange%2Cmango', {
		arrayFormat: 'none',
		types: {
			ids: 'number[]',
			foods: 'string[]',
		},
	}
	//=> {ids:'001,002,003', foods:'apple,orange,mango'}
	```

	@example
	Parse a query using multiple type definitions:
	```
	import queryString from 'query-string';

	queryString.parse('?ids=001%2C002%2C003&items=1%2C2%2C3&price=22%2E00&numbers=1%2C2%2C3&double=5&number=20', {
		arrayFormat: 'comma',
		types: {
			ids: 'string',
			items: 'string[]',
			price: 'string',
			numbers: 'number[]',
			double: (value) => value * 2,
			number: 'number',
		},
	});
	//=> {ids: '001,002,003', items: ['1', '2', '3'], price: '22.00', numbers: [1, 2, 3], double: 10, number: 20}
	```

	@example
	Force `flagged` to be parsed as a boolean even when `parseBooleans` is false:
	```
	queryString.parse('?isAdmin=true&flagged=true&isOkay=0', {
			parseBooleans: false,
			types: {
					flagged: 'boolean',
					isOkay: 'boolean',
			},
	});
	//=> {isAdmin: 'true', flagged: true, isOkay: false}
	```

	Note: The `'boolean'` type also converts `'0'` and `'1'` to booleans, and treats valueless keys (e.g. `?flag`) as `true`.
	*/
    readonly types?: Record<
        string,
        | 'boolean'
        | 'number'
        | 'string'
        | 'string[]'
        | 'number[]'
        | ((value: string) => unknown)
    >;
};

type Stringifiable

type Stringifiable = string | boolean | number | bigint | null | undefined;

Supported value types for query string parameters.
Note: Symbol, functions, and objects (except arrays) are not supported and will throw an error when stringified.

type StringifiableRecord

type StringifiableRecord = Record<string, Stringifiable | readonly Stringifiable[]>;

A record of stringifiable values.

type StringifyOptions

type StringifyOptions = {
    /**
	Strictly encode URI components. It uses [`encodeURIComponent`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) if set to `false`. You probably [don't care](https://github.com/sindresorhus/query-string/issues/42) about this option.

	@default true
	*/
    readonly strict?: boolean;

    /**
	[URL encode](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) the keys and values.

	@default true
	*/
    readonly encode?: boolean;

    /**
	@default 'none'

	- `bracket`: Serialize arrays using bracket representation:

		```
		import queryString from 'query-string';

		queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket'});
		//=> 'foo[]=1&foo[]=2&foo[]=3'
		```

	- `index`: Serialize arrays using index representation:

		```
		import queryString from 'query-string';

		queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'index'});
		//=> 'foo[0]=1&foo[1]=2&foo[2]=3'
		```

	- `comma`: Serialize arrays by separating elements with comma:

		```
		import queryString from 'query-string';

		queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'comma'});
		//=> 'foo=1,2,3'

		queryString.stringify({foo: [1, null, '']}, {arrayFormat: 'comma'});
		//=> 'foo=1,,'
		// Note that typing information for null values is lost
		// and `.parse('foo=1,,')` would return `{foo: [1, '', '']}`.
		```

	- `separator`: Serialize arrays by separating elements with character:

		```
		import queryString from 'query-string';

		queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'separator', arrayFormatSeparator: '|'});
		//=> 'foo=1|2|3'
		```

	- `bracket-separator`: Serialize arrays by explicitly post-fixing array names with brackets and separating elements with a custom character:

		```
		import queryString from 'query-string';

		queryString.stringify({foo: []}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> 'foo[]'

		queryString.stringify({foo: ['']}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> 'foo[]='

		queryString.stringify({foo: [1]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> 'foo[]=1'

		queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> 'foo[]=1|2|3'

		queryString.stringify({foo: [1, '', 3, null, null, 6]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> 'foo[]=1||3|||6'

		queryString.stringify({foo: [1, '', 3, null, null, 6]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|', skipNull: true});
		//=> 'foo[]=1||3|6'

		queryString.stringify({foo: [1, 2, 3], bar: 'fluffy', baz: [4]}, {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
		//=> 'foo[]=1|2|3&bar=fluffy&baz[]=4'
		```

	- `colon-list-separator`: Serialize arrays with parameter names that are explicitly marked with `:list`:

		```js
		import queryString from 'query-string';

		queryString.stringify({foo: ['one', 'two']}, {arrayFormat: 'colon-list-separator'});
		//=> 'foo:list=one&foo:list=two'
		```

	- `none`: Serialize arrays by using duplicate keys:

		```
		import queryString from 'query-string';

		queryString.stringify({foo: [1, 2, 3]});
		//=> 'foo=1&foo=2&foo=3'
		```
	*/
    readonly arrayFormat?:
        | 'bracket'
        | 'index'
        | 'comma'
        | 'separator'
        | 'bracket-separator'
        | 'colon-list-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.

	If omitted, keys are sorted using `Array#sort`, which means, converting them to strings and comparing strings in Unicode code point order.

	@default true

	@example
	```
	import queryString from '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'
	```

	@example
	```
	import queryString from 'query-string';

	queryString.stringify({b: 1, c: 2, a: 3}, {sort: false});
	//=> '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 from '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 from 'query-string';

	queryString.stringify({a: 1, b: '', c: '', d: 4}, {
		skipEmptyString: true
	});
	//=> 'a=1&d=4'
	```

	@example
	```
	import queryString from 'query-string';

	queryString.stringify({a: '', b: ''}, {
		skipEmptyString: true
	});
	//=> ''
	```
	*/
    readonly skipEmptyString?: boolean;

    /**
	A function that transforms key-value pairs before stringification.

	Similar to the `replacer` parameter of `JSON.stringify()`, this function is called for each key-value pair and can be used to transform values before they are stringified.

	The function receives the key and value, and should return the transformed value. Returning `undefined` will omit the key-value pair from the resulting query string.

	This is useful for custom serialization of non-primitive types like `Date`:

	@example
	```
	import queryString from 'query-string';

	queryString.stringify({
		date: new Date('2024-01-15T10:30:00Z'),
		name: 'John'
	}, {
		replacer: (key, value) => {
			if (value instanceof Date) {
				return value.toISOString();
			}

			return value;
		}
	});
	//=> 'date=2024-01-15T10%3A30%3A00.000Z&name=John'
	```

	@example
	```
	import queryString from 'query-string';

	// Omit keys with null values using replacer instead of skipNull
	queryString.stringify({
		a: 1,
		b: null,
		c: 3
	}, {
		replacer: (key, value) => value === null ? undefined : value
	});
	//=> 'a=1&c=3'
	```
	*/
    readonly replacer?: (key: string, value: unknown) => unknown;
};

type UrlObject

type UrlObject = {
    readonly url: string;

    /**
	Overrides queries in the `url` property.
	*/
    readonly query?: StringifiableRecord;

    /**
	Overrides the fragment identifier in the `url` property.
	*/
    readonly fragmentIdentifier?: string;
};

Package Files (2)

Dependencies (3)

Dev Dependencies (6)

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/query-string.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/query-string)

HTML

<a href="https://www.jsdocs.io/package/query-string"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated 7 days ago.
Package analyzed in 3026 ms.
Missing or incorrect documentation? Open an issue for this package.

query-string

Install

Overview

Index

Type Aliases

Namespaces

Type Aliases

type ParsedQuery

type ParsedUrl

type ParseOptions

type Stringifiable

type StringifiableRecord

type StringifyOptions

type UrlObject

Namespaces

namespace default

function exclude

Parameter url

Parameter keys

Parameter filter

Returns

Example 1

function extract

Example 1

function parse

Parameter query

function parseUrl

Parameter url

Returns

Example 1

function pick

Parameter url

Parameter keys

Parameter filter

Returns

Example 1

function stringify

Parameter object

Example 1

function stringifyUrl

Returns

Example 1

type ParsedQuery

type ParsedUrl

type ParseOptions

type Stringifiable

type StringifiableRecord

type StringifyOptions

type UrlObject

Package Files (2)

Dependencies (3)

Dev Dependencies (6)

Peer Dependencies (0)

Badge