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 URL WHATWG включает 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 реализованы как геттеры и сеттеры в прототипе класса, а не как свойства данных объекта. Таким образом, в отличие от delete устаревших urlObject, использование ключевого слова 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, будут закодированы в формате процентов. Обратите внимание, что выбор символов для кодирования в формате процентов может незначительно отличаться от того, что генерируют методы url.parse() и url.format().

url.toString()

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

Из-за необходимости соблюдения стандартов этот метод не позволяет пользователям настраивать процесс сериализации URL. Для большей гибкости может быть полезен метод require('url').format().

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

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

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 <строка>
• Возвращает: <строка>

Возвращает Punycode 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 <строка>
• Возвращает: <строка>

Возвращает Unicode-представление 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

url.format(URL[, options])

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

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

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

Например:

const { URL } = require('url');
const myURL = new URL('https://a:b@你好你好?abc#foo');

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

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

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

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

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

url.format({
  protocol: 'https',
  hostname: 'example.com',
  pathname: '/some/path',
  query: {
    page: 1,
    format: 'json'
  }
});

// => 'https://example.com/some/path?page=1&format=json'

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

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

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

url.resolve(from, to)

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

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

Например:

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

Кодировка процентов в 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+003C, U+003E и U+0060.

• Набор кодирования пути включает набор 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. Набор кодирования фрагмента используется для фрагментов URL. Набор C0 контрольных символов используется для хоста и пути в определённых условиях, а также во всех других случаях.

Когда не-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