minurl

Reduce and normalize the components of a WHATWG URL.

Installation

Node.js >= 4 is required. To install, type this at the command line:

npm install minurl

Usage

Input must be a URL instance.

const minURL = require('minurl');

const url = new URL('http://www.domain.com/index.html?param1=va%20lue&param2=');

minURL(url, options);
//-> http://domain.com?param1=va+lue&param2

Note: "www" subdomains and "index.html" document indexes are not part of any specification. They are merely a common configuration on many HTTP servers. Consider this when deciding on which options to use.

Options

It is simplest to use an option profile, but custom configurations are still possible.

clone

Type: Boolean
Default value: true
When set to true, the input URL will first be cloned before any changes are made. When set to false, the input URL will be mutated.

defaultPorts

Type: Object
Default value: {'ftps:':990, 'git:':9418, 'scp:':22, 'sftp:':22, 'ssh:':22}
A map of protocol default ports for removeDefaultPort. Be sure to include the suffixed ":" in the key. Common protocols already have their ports removed.

directoryIndexes

Type: Array<RegExp|string>
Default value: ['index.html']
A list of file names for removeDirectoryIndex.

plusQueries

Type: Boolean or Function
Default value: true
When set to true or a function that returns true, a URL will use "+" instead of "%20" to encode spaces in query parameter names and values.

queryNames

Type: Array<RegExp|string>
Default value: []
A list of query parameters for removeQueryNames.

removeDefaultPort

Type: Boolean or Function
Default value: true
When set to true or a function that returns true, a URL's port that matches any found in defaultPorts will be removed.

removeDirectoryIndex

Type: Boolean or Function
Default value: Function
When set to true or a function that returns true, a URL's file name that matches any found in directoryIndexes will be removed.

removeEmptyDirectoryNames

Type: Boolean or Function
Default value: false
When set to true or a function that returns true, empty directory names within a URL's path will be removed. For example, the "//" in "/path//to/" will become "/path/to/". Protocol-relative URLs will not be affected.

removeEmptyHash

Type: Boolean or Function
Default value: true
When set to true or a function that returns true, a URL hash value of "#" will be removed.

removeEmptyQueries

Type: Boolean or Function
Default value: Function
When set to true or a function that returns true, a URL's empty query parameters (such as "?=") will be removed.

removeEmptyQueryNames

Type: Boolean or Function
Default value: Function
When set to true or a function that returns true, a URL's query parameters that contain a value with no name (such as "?=value") will be removed.

removeEmptyQueryValues

Type: Boolean or Function
Default value: Function
When set to true or a function that returns true, a URL's query parameters that contain no value (such as "?var=" and "?var") will be removed.

removeHash

Type: Boolean or Function
Default value: false
When set to true or a function that returns true, a URL's hash will be removed.

removeQueryNames

Type: Boolean or Function
Default value: false
When set to true or a function that returns true, a URL's query parameters matching queryNames will be removed.

removeQueryOddities

Type: Boolean or Function
Default value: true
When set to true or a function that returns true, a URL's unnecessary occurrences of "?", "=" and "&" characters will be removed.

removeRootTrailingSlash

Type: Boolean or Function
Default value: true
When set to true or a function that returns true, a URL's root trailing slash (such as http://domain.com/?var) will be removed.

removeTrailingSlash

Type: Boolean or Function
Default value: false
When set to true or a function that returns true, any trailing slash in a URL (such as http://domain.com/dir/) will be removed.

removeWWW

Type: Boolean or Function
Default value: Function
When set to true or a function that returns true, a URL's "www" subdomain will be removed.

sortQueries

Type: Boolean or Function
Default value: Function
When set to true or a function that returns true, a URL's query parameters will be sorted alphanumerically.

stringify

Type: Boolean
Default value: true
When set to true, a string will be returned. When set to false, a URL will be returned. Beware that the removeRootTrailingSlash and removeTrailingSlash options can only be applied when this option is set to true.

Option as a Function

When an option is defined as a Function, it must return true to be included in the custom filter:

const options = {
  removeDirectoryIndex: function(url) {
    // Only URLs with these protocols will have their directory indexes removed
    return url.protocol === 'http:' && url.protocol === 'https:';
  }
};

Option Profiles

CAREFUL_PROFILE is useful for a URL to an unknown or third-party server that could be incorrectly configured according to specifications and common best practices.

COMMON_PROFILE, the default profile, is useful for a URL to a known server that you trust and expect to be correctly configured according to specifications and common best practices.

An example of checking for a trusted hostname:

const url = new URL('http://www.domain.com/index.html?param1=va%20lue&param2=');

const trustedHosts = ['domain.com'];

const isTrusted = trustedHosts.reduce(function(result, trustedHost) {
  return result || url.hostname.endsWith(trustedHost);
}, false);

const options = minURL[`${isTrusted ? 'COMMON' : 'CAREFUL'}_PROFILE`];

minURL(url, options);

Customizing Profiles

const custom = Object.assign({}, minURL.CAREFUL_PROFILE, { removeTrailingSlash:true });

Or:

const extend = require('extend');

const custom = extend(true, {}, minURL.COMMON_PROFILE, { directoryIndexes:['index.php'] });