query-string 9.3.0 → 9.4.0

package/base.d.ts

@@ -182,14 +182,14 @@ export type ParseOptions = {
 
 	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).
+	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.
 
 	NOTE: Array types (`string[]`, `number[]`) are ignored if `arrayFormat` is set to `'none'`.
 
 	@default {}
 
 	@example
-	Parse `phoneNumber` as a string, overriding the `parseNumber` option:
+	Parse `phoneNumber` as a string, overriding the `parseNumbers` option:
 	```
 	import queryString from 'query-string';
 
@@ -203,12 +203,12 @@ export type ParseOptions = {
 	```
 
 	@example
-	Parse `items` as an array of strings, overriding the `parseNumber` option:
+	Parse `items` as an array of strings, overriding the `parseNumbers` option:
 	```
 	import queryString from 'query-string';
 
 	queryString.parse('?age=20&items=1%2C2%2C3', {
-		parseNumber: true,
+		parseNumbers: true,
 		types: {
 			items: 'string[]',
 		}
@@ -236,12 +236,27 @@ export type ParseOptions = {
 
 	queryString.parse('?age=20&id=01234&zipcode=90210', {
 		types: {
-			age: (value) => value * 2,
+			age: value => value * 2,
 		}
 	});
 	//=> {age: 40, id: '01234', zipcode: '90210'}
 	```
 
+	@example
+	Custom functions are applied to each array element when using array formats:
+	```
+	import queryString from 'query-string';
+
+	// 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]}
+	```
+
 	@example
 	Array types are ignored when `arrayFormat` is set to `'none'`:
 	```
@@ -267,7 +282,7 @@ export type ParseOptions = {
 			items: 'string[]',
 			price: 'string',
 			numbers: 'number[]',
-			double: (value) => value * 2,
+			double: value => value * 2,
 			number: 'number',
 		},
 	});

package/base.js

@@ -24,15 +24,12 @@ function encoderForArrayFormat(options) {
 				}
 
 				if (value === null) {
-					return [
-						...result, [encode(key, options), '[', index, ']'].join(''),
-					];
+					result.push([encode(key, options), '[', index, ']'].join(''));
+					return result;
 				}
 
-				return [
-					...result,
-					[encode(key, options), '[', encode(index, options), ']=', encode(value, options)].join(''),
-				];
+				result.push([encode(key, options), '[', encode(index, options), ']=', encode(value, options)].join(''));
+				return result;
 			};
 		}
 
@@ -47,16 +44,12 @@ function encoderForArrayFormat(options) {
 				}
 
 				if (value === null) {
-					return [
-						...result,
-						[encode(key, options), '[]'].join(''),
-					];
+					result.push([encode(key, options), '[]'].join(''));
+					return result;
 				}
 
-				return [
-					...result,
-					[encode(key, options), '[]=', encode(value, options)].join(''),
-				];
+				result.push([encode(key, options), '[]=', encode(value, options)].join(''));
+				return result;
 			};
 		}
 
@@ -71,16 +64,12 @@ function encoderForArrayFormat(options) {
 				}
 
 				if (value === null) {
-					return [
-						...result,
-						[encode(key, options), ':list='].join(''),
-					];
+					result.push([encode(key, options), ':list='].join(''));
+					return result;
 				}
 
-				return [
-					...result,
-					[encode(key, options), ':list=', encode(value, options)].join(''),
-				];
+				result.push([encode(key, options), ':list=', encode(value, options)].join(''));
+				return result;
 			};
 		}
 
@@ -104,10 +93,12 @@ function encoderForArrayFormat(options) {
 				value = value === null ? '' : value;
 
 				if (result.length === 0) {
-					return [[encode(key, options), keyValueSeparator, encode(value, options)].join('')];
+					result.push([encode(key, options), keyValueSeparator, encode(value, options)].join(''));
+					return result;
 				}
 
-				return [[result, encode(value, options)].join(options.arrayFormatSeparator)];
+				result.push(encode(value, options));
+				return result;
 			};
 		}
 
@@ -122,16 +113,12 @@ function encoderForArrayFormat(options) {
 				}
 
 				if (value === null) {
-					return [
-						...result,
-						encode(key, options),
-					];
+					result.push(encode(key, options));
+					return result;
 				}
 
-				return [
-					...result,
-					[encode(key, options), '=', encode(value, options)].join(''),
-				];
+				result.push([encode(key, options), '=', encode(value, options)].join(''));
+				return result;
 			};
 		}
 	}
@@ -175,7 +162,12 @@ function parserForArrayFormat(options) {
 					return;
 				}
 
-				accumulator[key] = [...accumulator[key], value];
+				if (!Array.isArray(accumulator[key])) {
+					accumulator[key] = [accumulator[key], value];
+					return;
+				}
+
+				accumulator[key].push(value);
 			};
 		}
 
@@ -194,7 +186,12 @@ function parserForArrayFormat(options) {
 					return;
 				}
 
-				accumulator[key] = [...accumulator[key], value];
+				if (!Array.isArray(accumulator[key])) {
+					accumulator[key] = [accumulator[key], value];
+					return;
+				}
+
+				accumulator[key].push(value);
 			};
 		}
 
@@ -226,7 +223,13 @@ function parserForArrayFormat(options) {
 					return;
 				}
 
-				accumulator[key] = [...accumulator[key], ...arrayValue];
+				if (!Array.isArray(accumulator[key])) {
+					accumulator[key] = [accumulator[key]];
+				}
+
+				for (const item of arrayValue) {
+					accumulator[key].push(item);
+				}
 			};
 		}
 
@@ -237,7 +240,12 @@ function parserForArrayFormat(options) {
 					return;
 				}
 
-				accumulator[key] = [...[accumulator[key]].flat(), value];
+				if (Array.isArray(accumulator[key])) {
+					accumulator[key].push(value);
+					return;
+				}
+
+				accumulator[key] = [accumulator[key], value];
 			};
 		}
 	}
@@ -298,6 +306,12 @@ function getHash(url) {
 	return hash;
 }
 
+function getUrlWithoutQuery(url) {
+	// Avoid `split('?')` so query-heavy URLs don't allocate large arrays.
+	const queryStart = url.indexOf('?');
+	return queryStart === -1 ? url : url.slice(0, queryStart);
+}
+
 function parseValue(value, options, type) {
 	if (type === 'string' && typeof value === 'string') {
 		return value;
@@ -381,11 +395,21 @@ export function parse(query, options) {
 		return returnValue;
 	}
 
-	for (const parameter of query.split('&')) {
-		if (parameter === '') {
+	// Avoid `split('&')` so separator-heavy inputs don't allocate large arrays of empty strings.
+	let parameterStart = 0;
+
+	for (let index = 0; index <= query.length; index++) {
+		if (index < query.length && query[index] !== '&') {
+			continue;
+		}
+
+		if (index === parameterStart) {
+			parameterStart = index + 1;
 			continue;
 		}
 
+		const parameter = query.slice(parameterStart, index);
+		parameterStart = index + 1;
 		const parameter_ = options.decode ? parameter.replaceAll('+', ' ') : parameter;
 
 		let [key, value] = splitOnFirst(parameter_, '=');
@@ -403,7 +427,8 @@ export function parse(query, options) {
 	for (const [key, value] of Object.entries(returnValue)) {
 		if (typeof value === 'object' && value !== null && options.types[key] !== 'string') {
 			for (const [key2, value2] of Object.entries(value)) {
-				const type = options.types[key] ? options.types[key].replace('[]', '') : undefined;
+				const typeOption = options.types[key];
+				const type = typeof typeOption === 'function' ? typeOption : (typeOption ? typeOption.replace('[]', '') : undefined);
 				value[key2] = parseValue(value2, options, type);
 			}
 		} else if (typeof value === 'object' && value !== null && options.types[key] === 'string') {
@@ -497,9 +522,9 @@ export function stringify(object, options) {
 				).filter(item => item !== undefined);
 			}
 
-			return processedArray
-				.reduce(formatter(key), [])
-				.join('&');
+			const result = processedArray.reduce(formatter(key), []);
+			const arrayFormatSeparator = ['comma', 'separator', 'bracket-separator'].includes(options.arrayFormat) ? options.arrayFormatSeparator : '&';
+			return result.join(arrayFormatSeparator);
 		}
 
 		return encode(key, options) + '=' + encode(value, options);
@@ -519,7 +544,7 @@ export function parseUrl(url, options) {
 	}
 
 	return {
-		url: url_?.split('?')?.[0] ?? '',
+		url: getUrlWithoutQuery(url_ ?? ''),
 		query: parse(extract(url), options),
 		...(options && options.parseFragmentIdentifier && hash ? {fragmentIdentifier: decode(hash, options)} : {}),
 	};
@@ -533,7 +558,7 @@ export function stringifyUrl(object, options) {
 		...options,
 	};
 
-	const url = removeHash(object.url).split('?')[0] || '';
+	const url = getUrlWithoutQuery(removeHash(object.url)) || '';
 	const queryFromUrl = extract(object.url);
 
 	const query = {
@@ -571,7 +596,10 @@ export function pick(input, filter, options) {
 }
 
 export function exclude(input, filter, options) {
-	const exclusionFilter = Array.isArray(filter) ? key => !filter.includes(key) : (key, value) => !filter(key, value);
+	if (Array.isArray(filter)) {
+		const filterSet = new Set(filter);
+		return pick(input, key => !filterSet.has(key), options);
+	}
 
-	return pick(input, exclusionFilter, options);
+	return pick(input, (key, value) => !filter(key, value), options);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "query-string",
-	"version": "9.3.0",
+	"version": "9.4.0",
 	"description": "Parse and stringify URL query strings",
 	"license": "MIT",
 	"repository": "sindresorhus/query-string",

package/readme.md

@@ -13,6 +13,9 @@ npm install query-string
 
 For browser usage, this package targets the latest version of Chrome, Firefox, and Safari.
 
+> [!TIP]
+> Consider using [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) for simple use cases. It's a native browser API that handles basic query string operations.
+
 ## Usage
 
 ```js
@@ -201,13 +204,11 @@ Parse the value as a boolean type instead of string type if it's a boolean.
 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.
-
+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:
 
@@ -281,17 +282,26 @@ queryString.parse('?age=20&items=1%2C2%2C3', {
 //=> {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.
+- `'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: 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'`.
@@ -314,7 +324,7 @@ import queryString from 'query-string';
 
 queryString.parse('?age=20&id=01234&zipcode=90210', {
 	types: {
-		age: (value) => value * 2,
+		age: value => value * 2,
 	}
 });
 //=> {age: 40, id: '01234', zipcode: '90210'}