Table of Contents

• URL
  • URL Strings and URL Objects
    • urlObject.href
    • urlObject.protocol
    • urlObject.slashes
    • urlObject.host
    • urlObject.auth
    • urlObject.hostname
    • urlObject.port
    • urlObject.pathname
    • urlObject.search
    • urlObject.path
    • urlObject.query
    • urlObject.hash
  • url.format(urlObject)
  • url.parse(urlString[, parseQueryString[, slashesDenoteHost]])
  • url.resolve(from, to)
  • Escaped Characters

URL#

Stability: 2 - Stable

The url module provides utilities for URL resolution and parsing. It can be accessed using:

const url = require('url');

URL Strings and URL Objects#

A URL string is a structured string containing multiple meaningful components. When parsed, a URL object is returned containing properties for each of these components.

The following details each of the components of a parsed URL. The example 'http://user:pass@host.com:8080/p/a/t/h?query=string#hash' is used to illustrate each.

┌─────────────────────────────────────────────────────────────────────────────┐
│                                    href                                     │
├──────────┬┬───────────┬─────────────────┬───────────────────────────┬───────┤
│ protocol ││   auth    │      host       │           path            │ hash  │
│          ││           ├──────────┬──────┼──────────┬────────────────┤       │
│          ││           │ hostname │ port │ pathname │     search     │       │
│          ││           │          │      │          ├─┬──────────────┤       │
│          ││           │          │      │          │ │    query     │       │
"  http:   // user:pass @ host.com : 8080   /p/a/t/h  ?  query=string   #hash "
│          ││           │          │      │          │ │              │       │
└──────────┴┴───────────┴──────────┴──────┴──────────┴─┴──────────────┴───────┘
(all spaces in the "" line should be ignored -- they are purely for formatting)

urlObject.href#

The href property is the full URL string that was parsed with both the protocol and host components converted to lower-case.

For example: 'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'

urlObject.protocol#

The protocol property identifies the URL's lower-cased protocol scheme.

For example: 'http:'

urlObject.slashes#

The slashes property is a boolean with a value of true if two ASCII forward-slash characters (/) are required following the colon in the protocol.

urlObject.host#

The host property is the full lower-cased host portion of the URL, including the port if specified.

For example: 'host.com:8080'

urlObject.auth#

The auth property is the username and password portion of the URL, also referred to as "userinfo". This string subset follows the protocol and double slashes (if present) and precedes the host component, delimited by an ASCII "at sign" (@). The format of the string is {username}[:{password}], with the [:{password}] portion being optional.

For example: 'user:pass'

urlObject.hostname#

The hostname property is the lower-cased host name portion of the host component without the port included.

For example: 'host.com'

urlObject.port#

The port property is the numeric port portion of the host component.

For example: '8080'

urlObject.pathname#

The pathname property consists of the entire path section of the URL. This is everything following the host (including the port) and before the start of the query or hash components, delimited by either the ASCII question mark (?) or hash (#) characters.

For example '/p/a/t/h'

No decoding of the path string is performed.

urlObject.search#

The search property consists of the entire "query string" portion of the URL, including the leading ASCII question mark (?) character.

For example: '?query=string'

No decoding of the query string is performed.

urlObject.path#

The path property is a concatenation of the pathname and search components.

For example: '/p/a/t/h?query=string'

No decoding of the path is performed.

urlObject.query#

The query property is either the query string without the leading ASCII question mark (?), or an object returned by the querystring module's parse() method. Whether the query property is a string or object is determined by the parseQueryString argument passed to url.parse().

For example: 'query=string' or {'query': 'string'}

If returned as a string, no decoding of the query string is performed. If returned as an object, both keys and values are decoded.

urlObject.hash#

The hash property consists of the "fragment" portion of the URL including the leading ASCII hash (#) character.

For example: '#hash'

url.format(urlObject)#

• urlObject <Object> | <String> A URL object (as returned by url.parse() or constructed otherwise). If a string, it is converted to an object by passing it to url.parse().

The url.format() method returns a formatted URL string derived from urlObject.

If urlObject is not an object or a string, url.parse() will throw a TypeError.

The formatting process operates as follows:

• A new empty string result is created.
• If urlObject.protocol is a string, it is appended as-is to result.
• Otherwise, if urlObject.protocol is not undefined and is not a string, an Error is thrown.
• For all string values of urlObject.protocol that do not end with an ASCII colon (:) character, the literal string : will be appended to result.
• If either of the following conditions is true, then the literal string // will be appended to result:
  • urlObject.slashes property is true;
  • urlObject.protocol begins with http, https, ftp, gopher, or file;
• If the value of the urlObject.auth property is truthy, and either urlObject.host or urlObject.hostname are not undefined, the value of urlObject.auth will be coerced into a string and appended to result followed by the literal string