query-string 9.2.1 → 9.3.0

package/base.d.ts

@@ -184,7 +184,7 @@ export type ParseOptions = {
 
 	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).
 
-	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 {}
 
@@ -286,7 +286,8 @@ export type ParseOptions = {
 	});
 	//=> {isAdmin: 'true', flagged: true, isOkay: false}
 	```
-	Note: The `'boolean'` type will also convert `'0'` and `'1'` string values to booleans.
+
+	Note: The `'boolean'` type also converts `'0'` and `'1'` to booleans, and treats valueless keys (e.g. `?flag`) as `true`.
 	*/
 	readonly types?: Record<
 	string,
@@ -324,9 +325,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
 ```
@@ -533,17 +535,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:
@@ -558,7 +623,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;
 
@@ -579,6 +650,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;
 			};
 		}
@@ -309,6 +307,10 @@ function parseValue(value, options, type) {
 		return type(value);
 	}
 
+	if (type === 'boolean' && value === null) {
+		return true;
+	}
+
 	if (type === 'boolean' && value !== null && (value.toLowerCase() === 'true' || value.toLowerCase() === 'false')) {
 		return value.toLowerCase() === 'true';
 	}
@@ -461,7 +463,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 '';
@@ -476,7 +488,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.1",
+	"version": "9.3.0",
 	"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`
@@ -217,7 +225,7 @@ queryString.parse('?isAdmin=true&flagged=true&isOkay=0', {
 //=> {isAdmin: 'true', flagged: true, isOkay: false}
 ```
 
-Note: The `'boolean'` type will also convert `'0'` and `'1'` string values to booleans.
+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):
 
@@ -318,6 +326,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 +522,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?)