format
The url.format()
method returns a formatted URL string derived from urlObject
.
const url = require('node:url');
url.format({
protocol: 'https',
hostname: 'example.com',
pathname: '/some/path',
query: {
page: 1,
format: 'json',
},
});
// => 'https://example.com/some/path?page=1&format=json'
If urlObject
is not an object or a string, url.format()
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 toresult
.Otherwise, if
urlObject.protocol
is notundefined
and is not a string, anError
is thrown.For all string values of
urlObject.protocol
that do not end with an ASCII colon (:
) character, the literal string:
will be appended toresult
.If either of the following conditions is true, then the literal string
//
will be appended toresult
:urlObject.slashes
property is true;urlObject.protocol
begins withhttp
,https
,ftp
,gopher
, orfile
;If the value of the
urlObject.auth
property is truthy, and eitherurlObject.host
orurlObject.hostname
are notundefined
, the value ofurlObject.auth
will be coerced into a string and appended toresult
followed by the literal string@
.If the
urlObject.host
property isundefined
then:If the
urlObject.hostname
is a string, it is appended toresult
.Otherwise, if
urlObject.hostname
is notundefined
and is not a string, anError
is thrown.If the
urlObject.port
property value is truthy, andurlObject.hostname
is notundefined
: * The literal string:
is appended toresult
, and * The value ofurlObject.port
is coerced to a string and appended toresult
.Otherwise, if the
urlObject.host
property value is truthy, the value ofurlObject.host
is coerced to a string and appended toresult
.If the
urlObject.pathname
property is a string that is not an empty string:If the
urlObject.pathname
does not start with an ASCII forward slash (/
), then the literal string'/'
is appended toresult
.The value of
urlObject.pathname
is appended toresult
.Otherwise, if
urlObject.pathname
is notundefined
and is not a string, anError
is thrown.If the
urlObject.search
property isundefined
and if theurlObject.query
property is anObject
, the literal string?
is appended toresult
followed by the output of calling thequerystring
module'sstringify()
method passing the value ofurlObject.query
.Otherwise, if
urlObject.search
is a string:If the value of
urlObject.search
does not start with the ASCII question mark (?
) character, the literal string?
is appended toresult
.The value of
urlObject.search
is appended toresult
.Otherwise, if
urlObject.search
is notundefined
and is not a string, anError
is thrown.If the
urlObject.hash
property is a string:If the value of
urlObject.hash
does not start with the ASCII hash (#
) character, the literal string#
is appended toresult
.The value of
urlObject.hash
is appended toresult
.Otherwise, if the
urlObject.hash
property is notundefined
and is not a string, anError
is thrown.result
is returned.
Since
v0.1.25
Parameters
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()
.