normalize-url 7.0.3 → 7.1.0

package/index.d.ts

@@ -1,8 +1,10 @@
 export interface Options {
 	/**
 	@default 'http:'
+
+	Values: `'https:' | 'http:'`
 	*/
-	readonly defaultProtocol?: string;
+	readonly defaultProtocol?: string; // TODO: Make this `'https:' | 'http:'` in the next major version.
 
 	/**
 	Prepends `defaultProtocol` to the URL if it's protocol-relative.
@@ -87,7 +89,9 @@ export interface Options {
 	readonly stripHash?: boolean;
 
 	/**
-	Removes HTTP(S) protocol from an URL `http://sindresorhus.com` → `sindresorhus.com`.
+	Remove the protocol from the URL: `http://sindresorhus.com` → `sindresorhus.com`.
+
+	It will only remove `https://` and `http://` protocols.
 
 	@default false
 
@@ -175,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.
 
@@ -197,7 +218,7 @@ export interface Options {
 	readonly removeTrailingSlash?: boolean;
 
 	/**
-	Remove a sole `/` pathname in the output. This option is independant of `removeTrailingSlash`.
+	Remove a sole `/` pathname in the output. This option is independent of `removeTrailingSlash`.
 
 	@default true
 

package/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();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "normalize-url",
-	"version": "7.0.3",
+	"version": "7.1.0",
 	"description": "Normalize a URL",
 	"license": "MIT",
 	"repository": "sindresorhus/normalize-url",
@@ -16,7 +16,7 @@
 		"node": ">=12.20"
 	},
 	"scripts": {
-		"test": "ava && tsd"
+		"test": "xo && c8 ava && tsd"
 	},
 	"files": [
 		"index.js",

package/readme.md

@@ -12,7 +12,7 @@ Useful when you need to display, store, deduplicate, sort, compare, etc, URLs.
 npm install normalize-url
 ```
 
-*If you need to use this in the browser, use version 4: `npm i normalize-url@4`*
+*If you need Safari support, use version 4: `npm i normalize-url@4`*
 
 ## Usage
 
@@ -43,7 +43,8 @@ Type: `object`
 ##### defaultProtocol
 
 Type: `string`\
-Default: `http:`
+Default: `http:`\
+Values: `'https:' | 'http:'`
 
 ##### normalizeProtocol
 
@@ -127,7 +128,9 @@ normalizeUrl('sindresorhus.com/about.html#contact', {stripHash: true});
 Type: `boolean`\
 Default: `false`
 
-Remove HTTP(S) protocol from the URL: `http://sindresorhus.com` → `sindresorhus.com`.
+Remove the protocol from the URL: `http://sindresorhus.com` → `sindresorhus.com`.
+
+It will only remove `https://` and `http://` protocols.
 
 ```js
 normalizeUrl('https://sindresorhus.com');
@@ -207,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`\
@@ -232,7 +251,7 @@ normalizeUrl('http://sindresorhus.com/', {removeTrailingSlash: false});
 Type: `boolean`\
 Default: `true`
 
-Remove a sole `/` pathname in the output. This option is independant of `removeTrailingSlash`.
+Remove a sole `/` pathname in the output. This option is independent of `removeTrailingSlash`.
 
 ```js
 normalizeUrl('https://sindresorhus.com/');