Add replacer option to stringify()

Closes #203

Author: sindresorhus

base.d.ts

@@ -535,6 +535,51 @@ 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;
 };
 
 /**

base.js

@@ -463,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 '';
@@ -478,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('&');
 		}

readme.md

@@ -522,6 +522,50 @@ 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()`.

test/stringify.js

@@ -431,3 +431,167 @@ test('array stringify representation with (:list) colon-list-separator with null
 		arrayFormat: 'colon-list-separator',
 	}), 'bar:list=one&bar:list=&foo');
 });
+
+test('replacer option transforms Date objects to ISO strings', t => {
+	const date = new Date('2024-01-15T10:30:00.000Z');
+	t.is(queryString.stringify({
+		name: 'John',
+		created: date,
+	}, {
+		replacer(key, value) {
+			if (value instanceof Date) {
+				return value.toISOString();
+			}
+
+			return value;
+		},
+	}), 'created=2024-01-15T10%3A30%3A00.000Z&name=John');
+});
+
+test('replacer option can omit null values', t => {
+	t.is(queryString.stringify({
+		a: 1,
+		b: null,
+		c: 3,
+	}, {
+		replacer: (key, value) => value === null ? undefined : value,
+	}), 'a=1&c=3');
+});
+
+test('replacer option can transform specific keys', t => {
+	t.is(queryString.stringify({
+		price: 10,
+		quantity: 5,
+	}, {
+		replacer(key, value) {
+			if (key === 'price' && typeof value === 'number') {
+				return `$${value}`;
+			}
+
+			return value;
+		},
+	}), 'price=%2410&quantity=5');
+});
+
+test('replacer option can filter array elements', t => {
+	t.is(queryString.stringify({
+		tags: ['one', 'two', 'three'],
+	}, {
+		replacer(key, value) {
+			if (key.startsWith('tags[') && value === 'two') {
+				return undefined; // Skip 'two'
+			}
+
+			return value;
+		},
+	}), 'tags=one&tags=three');
+});
+
+test('replacer option returning undefined for all values results in empty string', t => {
+	t.is(queryString.stringify({
+		a: 1,
+		b: 2,
+	}, {
+		replacer: () => undefined,
+	}), '');
+});
+
+test('replacer option can transform array to string', t => {
+	t.is(queryString.stringify({
+		tags: ['one', 'two', 'three'],
+	}, {
+		replacer(key, value) {
+			if (Array.isArray(value)) {
+				return value.join('|');
+			}
+
+			return value;
+		},
+	}), 'tags=one%7Ctwo%7Cthree');
+});
+
+test('replacer option works with bracket array format', t => {
+	t.is(queryString.stringify({
+		items: [1, 2, 3],
+	}, {
+		arrayFormat: 'bracket',
+		replacer(key, value) {
+			if (typeof value === 'number') {
+				return value * 10;
+			}
+
+			return value;
+		},
+	}), 'items[]=10&items[]=20&items[]=30');
+});
+
+test('replacer option handles edge cases correctly', t => {
+	t.is(queryString.stringify({
+		undefinedValue: undefined,
+		nullValue: null,
+		empty: '',
+		zero: 0,
+		false: false,
+	}, {
+		replacer: (key, value) => value,
+	}), 'empty=&false=false&nullValue&zero=0');
+});
+
+test('replacer option can handle Symbol without crashing', t => {
+	const symbol = Symbol('test');
+	t.is(queryString.stringify({
+		a: 1,
+		b: symbol,
+	}, {
+		replacer(key, value) {
+			if (typeof value === 'symbol') {
+				return 'symbol-value';
+			}
+
+			return value;
+		},
+	}), 'a=1&b=symbol-value');
+});
+
+test('replacer option works with comma array format', t => {
+	t.is(queryString.stringify({
+		colors: ['red', 'green', 'blue'],
+	}, {
+		arrayFormat: 'comma',
+		replacer(key, value) {
+			if (key.startsWith('colors[') && value === 'green') {
+				return 'GREEN';
+			}
+
+			return value;
+		},
+	}), 'colors=red,GREEN,blue');
+});
+
+test('replacer option is called with correct keys for index array format', t => {
+	const replacerKeys = [];
+	queryString.stringify({
+		items: ['x', 'y'],
+	}, {
+		arrayFormat: 'index',
+		replacer(key, value) {
+			replacerKeys.push(key);
+			return value;
+		},
+	});
+	t.deepEqual(replacerKeys, ['items', 'items[0]', 'items[1]']);
+});
+
+test('replacer option can transform objects to JSON strings', t => {
+	t.is(queryString.stringify({
+		data: {nested: 'value'},
+	}, {
+		replacer(key, value) {
+			if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+				return JSON.stringify(value);
+			}
+
+			return value;
+		},
+	}), 'data=%7B%22nested%22%3A%22value%22%7D');
+});