{ "source": "doc/api/url.md", "modules": [ { "textRaw": "URL", "name": "url", "stability": 2, "stabilityText": "Stable", "desc": "

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

\n
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.

\n

The 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
┌─────────────────────────────────────────────────────────────────────────────┐\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.

\n

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

\n" }, { "textRaw": "urlObject.protocol", "name": "protocol", "desc": "

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

\n

For example: 'http:'

\n" }, { "textRaw": "urlObject.slashes", "name": "slashes", "desc": "

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.

\n" }, { "textRaw": "urlObject.host", "name": "host", "desc": "

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

\n

For example: 'host.com:8080'

\n" }, { "textRaw": "urlObject.auth", "name": "auth", "desc": "

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.

\n

For example: 'user:pass'

\n" }, { "textRaw": "urlObject.hostname", "name": "hostname", "desc": "

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

\n

For example: 'host.com'

\n" }, { "textRaw": "urlObject.port", "name": "port", "desc": "

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

\n

For example: '8080'

\n" }, { "textRaw": "urlObject.pathname", "name": "pathname", "desc": "

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.

\n

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

\n

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.

\n

For example: '?query=string'

\n

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.

\n

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

\n

No decoding of the path is performed.

\n" }, { "textRaw": "urlObject.query", "name": "query", "desc": "

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().

\n

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

\n

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.

\n

For example: '#hash'

\n" } ], "type": "module", "displayName": "URL Strings and URL Objects" }, { "textRaw": "Escaped Characters", "name": "escaped_characters", "desc": "

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:

\n
< > " ` \\r \\n \\t { } | \\ ^ '\n
\n

For example, the ASCII space character (' ') is encoded as %20. The ASCII\nforward slash (/) character is encoded as %3C.

\n", "type": "module", "displayName": "Escaped Characters" } ], "methods": [ { "textRaw": "url.format(urlObject)", "type": "method", "name": "format", "meta": { "added": [ "v0.1.25" ] }, "signatures": [ { "params": [ { "textRaw": "`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()`. ", "name": "urlObject", "type": "Object | String", "desc": "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()`." } ] }, { "params": [ { "name": "urlObject" } ] } ], "desc": "

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

\n

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

\n

The formatting process operates as follows:

\n\n" }, { "textRaw": "url.parse(urlString[, parseQueryString[, slashesDenoteHost]])", "type": "method", "name": "parse", "meta": { "added": [ "v0.1.25" ] }, "signatures": [ { "params": [ { "textRaw": "`urlString` {String} The URL string to parse. ", "name": "urlString", "type": "String", "desc": "The URL string to parse." }, { "textRaw": "`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`. ", "name": "parseQueryString", "type": "Boolean", "desc": "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`.", "optional": true }, { "textRaw": "`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`. ", "name": "slashesDenoteHost", "type": "Boolean", "desc": "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`.", "optional": true } ] }, { "params": [ { "name": "urlString" }, { "name": "parseQueryString", "optional": true }, { "name": "slashesDenoteHost", "optional": true } ] } ], "desc": "

The url.parse() method takes a URL string, parses it, and returns a URL\nobject.

\n" }, { "textRaw": "url.resolve(from, to)", "type": "method", "name": "resolve", "meta": { "added": [ "v0.1.25" ] }, "signatures": [ { "params": [ { "textRaw": "`from` {String} The Base URL being resolved against. ", "name": "from", "type": "String", "desc": "The Base URL being resolved against." }, { "textRaw": "`to` {String} The HREF URL being resolved. ", "name": "to", "type": "String", "desc": "The HREF URL being resolved." } ] }, { "params": [ { "name": "from" }, { "name": "to" } ] } ], "desc": "

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.

\n

For example:

\n
url.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" } ] }