query-string 9.5.0 → 10.0.0

package/package.json

@@ -1,15 +1,11 @@
 {
 	"name": "query-string",
-	"version": "9.5.0",
+	"version": "10.0.0",
 	"description": "Parse and stringify URL query strings",
 	"license": "MIT",
 	"repository": "sindresorhus/query-string",
 	"funding": "https://github.com/sponsors/sindresorhus",
-	"author": {
-		"name": "Sindre Sorhus",
-		"email": "sindresorhus@gmail.com",
-		"url": "https://sindresorhus.com"
-	},
+	"author": "Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)",
 	"type": "module",
 	"exports": {
 		"types": "./index.d.ts",
@@ -17,11 +13,11 @@
 	},
 	"sideEffects": false,
 	"engines": {
-		"node": ">=18"
+		"node": ">=22"
 	},
 	"scripts": {
-		"benchmark": "node benchmark.js",
-		"test": "xo && ava && tsd"
+		"benchmark": "node --experimental-bench --bench benchmark.js",
+		"test": "xo && node --test && nz"
 	},
 	"files": [
 		"index.js",
@@ -46,21 +42,14 @@
 		"filter"
 	],
 	"dependencies": {
-		"decode-uri-component": "^0.5.0",
-		"filter-obj": "^5.1.0",
-		"split-on-first": "^3.0.0"
+		"filter-obj": "^6.1.0",
+		"split-on-first": "^4.0.0"
 	},
 	"devDependencies": {
-		"ava": "^6.1.1",
-		"benchmark": "^2.1.4",
+		"@typescript/native": "npm:typescript@^7.0.2",
 		"deep-equal": "^2.2.3",
-		"fast-check": "^3.15.1",
-		"tsd": "^0.30.7",
-		"xo": "^0.57.0"
-	},
-	"tsd": {
-		"compilerOptions": {
-			"module": "node16"
-		}
+		"fast-check": "^4.10.2",
+		"nz": "^0.1.0",
+		"xo": "^5.0.1"
 	}
 }

package/readme.md

@@ -59,8 +59,8 @@ The returned object is created with [`Object.create(null)`](https://developer.mo
 queryString.parse('?foo=bar');
 //=> {foo: 'bar'}
 
-queryString.parse('#token=secret&name=jhon');
-//=> {token: 'secret', name: 'jhon'}
+queryString.parse('#token=secret&name=john');
+//=> {name: 'john', token: 'secret'}
 ```
 
 #### options
@@ -72,7 +72,7 @@ Type: `object`
 Type: `boolean`\
 Default: `true`
 
-Decode the keys and values. URL components are decoded with [`decode-uri-component`](https://github.com/SamVerschueren/decode-uri-component).
+Decode the keys and values. A byte that is not valid UTF-8 becomes the replacement character `U+FFFD`, and the bytes around it are still decoded, like the [`URL` parser](https://developer.mozilla.org/en-US/docs/Web/API/URL) and [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) do. A `%` that is not followed by two hexadecimal digits is not an escape and is kept as it is.
 
 ##### arrayFormat
 
@@ -97,6 +97,8 @@ queryString.parse('foo[0]=1&foo[1]=2&foo[3]=3', {arrayFormat: 'index'});
 //=> {foo: ['1', '2', '3']}
 ```
 
+Entries without an index, such as `foo[]`, are appended after the highest index seen so far. Appending after an index greater than or equal to `Number.MAX_SAFE_INTEGER` is unsupported.
+
 - `'comma'`: Parse arrays with elements separated by comma:
 
 ```js
@@ -104,6 +106,21 @@ import queryString from 'query-string';
 
 queryString.parse('foo=1,2,3', {arrayFormat: 'comma'});
 //=> {foo: ['1', '2', '3']}
+
+queryString.parse('foo=1,2&foo=3', {arrayFormat: 'comma'});
+//=> {foo: ['1', '2', '3']}
+```
+
+A single value has no separator, so it is a plain value, not an array with one element. Use the [`types`](#types) option to always get an array, or use `'bracket-separator'`, which marks arrays explicitly.
+
+```js
+import queryString from 'query-string';
+
+queryString.parse('foo=1', {arrayFormat: 'comma'});
+//=> {foo: '1'}
+
+queryString.parse('foo=1', {arrayFormat: 'comma', types: {foo: 'string[]'}});
+//=> {foo: ['1']}
 ```
 
 - `'separator'`: Parse arrays with elements separated by a custom character:
@@ -133,10 +150,10 @@ queryString.parse('foo[]=1|2|3', {arrayFormat: 'bracket-separator', arrayFormatS
 //=> {foo: ['1', '2', '3']}
 
 queryString.parse('foo[]=1||3|||6', {arrayFormat: 'bracket-separator', arrayFormatSeparator: '|'});
-//=> {foo: ['1', '', 3, '', '', '6']}
+//=> {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']}
+//=> {bar: 'fluffy', baz: ['4'], foo: ['1', '2', '3']}
 ```
 
 - `'colon-list-separator'`: Parse arrays with parameter names that are explicitly marked with `:list`:
@@ -164,6 +181,18 @@ Default: `','`
 
 The character used to separate array elements when using `{arrayFormat: 'separator'}`.
 
+Only a literal separator delimits array elements. A percent-encoded separator (for example, `%2C`) is part of the element, which is how [`.stringify()`](#stringifyobject-options) encodes elements that contain the separator. Because of this, `%` and a hexadecimal digit are unsupported, since those also appear inside percent-encoded elements, and so are `&`, `+`, and `#`, since those already have a meaning in a URL: `&` separates parameters, `+` is decoded as a space, and `#` starts the fragment identifier. Those are handled on a best-effort basis, so the result is undefined. Whitespace cannot work at all, since leading and trailing whitespace is ignored when parsing, and a lone surrogate cannot be percent-encoded, so both throw a `TypeError`.
+
+```js
+import queryString from 'query-string';
+
+queryString.parse('foo=a%2Cb,c', {arrayFormat: 'comma'});
+//=> {foo: ['a,b', 'c']}
+
+queryString.parse('foo[]=a%2Cb,c', {arrayFormat: 'bracket-separator'});
+//=> {foo: ['a,b', 'c']}
+```
+
 ##### sort
 
 Type: `Function | boolean`\
@@ -171,6 +200,8 @@ Default: `true`
 
 Supports both `Function` as a custom sorting function or `false` to disable sorting.
 
+If omitted, keys are sorted using `Array#sort()`.
+
 ##### parseNumbers
 
 Type: `boolean`\
@@ -212,18 +243,19 @@ You can also provide a custom function to transform the value. The function will
 
 Supported Types:
 
-
 - `'boolean'`: Parse `flagged` as a boolean (overriding the `parseBooleans` option):
 
 ```js
+import queryString from 'query-string';
+
 queryString.parse('?isAdmin=true&flagged=true&isOkay=0', {
-		parseBooleans: false,
-		types: {
-				flagged: 'boolean',
-				isOkay: 'boolean',
-		},
+	parseBooleans: false,
+	types: {
+		flagged: 'boolean',
+		isOkay: 'boolean',
+	},
 });
-//=> {isAdmin: 'true', flagged: true, isOkay: false}
+//=> {flagged: true, isAdmin: 'true', isOkay: false}
 ```
 
 Note: The `'boolean'` type also converts `'0'` and `'1'` to booleans, and treats valueless keys (e.g. `?flag`) as `true`.
@@ -239,7 +271,7 @@ queryString.parse('?phoneNumber=%2B380951234567&id=1', {
 		phoneNumber: 'string',
 	}
 });
-//=> {phoneNumber: '+380951234567', id: 1}
+//=> {id: 1, phoneNumber: '+380951234567'}
 ```
 
 - `'number'`:  Parse `age` as a number (even when `parseNumbers` is false):
@@ -260,7 +292,8 @@ queryString.parse('?age=20&id=01234&zipcode=90210', {
 ```js
 import queryString from 'query-string';
 
-queryString.parse('?age=20&items=1%2C2%2C3', {
+queryString.parse('?age=20&items=1,2,3', {
+	arrayFormat: 'comma',
 	parseNumbers: true,
 	types: {
 		items: 'string[]',
@@ -274,7 +307,8 @@ queryString.parse('?age=20&items=1%2C2%2C3', {
 ```js
 import queryString from 'query-string';
 
-queryString.parse('?age=20&items=1%2C2%2C3', {
+queryString.parse('?age=20&items=1,2,3', {
+	arrayFormat: 'comma',
 	types: {
 		items: 'number[]',
 	}
@@ -304,34 +338,19 @@ queryString.parse('?scores=10,20,30', {
 //=> {scores: [20, 40, 60]}
 ```
 
-NOTE: Array types (`string[]`, `number[]`) are ignored if `arrayFormat` is set to `'none'`.
+NOTE: With `arrayFormat: 'none'`, array types (`string[]`, `number[]`) do not turn a single value into an array. The value stays a string, and `parseNumbers` and `parseBooleans` do not apply to it. A repeated key is still an array, and its items are parsed with the element type.
 
 ```js
-queryString.parse('ids=001%2C002%2C003&foods=apple%2Corange%2Cmango', {
+queryString.parse('ids=001,002,003&foods=apple,orange,mango', {
 	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'}
+//=> {foods: 'apple,orange,mango', ids: '001,002,003'}
 ```
 
-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.
@@ -356,6 +375,8 @@ Default: `true`
 
 [URL encode](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) the keys and values.
 
+A lone surrogate, which cannot be percent-encoded, is replaced with the replacement character U+FFFD, like [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) does.
+
 ##### arrayFormat
 
 Type: `string`\
@@ -390,7 +411,7 @@ queryString.stringify({foo: [1, 2, 3]}, {arrayFormat: 'comma'});
 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, '', '']}`.
+// and `.parse('foo=1,,', {arrayFormat: 'comma'})` would return `{foo: ['1', '', '']}`.
 ```
 
 - `'separator'`: Serialize arrays by separating elements with a custom character:
@@ -426,7 +447,7 @@ queryString.stringify({foo: [1, '', 3, null, null, 6]}, {arrayFormat: 'bracket-s
 //=> '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'
+//=> 'bar=fluffy&baz[]=4&foo[]=1|2|3'
 ```
 
 - `'colon-list-separator'`: Serialize arrays with parameter names that are explicitly marked with `:list`:
@@ -454,9 +475,12 @@ Default: `','`
 
 The character used to separate array elements when using `{arrayFormat: 'separator'}`.
 
+A separator inside an element is percent-encoded, so [`.parse()`](#parsestring-options) can tell it apart from the separator between elements. With `comma` and `separator`, a plain value that contains the separator is percent-encoded the same way, so it does not turn into an array. Because of this, `%` and a hexadecimal digit are unsupported, since those also appear inside percent-encoded elements, and so are `&`, `+`, and `#`, since those already have a meaning in a URL: `&` separates parameters, `+` is decoded as a space, and `#` starts the fragment identifier. Those are handled on a best-effort basis, so the result is undefined. Whitespace cannot work at all, since leading and trailing whitespace is ignored when parsing, and a lone surrogate cannot be percent-encoded, so both throw a `TypeError`.
+
 ##### sort
 
-Type: `Function | boolean`
+Type: `Function | boolean`\
+Default: `true`
 
 Supports both `Function` as a custom sorting function or `false` to disable sorting.
 
@@ -478,7 +502,7 @@ queryString.stringify({b: 1, c: 2, a: 3}, {sort: false});
 //=> 'b=1&c=2&a=3'
 ```
 
-If omitted, keys are sorted using `Array#sort()`, which means, converting them to strings and comparing strings in Unicode code point order.
+If omitted, keys are sorted using `Array#sort()`.
 
 ##### skipNull
 
@@ -539,7 +563,7 @@ 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.
+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. The `skipNull` and `skipEmptyString` options apply to the returned value.
 
 This is useful for custom serialization of non-primitive types like `Date`:
 
@@ -587,7 +611,7 @@ queryString.extract('https://foo.bar?foo=bar');
 
 ### .parseUrl(string, options?)
 
-Extract the URL and the query string as an object.
+Extract the URL and the query string as an object. Leading and trailing whitespace is ignored.
 
 Returns an object with a `url` and `query` property.
 
@@ -633,7 +657,9 @@ 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.
+Query items in the `query` property overrides queries in the `url` property. The query in the `url` property is written back from its plain string values, so `parseNumbers`, `parseBooleans`, and `types` do not rewrite it when the options are shared with [`.parseUrl()`](#parseurlstring-options).
+
+With `encode: false`, an array marker in an existing parameter name is only treated as a marker when it is literal, such as `a[]`, so a percent-encoded marker such as `a%5B%5D` is not overridden by the plain key. The existing parameter is kept as-is, so overriding `a` alongside an existing `a%5B%5D` in the URL writes both `a=2&a%5B%5D=1`.
 
 The `fragmentIdentifier` property overrides the fragment identifier in the `url` property.
 
@@ -662,7 +688,7 @@ Type: `object`
 
 Type: `string`
 
-The URL to stringify.
+The URL to stringify. Leading and trailing whitespace is ignored.
 
 ##### query
 
@@ -670,12 +696,30 @@ Type: `object`
 
 Query items to add to the URL.
 
+##### fragmentIdentifier
+
+Type: `string`
+
+The fragment identifier to add to the URL, without the leading `#`. An empty string removes the fragment identifier from the URL.
+
+Like the query values, it is a decoded value and is percent-encoded when `encode` is `true`, so [`.parseUrl()`](#parseurlstring-options) reads it back unchanged. `/`, `?`, and `#` are kept as-is, so hash routes like `#/users?id=1` work. When `encode` is `false`, it is written as-is.
+
+```js
+import queryString from 'query-string';
+
+queryString.stringifyUrl({url: 'https://foo.bar', fragmentIdentifier: '100%'});
+//=> 'https://foo.bar#100%25'
+
+queryString.stringifyUrl({url: 'https://foo.bar', fragmentIdentifier: '/users?id=1'});
+//=> 'https://foo.bar#/users?id=1'
+```
+
 ### .pick(url, keys, options?)
 ### .pick(url, filter, options?)
 
 Pick query parameters from a URL.
 
-Returns a string with the new URL.
+Returns a string with the new URL. The query parameters are sorted, like with [`.stringify()`](#stringifyobject-options). Pass `sort: false` in the options to keep their order. With sorting disabled, integer-index keys come first in ascending numeric order, following JavaScript object enumeration. Repeated keys are grouped together.
 
 ```js
 import queryString from 'query-string';
@@ -692,7 +736,7 @@ queryString.pick('https://foo.bar?foo=1&bar=2#hello', (name, value) => value ===
 
 Exclude query parameters from a URL.
 
-Returns a string with the new URL.
+Returns a string with the new URL. The query parameters are sorted, like with [`.stringify()`](#stringifyobject-options). Pass `sort: false` in the options to keep their order. With sorting disabled, integer-index keys come first in ascending numeric order, following JavaScript object enumeration. Repeated keys are grouped together.
 
 ```js
 import queryString from 'query-string';
@@ -708,7 +752,7 @@ queryString.exclude('https://foo.bar?foo=1&bar=2#hello', (name, value) => value
 
 Type: `string`
 
-The URL containing the query parameters to filter.
+The URL containing the query parameters to filter. Leading and trailing whitespace is ignored.
 
 #### keys
 
@@ -720,7 +764,7 @@ The names of the query parameters to filter based on the function used.
 
 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`.
+A filter predicate that will be provided the name of each query parameter and its value. The `parseNumbers`, `parseBooleans`, and `types` options also affect `value`. They only affect the value passed to the filter. The query parameters are written back to the URL from the plain string values, so a value like `007` is not rewritten as `7`. The query is decoded only when `encode` is `true`, so a value like `a%20b` is not percent-encoded a second time. With `encode: false`, the filter receives the key and value as they are in the URL. The `decode` option is ignored. The stringify options apply to the output, so `skipNull` and `skipEmptyString` also drop a parameter that the filter kept.
 
 #### options