normalize-url 7.0.1 → 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
 
@@ -226,7 +247,7 @@ export interface Options {
 	//=> 'http://sindresorhus.com/foo'
 	```
 	*/
-	readonly removeDirectoryIndex?: ReadonlyArray<RegExp | string>;
+	readonly removeDirectoryIndex?: boolean | ReadonlyArray<RegExp | string>;
 
 	/**
 	Sorts the query parameters alphabetically by key.

package/index.js

@@ -192,6 +192,7 @@ export default function normalizeUrl(urlString, options) {
 
 	// Remove query unwanted parameters
 	if (Array.isArray(options.removeQueryParameters)) {
+		// 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.removeQueryParameters)) {
 				urlObject.searchParams.delete(key);
@@ -199,13 +200,28 @@ 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();
+
+		// Calling `.sort()` encodes the search parameters, so we need to decode them again.
+		try {
+			urlObject.search = decodeURIComponent(urlObject.search);
+		} catch {}
 	}
 
 	if (options.removeTrailingSlash) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "normalize-url",
-	"version": "7.0.1",
+	"version": "7.1.0",
 	"description": "Normalize a URL",
 	"license": "MIT",
 	"repository": "sindresorhus/normalize-url",
@@ -38,11 +38,10 @@
 		"canonical"
 	],
 	"devDependencies": {
-		"ava": "^3.15.0",
-		"c8": "^7.7.3",
-		"tsd": "^0.17.0",
-		"typescript": "^4.3.5",
-		"xo": "^0.41.0"
+		"ava": "^4.0.1",
+		"c8": "^7.11.0",
+		"tsd": "^0.19.1",
+		"xo": "^0.47.0"
 	},
 	"c8": {
 		"reporter": [

package/readme.md

@@ -4,13 +4,15 @@
 
 Useful when you need to display, store, deduplicate, sort, compare, etc, URLs.
 
+**Note:** This package does **not** do URL sanitization. [Garbage in, garbage out.](https://en.wikipedia.org/wiki/Garbage_in,_garbage_out) If you use this in a server context and accept URLs as user input, it's up to you to protect against invalid URLs, [path traversal attacks](https://owasp.org/www-community/attacks/Path_Traversal), etc.
+
 ## Install
 
-```
-$ npm install normalize-url
+```sh
+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
 
@@ -41,7 +43,8 @@ Type: `object`
 ##### defaultProtocol
 
 Type: `string`\
-Default: `http:`
+Default: `http:`\
+Values: `'https:' | 'http:'`
 
 ##### normalizeProtocol
 
@@ -125,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');
@@ -205,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`\
@@ -230,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/');
@@ -240,7 +261,6 @@ normalizeUrl('https://sindresorhus.com/', {removeSingleSlash: false});
 //=> 'https://sindresorhus.com/'
 ```
 
-
 ##### removeDirectoryIndex
 
 Type: `boolean | Array<RegExp | string>`\