Node.js url module | API Reference | Bun

Returns the Punycode ASCII serialization of the domain. If domain is an invalid domain, the empty string is returned.

It performs the inverse operation to domainToUnicode.

import url from 'node:url';

console.log(url.domainToASCII('español.com'));
// Prints xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'));
// Prints xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'));
// Prints an empty string

Returns the Unicode serialization of the domain. If domain is an invalid domain, the empty string is returned.

It performs the inverse operation to domainToASCII.

import url from 'node:url';

console.log(url.domainToUnicode('xn--espaol-zwa.com'));
// Prints español.com
console.log(url.domainToUnicode('xn--fiq228c.com'));
// Prints 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'));
// Prints an empty string

This function ensures the correct decodings of percent-encoded characters as well as ensuring a cross-platform valid absolute path string.

import { fileURLToPath } from 'node:url';

const __filename = fileURLToPath(import.meta.url);

new URL('file:http:///C:/path/').pathname; // Incorrect: /C:/path/
fileURLToPath('file:http:///C:/path/'); // Correct: C:\path\ (Windows)

new URL('file:http://nas/foo.txt').pathname; // Incorrect: /foo.txt
fileURLToPath('file:http://nas/foo.txt'); // Correct: \\nas\foo.txt (Windows)

new URL('file:http:///你好.txt').pathname; // Incorrect: /%E4%BD%A0%E5%A5%BD.txt
fileURLToPath('file:http:///你好.txt'); // Correct: /你好.txt (POSIX)

new URL('file:http:///hello world').pathname; // Incorrect: /hello%20world
fileURLToPath('file:http:///hello world'); // Correct: /hello world (POSIX)

Security Considerations:

This function decodes percent-encoded characters, including encoded dot-segments (%2e as . and %2e%2e as ..), and then normalizes the resulting path. This means that encoded directory traversal sequences (such as %2e%2e) are decoded and processed as actual path traversal, even though encoded slashes (%2F, %5C) are correctly rejected.

Applications must not rely on fileURLToPath() alone to prevent directory traversal attacks. Always perform explicit path validation and security checks on the returned path value to ensure it remains within expected boundaries before using it for file system operations.

The file URL string or URL object to convert to a path.

The fully-resolved platform-specific Node.js file path.

Like url.fileURLToPath(...) except that instead of returning a string representation of the path, a Buffer is returned. This conversion is helpful when the input URL contains percent-encoded segments that are not valid UTF-8 / Unicode sequences.

Security Considerations:

This function has the same security considerations as url.fileURLToPath(). It decodes percent-encoded characters, including encoded dot-segments (%2e as . and %2e%2e as ..), and normalizes the path. Applications must not rely on this function alone to prevent directory traversal attacks. Always perform explicit path validation on the returned buffer value before using it for file system operations.

The file URL string or URL object to convert to a path.

The fully-resolved platform-specific Node.js file path as a Buffer.

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

import url from '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 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.

import url from '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 URL object (as returned by url.parse() or constructed otherwise).

This function ensures that path is resolved absolutely, and that the URL control characters are correctly encoded when converting into a File URL.

import { pathToFileURL } from 'node:url';

new URL('/foo#1', 'file:'); // Incorrect: file:http:///foo#1
pathToFileURL('/foo#1'); // Correct: file:http:///foo%231 (POSIX)

new URL('/some/path%.c', 'file:'); // Incorrect: file:http:///some/path%.c
pathToFileURL('/some/path%.c'); // Correct: file:http:///some/path%25.c (POSIX)

The path to convert to a File URL.

The file URL object.

This utility function converts a URL object into an ordinary options object as expected by the http.request() and https.request() APIs.

import { urlToHttpOptions } from 'node:url';
const myURL = new URL('https://a:b@測試?abc#foo');

console.log(urlToHttpOptions(myURL));
/*
{
protocol: 'https:',
hostname: 'xn--g6w251d',
hash: '#foo',
search: '?abc',
pathname: '/',
path: '/?abc',
href: 'https://a:b@xn--g6w251d/?abc#foo',
auth: 'a:b'
}

The WHATWG URL object to convert to an options object.

Options object

true if the path should be return as a windows filepath, false for posix, and undefined for the system default.

true if the path should be return as a windows filepath, false for posix, and undefined for the system default.

true if the serialized URL string should include the username and password, false otherwise.

true if the serialized URL string should include the fragment, false otherwise.

true if the serialized URL string should include the search query, false otherwise.

true if Unicode characters appearing in the host component of the URL string should be encoded directly as opposed to being Punycode encoded.

Creates an iterator whose values are the values from this iterator after skipping the provided count.

The number of values to drop.

Determines whether all the members of this iterator satisfy the specified test.

A function that accepts up to two arguments. The every method calls the predicate function for each element in this iterator until the predicate returns false, or until the end of this iterator.

Creates an iterator whose values are those from this iterator for which the provided predicate returns true.

A function that accepts up to two arguments to be used to test values from the underlying iterator.

Creates an iterator whose values are those from this iterator for which the provided predicate returns true.

A function that accepts up to two arguments to be used to test values from the underlying iterator.

Returns the value of the first element in this iterator where predicate is true, and undefined otherwise.

find calls predicate once for each element of this iterator, in order, until it finds one where predicate returns true. If such an element is found, find immediately returns that element value. Otherwise, find returns undefined.

Creates an iterator whose values are the result of applying the callback to the values from this iterator and then flattening the resulting iterators or iterables.

A function that accepts up to two arguments to be used to transform values from the underlying iterator into new iterators or iterables to be flattened into the result.

Performs the specified action for each element in the iterator.

A function that accepts up to two arguments. forEach calls the callbackfn function one time for each element in the iterator.

Creates an iterator whose values are the result of applying the callback to the values from this iterator.

A function that accepts up to two arguments to be used to transform values from the underlying iterator.

Calls the specified callback function for all the elements in this iterator. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.

A function that accepts up to three arguments. The reduce method calls the callbackfn function one time for each element in the iterator.

Calls the specified callback function for all the elements in this iterator. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.

A function that accepts up to three arguments. The reduce method calls the callbackfn function one time for each element in the iterator.

If initialValue is specified, it is used as the initial value to start the accumulation. The first call to the callbackfn function provides this value as an argument instead of a value from the iterator.

Determines whether the specified callback function returns true for any element of this iterator.

A function that accepts up to two arguments. The some method calls the predicate function for each element in this iterator until the predicate returns a value true, or until the end of the iterator.

Creates an iterator whose values are the values from this iterator, stopping once the provided limit is reached.

The maximum number of values to yield.

Creates a new array from the values yielded by this iterator.