Add keepQueryParameters option (#173)

Co-authored-by: Sindre Sorhus <sindresorhus@gmail.com>
sindresorhus · Sep 1, 2022 · 6e24307 · 6e24307
1 parent 4ce3a64
commit 6e24307
Show file tree

Hide file tree

Showing 5 changed files with 58 additions and 1 deletion.
diff --git a/index.d.ts b/index.d.ts
@@ -179,6 +179,23 @@ export interface Options {
 	*/
 	readonly removeQueryParameters?: ReadonlyArray<RegExp | string> | boolean;
 
+	/**
+	Keeps only query parameters that matches any of the provided strings or regexes.
+
+	__Note__: It overrides the `removeQueryParameters` option.
+
+	@default undefined
+
+	@example
+	```
+	normalizeUrl('https://sindresorhus.com?foo=bar&ref=unicorn', {
+		keepQueryParameters: ['ref']
+	});
+	//=> 'https://sindresorhus.com/?ref=unicorn'
+	```
+	*/
+	readonly keepQueryParameters?: ReadonlyArray<RegExp | string>;
+
 	/**
 	Removes trailing slash.
 

diff --git a/index.js b/index.js
@@ -200,10 +200,20 @@ export default function normalizeUrl(urlString, options) {
 		}
 	}
 
-	if (options.removeQueryParameters === true) {
+	if (!Array.isArray(options.keepQueryParameters) && options.removeQueryParameters === true) {
 		urlObject.search = '';
 	}
 
+	// Keep wanted query parameters
+	if (Array.isArray(options.keepQueryParameters) && options.keepQueryParameters.length > 0) {
+		// eslint-disable-next-line unicorn/no-useless-spread -- We are intentionally spreading to get a copy.
+		for (const key of [...urlObject.searchParams.keys()]) {
+			if (!testParameter(key, options.keepQueryParameters)) {
+				urlObject.searchParams.delete(key);
+			}
+		}
+	}
+
 	// Sort query parameters
 	if (options.sortQueryParameters) {
 		urlObject.searchParams.sort();

diff --git a/index.test-d.ts b/index.test-d.ts
@@ -21,6 +21,9 @@ normalizeUrl('www.sindresorhus.com?foo=bar', {
 normalizeUrl('www.sindresorhus.com?foo=bar&utm_medium=test&ref=test_ref', {
 	removeQueryParameters: false,
 });
+normalizeUrl('www.sindresorhus.com?foo=bar&ref=test_ref', {
+	keepQueryParameters: ['ref', /test/],
+});
 normalizeUrl('http://sindresorhus.com/', {removeTrailingSlash: false});
 normalizeUrl('http://sindresorhus.com/', {removeSingleSlash: false});
 normalizeUrl('www.sindresorhus.com/foo/default.php', {

diff --git a/readme.md b/readme.md
@@ -210,6 +210,22 @@ normalizeUrl('www.sindresorhus.com?foo=bar&utm_medium=test&ref=test_ref', {
 //=> 'http://www.sindresorhus.com/?foo=bar&ref=test_ref&utm_medium=test'
 ```
 
+##### keepQueryParameters
+
+Type: `Array<RegExp | string>`\
+Default: `undefined`
+
+Keeps only query parameters that matches any of the provided strings or regexes.
+
+**Note:** It overrides the `removeQueryParameters` option.
+
+```js
+normalizeUrl('https://sindresorhus.com?foo=bar&ref=unicorn', {
+	keepQueryParameters: ['ref']
+});
+//=> 'https://sindresorhus.com/?ref=unicorn'
+```
+
 ##### removeTrailingSlash
 
 Type: `boolean`\

diff --git a/test.js b/test.js
@@ -141,6 +141,17 @@ test('removeQueryParameters boolean `false` option', t => {
 	t.is(normalizeUrl('www.sindresorhus.com?foo=bar&utm_medium=test&ref=test_ref', options), 'http://www.sindresorhus.com/?foo=bar&ref=test_ref&utm_medium=test');
 });
 
+test('keepQueryParameters option', t => {
+	const options = {
+		stripWWW: false,
+		removeQueryParameters: false,
+		keepQueryParameters: [/^utm_\w+/i, 'ref'],
+	};
+	t.is(normalizeUrl('https://sindresorhus.com', options), 'https://sindresorhus.com');
+	t.is(normalizeUrl('www.sindresorhus.com?foo=bar', options), 'http://www.sindresorhus.com');
+	t.is(normalizeUrl('www.sindresorhus.com?foo=bar&utm_medium=test&ref=test_ref', options), 'http://www.sindresorhus.com/?ref=test_ref&utm_medium=test');
+});
+
 test('forceHttp option', t => {
 	const options = {forceHttp: true};
 	t.is(normalizeUrl('https://sindresorhus.com'), 'https://sindresorhus.com');