query-string 6.13.8 → 9.3.1

package/readme.md

@@ -1,43 +1,22 @@
-# query-string [![Build Status](https://travis-ci.com/sindresorhus/query-string.svg?branch=master)](https://travis-ci.com/github/sindresorhus/query-string) [![](https://badgen.net/bundlephobia/minzip/query-string)](https://bundlephobia.com/result?p=query-string)
+# query-string
 
 > Parse and stringify URL [query strings](https://en.wikipedia.org/wiki/Query_string)
 
-<br>
-
----
-
-<div align="center">
-	<p>
-		<p>
-			<sup>
-				<a href="https://github.com/sponsors/sindresorhus">My open source work is supported by the community</a>
-			</sup>
-		</p>
-		<sup>Special thanks to:</sup>
-		<br>
-		<br>
-		<a href="https://standardresume.co">
-			<img src="https://sindresorhus.com/assets/thanks/standard-resume-logo.svg" width="200"/>
-		</a>
-	</p>
-</div>
-
----
-
-<br>
-
 ## Install
 
+```sh
+npm install query-string
 ```
-$ npm install query-string
-```
 
-This module targets Node.js 6 or later and the latest version of Chrome, Firefox, and Safari. If you want support for older browsers, or, if your project is using create-react-app v1, use version 5: `npm install query-string@5`.
+> [!WARNING]
+> Remember the hyphen! Do not install the deprecated [`querystring`](https://github.com/Gozala/querystring) package!
+
+For browser usage, this package targets the latest version of Chrome, Firefox, and Safari.
 
 ## Usage
 
 ```js
-const queryString = require('query-string');
+import queryString from 'query-string';
 
 console.log(location.search);
 //=> '?foo=bar'
@@ -73,6 +52,14 @@ Parse a query string into an object. Leading `?` or `#` are ignored, so you can
 
 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`.
 
+```js
+queryString.parse('?foo=bar');
+//=> {foo: 'bar'}
+
+queryString.parse('#token=secret&name=jhon');
+//=> {token: 'secret', name: 'jhon'}
+```
+
 #### options
 
 Type: `object`
@@ -92,7 +79,7 @@ Default: `'none'`
 - `'bracket'`: Parse arrays with bracket representation:
 
 ```js
-const queryString = require('query-string');
+import queryString from 'query-string';
 
 queryString.parse('foo[]=1&foo[]=2&foo[]=3', {arrayFormat: 'bracket'});
 //=> {foo: ['1', '2', '3']}
@@ -101,7 +88,7 @@ queryString.parse('foo[]=1&foo[]=2&foo[]=3', {arrayFormat: 'bracket'});
 - `'index'`: Parse arrays with index representation:
 
 ```js
-const queryString = require('query-string');
+import queryString from 'query-string';
 
 queryString.parse('foo[0]=1&foo[1]=2&foo[3]=3', {arrayFormat: 'index'});
 //=> {foo: ['1', '2', '3']}
@@ -110,7 +97,7 @@ queryString.parse('foo[0]=1&foo[1]=2&foo[3]=3', {arrayFormat: 'index'});
 - `'comma'`: Parse arrays with elements separated by comma:
 
 ```js
-const queryString = require('query-string');
+import queryString from 'query-string';
 
 queryString.parse('foo=1,2,3', {arrayFormat: 'comma'});
 //=> {foo: ['1', '2', '3']}
@@ -119,16 +106,49 @@ queryString.parse('foo=1,2,3', {arrayFormat: 'comma'});
 - `'separator'`: Parse arrays with elements separated by a custom character:
 
 ```js
-const queryString = require('query-string');
+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:
+
+```js
+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`:
+
+```js
+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:
 
 ```js
-const queryString = require('query-string');
+import queryString from 'query-string';
 
 queryString.parse('foo=1&foo=2&foo=3');
 //=> {foo: ['1', '2', '3']}
@@ -154,7 +174,7 @@ Type: `boolean`\
 Default: `false`
 
 ```js
-const queryString = require('query-string');
+import queryString from 'query-string';
 
 queryString.parse('foo=1', {parseNumbers: true});
 //=> {foo: 1}
@@ -168,7 +188,7 @@ Type: `boolean`\
 Default: `false`
 
 ```js
-const queryString = require('query-string');
+import queryString from 'query-string';
 
 queryString.parse('foo=true', {parseBooleans: true});
 //=> {foo: true}
@@ -176,10 +196,145 @@ queryString.parse('foo=true', {parseBooleans: true});
 
 Parse the value as a boolean type instead of string type if it's a boolean.
 
+##### types
+
+Type: `object`\
+Default: `{}`
+
+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. When used with array formats (like `comma`, `separator`, `bracket`, etc.), the function is applied to each array element individually.
+
+Supported Types:
+
+
+- `'boolean'`: Parse `flagged` as a boolean (overriding the `parseBooleans` option):
+
+```js
+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`.
+
+- `'string'`: Parse `phoneNumber` as a string (overriding the `parseNumbers` option):
+
+```js
+import queryString from 'query-string';
+
+queryString.parse('?phoneNumber=%2B380951234567&id=1', {
+	parseNumbers: true,
+	types: {
+		phoneNumber: 'string',
+	}
+});
+//=> {phoneNumber: '+380951234567', id: 1}
+```
+
+- `'number'`:  Parse `age` as a number (even when `parseNumbers` is false):
+
+```js
+import queryString from 'query-string';
+
+queryString.parse('?age=20&id=01234&zipcode=90210', {
+	types: {
+		age: 'number',
+	}
+});
+//=> {age: 20, id: '01234', zipcode: '90210'}
+```
+
+- `'string[]'`:  Parse `items` as an array of strings (overriding the `parseNumbers` option):
+
+```js
+import queryString from 'query-string';
+
+queryString.parse('?age=20&items=1%2C2%2C3', {
+	parseNumbers: true,
+	types: {
+		items: 'string[]',
+	}
+});
+//=> {age: 20, items: ['1', '2', '3']}
+```
+
+- `'number[]'`:  Parse `items` as an array of numbers (even when `parseNumbers` is false):
+
+```js
+import queryString from 'query-string';
+
+queryString.parse('?age=20&items=1%2C2%2C3', {
+	types: {
+		items: 'number[]',
+	}
+});
+//=> {age: '20', items: [1, 2, 3]}
+```
+
+- `'Function'`: Provide a custom function as the parameter type. The parameter's value will equal the function's return value. When used with array formats (like `comma`, `separator`, `bracket`, etc.), the function is applied to each array element individually.
+
+```js
+import queryString from 'query-string';
+
+queryString.parse('?age=20&id=01234&zipcode=90210', {
+	types: {
+		age: value => value * 2,
+	}
+});
+//=> {age: 40, id: '01234', zipcode: '90210'}
+
+// With arrays, the function is applied to each element
+queryString.parse('?scores=10,20,30', {
+	arrayFormat: 'comma',
+	types: {
+		scores: value => Number(value) * 2,
+	}
+});
+//=> {scores: [20, 40, 60]}
+```
+
+NOTE: Array types (`string[]`, `number[]`) are ignored if `arrayFormat` is set to `'none'`.
+
+```js
+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'}
+```
+
+###### Function
+
+```js
+import queryString from 'query-string';
+
+queryString.parse('?age=20&id=01234&zipcode=90210', {
+	types: {
+		age: value => value * 2,
+	}
+});
+//=> {age: 40, id: '01234', zipcode: '90210'}
+```
+
+Parse the value as a boolean type instead of string type if it's a boolean.
+
 ### .stringify(object, options?)
 
 Stringify an object into a query string and sorting the keys.
 
+**Supported value types:** `string`, `number`, `bigint`, `boolean`, `null`, `undefined`, and arrays of these types. Other types like `Symbol`, functions, or objects (except arrays) will throw an error.
+
 #### options
 
 Type: `object`
@@ -189,7 +344,7 @@ Type: `object`
 Type: `boolean`\
 Default: `true`
 
-Strictly encode URI components with [strict-uri-encode](https://github.com/kevva/strict-uri-encode). 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.
+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.
 
 ##### encode
 
@@ -206,7 +361,7 @@ Default: `'none'`
 - `'bracket'`: Serialize arrays using bracket representation:
 
 ```js
-const queryString = require('query-string');
+import queryString from 'query-string';
 
 queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket'});
 //=> 'foo[]=1&foo[]=2&foo[]=3'
@@ -215,7 +370,7 @@ queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'bracket'});
 - `'index'`: Serialize arrays using index representation:
 
 ```js
-const queryString = require('query-string');
+import queryString from 'query-string';
 
 queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'index'});
 //=> 'foo[0]=1&foo[1]=2&foo[2]=3'
@@ -224,16 +379,66 @@ queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'index'});
 - `'comma'`: Serialize arrays by separating elements with comma:
 
 ```js
-const queryString = require('query-string');
+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 a custom character:
+
+```js
+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:
+
+```js
+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:
 
 ```js
-const queryString = require('query-string');
+import queryString from 'query-string';
 
 queryString.stringify({foo: [1, 2, 3]});
 //=> 'foo=1&foo=2&foo=3'
@@ -253,7 +458,7 @@ Type: `Function | boolean`
 Supports both `Function` as a custom sorting function or `false` to disable sorting.
 
 ```js
-const queryString = require('query-string');
+import queryString from 'query-string';
 
 const order = ['c', 'a', 'b'];
 
@@ -264,7 +469,7 @@ queryString.stringify({a: 1, b: 2, c: 3}, {
 ```
 
 ```js
-const queryString = require('query-string');
+import queryString from 'query-string';
 
 queryString.stringify({b: 1, c: 2, a: 3}, {sort: false});
 //=> 'b=1&c=2&a=3'
@@ -282,7 +487,7 @@ Type: `boolean`\
 Default: `false`
 
 ```js
-const queryString = require('query-string');
+import queryString from 'query-string';
 
 queryString.stringify({a: 1, b: undefined, c: null, d: 4}, {
 	skipNull: true
@@ -291,7 +496,7 @@ queryString.stringify({a: 1, b: undefined, c: null, d: 4}, {
 ```
 
 ```js
-const queryString = require('query-string');
+import queryString from 'query-string';
 
 queryString.stringify({a: undefined, b: null}, {
 	skipNull: true
@@ -307,7 +512,7 @@ Type: `boolean`\
 Default: `false`
 
 ```js
-const queryString = require('query-string');
+import queryString from 'query-string';
 
 queryString.stringify({a: 1, b: '', c: '', d: 4}, {
 	skipEmptyString: true
@@ -316,7 +521,7 @@ queryString.stringify({a: 1, b: '', c: '', d: 4}, {
 ```
 
 ```js
-const queryString = require('query-string');
+import queryString from 'query-string';
 
 queryString.stringify({a: '', b: ''}, {
 	skipEmptyString: true
@@ -324,11 +529,58 @@ queryString.stringify({a: '', b: ''}, {
 //=> ''
 ```
 
+##### replacer
+
+A function that transforms key-value pairs before stringification.
+
+Type: `function`\
+Default: `undefined`
+
+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`:
+
+```js
+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'
+```
+
+You can also use it to filter out keys:
+
+```js
+import queryString from 'query-string';
+
+queryString.stringify({
+	a: 1,
+	b: null,
+	c: 3
+}, {
+	replacer: (key, value) => value === null ? undefined : value
+});
+//=> 'a=1&c=3'
+```
+
 ### .extract(string)
 
 Extract a query string from a URL that can be passed into `.parse()`.
 
-Note: This behaviour can be changed with the `skipNull` option.
+```js
+queryString.extract('https://foo.bar?foo=bar');
+//=> 'foo=bar'
+```
 
 ### .parseUrl(string, options?)
 
@@ -339,7 +591,7 @@ Returns an object with a `url` and `query` property.
 If the `parseFragmentIdentifier` option is `true`, the object will also contain a `fragmentIdentifier` property.
 
 ```js
-const queryString = require('query-string');
+import queryString from 'query-string';
 
 queryString.parseUrl('https://foo.bar?foo=bar');
 //=> {url: 'https://foo.bar', query: {foo: 'bar'}}
@@ -364,7 +616,7 @@ Type: `boolean`\
 Default: `false`
 
 ```js
-const queryString = require('query-string');
+import queryString from 'query-string';
 
 queryString.parseUrl('https://foo.bar?foo=bar#xyz', {parseFragmentIdentifier: true});
 //=> {url: 'https://foo.bar', query: {foo: 'bar'}, fragmentIdentifier: 'xyz'}
@@ -415,6 +667,64 @@ Type: `object`
 
 Query items to add to the URL.
 
+### .pick(url, keys, options?)
+### .pick(url, filter, options?)
+
+Pick query parameters from a URL.
+
+Returns a string with the new URL.
+
+```js
+import queryString from 'query-string';
+
+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'
+```
+
+### .exclude(url, keys, options?)
+### .exclude(url, filter, options?)
+
+Exclude query parameters from a URL.
+
+Returns a string with the new URL.
+
+```js
+import queryString from 'query-string';
+
+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'
+```
+
+#### url
+
+Type: `string`
+
+The URL containing the query parameters to filter.
+
+#### keys
+
+Type: `string[]`
+
+The names of the query parameters to filter based on the function used.
+
+#### filter
+
+Type: `(key, value) => boolean`
+
+A filter predicate that will be provided the name of each query parameter and its value. The `parseNumbers` and `parseBooleans` options also affect `value`.
+
+#### options
+
+Type: `object`
+
+[Parse options](#options) and [stringify options](#options-1).
+
 ## Nesting
 
 This module intentionally doesn't support nesting as it's not spec'd and varies between implementations, which causes a lot of [edge cases](https://github.com/visionmedia/node-querystring/issues).
@@ -422,7 +732,7 @@ This module intentionally doesn't support nesting as it's not spec'd and varies
 You're much better off just converting the object to a JSON string:
 
 ```js
-const queryString = require('query-string');
+import queryString from 'query-string';
 
 queryString.stringify({
 	foo: 'bar',
@@ -436,7 +746,7 @@ queryString.stringify({
 However, there is support for multiple instances of the same key:
 
 ```js
-const queryString = require('query-string');
+import queryString from 'query-string';
 
 queryString.parse('likes=cake&name=bob&likes=icecream');
 //=> {likes: ['cake', 'icecream'], name: 'bob'}
@@ -450,7 +760,7 @@ queryString.stringify({color: ['taupe', 'chartreuse'], id: '515'});
 Sometimes you want to unset a key, or maybe just make it present without assigning a value to it. Here is how falsy values are stringified:
 
 ```js
-const queryString = require('query-string');
+import queryString from 'query-string';
 
 queryString.stringify({foo: false});
 //=> 'foo=false'
@@ -462,8 +772,8 @@ queryString.stringify({foo: undefined});
 //=> ''
 ```
 
-## query-string for enterprise
+## FAQ
 
-Available as part of the Tidelift Subscription.
+### Why is it parsing `+` as a space?
 
-The maintainers of query-string and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-query-string?utm_source=npm-query-string&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)
+See [this answer](https://github.com/sindresorhus/query-string/issues/305).