Support undefined values for searchParams object

Fixes #293

Author: sindresorhus

readme.md

@@ -161,13 +161,15 @@ Shortcut for sending JSON. Use this instead of the `body` option. Accepts any pl
 
 ##### searchParams
 
-Type: `string | object<string, string | number | boolean> | Array<Array<string | number | boolean>> | URLSearchParams`\
+Type: `string | object<string, string | number | boolean | undefined> | Array<Array<string | number | boolean>> | URLSearchParams`\
 Default: `''`
 
 Search parameters to include in the request URL. Setting this will override all existing search parameters in the input URL.
 
 Accepts any value supported by [`URLSearchParams()`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/URLSearchParams).
 
+When passing an object, `undefined` values are automatically filtered out, while `null` values are preserved and converted to the string `'null'`.
+
 ##### prefixUrl
 
 Type: `string | URL`

source/core/Ky.ts

@@ -130,6 +130,18 @@ export class Ky {
 		return result;
 	}
 
+	// eslint-disable-next-line unicorn/prevent-abbreviations
+	static #normalizeSearchParams(searchParams: any): any {
+		// Filter out undefined values from plain objects
+		if (searchParams && typeof searchParams === 'object' && !Array.isArray(searchParams) && !(searchParams instanceof URLSearchParams)) {
+			return Object.fromEntries(
+				Object.entries(searchParams).filter(([, value]) => value !== undefined),
+			);
+		}
+
+		return searchParams;
+	}
+
 	public request: Request;
 	protected abortController?: AbortController;
 	protected _retryCount = 0;
@@ -199,7 +211,7 @@ export class Ky {
 			// eslint-disable-next-line unicorn/prevent-abbreviations
 			const textSearchParams = typeof this._options.searchParams === 'string'
 				? this._options.searchParams.replace(/^\?/, '')
-				: new URLSearchParams(this._options.searchParams as unknown as SearchParamsInit).toString();
+				: new URLSearchParams(Ky.#normalizeSearchParams(this._options.searchParams) as unknown as SearchParamsInit).toString();
 			// eslint-disable-next-line unicorn/prevent-abbreviations
 			const searchParams = '?' + textSearchParams;
 			const url = this.request.url.replace(/(?:\?.*?)?(?=#|$)/, searchParams);

source/types/options.ts

@@ -6,7 +6,7 @@ import type {RetryOptions} from './retry.js';
 export type SearchParamsInit = string | string[][] | Record<string, string> | URLSearchParams | undefined;
 
 // eslint-disable-next-line unicorn/prevent-abbreviations
-export type SearchParamsOption = SearchParamsInit | Record<string, string | number | boolean> | Array<Array<string | number | boolean>>;
+export type SearchParamsOption = SearchParamsInit | Record<string, string | number | boolean | undefined> | Array<Array<string | number | boolean>>;
 
 export type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'head' | 'delete';
 
@@ -88,6 +88,8 @@ export type KyOptions = {
 	Search parameters to include in the request URL. Setting this will override all existing search parameters in the input URL.
 
 	Accepts any value supported by [`URLSearchParams()`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/URLSearchParams).
+
+	When passing an object, `undefined` values are automatically filtered out, while `null` values are preserved and converted to the string `'null'`.
 	*/
 	searchParams?: SearchParamsOption;
 

test/main.ts

@@ -406,6 +406,35 @@ test('searchParams option', async t => {
 	await server.close();
 });
 
+test('searchParams option with undefined values', async t => {
+	const server = await createHttpTestServer();
+
+	server.get('/', (request, response) => {
+		response.end(request.url.slice(1));
+	});
+
+	const objectWithUndefined = {
+		cats: 'meow',
+		dogs: undefined,
+		opossums: 'false',
+		birds: undefined,
+	};
+
+	const objectWithNull = {
+		cats: 'meow',
+		dogs: null as any,
+		opossums: 'false',
+	};
+
+	// Undefined values should be filtered out
+	t.is(await ky(server.url, {searchParams: objectWithUndefined}).text(), '?cats=meow&opossums=false');
+
+	// Null values should be preserved as string "null"
+	t.is(await ky(server.url, {searchParams: objectWithNull}).text(), '?cats=meow&dogs=null&opossums=false');
+
+	await server.close();
+});
+
 test('throwHttpErrors option', async t => {
 	const server = await createHttpTestServer();
 	server.get('/', (_request, response) => {