query-string 9.2.2 → 9.3.1

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'`. (See Example 5.)
+	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',
 		},
 	});
@@ -325,9 +340,10 @@ export type 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.
-
 @param url - The URL to parse.
+@returns An object with a `url` and `query` property.
+
+If the `parseFragmentIdentifier` option is `true`, the object will also contain a `fragmentIdentifier` property.
 
 @example
 ```
@@ -534,17 +550,80 @@ export type StringifyOptions = {
 	```
 	*/
 	readonly skipEmptyString?: boolean;
+
+	/**
+	A function that transforms key-value pairs before stringification.
+
+	Similar to the `replacer` parameter of `JSON.stringify()`, this function is called for each key-value pair and can be used to transform values before they are stringified.
+
+	The function receives the key and value, and should return the transformed value. Returning `undefined` will omit the key-value pair from the resulting query string.
+
+	This is useful for custom serialization of non-primitive types like `Date`:
+
+	@example
+	```
+	import queryString from 'query-string';
+
+	queryString.stringify({
+		date: new Date('2024-01-15T10:30:00Z'),
+		name: 'John'
+	}, {
+		replacer: (key, value) => {
+			if (value instanceof Date) {
+				return value.toISOString();
+			}
+
+			return value;
+		}
+	});
+	//=> 'date=2024-01-15T10%3A30%3A00.000Z&name=John'
+	```
+
+	@example
+	```
+	import queryString from 'query-string';
+
+	// Omit keys with null values using replacer instead of skipNull
+	queryString.stringify({
+		a: 1,
+		b: null,
+		c: 3
+	}, {
+		replacer: (key, value) => value === null ? undefined : value
+	});
+	//=> 'a=1&c=3'
+	```
+	*/
+	readonly replacer?: (key: string, value: unknown) => unknown;
 };
 
+/**
+Supported value types for query string parameters.
+
+Note: `Symbol`, functions, and objects (except arrays) are not supported and will throw an error when stringified.
+*/
 export type Stringifiable = string | boolean | number | bigint | null | undefined; // eslint-disable-line @typescript-eslint/ban-types
 
+/**
+A record of stringifiable values.
+*/
 export type StringifiableRecord = Record<
 string,
 Stringifiable | readonly Stringifiable[]
 >;
 
 /**
-Stringify an object into a query string and sort the keys.
+Stringify an object into a query string and sorting the keys.
+
+@param object - Object to stringify. Supported value types are: `string`, `number`, `bigint`, `boolean`, `null`, `undefined`, and arrays of these types. Other types like `Symbol`, functions, or objects (except arrays) will throw an error.
+
+@example
+```
+import queryString from 'query-string';
+
+queryString.stringify({foo: 'bar', baz: 42, qux: true});
+//=> 'baz=42&foo=bar&qux=true'
+```
 */
 export function stringify(
 	// TODO: Use the below instead when the following TS issues are fixed:
@@ -559,7 +638,13 @@ export function stringify(
 /**
 Extract a query string from a URL that can be passed into `.parse()`.
 
-Note: This behaviour can be changed with the `skipNull` option.
+@example
+```
+import queryString from 'query-string';
+
+queryString.extract('https://foo.bar?foo=bar');
+//=> 'foo=bar'
+```
 */
 export function extract(url: string): string;
 
@@ -580,6 +665,10 @@ export type UrlObject = {
 /**
 Stringify an object into a URL with a query string and sorting the keys. The inverse of [`.parseUrl()`](https://github.com/sindresorhus/query-string#parseurlstring-options)
 
+The `options` are the same as for `.stringify()`.
+
+@returns A string with the URL and a query string.
+
 Query items in the `query` property overrides queries in the `url` property.
 
 The `fragmentIdentifier` property overrides the fragment identifier in the `url` property.

package/base.js

@@ -202,9 +202,7 @@ function parserForArrayFormat(options) {
 		case 'separator': {
 			return (key, value, accumulator) => {
 				const isArray = typeof value === 'string' && value.includes(options.arrayFormatSeparator);
-				const isEncodedArray = (typeof value === 'string' && !isArray && decode(value, options).includes(options.arrayFormatSeparator));
-				value = isEncodedArray ? decode(value, options) : value;
-				const newValue = isArray || isEncodedArray ? value.split(options.arrayFormatSeparator).map(item => decode(item, options)) : (value === null ? value : decode(value, options));
+				const newValue = isArray ? value.split(options.arrayFormatSeparator).map(item => decode(item, options)) : (value === null ? value : decode(value, options));
 				accumulator[key] = newValue;
 			};
 		}
@@ -405,7 +403,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') {
@@ -465,7 +464,17 @@ export function stringify(object, options) {
 	}
 
 	return keys.map(key => {
-		const value = object[key];
+		let value = object[key];
+
+		// Apply replacer function if provided
+		if (options.replacer) {
+			value = options.replacer(key, value);
+
+			// If replacer returns undefined, skip this key
+			if (value === undefined) {
+				return '';
+			}
+		}
 
 		if (value === undefined) {
 			return '';
@@ -480,7 +489,16 @@ export function stringify(object, options) {
 				return encode(key, options) + '[]';
 			}
 
-			return value
+			// Apply replacer to array elements if provided
+			// Note: We don't re-apply replacer to the array itself, only to elements
+			let processedArray = value;
+			if (options.replacer) {
+				processedArray = value.map((item, index) =>
+					options.replacer(`${key}[${index}]`, item),
+				).filter(item => item !== undefined);
+			}
+
+			return processedArray
 				.reduce(formatter(key), [])
 				.join('&');
 		}

package/package.json

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

package/readme.md

@@ -52,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`
@@ -193,13 +201,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:
 
@@ -273,17 +279,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'`.
@@ -306,7 +321,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'}
@@ -318,6 +333,8 @@ Parse the value as a boolean type instead of string type if it's a boolean.
 
 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`
@@ -512,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?)