normalize-url 7.0.3 → 7.2.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.
@@ -11,10 +13,10 @@ export interface Options {
 
 	@example
 	```
-	normalizeUrl('//sindresorhus.com:80/');
+	normalizeUrl('//sindresorhus.com');
 	//=> 'http://sindresorhus.com'
 
-	normalizeUrl('//sindresorhus.com:80/', {normalizeProtocol: false});
+	normalizeUrl('//sindresorhus.com', {normalizeProtocol: false});
 	//=> '//sindresorhus.com'
 	```
 	*/
@@ -27,10 +29,10 @@ export interface Options {
 
 	@example
 	```
-	normalizeUrl('https://sindresorhus.com:80/');
+	normalizeUrl('https://sindresorhus.com');
 	//=> 'https://sindresorhus.com'
 
-	normalizeUrl('https://sindresorhus.com:80/', {forceHttp: true});
+	normalizeUrl('https://sindresorhus.com', {forceHttp: true});
 	//=> 'http://sindresorhus.com'
 	```
 	*/
@@ -45,10 +47,10 @@ export interface Options {
 
 	@example
 	```
-	normalizeUrl('https://sindresorhus.com:80/');
-	//=> 'https://sindresorhus.com'
+	normalizeUrl('http://sindresorhus.com');
+	//=> 'http://sindresorhus.com'
 
-	normalizeUrl('http://sindresorhus.com:80/', {forceHttps: true});
+	normalizeUrl('http://sindresorhus.com', {forceHttps: true});
 	//=> 'https://sindresorhus.com'
 	```
 	*/
@@ -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
 
@@ -228,6 +249,23 @@ export interface Options {
 	*/
 	readonly removeDirectoryIndex?: boolean | ReadonlyArray<RegExp | string>;
 
+	/**
+	Removes an explicit port number from the URL.
+
+	Port 443 is always removed from HTTPS URLs and 80 is always removed from HTTP URLs regardless of this option.
+
+	@default false
+
+	@example
+	```
+	normalizeUrl('sindresorhus.com:123', {
+		removeExplicitPort: true
+	});
+	//=> 'http://sindresorhus.com'
+	```
+	*/
+	readonly removeExplicitPort?: boolean;
+
 	/**
 	Sorts the query parameters alphabetically by key.
 

package/index.js

@@ -69,6 +69,7 @@ export default function normalizeUrl(urlString, options) {
 		removeTrailingSlash: true,
 		removeSingleSlash: true,
 		removeDirectoryIndex: false,
+		removeExplicitPort: false,
 		sortQueryParameters: true,
 		...options,
 	};
@@ -200,10 +201,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();
@@ -218,6 +229,11 @@ export default function normalizeUrl(urlString, options) {
 		urlObject.pathname = urlObject.pathname.replace(/\/$/, '');
 	}
 
+	// Remove an explicit port number, excluding a default port number, if applicable
+	if (options.removeExplicitPort && urlObject.port) {
+		urlObject.port = '';
+	}
+
 	const oldUrlString = urlString;
 
 	// Take advantage of many of the Node `url` normalizations

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "normalize-url",
-	"version": "7.0.3",
+	"version": "7.2.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
 
@@ -53,10 +54,10 @@ Default: `true`
 Prepend `defaultProtocol` to the URL if it's protocol-relative.
 
 ```js
-normalizeUrl('//sindresorhus.com:80/');
+normalizeUrl('//sindresorhus.com');
 //=> 'http://sindresorhus.com'
 
-normalizeUrl('//sindresorhus.com:80/', {normalizeProtocol: false});
+normalizeUrl('//sindresorhus.com', {normalizeProtocol: false});
 //=> '//sindresorhus.com'
 ```
 
@@ -68,10 +69,10 @@ Default: `false`
 Normalize `https:` to `http:`.
 
 ```js
-normalizeUrl('https://sindresorhus.com:80/');
+normalizeUrl('https://sindresorhus.com');
 //=> 'https://sindresorhus.com'
 
-normalizeUrl('https://sindresorhus.com:80/', {forceHttp: true});
+normalizeUrl('https://sindresorhus.com', {forceHttp: true});
 //=> 'http://sindresorhus.com'
 ```
 
@@ -83,10 +84,10 @@ Default: `false`
 Normalize `http:` to `https:`.
 
 ```js
-normalizeUrl('https://sindresorhus.com:80/');
-//=> 'https://sindresorhus.com'
+normalizeUrl('http://sindresorhus.com');
+//=> 'http://sindresorhus.com'
 
-normalizeUrl('http://sindresorhus.com:80/', {forceHttps: true});
+normalizeUrl('http://sindresorhus.com', {forceHttps: true});
 //=> 'https://sindresorhus.com'
 ```
 
@@ -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/');
@@ -256,6 +275,22 @@ normalizeUrl('www.sindresorhus.com/foo/default.php', {
 //=> 'http://sindresorhus.com/foo'
 ```
 
+##### removeExplicitPort
+
+Type: `boolean`\
+Default: `false`
+
+Removes an explicit port number from the URL.
+
+Port 443 is always removed from HTTPS URLs and 80 is always removed from HTTP URLs regardless of this option.
+
+```js
+normalizeUrl('sindresorhus.com:123', {
+	removeExplicitPort: true
+});
+//=> 'http://sindresorhus.com'
+```
+
 ##### sortQueryParameters
 
 Type: `boolean`\