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 = ; const url1 = 'http://domain.com/';const url2 = 'http://domain.com/#hash'; const relation = ;//-> 14 if relation >= urlRelationHOST console;
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 URL
s 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 URL
s 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 URL
s 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 = { // Only URLs with these protocols will have their directory indexes ignored return url1protocol === 'http:' && url1protocol === '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 = 'http://domain.com/';const url2 = 'http://domain.com/#hash'; const trustedHosts = 'domain.com'; const isTrusted = trustedHosts ; const options = urlRelation`_PROFILE`; ;
Customizing Profiles
const custom = Object;
Or:
const extend = ; const custom = ;
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:password@www.example.com: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 afterHOST
because matching authentication on a different domain is pointless.TLD
is prioritized beforeDOMAIN
because matching a domain on a different top-level domain is pointless.SUBDOMAIN
is prioritized afterDOMAIN
.
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
.