URL

Модуль url предоставляет утилиты для разрешения и разбора URL. К нему можно получить доступ, используя:

const url = require('url');

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

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

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

Примечание: Хотя устаревший API не был устаревшим, он поддерживается только для обратной совместимости с существующими приложениями. Новый код приложения должен использовать API WHATWG.

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

Примечание: Свойство origin объекта WHATWG URL включает protocol и host, но не username или password.

┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│                                            href                                             │
├──────────┬──┬─────────────────────┬─────────────────────┬───────────────────────────┬───────┤
│ protocol │  │        auth         │        host         │           path            │ hash  │
│          │  │                     ├──────────────┬──────┼──────────┬────────────────┤       │
│          │  │                     │   hostname   │ port │ pathname │     search     │       │
│          │  │                     │              │      │          ├─┬──────────────┤       │
│          │  │                     │              │      │          │ │    query     │       │
"  https:   //    user   :   pass   @ sub.host.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)

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

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

Примечание: В веб-браузерах класс WHATWG URL является глобальным и всегда доступен. В Node.js, однако, класс URL необходимо получить через require('url').URL.

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

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

API WHATWG URL

Класс: URL

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

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

Конструктор: new URL(input[, base])

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

const { URL } = require('url');
const myURL = new URL('/foo', 'https://example.org/');
// https://example.org/foo

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

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

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

const { URL } = require('url');
const myURL = new URL('https://你好你好');
// https://xn--6qqa088eba/

Примечание: Эта функция доступна только в том случае, если исполняемый файл node был скомпилирован с включённой поддержкой ICU. В противном случае имена доменов передаются без изменений.

url.hash

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

const { URL } = require('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

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

url.host

Получает и задаёт часть хоста URL.

const { URL } = require('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

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

url.hostname

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

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

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

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

url.href

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

const { URL } = require('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

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

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

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

url.origin

Получает неизменяемую сериализацию источника URL.

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

const { URL } = require('url');
const idnURL = new URL('https://你好你好');
console.log(idnURL.origin);
// Prints https://xn--6qqa088eba

console.log(idnURL.hostname);
// Prints xn--6qqa088eba

url.password

Получает и задаёт часть пароля URL.

const { URL } = require('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

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

url.pathname

Получает и задаёт часть пути URL.

const { URL } = require('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

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

url.port

Получает и задаёт часть порта URL.

const { URL } = require('url');
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 are ignored
myURL.port = 1e10;
console.log(myURL.port);
// Prints 1234

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

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

url.protocol

Получает и задаёт часть протокола URL.

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

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

url.search

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

const { URL } = require('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

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

url.searchParams

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

url.username

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

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

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

url.toString()

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

Из-за необходимости соблюдения стандартов, этот метод не позволяет пользователям настраивать процесс сериализации URL.

url.toJSON()

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

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

const { URL } = require('url');
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/"]

Класс: URLSearchParams

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

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

const { URL, URLSearchParams } = require('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

Конструктор: new URLSearchParams()

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

Конструктор: new URLSearchParams(string)

Парсит строку string как строку запроса и использует её для создания нового объекта URLSearchParams.

const { URLSearchParams } = require('url');
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'

Конструктор: new URLSearchParams(obj)

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

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

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

const { URLSearchParams } = require('url');
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'

Конструктор: new URLSearchParams(iterable)

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

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

Элементы iterable - это пары ключ-значение, которые сами могут быть любыми итерируемыми объектами.

Повторные ключи разрешены.

const { URLSearchParams } = require('url');
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

urlSearchParams.append(name, value)

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

urlSearchParams.delete(name)

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

urlSearchParams.entries()

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

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

urlSearchParams.forEach(fn[, thisArg])

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

const { URL } = require('url');
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

urlSearchParams.get(name)

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

urlSearchParams.getAll(name)

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

urlSearchParams.has(name)

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

urlSearchParams.keys()

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

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

urlSearchParams.set(name, value)

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

const { URLSearchParams } = require('url');

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

urlSearchParams.sort()

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

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

const { URLSearchParams } = require('url');
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

urlSearchParams.toString()

Возвращает сериализованные параметры поиска в виде строки, с необходимой кодировкой символов по схеме percent-encoding.

urlSearchParams.values()

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

urlSearchParams[@@iterator]()

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

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

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

url.domainToASCII(domain)

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

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

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

const url = require('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 <строка>
• Возвращает: <строка>

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

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

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

API URL (старая версия)

urlObject (старая версия)

Объект urlObject (require('url').Url) создается и возвращается функцией url.parse().

urlObject.auth

Свойство auth — это часть имени пользователя и пароля в URL, также известная как «userinfo». Эта подстрока следует за protocol и двумя косыми чертами (если они присутствуют) и предшествует компоненту host, ограниченному ASCII символом «собачка» (@). Формат строки — {username}[:{password}], при этом часть [:{password}] является необязательной.

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

urlObject.hash

Свойство hash состоит из части «фрагмент» URL, включая ведущий символ ASCII решётки (#).

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

urlObject.host

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

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

urlObject.hostname

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

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

urlObject.href

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

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

urlObject.port

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

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

urlObject.pathname

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

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

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

urlObject.search

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

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

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

urlObject.path

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

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

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

urlObject.query

Свойство query — это либо строка запроса без ведущего ASCII вопросительного знака (?), либо объект, возвращаемый методом querystring модуля 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 <Объект> | <строка> Объект URL (как возвращается url.parse() или созданный иным образом). Если строка, она преобразуется в объект, передав её в url.parse().

Метод url.format() возвращает отформатированную строку URL, полученную из urlObject.

Если 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.

url.resolve(from, to)

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

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

Например:

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'

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

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

Устаревший API

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

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

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

API WHATWG

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

Алгоритм WHATWG определяет три «набора кодируемых символов»:

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

• Набор кодируемых символов пути включает в себя набор C0 управляющих символов и код-точки U+0020, U+0022, U+0023, U+003C, U+003E, U+003F, U+0060, U+007B, и U+007D.

• Набор кодируемых символов пользовательских данных включает в себя набор кодируемых символов пути и код-точки U+002F, U+003A, U+003B, U+003D, U+0040, U+005B, U+005C, U+005D, U+005E, и U+007C.

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

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

const { URL } = require('url');
const myURL = new URL('https://%CF%80.com/foo');
console.log(myURL.href);
// Prints https://xn--1xa.com/foo
console.log(myURL.origin);
// Prints https://π.com