{ "source": "doc/api/url.md", "modules": [ { "textRaw": "URL", "name": "url", "introduced_in": "v0.10.0", "stability": 2, "stabilityText": "Stable", "desc": "
The url
module provides utilities for URL resolution and parsing. It can be\naccessed using:
const url = require('url');\n
\n",
"modules": [
{
"textRaw": "URL Strings and URL Objects",
"name": "url_strings_and_url_objects",
"desc": "A URL string is a structured string containing multiple meaningful components.\nWhen parsed, a URL object is returned containing properties for each of these\ncomponents.
\nThe following details each of the components of a parsed URL. The example\n'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'
is used to\nillustrate each.
┌─────────────────────────────────────────────────────────────────────────────┐\n│ href │\n├──────────┬┬───────────┬─────────────────┬───────────────────────────┬───────┤\n│ protocol ││ auth │ host │ path │ hash │\n│ ││ ├──────────┬──────┼──────────┬────────────────┤ │\n│ ││ │ hostname │ port │ pathname │ search │ │\n│ ││ │ │ │ ├─┬──────────────┤ │\n│ ││ │ │ │ │ │ query │ │\n" http: // user:pass @ host.com : 8080 /p/a/t/h ? query=string #hash "\n│ ││ │ │ │ │ │ │ │\n└──────────┴┴───────────┴──────────┴──────┴──────────┴─┴──────────────┴───────┘\n(all spaces in the "" line should be ignored -- they are purely for formatting)\n
\n",
"properties": [
{
"textRaw": "urlObject.href",
"name": "href",
"desc": "The href
property is the full URL string that was parsed with both the\nprotocol
and host
components converted to lower-case.
For example: 'http://user:pass@host.com: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\nforward-slash characters (/
) are required following the colon in the\nprotocol
.
The host
property is the full lower-cased host portion of the URL, including\nthe port
if specified.
For example: 'host.com:8080'
The auth
property is the username and password portion of the URL, also\nreferred to as "userinfo". This string subset follows the protocol
and\ndouble slashes (if present) and precedes the host
component, delimited by an\nASCII "at sign" (@
). The format of the string is {username}[:{password}]
,\nwith the [:{password}]
portion being optional.
For example: 'user:pass'
The hostname
property is the lower-cased host name portion of the host
\ncomponent 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\nis everything following the host
(including the port
) and before the start\nof the query
or hash
components, delimited by either the ASCII question\nmark (?
) or hash (#
) characters.
For example '/p/a/t/h'
No decoding of the path string is performed.
\n" }, { "textRaw": "urlObject.search", "name": "search", "desc": "The search
property consists of the entire "query string" portion of the\nURL, including the leading ASCII question mark (?
) character.
For example: '?query=string'
No decoding of the query string is performed.
\n" }, { "textRaw": "urlObject.path", "name": "path", "desc": "The path
property is a concatenation of the pathname
and search
\ncomponents.
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\nquestion mark (?
), or an object returned by the querystring
module's\nparse()
method. Whether the query
property is a string or object is\ndetermined 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\nreturned as an object, both keys and values are decoded.
\n" }, { "textRaw": "urlObject.hash", "name": "hash", "desc": "The hash
property consists of the "fragment" portion of the URL including\nthe leading ASCII hash (#
) character.
For example: '#hash'
URLs are only permitted to contain a certain range of characters. Spaces (' '
)\nand the following characters will be automatically escaped in the\nproperties of URL objects:
< > " ` \\r \\n \\t { } | \\ ^ '\n
\nFor example, the ASCII space character (' '
) is encoded as %20
. The ASCII\nforward slash (/
) character is encoded as %3C
.
The url.format()
method returns a formatted URL string derived from\nurlObject
.
If urlObject
is not an object or a string, url.parse()
will throw a\nTypeError
.
The formatting process operates as follows:
\nresult
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\nError
is thrown.urlObject.protocol
that do not end with an ASCII\ncolon (:
) character, the literal string :
will be appended to result
.//
\nwill be appended to result
:urlObject.slashes
property is true;urlObject.protocol
begins with http
, https
, ftp
, gopher
, or\nfile
;urlObject.auth
property is truthy, and either\nurlObject.host
or urlObject.hostname
are not undefined
, the value of\nurlObject.auth
will be coerced into a string and appended to result
\n 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,\nan Error
is thrown.urlObject.port
property value is truthy, and urlObject.hostname
\nis not undefined
::
is appended to result
, andurlObject.port
is coerced to a string and appended to\nresult
.urlObject.host
property value is truthy, the value of\nurlObject.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\n(/
), 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\nError
is thrown.urlObject.search
property is undefined
and if the urlObject.query
\nproperty is an Object
, the literal string ?
is appended to result
\nfollowed by the output of calling the querystring
module's stringify()
\nmethod passing the value of urlObject.query
.urlObject.search
is a string:urlObject.search
does not start with the ASCII question\nmark (?
) 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\nError
is thrown.urlObject.hash
property is a string:urlObject.hash
does not start with the ASCII hash (#
)\ncharacter, the literal string #
is appended to result
.urlObject.hash
is appended to result
.urlObject.hash
property is not undefined
and is not a\nstring, an Error
is thrown.result
is returned.The url.parse()
method takes a URL string, parses it, and returns a URL\nobject.
The url.resolve()
method resolves a target URL relative to a base URL in a\nmanner similar to that of a Web browser resolving an anchor tag HREF.
For example:
\nurl.resolve('/one/two/three', 'four'); // '/one/two/four'\nurl.resolve('http://example.com/', '/one'); // 'http://example.com/one'\nurl.resolve('http://example.com/one', '/two'); // 'http://example.com/two'\n
\n"
}
],
"type": "module",
"displayName": "URL"
}
]
}