Logo for jsDocs.io

query-string

  • Version 9.1.0
  • Published
  • 51.9 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

Index

Type Aliases

Namespaces

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;
      

          /**
      	Specify a pre-defined schema to be used when parsing values. The types specified will take precedence over options such as: `parseNumber`, `parseBooleans`, and `arrayFormat`.
      

      	Use this feature to override the type of a value. This can be useful when the type is ambiguous such as a phone number (see example 1 and 2).
      

      	It is possible to provide a custom function as the parameter type. The parameter's value will equal the function's return value (see example 4).
      

      	NOTE: Array types (`string[]` and `number[]`) will have no effect if `arrayFormat` is set to `none` (see example 5).
      

      	@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
      	Parse `age` as a number, even when `parseNumber` 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
      	Parse `age` using a custom value parser:
      	```
      	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 will have no effect 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 utilizing all types:
      	```
      	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}
      	```
      	*/
          readonly types?: Record<
              string,
              'number' | 'string' | 'string[]' | 'number[]' | ((value: string) => unknown)
          >;
      };

        type Stringifiable

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

          type StringifiableRecord

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

            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;
            };

              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().

                  Note: This behaviour can be changed with the skipNull option.

                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.

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

                  Parameter url

                  The URL to parse.

                  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 sort the keys.

                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)

                  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;
                    

                        /**
                    	Specify a pre-defined schema to be used when parsing values. The types specified will take precedence over options such as: `parseNumber`, `parseBooleans`, and `arrayFormat`.
                    

                    	Use this feature to override the type of a value. This can be useful when the type is ambiguous such as a phone number (see example 1 and 2).
                    

                    	It is possible to provide a custom function as the parameter type. The parameter's value will equal the function's return value (see example 4).
                    

                    	NOTE: Array types (`string[]` and `number[]`) will have no effect if `arrayFormat` is set to `none` (see example 5).
                    

                    	@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
                    	Parse `age` as a number, even when `parseNumber` 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
                    	Parse `age` using a custom value parser:
                    	```
                    	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 will have no effect 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 utilizing all types:
                    	```
                    	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}
                    	```
                    	*/
                        readonly types?: Record<
                            string,
                            'number' | 'string' | 'string[]' | 'number[]' | ((value: string) => unknown)
                        >;
                    };

                      type Stringifiable

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

                        type StringifiableRecord

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

                          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;
                          };

                            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 onejsDocs.io badgeto 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>