url-relation

Determine the relation between two URLs.

Installation

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

npm install url-relation

Usage

• Inputs must be URL instances.
• The result will be a number that correponds to a relation constant.

const urlRelation = require('url-relation');

const url1 = new URL('http://domain.com/');
const url2 = new URL('http://domain.com/#hash');

const relation = urlRelation(url1, url2, options);
//-> 14

if (relation >= urlRelation.HOST) {
  console.log('same server!');
}

Options

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

defaultPorts

Type: Object
Default value: {}
A map of protocol default ports for ignoreDefaultPort. 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 ignoreDirectoryIndex.

ignoreDefaultPort

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 ignored during comparison.

ignoreDirectoryIndex

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 ignored during comparison.

ignoreEmptyDirectoryNames

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 (such as the "//" in "/path//to/") will be ignored during comparison.

ignoreEmptyQueries

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 not distinguish one URL from another. This option will be silently skipped if the input URLs do not support URLSearchParams.

ignoreQueryNames

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 not distinguish one URL from another. This option will be silently skipped if the input URLs do not support URLSearchParams.

ignoreQueryOrder

Type: Boolean or Function
Default value: Function
When set to true or a function that returns true, the order of unique query parameters will not distinguish one URL from another. This option will be silently skipped if the input URLs do not support URLSearchParams.

ignoreWWW

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

queryNames

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

Function as an Option

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

const options = {
  ignoreDirectoryIndex: function(url1, url2) {
    // Only URLs with these protocols will have their directory indexes ignored
    return url1.protocol === 'http:' && url1.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 url1 = new URL('http://domain.com/');
const url2 = new URL('http://domain.com/#hash');

const trustedHosts = ['domain.com'];

const isTrusted = trustedHosts
  .reduce(function(results, trustedHost) {
    results[0] = results[0] || url1.hostname.endsWith(trustedHost);
    results[1] = results[1] || url2.hostname.endsWith(trustedHost);
    return results;
  }, [false,false])
  .every(result => result);

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

urlRelation(url1, url2, options);

Customizing Profiles

const custom = Object.assign({}, urlRelation.CAREFUL_PROFILE, { ignoreTrailingSlash:true });

Or:

const extend = require('extend');

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

Relation Constants

Returned values can be compared with: NONE, PROTOCOL, TLD, DOMAIN, SUBDOMAIN, HOSTNAME, PORT, HOST, USERNAME, PASSWORD, AUTH, DIRECTORY, FILENAME, PATHNAME, SEARCH, PATH, HASH, ALL.

               AUTH                 HOST                         PATH
              __|__                ___|___                 _______|______
             /     \              /       \               /              \
        USERNAME PASSWORD     HOSTNAME    PORT        PATHNAME        SEARCH  HASH
         ___|__   __|___   ______|______   |   __________|_________   ___|___   |
        /      \ /      \ /             \ / \ /                    \ /       \ / \
  foo://username:[email protected]:123/hello/world/there.html?var=value#foo
  \_/                     \_/ \_____/ \_/     \_________/ \________/
   |                       |     |     |           |           |
PROTOCOL               SUBDOMAIN |    TLD      DIRECTORY   FILENAME
                                 |
                              DOMAIN

Note: there are a few breaks in the linearity of these values:

• AUTH is prioritized after HOST because matching authentication on a different domain is pointless.
• TLD is prioritized before DOMAIN because matching a domain on a different top-level domain is pointless.
• SUBDOMAIN is prioritized after DOMAIN.

Browserify/etc

Due to extreme file size in correctly parsing domains, browser builds will not include such functionality by default. As a result, output of this library within a web browser will never exactly equal TLD, DOMAIN nor SUBDOMAIN.