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

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

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

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

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

API WHATWG URL

Класс: URL

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

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

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

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

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

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

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

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

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

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

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

В тех случаях, когда заранее неизвестно, является ли 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/

url.hash

• <строка>

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

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

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

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

url.host

• <строка>

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

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

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

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

url.hostname

• <строка>

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

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

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

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

url.href

• <строка>

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

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

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

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

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

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

url.origin

• <строка>

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

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

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

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

url.password

• <строка>

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

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

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

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

url.pathname

• <строка>

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

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

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

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

url.port

• <строка>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

url.protocol

• <строка>

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

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

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

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

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

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

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

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

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

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

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

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

Протоколы, рассматриваемые как специальные в стандарте WHATWG URL, включают: ftp, file, gopher, http, https, ws, и wss.

url.search

• <строка>

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

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

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

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

url.searchParams

• <URLSearchParams>

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

url.username

• <строка>

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

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

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

Любые недопустимые символы 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 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 также может быть использован автономно с одним из четырёх конструкторов. Класс 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

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

Инициализирует новый пустой объект URLSearchParams.

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

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

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

let params;

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

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

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

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

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

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

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

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

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

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

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

let params;

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

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

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

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

urlSearchParams.append(name, value)

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

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

urlSearchParams.delete(name)

• name <строка>

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

urlSearchParams.entries()

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

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

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

urlSearchParams.forEach(fn[, thisArg])

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

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

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

urlSearchParams.get(name)

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

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

Если таких пар нет, возвращается null.

urlSearchParams.getAll(name)

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

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

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

urlSearchParams.has(name)

• name <строка>
• Возвращает: <булево значение>

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

urlSearchParams.keys()

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

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

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

urlSearchParams.set(name, value)

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

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

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

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

urlSearchParams.sort()

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

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

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 Iterator по значениям каждой пары имя-значение.

urlSearchParams[Symbol.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

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.fileURLToPath(url)

• url <URL> | <строка> Строка или объект URL файла, который нужно преобразовать в путь.
• Возвращает: <строка> Полный, разрешенный путь к файлу на платформе Node.js.

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

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

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

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

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

url.format(URL[, options])[src]

• URL <URL> Объект WHATWG URL

• options <Объект>

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

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

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

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)

• path <строка> Путь, который нужно преобразовать в URL файла.
• Возвращает: <URL> Объект URL файла.

Эта функция гарантирует, что path разрешен абсолютно, а управляющие символы URL правильно закодированы при преобразовании в 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%.js', 'file:'); // Incorrect: file:///some/path%
pathToFileURL('/some/path%.js');    // Correct:   file:///some/path%25 (POSIX)

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

Прежнее API urlObject

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

urlObject.auth

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

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

urlObject.hash

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

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

urlObject.host

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

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

urlObject.hostname

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

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

urlObject.href

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

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

urlObject.path

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

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

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

urlObject.pathname

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

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

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

urlObject.port

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

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

urlObject.protocol

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

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

urlObject.query

Свойство query представляет собой строку запроса без начального символа 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)[src]

• 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 является строкой, то в конец 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.

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

• 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 не строка.

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

url.resolve(from, to)[src]

• from <строка> Базовый URL, относительно которого разрешается целевой 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

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

Алгоритм 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.

• Набор кодирования процентов userinfo включает набор кодирования процентов пути и кодные точки U+002F, U+003A, U+003B, U+003D, U+0040, U+005B, U+005C, U+005D, 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