Строки URL и объекты URL

Строка URL — это структурированная строка, содержащая многочисленные значимые компоненты. При разборе возвращается объект URL, содержащий свойства для каждого из этих компонентов.

Модуль node:url предоставляет два API для работы с URL: устаревший API, специфичный для Node.js, и новый API, реализующий тот же стандарт WHATWG URL, используемый веб-браузерами.

Сравнение между API WHATWG и устаревшим API приведено ниже. Выше URL 'https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash', показаны свойства объекта, возвращаемого устаревшим url.parse() API. Ниже него — свойства объекта WHATWG URL API.

Свойство origin URL WHATWG включает protocol и host, но не username или password.

┌────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                              href                                              │
├──────────┬──┬─────────────────────┬────────────────────────┬───────────────────────────┬───────┤
│ protocol │  │        auth         │          host          │           path            │ hash  │
│          │  │                     ├─────────────────┬──────┼──────────┬────────────────┤       │
│          │  │                     │    hostname     │ port │ pathname │     search     │       │
│          │  │                     │                 │      │          ├─┬──────────────┤       │
│          │  │                     │                 │      │          │ │    query     │       │
"  https:   //    user   :   pass   @ sub.example.com : 8080   /p/a/t/h  ?  query=string   #hash "
│          │  │          │          │    hostname     │ port │          │                │       │
│          │  │          │          ├─────────────────┴──────┤          │                │       │
│ protocol │  │ username │ password │          host          │          │                │       │
├──────────┴──┼──────────┴──────────┼────────────────────────┤          │                │       │
│   origin    │                     │         origin         │ pathname │     search     │ hash  │
├─────────────┴─────────────────────┴────────────────────────┴──────────┴────────────────┴───────┤
│                                              href                                              │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
(All spaces in the "" line should be ignored. They are purely for formatting.) copy

Разбор строки URL с помощью API WHATWG:

const myURL =
  new URL('https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash'); copy

Разбор строки URL с помощью устаревшего API:

Модули MJS

import url from 'node:url';
const myURL =
  url.parse('https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash');

Модули CJS

const url = require('node:url');
const myURL =
  url.parse('https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash');

Создание URL из компонентов и получение созданной строки

Возможно создать объект WHATWG URL из компонентов, используя либо установщики свойств, либо строку шаблона:

const myURL = new URL('https://example.org');
myURL.pathname = '/a/b/c';
myURL.search = '?d=e';
myURL.hash = '#fgh'; copy

const pathname = '/a/b/c';
const search = '?d=e';
const hash = '#fgh';
const myURL = new URL(`https://example.org${pathname}${search}${hash}`); copy

Для получения созданной строки URL используйте доступ к свойству href:

console.log(myURL.href); copy

API URL WHATWG

Класс: URL

Совместимый с браузерами URL класс, реализованный в соответствии со стандартом WHATWG URL. Примеры парсинга URL можно найти в самом стандарте. Класс URL также доступен в глобальном объекте.

В соответствии с правилами браузеров, все свойства объектов URL реализованы как геттеры и сеттеры в прототипе класса, а не как свойства данных самого объекта. Таким образом, в отличие от предыдущих urlObject, использование ключевого слова delete для любых свойств объектов URL (например, delete myURL.protocol, delete myURL.pathname, и т. д.) не оказывает никакого эффекта, но всё же вернёт true.

new URL(input[, base])

• input <строка> Абсолютный или относительный URL ввода для парсинга. Если input является относительным, то base требуется. Если input абсолютный, то base игнорируется. Если input не является строкой, оно сначала преобразуется в строку.
• base <строка> Базовый URL для разрешения, если input не является абсолютным. Если base не является строкой, оно сначала преобразуется в строку.

Создаёт новый объект URL путём парсинга input относительно base. Если base передано как строка, она будет обработана так же, как если бы new URL(base).

const myURL = new URL('/foo', 'https://example.org/');
// https://example.org/foo copy

Конструктор URL доступен как свойство глобального объекта. Его также можно импортировать из встроенного модуля url:

Модули MJS

import { URL } from 'node:url';
console.log(URL === globalThis.URL); // Prints 'true'.

Модули CJS

console.log(URL === require('node:url').URL); // Prints 'true'.

Будет брошено исключение TypeError , если input или base не являются валидными URL. Обратите внимание, что будет предпринята попытка принудительно преобразовать данные значения в строки. Например:

const myURL = new URL({ toString: () => 'https://example.org/' });
// https://example.org/ copy

Символы Юникода, встречающиеся в имени хоста input , будут автоматически преобразованы в ASCII с использованием алгоритма Punycode.

const myURL = new URL('https://測試');
// https://xn--g6w251d/ copy

В тех случаях, когда заранее неизвестно, является ли input абсолютным URL и предоставлен base, рекомендуется проверить, что origin объекта URL соответствует ожиданиям.

let myURL = new URL('http://Example.com/', 'https://example.org/');
// http://example.com/

myURL = new URL('https://Example.com/', 'https://example.org/');
// https://example.com/

myURL = new URL('foo://Example.com/', 'https://example.org/');
// foo://Example.com/

myURL = new URL('http:Example.com/', 'https://example.org/');
// http://example.com/

myURL = new URL('https:Example.com/', 'https://example.org/');
// https://example.org/Example.com/

myURL = new URL('foo:Example.com/', 'https://example.org/');
// foo:Example.com/ copy

url.hash

• <строка>

Получает и устанавливает фрагмент URL.

const myURL = new URL('https://example.org/foo#bar');
console.log(myURL.hash);
// Prints #bar

myURL.hash = 'baz';
console.log(myURL.href);
// Prints https://example.org/foo#baz copy

Некорректные символы URL, включённые в значение, присвоенное свойству hash, кодируются по схеме percent. Выбор символов для кодирования может немного отличаться от того, что производят методы url.parse() и url.format().

url.host

• <строка>

Получает и устанавливает часть хоста URL.

const myURL = new URL('https://example.org:81/foo');
console.log(myURL.host);
// Prints example.org:81

myURL.host = 'example.com:82';
console.log(myURL.href);
// Prints https://example.com:82/foo copy

Некорректные значения хоста, присвоенные свойству host, игнорируются.

url.hostname

• <строка>

Получает и устанавливает имя хоста URL. Ключевое различие между url.host и url.hostname заключается в том, что url.hostname не включает порт.

const myURL = new URL('https://example.org:81/foo');
console.log(myURL.hostname);
// Prints example.org

// Setting the hostname does not change the port
myURL.hostname = 'example.com';
console.log(myURL.href);
// Prints https://example.com:81/foo

// Use myURL.host to change the hostname and port
myURL.host = 'example.org:82';
console.log(myURL.href);
// Prints https://example.org:82/foo copy

Некорректные значения имени хоста, присвоенные свойству hostname, игнорируются.

url.href

• <строка>

Получает и устанавливает сериализованный URL.

const myURL = new URL('https://example.org/foo');
console.log(myURL.href);
// Prints https://example.org/foo

myURL.href = 'https://example.com/bar';
console.log(myURL.href);
// Prints https://example.com/bar copy

Получение значения свойства href эквивалентно вызову url.toString().

Установка значения этого свойства на новое значение эквивалентно созданию нового объекта URL с помощью new URL(value). Каждое из свойств объекта URL будет изменено.

Если значение, присвоенное свойству href, не является валидным URL, будет брошено исключение TypeError.

url.origin

• <строка>

Получает сериализованное значение источника URL.

const myURL = new URL('https://example.org/foo/bar?baz');
console.log(myURL.origin);
// Prints https://example.org copy

const idnURL = new URL('https://測試');
console.log(idnURL.origin);
// Prints https://xn--g6w251d

console.log(idnURL.hostname);
// Prints xn--g6w251d copy

url.password

• <строка>

Получает и устанавливает часть пароля URL.

const myURL = new URL('https://abc:xyz@example.com');
console.log(myURL.password);
// Prints xyz

myURL.password = '123';
console.log(myURL.href);
// Prints https://abc:123@example.com/ copy

Некорректные символы URL, включённые в значение, присвоенное свойству password, кодируются по схеме percent. Выбор символов для кодирования может немного отличаться от того, что производят методы url.parse() и url.format().

url.pathname

• <строка>

Получает и устанавливает часть пути URL.

const myURL = new URL('https://example.org/abc/xyz?123');
console.log(myURL.pathname);
// Prints /abc/xyz

myURL.pathname = '/abcdef';
console.log(myURL.href);
// Prints https://example.org/abcdef?123 copy

Некорректные символы URL, включённые в значение, присвоенное свойству pathname, кодируются по схеме percent. Выбор символов для кодирования может немного отличаться от того, что производят методы url.parse() и url.format().

url.port

• <строка>

Получает и устанавливает часть порта URL.

Значение порта может быть числом или строкой, содержащей число в диапазоне 0 до 65535 (включительно). Установка значения на стандартный порт объектов URL с учётом protocol приведет к тому, что значение port станет пустой строкой ('').

Значение порта может быть пустой строкой, в этом случае порт зависит от протокола/схемы:

При присваивании значения порту, значение сначала преобразуется в строку с помощью .toString().

Если эта строка некорректна, но начинается с числа, ведущая цифра присваивается port. Если число находится вне указанного диапазона, оно игнорируется.

const myURL = new URL('https://example.org:8888');
console.log(myURL.port);
// Prints 8888

// Default ports are automatically transformed to the empty string
// (HTTPS protocol's default port is 443)
myURL.port = '443';
console.log(myURL.port);
// Prints the empty string
console.log(myURL.href);
// Prints https://example.org/

myURL.port = 1234;
console.log(myURL.port);
// Prints 1234
console.log(myURL.href);
// Prints https://example.org:1234/

// Completely invalid port strings are ignored
myURL.port = 'abcd';
console.log(myURL.port);
// Prints 1234

// Leading numbers are treated as a port number
myURL.port = '5678abcd';
console.log(myURL.port);
// Prints 5678

// Non-integers are truncated
myURL.port = 1234.5678;
console.log(myURL.port);
// Prints 1234

// Out-of-range numbers which are not represented in scientific notation
// will be ignored.
myURL.port = 1e10; // 10000000000, will be range-checked as described below
console.log(myURL.port);
// Prints 1234 copy

Числа, содержащие десятичную точку, такие как числа с плавающей точкой или числа в научной записи, не являются исключением из этого правила. Ведущие цифры до десятичной точки будут установлены в качестве порта URL, при условии их корректности:

myURL.port = 4.567e21;
console.log(myURL.port);
// Prints 4 (because it is the leading number in the string '4.567e21') copy

url.protocol

• <строка>

Получает и устанавливает часть протокола URL.

const myURL = new URL('https://example.org');
console.log(myURL.protocol);
// Prints https:

myURL.protocol = 'ftp';
console.log(myURL.href);
// Prints ftp://example.org/ copy

Некорректные значения протокола URL, присвоенные свойству protocol, игнорируются.

Специальные схемы

Стандарт WHATWG URL считает несколько схем протоколов URL специальными с точки зрения их парсинга и сериализации. Когда URL парсится с использованием одного из этих специальных протоколов, свойство url.protocol может быть изменено на другой специальный протокол, но не может быть изменено на неспециальный протокол, и наоборот.

Например, изменение с http на https работает:

const u = new URL('http://example.org');
u.protocol = 'https';
console.log(u.href);
// https://example.org/ copy

Однако, изменение с http на гипотетический протокол fish не работает, потому что новый протокол не является специальным.

const u = new URL('http://example.org');
u.protocol = 'fish';
console.log(u.href);
// http://example.org/ copy

Аналогично, изменение с неспециального протокола на специальный также не разрешено:

const u = new URL('fish://example.org');
u.protocol = 'http';
console.log(u.href);
// fish://example.org copy

Согласно стандарту WHATWG URL, специальные схемы протоколов — ftp, file, http, https, ws, и wss.

url.search

• <строка>

Получает и устанавливает сериализованную часть запроса URL.

const myURL = new URL('https://example.org/abc?123');
console.log(myURL.search);
// Prints ?123

myURL.search = 'abc=xyz';
console.log(myURL.href);
// Prints https://example.org/abc?abc=xyz copy

Любые недопустимые символы URL, присутствующие в значении, присвоенном свойству search, будут кодированы в процентах. Выбор символов для кодирования в процентах может незначительно отличаться от того, что создают методы url.parse() и url.format().

url.searchParams

• <URLSearchParams>

Получает объект URLSearchParams, представляющий параметры запроса URL. Это свойство является только для чтения, но предоставляемый объект URLSearchParams может использоваться для изменения экземпляра URL; для замены всех параметров запроса URL используйте установщик url.search. Подробнее см. документацию URLSearchParams.

Будьте внимательны при использовании .searchParams для изменения URL, потому что, согласно спецификации WHATWG, объект URLSearchParams использует разные правила для определения символов, которые следует кодировать в процентах. Например, объект URL не будет кодировать в процентах символ ASCII тильды (~ ), в то время как URLSearchParams всегда будет его кодировать:

const myURL = new URL('https://example.org/abc?foo=~bar');

console.log(myURL.search);  // prints ?foo=~bar

// Modify the URL via searchParams...
myURL.searchParams.sort();

console.log(myURL.search);  // prints ?foo=%7Ebar copy

url.username

• <строка>

Получает и устанавливает часть имени пользователя URL.

const myURL = new URL('https://abc:xyz@example.com');
console.log(myURL.username);
// Prints abc

myURL.username = '123';
console.log(myURL.href);
// Prints https://123:xyz@example.com/ copy

Любые недопустимые символы URL, присутствующие в значении, присвоенном свойству username, будут кодированы в процентах. Выбор символов для кодирования в процентах может незначительно отличаться от того, что создают методы url.parse() и url.format().

url.toString()

• Возвращает: <строка>

Метод toString() объекта URL возвращает сериализованный URL. Возвращаемое значение эквивалентно значению url.href и url.toJSON().

url.toJSON()

• Возвращает: <строка>

Метод toJSON() объекта URL возвращает сериализованный URL. Возвращаемое значение эквивалентно значению url.href и url.toString().

Этот метод автоматически вызывается при сериализации объекта URL с помощью JSON.stringify().

const myURLs = [
  new URL('https://www.example.com'),
  new URL('https://test.example.org'),
];
console.log(JSON.stringify(myURLs));
// Prints ["https://www.example.com/","https://test.example.org/"] copy

URL.createObjectURL(blob)

• blob <Blob>
• Возвращает: <строка>

Создаёт строку URL 'blob:nodedata:...', представляющую заданный объект <Blob>, и может использоваться для получения Blob позже.

const {
  Blob,
  resolveObjectURL,
} = require('node:buffer');

const blob = new Blob(['hello']);
const id = URL.createObjectURL(blob);

// later...

const otherBlob = resolveObjectURL(id);
console.log(otherBlob.size); copy

Данные, хранящиеся зарегистрированным объектом <Blob>, будут храниться в памяти до тех пор, пока не будет вызвано URL.revokeObjectURL() для его удаления.

Объекты Blob регистрируются в текущей потоковой нити. Если вы используете потоки Worker, объекты Blob , зарегистрированные в одном потоке Worker, не будут доступны другим потокам Worker или основной потоковой нити.

URL.revokeObjectURL(id)

• id <строка> Строка URL 'blob:nodedata:... , возвращённая предыдущим вызовом URL.createObjectURL().

Удаляет сохранённый объект <Blob>, идентифицированный заданным идентификатором. Попытка аннулирования идентификатора, который не зарегистрирован, тихо завершится ошибкой.

URL.canParse(input[, base])

• input <строка> Абсолютный или относительный входной URL для анализа. Если input относительный, то base требуется. Если input абсолютный, то base игнорируется. Если input не является строкой, он сначала преобразуется в строку.
• base <строка> Базовый URL для разрешения, если input не является абсолютным. Если base не является строкой, он сначала преобразуется в строку.
• Возвращает: <логическое>

Проверяет, можно ли анализировать относительный input по отношению к base до объекта URL.

const isValid = URL.canParse('/foo', 'https://example.org/'); // true

const isNotValid = URL.canParse('/foo'); // false copy

Класс: URLSearchParams

API URLSearchParams обеспечивает чтение и запись запроса URL. Класс URLSearchParams также может быть использован автономно с одним из четырёх конструкторов. Класс URLSearchParams также доступен в глобальном объекте.

Интерфейс WHATWG URLSearchParams и модуль querystring имеют схожую цель, но цель модуля querystring более общая, поскольку он позволяет настраивать разделительные символы (& и =). С другой стороны, этот API предназначен исключительно для строк запроса URL.

const myURL = new URL('https://example.org/?abc=123');
console.log(myURL.searchParams.get('abc'));
// Prints 123

myURL.searchParams.append('abc', 'xyz');
console.log(myURL.href);
// Prints https://example.org/?abc=123&abc=xyz

myURL.searchParams.delete('abc');
myURL.searchParams.set('a', 'b');
console.log(myURL.href);
// Prints https://example.org/?a=b

const newSearchParams = new URLSearchParams(myURL.searchParams);
// The above is equivalent to
// const newSearchParams = new URLSearchParams(myURL.search);

newSearchParams.append('a', 'c');
console.log(myURL.href);
// Prints https://example.org/?a=b
console.log(newSearchParams.toString());
// Prints a=b&a=c

// newSearchParams.toString() is implicitly called
myURL.search = newSearchParams;
console.log(myURL.href);
// Prints https://example.org/?a=b&a=c
newSearchParams.delete('a');
console.log(myURL.href);
// Prints https://example.org/?a=b&a=c copy

new URLSearchParams()

Создаёт новый пустой объект URLSearchParams.

new URLSearchParams(string)

• string <строка> Строка запроса

Анализирует string как строку запроса и использует её для создания нового объекта URLSearchParams . Ведущий '?', если он есть, игнорируется.

let params;

params = new URLSearchParams('user=abc&query=xyz');
console.log(params.get('user'));
// Prints 'abc'
console.log(params.toString());
// Prints 'user=abc&query=xyz'

params = new URLSearchParams('?user=abc&query=xyz');
console.log(params.toString());
// Prints 'user=abc&query=xyz' copy

new URLSearchParams(obj)

• obj <Объект> Объект, представляющий коллекцию пар ключ-значение

Создаёт новый объект URLSearchParams с хэш-таблицей запроса. Ключ и значение каждого свойства obj всегда преобразуются в строки.

В отличие от модуля querystring, дубликаты ключей в виде значений массива недопустимы. Массивы строятся с помощью array.toString(), который просто объединяет все элементы массива запятыми.

const params = new URLSearchParams({
  user: 'abc',
  query: ['first', 'second'],
});
console.log(params.getAll('query'));
// Prints [ 'first,second' ]
console.log(params.toString());
// Prints 'user=abc&query=first%2Csecond' copy

new URLSearchParams(iterable)

• iterable <Итерируемый> Итерируемый объект, элементы которого представляют пары ключ-значение

Создаёт новый объект URLSearchParams с итерируемой картой аналогично конструктору Map. iterable может быть Array или любым итерируемым объектом. Это означает, что iterable может быть другим URLSearchParams, в этом случае конструктор просто создаст копию предоставленного URLSearchParams. Элементы iterable — пары ключ-значение, которые сами могут быть итерируемыми объектами.

Дубликаты ключей разрешены.

let params;

// Using an array
params = new URLSearchParams([
  ['user', 'abc'],
  ['query', 'first'],
  ['query', 'second'],
]);
console.log(params.toString());
// Prints 'user=abc&query=first&query=second'

// Using a Map object
const map = new Map();
map.set('user', 'abc');
map.set('query', 'xyz');
params = new URLSearchParams(map);
console.log(params.toString());
// Prints 'user=abc&query=xyz'

// Using a generator function
function* getQueryPairs() {
  yield ['user', 'abc'];
  yield ['query', 'first'];
  yield ['query', 'second'];
}
params = new URLSearchParams(getQueryPairs());
console.log(params.toString());
// Prints 'user=abc&query=first&query=second'

// Each key-value pair must have exactly two elements
new URLSearchParams([
  ['user', 'abc', 'error'],
]);
// Throws TypeError [ERR_INVALID_TUPLE]:
//        Each query pair must be an iterable [name, value] tuple copy

urlSearchParams.append(name, value)

• name <строка>
• value <строка>

Добавляет новую пару имя-значение в строку запроса.

urlSearchParams.delete(name[, value])

• name <string>
• value <string>

Если value предоставлено, удаляет все пары имя-значение, где имя равно name, а значение равно value.

Если value не предоставлено, удаляет все пары имя-значение, имя которых равно name.

urlSearchParams.entries()

• Возвращает: <Итератор>

Возвращает итератор ES6 Iterator по каждой паре имя-значение в запросе. Каждый элемент итератора — это JavaScript Array. Первый элемент итератора — name, второй — value.

Псевдоним для urlSearchParams[@@iterator]().

urlSearchParams.forEach(fn[, thisArg])

• fn <Функция> Вызывается для каждой пары имя-значение в запросе
• thisArg <Объект> Используется в качестве значения this при вызове fn

Итерируется по каждой паре имя-значение в запросе и вызывает заданную функцию.

const myURL = new URL('https://example.org/?a=b&c=d');
myURL.searchParams.forEach((value, name, searchParams) => {
  console.log(name, value, myURL.searchParams === searchParams);
});
// Prints:
//   a b true
//   c d true copy

urlSearchParams.get(name)

• name <string>
• Возвращает: <string> | <null> Строку или null, если пары имя-значение с заданным name нет.

Возвращает значение первой пары имя-значение, имя которой равно name. Если таких пар нет, возвращается null.

urlSearchParams.getAll(name)

• name <string>
• Возвращает: <string[]>

Возвращает значения всех пар имя-значение, у которых имя равно name. Если таких пар нет, возвращается пустой массив.

urlSearchParams.has(name[, value])

• name <string>
• value <string>
• Возвращает: <boolean>

Проверяет, содержит ли объект URLSearchParams пару(ы) ключ-значение, основываясь на name и необязательном аргументе value.

Если value предоставлен, возвращает true, когда существует пара имя-значение с таким же name и value.

Если value не предоставлен, возвращает true если существует хотя бы одна пара имя-значение, у которой имя равно name.

urlSearchParams.keys()

• Возвращает: <Итератор>

Возвращает итератор ES6 Iterator по именам каждой пары имя-значение.

const params = new URLSearchParams('foo=bar&foo=baz');
for (const name of params.keys()) {
  console.log(name);
}
// Prints:
//   foo
//   foo copy

urlSearchParams.set(name, value)

• name <string>
• value <string>

Устанавливает значение в объекте URLSearchParams по ключу name в value. Если уже есть пары имя-значение с именами name, устанавливает значение первой такой пары в value и удаляет все остальные. В противном случае добавляет пару имя-значение в строку запроса.

const params = new URLSearchParams();
params.append('foo', 'bar');
params.append('foo', 'baz');
params.append('abc', 'def');
console.log(params.toString());
// Prints foo=bar&foo=baz&abc=def

params.set('foo', 'def');
params.set('xyz', 'opq');
console.log(params.toString());
// Prints foo=def&abc=def&xyz=opq copy

urlSearchParams.size

Общее количество записей параметров.

urlSearchParams.sort()

Сортирует все существующие пары имя-значение на месте по их именам. Сортировка выполняется с помощью стабильного алгоритма сортировки, поэтому относительный порядок пар имя-значение с одинаковыми именами сохраняется.

Этот метод может быть использован, в частности, для повышения попаданий в кэш.

const params = new URLSearchParams('query[]=abc&type=search&query[]=123');
params.sort();
console.log(params.toString());
// Prints query%5B%5D=abc&query%5B%5D=123&type=search copy

urlSearchParams.toString()

• Возвращает: <string>

Возвращает сериализованные параметры поиска как строку с необходимым кодированием символов в процентах.

urlSearchParams.values()

• Возвращает: <Итератор>

Возвращает итератор ES6 Iterator по значениям каждой пары имя-значение.

urlSearchParams[Symbol.iterator]()

• Возвращает: <Итератор>

Возвращает итератор ES6 Iterator по каждой паре имя-значение в строке запроса. Каждый элемент итератора — JavaScript Array. Первый элемент итератора — name, второй — value.

Псевдоним для urlSearchParams.entries().

const params = new URLSearchParams('foo=bar&xyz=baz');
for (const [name, value] of params) {
  console.log(name, value);
}
// Prints:
//   foo bar
//   xyz baz copy

url.domainToASCII(domain)

• domain <string>
• Возвращает: <string>

Возвращает строку Punycode ASCII-сериализации domain. Если domain — недопустимый домен, возвращается пустая строка.

Выполняет обратную операцию к url.domainToUnicode().

Модули MJS

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

Модули CJS

const url = require('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

url.domainToUnicode(domain)

• domain <string>
• Возвращает: <string>

Возвращает Unicode-сериализацию domain. Если domain — недопустимый домен, возвращается пустая строка.

Выполняет обратную операцию к url.domainToASCII().

Модули MJS

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

Модули CJS

const url = require('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

url.fileURLToPath(url[, options])

• url <URL> | <string> Строка URL файла или объект URL, который нужно преобразовать в путь.
• options <Object>
  • windows <boolean> | <undefined> true если path должен быть возвращен как путь к файлу Windows, false для POSIX и undefined для системного значения по умолчанию. По умолчанию: undefined.
• Возвращает: <string> Полный, разрешенный платформозависимый путь к файлу Node.js.

Эта функция гарантирует правильное декодирование процентов-кодированных символов, а также обеспечивает создание валидного абсолютного пути для кроссплатформенной работы.

Модули MJS

import { fileURLToPath } from 'node:url';

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

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

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

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

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

Модули CJS

const { fileURLToPath } = require('node:url');
new URL('file:///C:/path/').pathname;      // Incorrect: /C:/path/
fileURLToPath('file:///C:/path/');         // Correct:   C:\path\ (Windows)

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

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

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

url.format(URL[, options])

• URL <URL> Объект URL WHATWG
• options <Object>
  • auth <boolean> true если строка сериализованного URL должна включать имя пользователя и пароль, true иначе. По умолчанию: true.
  • fragment <boolean> true если строка сериализованного URL должна включать фрагмент, false иначе. По умолчанию: true.
  • search <boolean> true если строка сериализованного URL должна включать поисковый запрос, false иначе. По умолчанию: true.
  • unicode <boolean> true если символы Unicode, присутствующие в компоненте хоста строки URL, должны быть закодированы напрямую, а не с помощью Punycode. По умолчанию: false.
• Возвращает: <string>

Возвращает настраиваемую сериализацию URL String представления объекта URL WHATWG.

Объект URL имеет метод toString() и свойство href, которые возвращают строковые сериализации URL. Однако они никак не настраиваются. Метод url.format(URL[, options]) позволяет настраивать вывод.

Модули MJS

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

console.log(myURL.href);
// Prints https://a:b@xn--g6w251d/?abc#foo

console.log(myURL.toString());
// Prints https://a:b@xn--g6w251d/?abc#foo

console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }));
// Prints 'https://測試/?abc'

Модули CJS

const url = require('node:url');
const myURL = new URL('https://a:b@測試?abc#foo');

console.log(myURL.href);
// Prints https://a:b@xn--g6w251d/?abc#foo

console.log(myURL.toString());
// Prints https://a:b@xn--g6w251d/?abc#foo

console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }));
// Prints 'https://測試/?abc'

url.pathToFileURL(path[, options])

• path <string> Путь, который нужно преобразовать в URL файла.
• options <Object>
  • windows <boolean> | <undefined> true если path должен рассматриваться как путь к файлу Windows, false для POSIX и undefined для системного значения по умолчанию. По умолчанию: undefined.
• Возвращает: <URL> Объект URL файла.

Эта функция гарантирует, что path разрешен абсолютно, и что символы управления URL правильно закодированы при преобразовании в URL файла.

Модули MJS

import { pathToFileURL } from 'node:url';

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

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

Модули CJS

const { pathToFileURL } = require('node:url');
new URL(__filename);                  // Incorrect: throws (POSIX)
new URL(__filename);                  // Incorrect: C:\... (Windows)
pathToFileURL(__filename);            // Correct:   file:///... (POSIX)
pathToFileURL(__filename);            // Correct:   file:///C:/... (Windows)

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

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

url.urlToHttpOptions(url)

• url <URL> Объект URL WHATWG, который нужно преобразовать в объект параметров.
• Возвращает: <Object> Объект параметров
  • protocol <string> Протокол для использования.
  • hostname <string> Имя домена или IP-адрес сервера, которому нужно отправить запрос.
  • hash <string> Фрагмент части URL.
  • search <string> Сериализованная часть запроса URL.
  • pathname <string> Часть пути URL.
  • path <string> Путь запроса. Если есть, должен включать строку запроса. Например: '/index.html?page=12'. Исключение выбрасывается, когда путь запроса содержит недопустимые символы. В настоящее время отклоняются только пробелы, но в будущем это может измениться.
  • href <string> Сериализованный URL.
  • port <number> Порт удаленного сервера.
  • auth <string> Базовая аутентификация, т. е. 'user:password' для вычисления заголовка Authorization.

Эта служебная функция преобразует объект URL в обычный объект параметров, как ожидается API http.request() и https.request().

Модули MJS

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'
}
*/

Модули CJS

const { urlToHttpOptions } = require('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'
}
*/

API URL-ов устаревшего формата

Устаревший urlObject

Устаревший urlObject (require('node:url').Url или import { Url } from 'node:url') создаётся и возвращается функцией url.parse().

urlObject.auth

Свойство auth — это часть URL, содержащая имя пользователя и пароль (также известная как userinfo). Эта подстрока следует за protocol и двумя слешами (если они есть), и предшествует host компоненту, разделённому @. Строка содержит либо имя пользователя, либо имя пользователя и пароль, разделённые :.

Например: 'user:pass'.

urlObject.hash

Свойство hash — это часть URL, содержащая идентификатор фрагмента, включая ведущий символ #.

Например: '#hash'.

urlObject.host

Свойство host — это полное имя хоста URL в нижнем регистре, включая port (если указано).

Например: 'sub.example.com:8080'.

urlObject.hostname

Свойство hostname — это имя хоста в нижнем регистре из host компонента без port.

Например: 'sub.example.com'.

urlObject.href

Свойство href — это полная строка URL, которая была обработана с protocol и host компонентами в нижнем регистре.

Например: 'http://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash'.

urlObject.path

Свойство path — это конкатенация pathname и search компонентов.

Например: '/p/a/t/h?query=string'.

Декодирование path не выполняется.

urlObject.pathname

Свойство pathname содержит весь раздел пути URL. Это всё, что следует за host (включая port) и идёт до начала query или hash компонентов, разделённых знаком вопроса (?) или диез (#) (#) соответственно.

Например: '/p/a/t/h'.

Декодирование строки пути не выполняется.

urlObject.port

Свойство port — это числовой порт host компонента.

Например: '8080'.

urlObject.protocol

Свойство protocol определяет схему протокола URL в нижнем регистре.

Например: 'http:'.

urlObject.query

Свойство query — это либо строка запроса без ведущего знака вопроса (?), либо объект, возвращённый методом parse() модуля querystring. Тип свойства (query) — строка или объект — определяется аргументом parseQueryString, переданным в url.parse().

Например: 'query=string' или {'query': 'string'}.

Если возвращается строка, декодирование строки запроса не выполняется. Если возвращается объект, ключи и значения декодируются.

urlObject.search

Свойство search содержит часть URL, представляющую «строку запроса», включая ведущий символ ASCII-знака вопроса (?).

Например: '?query=string'.

Декодирование строки запроса не выполняется.

urlObject.slashes

Свойство slashes имеет значение true если после двоеточия в protocol требуются два слеша (/).

url.format(urlObject)

• urlObject <Объект> | <строка> Объект URL (возвращаемый url.parse() или созданный другим способом). Если строка, она преобразуется в объект путём передачи в url.parse().

Метод url.format() возвращает отформатированную строку URL, полученную из 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' copy

Если urlObject не является объектом или строкой, url.format() выбросит ошибку TypeError.

Процесс форматирования выполняется следующим образом:

• Создается новая пустая строка result.
• Если urlObject.protocol является строкой, она добавляется как есть к result.
• В противном случае, если urlObject.protocol не undefined и не является строкой, выбрасывается Error.
• Для всех строковых значений urlObject.protocol, которые не заканчиваются символом ASCII двоеточия (:), к result будет добавлена литерная строка :.
• Если выполняется хотя бы одно из следующих условий, к result будет добавлена литерная строка //:
  • свойство urlObject.slashes имеет значение true;
  • urlObject.protocol начинается с http, https, ftp, gopher, или file;
• Если значение свойства urlObject.auth истинно, а urlObject.host или urlObject.hostname не undefined, значение urlObject.auth будет приведено к строке и добавлено к result, за которым следует литерная строка @.
• Если свойство urlObject.host имеет значение undefined, то:
  • Если urlObject.hostname является строкой, она добавляется к result.
  • В противном случае, если urlObject.hostname не undefined и не является строкой, выбрасывается Error.
  • Если значение свойства urlObject.port истинно, а urlObject.hostname не undefined, то:
    • к result добавляется литерная строка :, и
    • значение urlObject.port приводится к строке и добавляется к result.
• В противном случае, если значение свойства urlObject.host истинно, значение urlObject.host приводится к строке и добавляется к result.
• Если свойство urlObject.pathname является строкой, которая не пустая:
  • Если urlObject.pathname не начинается с символа ASCII прямой косой черты (/), то к result добавляется литерная строка '/'.
  • Значение urlObject.pathname добавляется к result.
• В противном случае, если urlObject.pathname не undefined и не является строкой, выбрасывается Error.
• Если свойство urlObject.search имеет значение undefined, а свойство urlObject.query является Object, к result добавляется литерная строка ? и результат вызова метода stringify() модуля querystring с аргументом urlObject.query.
• В противном случае, если urlObject.search является строкой:
  • Если значение urlObject.search не начинается с символа ASCII вопроса (?) , то к result добавляется литерная строка ?.
  • Значение urlObject.search добавляется к result.
• В противном случае, если urlObject.search не undefined и не является строкой, выбрасывается Error.
• Возвращается result.

url.parse(urlString[, parseQueryString[, slashesDenoteHost]])

• urlString <строка> Строка URL для разбора.
• parseQueryString <логическое> Если true, свойство query всегда будет установлено в объект, возвращаемый методом parse() модуля querystring. Если false, свойство query в возвращаемом объекте URL будет необработанной, нерасшифрованной строкой. По умолчанию: false.
• slashesDenoteHost <логическое> Если true, первый токен после литерной строки // и перед следующим / будет интерпретироваться как host. Например, при //foo/bar, результат будет {host: 'foo', pathname: '/bar'}, а не {pathname: '//foo/bar'}. По умолчанию: false.

Метод url.parse() принимает строку URL, анализирует её и возвращает объект URL.

Если urlString не является строкой, выбрасывается TypeError.

Выбрасывается URIError , если свойство auth присутствует, но не может быть декодировано.

url.parse() использует мягкий, нестандартный алгоритм для разбора строк URL. Он подвержен проблемам безопасности, таким как подмена имени хоста и неправильная обработка имен пользователей и паролей. Не используйте с ненадежными данными. CVEs не выдаются для url.parse() уязвимостей. Используйте API WHATWG URL вместо этого.

url.resolve(from, to)

• from <строка> Базовый URL, который используется, если to является относительным URL.
• to <строка> Целевой URL для разрешения.

Метод url.resolve() разрешает целевой URL относительно базового URL аналогично тому, как это делает веб-браузер при разрешении тега якоря.

const url = require('node:url');
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' copy

Для достижения такого же результата с помощью API WHATWG URL:

function resolve(from, to) {
  const resolvedUrl = new URL(to, new URL(from, 'resolve://'));
  if (resolvedUrl.protocol === 'resolve:') {
    // `from` is a relative URL.
    const { pathname, search, hash } = resolvedUrl;
    return pathname + search + hash;
  }
  return resolvedUrl.toString();
}

resolve('/one/two/three', 'four');         // '/one/two/four'
resolve('http://example.com/', '/one');    // 'http://example.com/one'
resolve('http://example.com/one', '/two'); // 'http://example.com/two' copy

Кодирование процентов в URL

В URL разрешено использовать только определённый диапазон символов. Любой символ, выходящий за пределы этого диапазона, должен быть закодирован. Способ кодирования и какие символы кодировать зависят от расположения символа в структуре URL.

API устаревшего стандарта

В API устаревшего стандарта пробелы (' ') и следующие символы будут автоматически экранироваться в свойствах объектов URL:

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

Например, символ ASCII пробел (' ') кодируется как %20. Символ ASCII слэша (/) кодируется как %3C.

API WHATWG

Стандарт URL WHATWG (WHATWG URL Standard) использует более избирательный и точный подход к выбору кодируемых символов, чем API устаревшего стандарта.

Алгоритм WHATWG определяет четыре «набора кодирования процентов» (percent-encode sets), которые описывают диапазоны символов, которые должны быть закодированы:

• Набор кодирования процентов C0 включает символы с кодами U+0000 до U+001F (включительно) и все символы с кодами больше U+007E (~).

• Набор кодирования процентов фрагмента включает набор кодирования процентов C0 и символы U+0020 (пробел), U+0022 ("), U+003C (<), U+003E (>) и U+0060 (`).

• Набор кодирования процентов пути включает набор кодирования процентов C0 и символы U+0020 (пробел), U+0022 ("), U+0023 (#), U+003C (<), U+003E (>), U+003F (?), U+0060 (`), U+007B ({) и U+007D (}).

• Набор кодирования процентов userinfo включает набор кодирования процентов пути и символы U+002F (/), U+003A (:), U+003B (;), U+003D (=), U+0040 (@), U+005B ([) до U+005E(^), и U+007C (|).

Набор кодирования процентов userinfo используется исключительно для кодирования имени пользователя и пароля в URL. Набор кодирования процентов пути используется для пути большинства URL. Набор кодирования процентов фрагмента используется для фрагментов URL. Набор кодирования процентов C0 используется для имени хоста и пути в определённых условиях, помимо всех остальных случаев.

Когда в имени хоста появляются не-ASCII символы, имя хоста кодируется с помощью алгоритма Punycode. Однако имя хоста может содержать как закодированные Punycode символы, так и символы, закодированные в процентах:

const myURL = new URL('https://%CF%80.example.com/foo');
console.log(myURL.href);
// Prints https://xn--1xa.example.com/foo
console.log(myURL.origin);
// Prints https://xn--1xa.example.com copy