URL

Модуль node:url предоставляет служебные средства для разрешения и разбора URL. Его можно подключить следующим образом:

import url from 'node:url';

const url = require('node:url');

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

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

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

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

Свойство 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.)
textcopy

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

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

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

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

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

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

URL WHATWG можно создать из отдельных компонентов с помощью установщиков свойств или строкового литерала шаблона:

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

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

Чтобы получить созданную строку URL, используйте средство доступа к свойству href:

console.log(myURL.href);
jscopy

API URL WHATWG

Класс: URL

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

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

new URL(input[, base])

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

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

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

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

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

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

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

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

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

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

Если заранее неизвестно, является ли 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/
jscopy

url.hash

• Тип: <string>

Получает и задаёт часть 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
jscopy

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

url.host

• Тип: <string>

Получает и задаёт часть 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
jscopy

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

url.hostname

• Тип: <string>

Получает и задаёт часть 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
jscopy

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

url.href

• Тип: <string>

Получает и задаёт сериализованный 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
jscopy

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

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

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

url.origin

• Тип: <string>

Получает сериализованное происхождение URL только для чтения.

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

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

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

url.password

• Тип: <string>

Получает и задаёт часть 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/
jscopy

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

url.pathname

• Тип: <string>

Получает и задаёт часть 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
jscopy

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

url.port

• Тип: <string>

Получает и задаёт часть 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
jscopy

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

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

url.protocol

• Тип: <string>

Получает и задаёт часть 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/
jscopy

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

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

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

Например, переход от http к https возможен:

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

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

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

Аналогично, переход от неспециального протокола к специальному также не разрешён:

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

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

url.search

• Тип: <string>

Получает и задаёт сериализованную часть 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
jscopy

Любые недопустимые символы 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
jscopy

url.username

• Тип: <string>

Получает и задаёт часть 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/
jscopy

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

url.toString()

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

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

url.toJSON()

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

Метод 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/"]
jscopy

URL.createObjectURL(blob)

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

Создаёт строку 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);
jscopy

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

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

URL.revokeObjectURL(id)

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

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

URL.canParse(input[, base])

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

Проверяет, можно ли разобрать input относительно base как URL.

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

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

URL.parse(input[, base])

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

Разбирает строку как URL. Если задан base, он будет использоваться как базовый URL для разрешения относительных URL input. Возвращает null, если параметры невозможно разрешить в допустимый URL.

Класс: URLPattern

API URLPattern предоставляет интерфейс для сопоставления URL или их частей с шаблоном.

const myPattern = new URLPattern('https://nodejs.org/docs/latest/api/*.html');
console.log(myPattern.exec('https://nodejs.org/docs/latest/api/dns.html'));
// Prints:
// {
//  "hash": { "groups": {  "0": "" },  "input": "" },
//  "hostname": { "groups": {}, "input": "nodejs.org" },
//  "inputs": [
//    "https://nodejs.org/docs/latest/api/dns.html"
//  ],
//  "password": { "groups": { "0": "" }, "input": "" },
//  "pathname": { "groups": { "0": "dns" }, "input": "/docs/latest/api/dns.html" },
//  "port": { "groups": {}, "input": "" },
//  "protocol": { "groups": {}, "input": "https" },
//  "search": { "groups": { "0": "" }, "input": "" },
//  "username": { "groups": { "0": "" }, "input": "" }
// }

console.log(myPattern.test('https://nodejs.org/docs/latest/api/dns.html'));
// Prints: true
jscopy

new URLPattern()

Создаёт экземпляр нового пустого объекта URLPattern.

new URLPattern(string[, baseURL][, options])

• string <string> Строка URL
• baseURL <string> | <undefined> Строка базового URL
• options <Object> Параметры

Разбирает string как URL и использует его для создания экземпляра нового объекта URLPattern.

Если baseURL не задан, по умолчанию используется undefined.

Параметр может содержать булев атрибут ignoreCase, который при значении true включает сопоставление без учёта регистра.

Конструктор может выбросить исключение TypeError, указывающее на ошибку разбора.

new URLPattern(obj[, baseURL][, options])

• obj <Object> Входной шаблон
• baseURL <string> | <undefined> Строка базового URL
• options <Object> Параметры

Разбирает Object как входной шаблон и использует его для создания экземпляра нового объекта URLPattern. Членами объекта могут быть любые из следующих: protocol, username, password, hostname, port, pathname, search, hash или baseURL.

Если baseURL не задан, по умолчанию используется undefined.

Параметр может содержать булев атрибут ignoreCase, который при значении true включает сопоставление без учёта регистра.

Конструктор может выбросить исключение TypeError, указывающее на ошибку разбора.

urlPattern.exec(input[, baseURL])

• input <string> | <Object> URL или части URL
• baseURL <string> | <undefined> Строка базового URL

Входные данные могут быть строкой или объектом, содержащим отдельные части URL. Членами объекта могут быть любые из следующих: protocol, username, password, hostname, port, pathname, search, hash или baseURL.

Если baseURL не задан, по умолчанию используется undefined.

Возвращает объект с ключом inputs, содержащим массив аргументов, переданных функции, и ключами компонентов URL, содержащими совпавшие входные данные и совпавшие группы.

const myPattern = new URLPattern('https://nodejs.org/docs/latest/api/*.html');
console.log(myPattern.exec('https://nodejs.org/docs/latest/api/dns.html'));
// Prints:
// {
//  "hash": { "groups": {  "0": "" },  "input": "" },
//  "hostname": { "groups": {}, "input": "nodejs.org" },
//  "inputs": [
//    "https://nodejs.org/docs/latest/api/dns.html"
//  ],
//  "password": { "groups": { "0": "" }, "input": "" },
//  "pathname": { "groups": { "0": "dns" }, "input": "/docs/latest/api/dns.html" },
//  "port": { "groups": {}, "input": "" },
//  "protocol": { "groups": {}, "input": "https" },
//  "search": { "groups": { "0": "" }, "input": "" },
//  "username": { "groups": { "0": "" }, "input": "" }
// }
jscopy

urlPattern.test(input[, baseURL])

• input <string> | <Object> URL или части URL
• baseURL <string> | <undefined> Строка базового URL

Входные данные могут быть строкой или объектом, содержащим отдельные части URL. Членами объекта могут быть любые из следующих: protocol, username, password, hostname, port, pathname, search, hash или baseURL.

Если baseURL не задан, по умолчанию используется undefined.

Возвращает логическое значение, указывающее, соответствует ли входное значение текущему шаблону.

const myPattern = new URLPattern('https://nodejs.org/docs/latest/api/*.html');
console.log(myPattern.test('https://nodejs.org/docs/latest/api/dns.html'));
// Prints: true
jscopy

Класс: 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
jscopy

new URLSearchParams()

Создаёт экземпляр нового пустого объекта URLSearchParams.

new URLSearchParams(string)

• 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'
jscopy

new URLSearchParams(obj)

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

Создает новый объект 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'
jscopy

new URLSearchParams(iterable)

• 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
jscopy

urlSearchParams.append(name, value)

• name <string>
• value <string>

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

urlSearchParams.delete(name[, value])

• name <string>
• value <string>

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

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

urlSearchParams.entries()

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

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

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

urlSearchParams.forEach(fn[, thisArg])

• fn <Function> Вызывается для каждой пары «имя-значение» в запросе
• thisArg <Object> Используется как значение 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
jscopy

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

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

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

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

urlSearchParams.set(name, value)

• name <string>
• value <string>

Устанавливает в объекте URLSearchParams значение value, связанное с name. Если уже существуют пары «имя-значение» с именем 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
jscopy

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
jscopy

urlSearchParams.toString()

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

Возвращает параметры поиска в виде сериализованной строки, в которой необходимые символы закодированы с помощью процентного кодирования.

urlSearchParams.values()

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

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

urlSearchParams[Symbol.iterator]()

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

Возвращает итератор ES6 Iterator для каждой пары «имя-значение» в строке запроса. Каждый элемент итератора — это JavaScript Array. Первый элемент Array — это name, второй элемент Array — это 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
jscopy

url.domainToASCII(domain)

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

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

Выполняет обратную операцию по отношению к url.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

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>

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

Выполняет обратную операцию по отношению к url.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

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, специфичный для платформы.

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

Меры безопасности:

Эта функция декодирует символы, закодированные с помощью процентного кодирования, включая закодированные сегменты-точки (%2e как . и %2e%2e как ..), а затем нормализует полученный путь. Это означает, что закодированные последовательности обхода каталогов (например, %2e%2e) декодируются и обрабатываются как фактический обход пути, хотя закодированные косые черты (%2F, %5C) корректно отклоняются.

Приложения не должны полагаться только на fileURLToPath() для предотвращения атак с обходом каталогов. Всегда выполняйте явную проверку пути и проверки безопасности возвращенного значения пути, чтобы убедиться, что он остается в ожидаемых границах, прежде чем использовать его для операций с файловой системой.

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)

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.fileURLToPathBuffer(url[, options])

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

Подобно url.fileURLToPath(...), но вместо строкового представления пути возвращает Buffer. Это преобразование полезно, если входной URL содержит сегменты с процентным кодированием, которые не являются допустимыми последовательностями UTF-8 / Unicode.

Меры безопасности:

Для этой функции действуют те же меры безопасности, что и для url.fileURLToPath(). Она декодирует символы, закодированные с помощью процентного кодирования, включая закодированные сегменты-точки (%2e как . и %2e%2e как ..), и нормализует путь. Приложения не должны полагаться только на эту функцию для предотвращения атак с обходом каталогов. Всегда выполняйте явную проверку возвращенного значения буфера пути, прежде чем использовать его для операций с файловой системой.

url.format(URL[, options])

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

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

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

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'

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 файла.

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)

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> Объект WHATWG URL для преобразования в объект параметров.
• Возвращает: <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().

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

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; эта часть также называется информацией пользователя. Эта подстрока следует за 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, отделенных символом ASCII «вопросительный знак» (?) или «решетка» (#).

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

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

urlObject.port

Свойство port содержит числовую часть порта компонента host.

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

urlObject.protocol

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

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

urlObject.query

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

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

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

urlObject.search

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

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

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

urlObject.slashes

Свойство slashes — это boolean со значением true, если после двоеточия в protocol должны следовать две косые черты ASCII (/).

url.format(urlObject)

• urlObject <Object> Объект URL (возвращаемый 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'
jscopy

Если 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.
• Если свойство urlObject.hash является строкой:
  • Если значение urlObject.hash не начинается с символа решётки ASCII (#), к result добавляется строка #.
  • Значение urlObject.hash добавляется к result.
• В противном случае, если свойство urlObject.hash не является undefined и не является строкой, выбрасывается Error.
• Возвращается result.

Доступна автоматизированная миграция (исходный код).

npx codemod@latest @nodejs/node-url-to-whatwg-url
bashcopy

url.format(urlString)

• urlString <string> Строка, которая будет передана в url.parse(), а затем отформатирована.

url.format(urlString) — это сокращённая форма url.format(url.parse(urlString)).

Поскольку внутри вызывается устаревший метод url.parse(), передача строкового аргумента в url.format() также объявлена устаревшей.

Канонизацию строки URL можно выполнить с помощью API URL WHATWG: создать новый объект URL и вызвать url.toString().

import { URL } from 'node:url';

const unformatted = 'http://[fe80:0:0:0:0:0:0:1]:/a/b?a=b#abc';
const formatted = new URL(unformatted).toString();

console.log(formatted); // Prints: http://[fe80::1]/a/b?a=b#abc

const { URL } = require('node:url');

const unformatted = 'http://[fe80:0:0:0:0:0:0:1]:/a/b?a=b#abc';
const formatted = new URL(unformatted).toString();

console.log(formatted); // Prints: http://[fe80::1]/a/b?a=b#abc

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

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

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

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

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

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

function getURL(req) {
  const proto = req.headers['x-forwarded-proto'] || 'https';
  const host = req.headers['x-forwarded-host'] || req.headers.host || 'example.com';
  return new URL(`${proto}://${host}${req.url || '/'}`);
}
jscopy

В приведённом выше примере предполагается, что обратный прокси передаёт вашему серверу Node.js корректно сформированные заголовки. Если вы не используете обратный прокси, используйте приведённый ниже пример:

function getURL(req) {
  return new URL(`https://example.com${req.url || '/'}`);
}
jscopy

Доступна автоматизированная миграция (исходный код).

npx codemod@latest @nodejs/node-url-to-whatwg-url
bashcopy

url.resolve(from, to)

• from <string> Базовый URL, используемый, если to является относительным URL.
• to <string> Целевой 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'
jscopy

Поскольку внутри вызывается устаревший метод url.parse(), сам метод url.resolve() также объявлен устаревшим.

Чтобы получить тот же результат с помощью API URL WHATWG:

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'
jscopy

Процентное кодирование в URL

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

Устаревший API

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

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

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

API WHATWG

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

Алгоритм WHATWG определяет четыре «набора символов для процентного кодирования», описывающих диапазоны символов, которые необходимо кодировать с помощью процентов:

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

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

• Набор пути для процентного кодирования включает набор C0 управляющих символов для процентного кодирования и кодовые точки U+0020 SPACE, 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
jscopy