The url
module provides utilities for URL resolution and parsing. It can be accessed using:
const url = require('url');
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:[email protected]: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)
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:[email protected]:8080/p/a/t/h?query=string#hash'
The protocol
property identifies the URL's lower-cased protocol scheme.
For example: 'http:'
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
.
The host
property is the full lower-cased host portion of the URL, including the port
if specified.
For example: 'host.com:8080'
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'
The hostname
property is the lower-cased host name portion of the host
component without the port
included.
For example: 'host.com'
The port
property is the numeric port portion of the host
component.
For example: '8080'
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.
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.
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.
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.
The hash
property consists of the "fragment" portion of the URL including the leading ASCII hash (#
) character.
For example: '#hash'
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:
result
is created.urlObject.protocol
is a string, it is appended as-is to result
.urlObject.protocol
is not undefined
and is not a string, an Error
is thrown.urlObject.protocol
that do not end with an ASCII colon (:
) character, the literal string :
will be appended to result
.//
will be appended to result
:urlObject.slashes
property is true;urlObject.protocol
begins with http
, https
, ftp
, gopher
, or file
;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 @
.urlObject.host
property is undefined
then:urlObject.hostname
is a string, it is appended to result
.urlObject.hostname
is not undefined
and is not a string, an Error
is thrown.urlObject.port
property value is truthy, and urlObject.hostname
is not undefined
::
is appended to result
, andurlObject.port
is coerced to a string and appended to result
.urlObject.host
property value is truthy, the value of urlObject.host
is coerced to a string and appended to result
.urlObject.pathname
property is a string that is not an empty string:urlObject.pathname
does not start with an ASCII forward slash (/
), then the literal string '/' is appended to result
.urlObject.pathname
is appended to result
.urlObject.pathname
is not undefined
and is not a string, an Error
is thrown.urlObject.search
property is undefined
and if the urlObject.query
property is an Object
, the literal string ?
is appended to result
followed by the output of calling the querystring
module's stringify()
method passing the value of urlObject.query
.urlObject.search
is a string:urlObject.search
does not start with the ASCII question mark (?
) character, the literal string ?
is appended to result
.urlObject.search
is appended to result
.urlObject.search
is not undefined
and is not a string, an Error
is thrown.urlObject.hash
property is a string:urlObject.hash
does not start with the ASCII hash (#
) character, the literal string #
is appended to result
.urlObject.hash
is appended to result
.urlObject.hash
property is not undefined
and is not a string, an Error
is thrown.result
is returned.urlString
<String> The URL string to parse.parseQueryString
<Boolean> If true
, the query
property will always be set to an object returned by the querystring
module's parse()
method. If false
, the query
property on the returned URL object will be an unparsed, undecoded string. Defaults to false
.slashesDenoteHost
<Boolean> If true
, the first token after the literal string //
and preceding the next /
will be interpreted as the host
. For instance, given //foo/bar
, the result would be {host: 'foo', pathname: '/bar'}
rather than {pathname: '//foo/bar'}
. Defaults to false
.The url.parse()
method takes a URL string, parses it, and returns a URL object.
The url.resolve()
method resolves a target URL relative to a base URL in a manner similar to that of a Web browser resolving an anchor tag HREF.
For example:
url.resolve('/one/two/three', 'four') // '/one/two/four' url.resolve('http://example.com/', '/one') // 'http://example.com/one' url.resolve('http://example.com/one', '/two') // 'http://example.com/two'
URLs are only permitted to contain a certain range of characters. Spaces (' '
) and the following characters will be automatically escaped in the properties of URL objects:
< > " ` \r \n \t { } | \ ^ '
For example, the ASCII space character (' '
) is encoded as %20
. The ASCII forward slash (/
) character is encoded as %3C
.
© Joyent, Inc. and other Node contributors
Licensed under the MIT License.
Node.js is a trademark of Joyent, Inc. and is used with its permission.
We are not endorsed by or affiliated with Joyent.
https://nodejs.org/dist/latest-v6.x/docs/api/url.html