Справочник

• объекты nginx
• HTTP-запрос
• Сеанс Stream
• Периодический сеанс
• Заголовки
• Запрос
• Ответ
• ngx
• ngx.shared
• встроенные объекты
• console
• crypto
• CryptoKey
• CryptoKeyPair
• njs
• process
• String
• веб-API
• Декодер текста
• Кодировщик текста
• таймеры
• Глобальные функции
• встроенные модули
• Buffer
• Crypto
• Файловая система
• Строка запроса
• XML
• zlib

njs предоставляет объекты, методы и свойства для расширения функциональности nginx.

В этом справочнике описаны только специфичные для njs свойства, методы и модули, не соответствующие ECMAScript. Определения свойств и методов njs, соответствующих ECMAScript, приведены в спецификации ECMAScript. Список всех свойств и методов njs приведён в разделе Совместимость.

Объекты nginx

HTTP-запрос

Объект HTTP-запроса доступен только в модуле ngx_http_js_module. До версии 0.8.5 все строковые свойства объекта были байтовыми строками.

r.args{}

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

Строка запроса возвращается в виде объекта. Начиная с версии 0.7.6, повторяющиеся ключи возвращаются в виде массива; ключи чувствительны к регистру, а ключи и значения декодируются из процентного кодирования.

Например, строка запроса

'a=1&b=%32&A=3&b=4&B=two%20words'

преобразуется в r.args следующим образом:

{a: "1", b: ["2", "4"], A: "3", B: "two words"}

Более сложные сценарии разбора можно реализовать с помощью модуля Строка запроса и переменной $args, например:

import qs from 'querystring';

function args(r) {
    return qs.parse(r.variables.args);
}

Объект аргументов вычисляется при первом обращении к r.args. Если нужен только один аргумент, например foo, можно использовать переменные nginx:

r.variables.arg_foo

В этом случае объект переменных nginx возвращает первое значение для заданного ключа, без учёта регистра и без декодирования процентного кодирования.

Для обратного преобразования r.args в строку можно использовать метод stringify модуля Query String.

r.decline()

указывает обработчику js_access, что он не выносит решения о доступе, и передаёт его другим средствам проверки доступа в соответствии с директивой satisfy any (0.9.9). Обработчик, завершившийся без вызова r.decline() или r.return(), неявно предоставляет доступ. Может вызываться только из функции js_access.

r.done()

после вызова этой функции следующие фрагменты данных будут передаваться клиенту без вызова js_body_filter (0.5.2). Может вызываться только из функции js_body_filter

r.error(string)

записывает string в журнал ошибок с уровнем логирования error

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

r.finish()

завершает отправку ответа клиенту

r.headersIn{}

объект входящих заголовков, доступный только для чтения.

Доступ к заголовку запроса Foo можно получить с помощью синтаксиса: headersIn.foo или headersIn['Foo'].

Заголовки запросов “Authorization”, “Content-Length”, “Content-Range”, “Content-Type”, “ETag”, “Expect”, “From”, “Host”, “If-Match”, “If-Modified-Since”, “If-None-Match”, “If-Range”, “If-Unmodified-Since”, “Max-Forwards”, “Proxy-Authorization”, “Referer”, “Transfer-Encoding” и “User-Agent” могут иметь только одно значение поля (0.4.1). Повторяющиеся значения полей в заголовках “Cookie” разделяются точкой с запятой (;). Повторяющиеся значения полей во всех остальных заголовках запросов разделяются запятыми.

r.headersOut{}

объект исходящих заголовков основного запроса, доступный для записи.

Если r.headersOut{} — объект ответа подзапроса, он представляет заголовки ответа. В этом случае значения полей заголовков ответа “Accept-Ranges”, “Connection”, “Content-Disposition”, “Content-Encoding”, “Content-Length”, “Content-Range”, “Date”, “Keep-Alive”, “Server”, “Transfer-Encoding” и “X-Accel-*” могут отсутствовать.

Доступ к заголовку ответа “Foo” можно получить с помощью синтаксиса: headersOut.foo или headersOut['Foo'].

Исходящие заголовки следует задавать до отправки заголовка ответа клиенту, иначе обновление заголовка будет проигнорировано. Это означает, что r.headersOut{} доступно для записи только в следующих случаях:

• в обработчике js_content до вызова r.sendHeader() или r.return()
• в обработчике js_header_filter

Значения полей заголовков ответов с несколькими значениями (0.4.0) можно задать с помощью синтаксиса:

r.headersOut['Foo'] = ['a', 'b']

в результате чего будет выведено:

Foo: a
Foo: b

Все предыдущие значения поля заголовка ответа “Foo” будут удалены.

Для стандартных заголовков ответа, допускающих только одно значение поля, например “Content-Type”, учитывается только последний элемент массива. Значения полей заголовка ответа “Set-Cookie” всегда возвращаются в виде массива. Повторяющиеся значения полей в заголовках ответа “Age”, “Content-Encoding”, “Content-Length”, “Content-Type”, “ETag”, “Expires”, “Last-Modified”, “Location” и “Retry-After” игнорируются. Повторяющиеся значения полей во всех остальных заголовках ответа разделяются запятыми.

r.httpVersion

версия HTTP, доступна только для чтения

r.internal

логическое значение: true для внутренних location

r.internalRedirect(uri)

выполняет внутреннее перенаправление на указанный uri. Если URI начинается с префикса “@”, он считается именованным location. В новом location обработка запроса повторяется с этапа NGX_HTTP_SERVER_REWRITE_PHASE для обычных location и с этапа NGX_HTTP_REWRITE_PHASE для именованных location. В результате при перенаправлении на именованный location ограничение client_max_body_size не проверяется. Дополнительные сведения см. в руководстве для разработчиков. Перенаправленные запросы становятся внутренними и могут обращаться к внутренним location. Фактическое перенаправление происходит после завершения выполнения обработчика.

После перенаправления в целевом location запускается новая виртуальная машина njs, а виртуальная машина в исходном location останавливается. Значения переменных nginx сохраняются и могут использоваться для передачи информации в целевой location. Начиная с версии 0.5.3, можно использовать переменную, объявленную директивой js_var для http или stream.

Начиная с версии 0.7.4, метод принимает экранированные URI.

r.log(string)

записывает string в журнал ошибок с уровнем логирования info

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

r.method

метод HTTP, доступен только для чтения

r.parent

ссылка на объект родительского запроса

r.remoteAddress

адрес клиента, доступен только для чтения

r.readRequestArrayBuffer()

возвращает Promise, который разрешается телом запроса клиента в виде ArrayBuffer (0.9.9). Сведения о доступности, кэшировании тела и семантике параллельных вызовов см. в описании r.readRequestText().

r.readRequestForm([options])

считывает тело запроса клиента и разбирает его как HTML-форму, возвращая Promise, который разрешается объектом формы (0.9.9). Поддерживаются типы содержимого application/x-www-form-urlencoded и multipart/form-data.

Объект формы предоставляет следующие методы:

get(name)

возвращает первое значение для name или null, если оно отсутствует.

getAll(name)

возвращает массив со всеми значениями для name.

has(name)

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

forEach(callback[, thisArg])

вызывает callback для каждой записи с аргументами (value, key, form).

hasFiles()

возвращает true, если форма содержит какие-либо части с файлами.

Значения текстовых полей — декодированные строки. Для частей с файлами значением является объект, свойство name которого содержит имя файла, указанное клиентом; содержимое файла недоступно. Имя файла указывает клиент, оно не проходит очистку.

Необязательный объект options принимает следующие свойства:

maxKeys number

максимальное количество полей для разбора; по умолчанию — 128. При превышении ограничения возвращённый промис отклоняется.

Сведения о доступности, кэшировании тела и семантике параллельных вызовов см. в описании r.readRequestText(). Разобранная форма кэшируется непосредственно в запросе: последующий вызов возвращает тот же объект формы и игнорирует новый аргумент options.

r.readRequestJSON()

возвращает Promise, который разрешается телом запроса клиента, разобранным как JSON (0.9.9). Сведения о доступности, кэшировании тела и семантике параллельных вызовов см. в описании r.readRequestText().

r.readRequestText()

возвращает Promise, который разрешается телом запроса клиента в виде строки (0.9.9). Размер тела запроса ограничен директивой client_max_body_size. Метод доступен в директивах js_access и js_content.

Тело считывается один раз и кэшируется в запросе: последующие вызовы r.readRequestText(), r.readRequestArrayBuffer(), r.readRequestJSON() или r.readRequestForm() используют кэшированное тело, не считывая его повторно из сетевого потока. Второй вызов, сделанный до завершения предыдущего чтения, вызывает исключение "request body is already being read".

Обратите внимание, что байты, недопустимые в кодировке UTF-8, могут быть преобразованы в символ замены.

r.requestBody

свойство признано устаревшим в версии 0.5.0 и удалено в версии 0.8.0. Вместо него следует использовать свойство r.requestBuffer или r.requestText.

r.requestBuffer

тело запроса клиента, если оно не было записано во временный файл (начиная с версии 0.5.0). Чтобы тело запроса клиента находилось в памяти, его размер должен быть ограничен директивой client_max_body_size, а с помощью директивы client_body_buffer_size необходимо задать буфер достаточного размера. Свойство доступно только в директиве js_content. Для асинхронного доступа или использования в js_access см. r.readRequestText() и другие методы «r.readRequest*()».

r.requestText

аналогично r.requestBuffer, но возвращает string. Обратите внимание, что байты, недопустимые в кодировке UTF-8, могут быть преобразованы в символ замены. Для асинхронного доступа или использования в js_access см. r.readRequestText().

r.rawHeadersIn[]

возвращает массив пар «ключ — значение» в точности в том виде, в котором они были получены от клиента (0.4.1).

Например, для следующих заголовков запроса:

Host: localhost
Foo:  bar
foo:  bar2

результат r.rawHeadersIn будет следующим:

[
    ['Host', 'localhost'],
    ['Foo', 'bar'],
    ['foo', 'bar2']
]

Все заголовки foo можно получить с помощью синтаксиса:

r.rawHeadersIn.filter(v=>v[0].toLowerCase() == 'foo').map(v=>v[1])

результат будет следующим:

['bar', 'bar2']

Имена полей заголовков не преобразуются в нижний регистр, повторяющиеся значения полей не объединяются.

r.rawHeadersOut[]

возвращает массив пар «ключ — значение» для заголовков ответа (0.4.1). Имена полей заголовков не преобразуются в нижний регистр, повторяющиеся значения полей не объединяются.

r.responseBody

свойство признано устаревшим в версии 0.5.0 и удалено в версии 0.8.0. Вместо него следует использовать свойство r.responseBuffer или r.responseText.

r.responseBuffer

содержит тело ответа подзапроса, доступное только для чтения (начиная с версии 0.5.0). Размер r.responseBuffer ограничен директивой subrequest_output_buffer_size.

r.responseText

аналогично r.responseBuffer, но возвращает строку (начиная с версии 0.5.0). Обратите внимание, что байты, недопустимые в кодировке UTF-8, могут быть преобразованы в символ замены.

r.return(status[, string | Buffer])

отправляет клиенту весь ответ с указанным status. Ответ может быть строкой или Buffer (0.5.0).

Может вызываться из обработчика js_content или, начиная с версии 0.9.9, из обработчика js_access.

В качестве второго аргумента можно указать URL перенаправления (для кодов 301, 302, 303, 307 и 308) или текст тела ответа (для остальных кодов).

r.send(string | Buffer)

отправляет клиенту часть тела ответа. Отправляемые данные могут быть строкой или Buffer (0.5.0)

r.sendBuffer(data[, options])

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

Данные могут быть строкой или Buffer. options — объект, используемый для переопределения флагов буфера nginx, полученных из буфера входящего фрагмента данных. Можно переопределить следующие флаги:

last

логическое значение: true, если это последний буфер

flush

логическое значение: true, если буфер должен иметь флаг flush

Метод может вызываться только из функции js_body_filter.

r.sendHeader()

отправляет HTTP-заголовки клиенту

r.setReturnValue(value)

задаёт возвращаемое значение обработчика js_set (0.7.0). В отличие от обычного оператора return, этот метод следует использовать, если обработчик является асинхронной функцией JS. Например:

async function js_set(r) {
    const digest = await crypto.subtle.digest('SHA-256', r.headersIn.host);
    r.setReturnValue(digest);
}

r.status

статус, доступен для записи

r.subrequest(uri[, options[, callback]])

создаёт подзапрос с указанными uri и options, а также устанавливает необязательный обработчик завершения callback.

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

Если options является строкой, она содержит строку аргументов подзапроса. В противном случае options должен быть объектом со следующими ключами:

args

строка аргументов; по умолчанию используется пустая строка

body

тело запроса; по умолчанию используется тело запроса родительского объекта запроса

method

метод HTTP; по умолчанию используется метод GET

detached

логический флаг (0.3.9): если true, созданный подзапрос является отсоединённым. Ответы на отсоединённые подзапросы игнорируются. В отличие от обычных подзапросов, отсоединённый подзапрос можно создать внутри обработчика переменной. Флаг detached и аргумент обратного вызова нельзя использовать одновременно.

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

Начиная с версии 0.3.8, если callback не указан, возвращается объект Promise, который разрешается объектом ответа подзапроса.

Например, чтобы просмотреть все заголовки ответа в подзапросе:

async function handler(r) {
    const reply = await r.subrequest('/path');

    for (const h in reply.headersOut) {
        r.log(`${h}: ${reply.headersOut[h]}`);
    }

    r.return(200);
}

r.uri

текущий URI запроса, нормализованный, доступен только для чтения

r.rawVariables{}

переменные nginx в виде Buffer, доступны для записи (начиная с версии 0.5.0)

r.jsVarNames([prefix])

возвращает новый массив имён переменных nginx, объявленных директивой js_var (начиная с версии 0.9.9). Необязательный аргумент prefix должен быть строкой. Если он указан, возвращаются только имена, начинающиеся с этого префикса.

r.variables{}

объект переменных nginx, доступный для записи (начиная с версии 0.2.8).

Например, чтобы получить переменную $foo, можно использовать один из следующих вариантов синтаксиса:

r.variables['foo']
r.variables.foo

Начиная с версии 0.8.6, к захватам регулярного выражения можно обращаться с помощью следующего синтаксиса:

r.variables['1']
r.variables[1]

nginx по-разному обрабатывает переменные, на которые есть ссылки в nginx.conf, и переменные, на которые ссылок нет. При наличии ссылки значение переменной может кэшироваться, а при её отсутствии оно никогда не кэшируется. Например, если переменная $request_id используется только из njs, при каждом вычислении она получает новое значение. Но если на $request_id есть ссылка, например:

proxy_set_header X-Request-Id $request_id;

r.variables.request_id каждый раз возвращает одно и то же значение.

Переменная доступна для записи, если:

• она создана с помощью директивы js_var для http или stream (начиная с версии 0.5.3)
• на неё есть ссылка в файле конфигурации nginx

Тем не менее некоторым встроенным переменным по-прежнему нельзя присвоить значение (например, $http_).

r.warn(string)

записывает string в журнал ошибок с уровнем логирования warning

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

Сеанс Stream

Объект сеанса stream доступен только в модуле ngx_stream_js_module. До версии 0.8.5 все строковые свойства объекта были байтовыми строками.

s.allow()

псевдоним для s.done(0) (0.2.4)

s.decline()

псевдоним для s.done(-5) (0.2.4)

s.deny()

псевдоним для s.done(403) (0.2.4)

s.done([code])

задаёт код code для обработчика текущей фазы, по умолчанию — 0. Фактическое завершение происходит после выполнения обработчика js и обработки всех ожидающих событий, например, от ngx.fetch() или setTimeout() (0.2.4).

Возможные значения кода:

• 0 — успешное завершение, передача управления следующей фазе
• -5 — решение не принято, передача управления следующему обработчику текущей фазы (если он есть)
• 403 — доступ запрещён

Может вызываться только из функции-обработчика фазы: js_access или js_preread.

s.error(string)

записывает переданное string в журнал ошибок на уровне логирования error

Поскольку в nginx установлен жёстко заданный максимальный предел длины строки, в журнал можно записать только первые 2048 байт строки.

s.log(string)

записывает переданное string в журнал ошибок на уровне логирования info

Поскольку в nginx установлен жёстко заданный максимальный предел длины строки, в журнал можно записать только первые 2048 байт строки.

s.off(eventName)

отменяет регистрацию обратного вызова, заданного методом s.on() (0.2.4)

s.on(event, callback)

регистрирует callback для указанного event (0.2.4).

event может быть одной из следующих строк:

upload

новые данные (строка) от клиента

download

новые данные (строка) клиенту

upstream

новые данные (Buffer) от клиента (начиная с версии 0.5.0)

downstream

новые данные (Buffer) клиенту (начиная с версии 0.5.0)

Обратный вызов завершения имеет следующий прототип: callback(data, flags), где data — строка или Buffer (в зависимости от типа события), а flags — объект со следующими свойствами:

last

логическое значение: true, если это последний буфер данных.

s.remoteAddress

адрес клиента, только для чтения

s.rawVariables

переменные nginx в виде Buffer, доступны для записи (начиная с версии 0.5.0)

s.jsVarNames([prefix])

возвращает новый массив имён переменных nginx, объявленных директивой js_var (начиная с версии 0.9.9). Необязательный аргумент prefix должен быть строкой. Если он указан, возвращаются только имена, начинающиеся с заданного префикса.

s.send(data[, options])

добавляет данные в цепочку фрагментов данных, которые будут переданы в прямом направлении: в обратном вызове загрузки — клиенту, при отправке — вышестоящему серверу (0.2.4). Фактическая передача происходит позже, после обработки всех фрагментов данных текущей цепочки.

Данные могут быть строкой или Buffer (0.5.0). options — объект, используемый для переопределения флагов буфера nginx, унаследованных от буфера входящего фрагмента данных. Флаги можно переопределить следующими флагами:

last

логическое значение: true, если буфер является последним

flush

логическое значение: true, если для буфера должен быть установлен флаг flush

Метод можно вызывать несколько раз за один вызов обратного вызова.

s.sendDownstream()

идентичен s.send(), но всегда отправляет данные клиенту (начиная с версии 0.7.8).

s.sendUpstream()

идентичен s.send(), но всегда отправляет данные от клиента (начиная с версии 0.7.8).

s.status

код состояния сеанса, псевдоним переменной $status, только для чтения (начиная с версии 0.5.2)

s.setReturnValue(value)

задаёт возвращаемое значение обработчика js_set (0.7.0). В отличие от обычного оператора return, этот метод следует использовать, если обработчик является асинхронной функцией JS. Например:

async function js_set(r) {
    const digest = await crypto.subtle.digest('SHA-256', r.headersIn.host);
    r.setReturnValue(digest);
}

s.variables{}

объект переменных nginx, доступен для записи (начиная с версии 0.2.8). Переменная доступна для записи, только если на неё есть ссылка в файле конфигурации nginx. При этом некоторым встроенным переменным по-прежнему нельзя присвоить значение.

s.warn(string)

записывает переданное string в журнал ошибок на уровне логирования warning

Поскольку в nginx установлен жёстко заданный максимальный предел длины строки, в журнал можно записать только первые 2048 байт строки.

Периодический сеанс

Объект Periodic Session передаётся первым аргументом обработчику js_periodic для http и stream (начиная с версии 0.8.1).

PeriodicSession.rawVariables{}

переменные nginx в виде Buffer, доступны для записи.

PeriodicSession.variables{}

объект переменных nginx, доступен для записи.

Заголовки

Интерфейс Headers для Fetch API доступен начиная с версии 0.5.1.

Новый объект Headers можно создать с помощью конструктора Headers() (начиная с версии 0.7.10):

Headers([init])

init

Объект с HTTP-заголовками для предварительного заполнения объекта Headers; это может быть string, array пар «имя-значение» или существующий объект Headers.

Новый объект Headers можно создать со следующими свойствами и методами:

append()

Добавляет новое значение к существующему заголовку в объекте Headers или добавляет заголовок, если он ещё не существует (начиная с версии 0.7.10).

delete()

Удаляет заголовок из объекта Headers (начиная с версии 0.7.10).

get()

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

getAll(name)

Возвращает массив со значениями всех заголовков с указанным именем.

forEach()

Выполняет заданную функцию один раз для каждой пары «ключ-значение» в объекте Headers (начиная с версии 0.7.10).

has()

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

set()

Задаёт новое значение для существующего заголовка в объекте Headers или добавляет заголовок, если он ещё не существует (начиная с версии 0.7.10).

Запрос

Интерфейс Request для Fetch API доступен начиная с версии 0.7.10.

Новый объект Request можно создать с помощью конструктора Request():

Request[resource[, options]])

Создаёт объект Request для выполнения запроса, который позднее можно передать в ngx.fetch(). resource может быть URL или существующим объектом Request. options — необязательный аргумент, который должен быть объектом со следующими ключами:

body

Тело запроса; по умолчанию пустое.

headers

Объект заголовков ответа — объект с HTTP-заголовками для предварительного заполнения объекта Headers; это может быть string, array пар «имя-значение» или существующий объект Headers.

method

Метод HTTP; по умолчанию используется метод GET.

Новый объект Request можно создать со следующими свойствами и методами:

arrayBuffer()

Возвращает Promise, которое разрешается значением ArrayBuffer.

bodyUsed

Логическое значение: true, если тело было использовано в запросе.

cache

Содержит режим кэширования запроса.

credentials

Содержит учётные данные запроса; по умолчанию — same-origin.

headers

Связанный с Request объект Headers, доступный только для чтения.

json()

Возвращает Promise, которое разрешается результатом разбора тела запроса как JSON.

method

Содержит метод запроса.

mode

Содержит режим запроса.

text()

Возвращает Promise, которое разрешается строковым представлением тела запроса.

url

Содержит URL запроса.

Ответ

Интерфейс Response доступен начиная с версии 0.5.1.

Новый объект Response можно создать с помощью конструктора Response() (начиная с версии 0.7.10):

Response[body[, options]])

Создаёт объект Response. body — необязательный аргумент, который может быть string или buffer; по умолчанию — null. options — необязательный аргумент, который должен быть объектом со следующими ключами:

headers

Объект заголовков ответа — объект с HTTP-заголовками для предварительного заполнения объекта Headers; это может быть string, array пар «имя-значение» или существующий объект Headers.

status

Код состояния ответа.

statusText

Сообщение состояния, соответствующее коду состояния.

Новый объект Response() можно создать со следующими свойствами и методами:

arrayBuffer()

Читает поток Response до конца. Возвращает Promise, которое разрешается значением ArrayBuffer.

bodyUsed

Логическое значение: true, если тело было прочитано.

headers

Связанный с Response объект Headers, доступный только для чтения.

json()

Читает поток Response до конца. Возвращает Promise, которое разрешается результатом разбора текста тела как JSON.

ok

Логическое значение: true, если ответ успешен (коды состояния в диапазоне 200–299).

redirected

Логическое значение: true, если ответ получен в результате перенаправления.

status

Код состояния ответа.

statusText

Сообщение состояния, соответствующее коду состояния.

text()

Читает поток Response до конца. Возвращает Promise, которое разрешается строкой.

type

Тип ответа.

url

URL ответа.

ngx

Глобальный объект ngx доступен начиная с версии 0.5.0.

ngx.build

строка с необязательным именем сборки nginx, соответствует аргументу --build=name скрипта configure; по умолчанию — "" (0.8.0)

ngx.conf_file_path

строка с путём к текущему файлу конфигурации nginx (0.8.0)

ngx.conf_prefix

строка с путём к префиксу конфигурации nginx — каталогу, в котором nginx ищет файлы конфигурации (0.7.8)

ngx.error_log_path

строка с путём к текущему файлу журнала ошибок (0.8.0)

ngx.fetch(resource, [options])

Выполняет запрос для получения resource (0.5.1), которым может быть URL или объект Request (0.7.10). Возвращает Promise, которое разрешается объектом Response. Начиная с версии 0.7.0 поддерживается схема https://; перенаправления не обрабатываются.

Если в resource указан URL с доменным именем, имя определяется с помощью резолвера. Если указана схема https://, для аутентификации HTTPS-сервера resource необходимо настроить директиву js_fetch_trusted_certificate.

Параметр options должен быть объектом со следующими ключами:

body

тело запроса; по умолчанию пустое

buffer_size

размер буфера для чтения ответа; по умолчанию — 4096

headers

объект заголовков запроса

max_response_body_size

максимальный размер тела ответа в байтах; по умолчанию — 32768

method

метод HTTP; по умолчанию используется метод GET

verify

включает или отключает проверку сертификата HTTPS-сервера; по умолчанию — true (0.7.0)

Пример:

let reply = await ngx.fetch('http://nginx.org/');
let body = await reply.text();

r.return(200, body);

ngx.log(level, message)

записывает сообщение в журнал ошибок с указанным уровнем логирования. Параметр level задаёт один из уровней логирования, параметр message может быть строкой или Buffer. Можно указать следующие уровни логирования: ngx.INFO, ngx.WARN и ngx.ERR.

Поскольку в nginx установлен жёстко заданный максимальный предел длины строки, в журнал можно записать только первые 2048 байт строки.

ngx.prefix

строка с путём к префиксу nginx — каталогу, в котором хранятся файлы сервера (0.8.0)

ngx.version

строка с версией nginx, например: 1.25.0 (0.8.0)

ngx.version_number

число, содержащее версию nginx, например: 1025000 (0.8.0)

ngx.worker_id

число, соответствующее внутреннему идентификатору рабочего процесса nginx; значение находится в диапазоне от 0 до значения, указанного в директиве worker_processes (0.8.0)

ngx.shared

Глобальный объект ngx.shared доступен начиная с версии 0.8.0.

SharedDict

Общий словарь доступен начиная с версии 0.8.0. Имя, тип и размер общего словаря задаются директивой js_shared_dict_zone в контексте http или stream.

Объект SharedDict() имеет следующие свойства и методы:

ngx.shared.SharedDict.add(key, value [,timeout])

Устанавливает value для указанного key в словаре, только если ключ ещё не существует. key — это строка, представляющая ключ добавляемого элемента, а value — значение добавляемого элемента.

Необязательный аргумент timeout задаётся в миллисекундах и переопределяет параметр timeout директивы js_shared_dict_zone в http или stream (начиная с 0.8.5). Это может быть полезно, если для некоторых ключей ожидаются уникальные тайм-ауты.

Возвращает true, если значение успешно добавлено в словарь SharedDict, и false, если ключ уже существует в словаре. Выбрасывает SharedMemoryError, если в словаре SharedDict недостаточно свободного места. Выбрасывает TypeError, если value имеет тип, отличный от ожидаемого этим словарём.

ngx.shared.SharedDict.capacity

Возвращает ёмкость словаря SharedDict, соответствующую параметру size директивы js_shared_dict_zone в http или stream.

ngx.shared.SharedDict.clear()

Удаляет все элементы из словаря SharedDict.

ngx.shared.SharedDict.delete(key)

Удаляет элемент, связанный с указанным ключом, из словаря SharedDict; возвращает true, если элемент существовал в словаре и был удалён, и false в противном случае.

ngx.shared.SharedDict.freeSpace()

Возвращает размер свободных страниц в байтах. Если размер равен нулю, словарь SharedDict всё равно будет принимать новые значения, если на занятых страницах есть свободное место.

ngx.shared.SharedDict.get(key)

Получает элемент по его key, возвращает значение, связанное с key, или undefined, если такого значения нет.

ngx.shared.SharedDict.has(key)

Выполняет поиск элемента по его key, возвращает true, если такой элемент существует, и false в противном случае.

ngx.shared.SharedDict.incr(key,delta[[,init], timeout]))

Увеличивает целочисленное значение, связанное с key, на delta. key — это строка, а delta — число, на которое нужно увеличить или уменьшить значение. Если ключ не существует, элемент будет инициализирован необязательным аргументом init; по умолчанию используется 0.

Необязательный аргумент timeout задаётся в миллисекундах и переопределяет параметр timeout директивы js_shared_dict_zone в http или stream (начиная с 0.8.5). Если аргумент timeout не указан, существующий TTL записи сохраняется (начиная с 0.9.7). До версии 0.9.7 отсутствие timeout сбрасывало время истечения срока действия записи на значение по умолчанию, заданное директивой.

Возвращает новое значение. Выбрасывает SharedMemoryError, если в словаре SharedDict недостаточно свободного места. Выбрасывает TypeError, если этот словарь не ожидает числовых значений.

Этот метод можно использовать, только если тип словаря объявлен с параметром type=number директивы js_shared_dict_zone в http или stream.

ngx.shared.SharedDict.items([maxCount])

Возвращает массив пар «ключ — значение» словаря SharedDict (начиная с 0.8.1). Параметр maxCount задаёт максимальное количество получаемых элементов; по умолчанию используется 1024.

ngx.shared.SharedDict.keys([maxCount])

Возвращает массив ключей словаря SharedDict. Параметр maxCount задаёт максимальное количество получаемых ключей; по умолчанию используется 1024.

ngx.shared.SharedDict.name

Возвращает имя словаря SharedDict, соответствующее параметру zone= директивы js_shared_dict_zone в http или stream.

ngx.shared.SharedDict.pop(key)

Удаляет из словаря SharedDict элемент, связанный с указанным key, и возвращает значение, связанное с key, или undefined, если такого значения нет.

ngx.shared.SharedDict.replace(key, value)

Заменяет value для указанного key, только если ключ уже существует; возвращает true, если значение успешно заменено, и false, если ключ не существует в словаре SharedDict. Выбрасывает SharedMemoryError, если в словаре SharedDict недостаточно свободного места. Выбрасывает TypeError, если value имеет тип, отличный от ожидаемого этим словарём.

ngx.shared.SharedDict.set(key, value [,timeout])

Устанавливает value для указанного key и возвращает этот словарь SharedDict (для цепочки вызовов методов).

Необязательный аргумент timeout задаётся в миллисекундах и переопределяет параметр timeout директивы js_shared_dict_zone в http или stream (начиная с 0.8.5). Это может быть полезно, если для некоторых ключей ожидаются уникальные тайм-ауты.

ngx.shared.SharedDict.size()

Возвращает количество элементов в словаре SharedDict.

ngx.shared.SharedDict.ttl(key)

Возвращает оставшееся время жизни в миллисекундах для указанного key или undefined, если ключ не существует или срок его действия истёк (начиная с 0.9.7).

Выбрасывает TypeError, если словарь объявлен без параметра timeout директивы js_shared_dict_zone в http или stream.

ngx.shared.SharedDict.type

Возвращает string или number, соответствующий типу словаря SharedDict, заданному параметром type= директивы js_shared_dict_zone в http или stream.

встроенные объекты

console

Объект console доступен в nginx начиная с 0.8.2, а в CLI — начиная с 0.2.6.

console.error(msg[, msg2 ...])

Выводит одно или несколько сообщений об ошибках. Сообщение может быть строкой или объектом.

console.info(msg[, msg2 ...])

Выводит одно или несколько информационных сообщений. Сообщение может быть строкой или объектом.

console.log(msg[, msg2 ...])

Выводит одно или несколько сообщений журнала. Сообщение может быть строкой или объектом.

console.time(label)

Запускает таймер, который позволяет измерить продолжительность операции. Параметр label позволяет задавать имена для разных таймеров. Если вызвать console.timeEnd() с тем же именем, будет выведено время, прошедшее с момента запуска таймера, в миллисекундах.

console.timeEnd(label)

Останавливает таймер, ранее запущенный с помощью console.time(). Параметр label позволяет задавать имена для разных таймеров.

console.warn(msg[, msg2 ...])

Выводит одно или несколько предупреждений. Сообщение может быть строкой или объектом.

crypto

Объект crypto — это глобальный объект, предоставляющий доступ к криптографическим функциям (начиная с 0.7.0). Начиная с 0.9.7 поддерживается полная спецификация Web Crypto API.

сrypto.getRandomValues(typedArray)

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

typedArray

может быть Int8Array, Int16Array, Uint16Array, Int32Array или Uint32Array

сrypto.randomUUID()

Возвращает случайно сгенерированную строку UUID версии 4 длиной 36 символов, например "36b8f84d-df4e-4d49-b662-bcde71a8764f" (начиная с 0.9.7).

сrypto.subtle.encrypt(algorithm, key, data)

Шифрует data с использованием предоставленных algorithm и key. Возвращает Promise, который выполняется с результатом ArrayBuffer, содержащим шифротекст. Возможные значения:

algorithm

объект, задающий используемый алгоритм и любые дополнительные параметры, если они требуются:

• для RSA-OAEP передайте объект со следующими ключами:
  • name — строка, значение которой должно быть RSA-OAEP:

    crypto.subtle.encrypt({name: "RSA-OAEP"}, key, data)
    

• для AES-CTR передайте объект со следующими ключами:
  • name — строка, значение которой должно быть AES-CTR
  • counter — ArrayBuffer, TypedArray или DataView — начальное значение блока счетчика, длина которого должна составлять 16 байт (размер блока AES). Для счетчика используются крайние правые биты этого блока в количестве, заданном параметром length, а остальные биты используются для nonce. Например, если length задано равным 64, первая половина счетчика является nonce, а вторая используется для счетчика
  • length — количество битов блока счетчика, используемых непосредственно для счетчика. Размер счетчика должен быть достаточным, чтобы не произошло его переполнение.
• для AES-CBC передайте объект со следующими ключами:
  • name — строка, значение которой должно быть AES-CBC
  • iv, или вектор инициализации, — это ArrayBuffer, TypedArray или DataView длиной 16 байт; он должен быть непредсказуемым и, предпочтительно, криптографически случайным. Однако его не нужно хранить в секрете; например, его можно передавать вместе с шифротекстом в незашифрованном виде.
• для AES-GCM передайте объект со следующими ключами:
  • name — строка, значение которой должно быть AES-GCM
  • iv, или вектор инициализации, — это ArrayBuffer, TypedArray или DataView длиной 16 байт; он должен быть уникальным для каждой операции шифрования, выполняемой с данным ключом
  • additionalData (необязательный параметр) — это ArrayBuffer, TypedArray или DataView, содержащий дополнительные данные, которые не будут зашифрованы, но будут аутентифицированы вместе с зашифрованными данными. Если задан additionalData, те же данные необходимо указать в соответствующем вызове decrypt(): если данные, переданные в вызове decrypt(), не совпадут с исходными данными, при расшифровании будет выброшено исключение. Длина additionalData в битах должна быть меньше 2^64 - 1.
  • tagLength (необязательный параметр, значение по умолчанию — 128) — number, определяющий размер в битах тега аутентификации, создаваемого при шифровании и используемого для аутентификации при соответствующем расшифровании. Возможные значения: 32, 64, 96, 104, 112, 120 или 128. Спецификация AES-GCM рекомендует использовать 96, 104, 112, 120 или 128, хотя в некоторых приложениях могут быть допустимы 32 или 64 битов.

key

объект CryptoKey, содержащий ключ для шифрования

data

ArrayBuffer, TypedArray или DataView, содержащий данные для шифрования (также известные как открытый текст)

сrypto.subtle.decrypt(algorithm, key, data)

Расшифровывает зашифрованные данные. Возвращает Promise с расшифрованными данными. Возможные значения:

algorithm

объект, задающий используемый алгоритм и любые необходимые дополнительные параметры. Значения дополнительных параметров должны совпадать со значениями, переданными в соответствующем вызове encrypt().

• для RSA-OAEP передайте объект со следующими ключами:
  • name — строка, значение которой должно быть RSA-OAEP:

    crypto.subtle.encrypt({name: "RSA-OAEP"}, key, data)
    

• для AES-CTR передайте объект со следующими ключами:
  • name — строка, значение которой должно быть AES-CTR
  • counter — ArrayBuffer, TypedArray или DataView — начальное значение блока счетчика, длина которого должна составлять 16 байт (размер блока AES). Для счетчика используются крайние правые биты этого блока в количестве, заданном параметром length, а остальные биты используются для nonce. Например, если length задано равным 64, первая половина счетчика является nonce, а вторая используется для счетчика.
  • length — количество битов блока счетчика, используемых непосредственно для счетчика. Размер счетчика должен быть достаточным, чтобы не произошло его переполнение.
• для AES-CBC передайте объект со следующими ключами:
  • name — строка, значение которой должно быть AES-CBC
  • iv, или вектор инициализации, — это ArrayBuffer, TypedArray или DataView длиной 16 байт; он должен быть непредсказуемым и, предпочтительно, криптографически случайным. Однако его не нужно хранить в секрете (например, его можно передавать вместе с шифротекстом в незашифрованном виде).
• для AES-GCM передайте объект со следующими ключами:
  • name — строка, значение которой должно быть AES-GCM
  • iv, или вектор инициализации, — это ArrayBuffer, TypedArray или DataView длиной 16 байт; он должен быть уникальным для каждой операции шифрования, выполняемой с данным ключом
  • additionalData (необязательный параметр) — это ArrayBuffer, TypedArray или DataView, содержащий дополнительные данные, которые не будут зашифрованы, но будут аутентифицированы вместе с зашифрованными данными. Если задан additionalData, те же данные необходимо указать в соответствующем вызове decrypt(): если данные, переданные в вызове decrypt(), не совпадут с исходными данными, при расшифровании будет выброшено исключение. Длина additionalData в битах должна быть меньше 2^64 - 1.
  • tagLength (необязательный параметр, значение по умолчанию — 128) — number, определяющий размер в битах тега аутентификации, создаваемого при шифровании и используемого для аутентификации при соответствующем расшифровании. Возможные значения: 32, 64, 96, 104, 112, 120 или 128. Спецификация AES-GCM рекомендует использовать 96, 104, 112, 120 или 128, хотя в некоторых приложениях могут быть допустимы 32 или 64 битов.

key

объект CryptoKey, содержащий ключ для расшифрования. Если используется RSA-OAEP, это свойство privateKey объекта CryptoKeyPair.

data

ArrayBuffer, TypedArray или DataView, содержащий данные для расшифрования (также известные как шифротекст)

сrypto.subtle.deriveBits(algorithm, baseKey, length)

Получает массив битов на основе базового ключа. Возвращает Promise, который будет выполнен с результатом ArrayBuffer, содержащим полученные биты. Возможные значения:

algorithm

объект, определяющий используемый алгоритм получения ключа:

• для HKDF передайте объект со следующими ключами:
  • name — строка, значение которой должно быть HKDF
  • hash — строка с используемым алгоритмом хеширования: SHA-1, SHA-256, SHA-384 или SHA-512
  • salt — ArrayBuffer, TypedArray или DataView, представляющий случайное или псевдослучайное значение длиной, равной выходным данным функции digest. В отличие от исходного ключевого материала, переданного в deriveKey(), соль не требуется хранить в секрете.
  • info — ArrayBuffer, TypedArray или DataView, представляющий контекстную информацию, специфичную для приложения, которая связывает полученный ключ с приложением или контекстом и позволяет получать разные ключи для разных контекстов, используя один и тот же исходный ключевой материал. Это свойство является обязательным, но буфер может быть пустым.
• для PBKDF2 передайте объект со следующими ключами:
  • name — строка, значение которой должно быть PBKDF2
  • hash — строка с используемым алгоритмом хеширования: SHA-1, SHA-256, SHA-384 или SHA-512
  • salt — ArrayBuffer, TypedArray или DataView, представляющий случайное или псевдослучайное значение длиной не менее 16 байт. В отличие от исходного ключевого материала, переданного в deriveKey(), соль не требуется хранить в секрете.
  • iterations — number, представляющий количество выполнений хеш-функции в deriveKey()
• для ECDH передайте объект со следующими ключами (начиная с 0.9.1):
  • name — строка, значение которой должно быть ECDH
  • public — CryptoKey, представляющий открытый ключ другой стороны. Ключ должен быть сгенерирован с использованием той же эллиптической кривой, что и базовый ключ.
• для X25519 передайте объект со следующими ключами (начиная с 0.9.7):
  • name — строка, значение которой должно быть X25519
  • public — CryptoKey, представляющий открытый ключ другой стороны

baseKey

CryptoKey, представляющий входные данные алгоритма получения ключа — исходный ключевой материал для функции получения ключа: например, для PBKDF2 это может быть пароль, импортированный как CryptoKey с помощью сrypto.subtle.importKey()

length

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

сrypto.subtle.deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)

Получает секретный ключ из главного ключа. Возможные значения:

algorithm

объект, определяющий используемый алгоритм получения ключа:

• для HKDF передайте объект со следующими ключами:
  • name — строка, значение которой должно быть HKDF
  • hash — строка с используемым алгоритмом хеширования: SHA-1, SHA-256, SHA-384 или SHA-512
  • salt — ArrayBuffer, TypedArray или DataView, представляющий случайное или псевдослучайное значение длиной, равной выходным данным функции digest. В отличие от исходного ключевого материала, переданного в deriveKey(), соль не требуется хранить в секрете.
  • info — ArrayBuffer, TypedArray или DataView, представляющий контекстную информацию, специфичную для приложения, которая связывает полученный ключ с приложением или контекстом и позволяет получать разные ключи для разных контекстов, используя один и тот же исходный ключевой материал. Это свойство является обязательным, но буфер может быть пустым.
• для PBKDF2 передайте объект со следующими ключами:
  • name — строка, значение которой должно быть PBKDF2
  • hash — строка с используемым алгоритмом хеширования: SHA-1, SHA-256, SHA-384 или SHA-512
  • salt — ArrayBuffer, TypedArray или DataView, представляющий случайное или псевдослучайное значение длиной не менее 16 байт. В отличие от исходного ключевого материала, переданного в deriveKey(), соль не требуется хранить в секрете.
  • iterations — number, представляющий количество выполнений хеш-функции в deriveKey()
• для ECDH передайте объект со следующими ключами (начиная с 0.9.1):
  • name — строка, значение которой должно быть ECDH
  • public — CryptoKey, представляющий открытый ключ другой стороны. Ключ должен быть сгенерирован с использованием той же эллиптической кривой, что и базовый ключ.
• для X25519 передайте объект со следующими ключами (начиная с 0.9.7):
  • name — строка, значение которой должно быть X25519
  • public — CryptoKey, представляющий открытый ключ другой стороны

baseKey

CryptoKey, представляющий входные данные алгоритма получения ключа — исходный ключевой материал для функции получения ключа: например, для PBKDF2 это может быть пароль, импортированный как CryptoKey с помощью сrypto.subtle.importKey().

derivedKeyAlgorithm

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

• для HMAC передайте объект со следующими ключами:
  • name — строка, значение которой должно быть HMAC
  • hash — строка с названием используемой функции хеширования: SHA-1, SHA-256, SHA-384 или SHA-512
  • length (необязательный параметр) — number, задающий длину ключа в битах. Если параметр не задан, длина ключа равна размеру блока выбранной хеш-функции
• для AES-CTR, AES-CBC, AES-GCM или AES-KW (начиная с 0.9.7) передайте объект со следующими ключами:
  • name — строка, значение которой должно быть AES-CTR, AES-CBC, AES-GCM или AES-KW, в зависимости от используемого алгоритма
  • length — number, задающий длину генерируемого ключа в битах: 128, 192 или 256

extractable

логическое значение, указывающее, можно ли экспортировать ключ

keyUsages

Array, указывающий, какие операции можно выполнять с полученным ключом. Использование ключа должно допускаться алгоритмом, заданным в derivedKeyAlgorithm. Возможные значения:

encrypt

ключ для шифрования сообщений

decrypt

ключ для расшифрования сообщений

sign

ключ для подписания сообщений

verify

ключ для проверки подписей

deriveKey

ключ для получения нового ключа

deriveBits

ключ для получения битов

wrapKey

ключ для обертывания ключа

unwrapKey

ключ для развертывания ключа

сrypto.subtle.digest(algorithm, data)

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

algorithm

строка, задающая используемую хеш-функцию: SHA-1 (не для криптографических приложений), SHA-256, SHA-384 или SHA-512

data

ArrayBuffer, TypedArray или DataView, содержащий данные для обработки

сrypto.subtle.exportKey(format, key)

Экспортирует ключ: принимает ключ в виде объекта CryptoKey и возвращает его во внешнем переносимом формате (начиная с 0.7.10). Если format имел значение jwk, то Promise выполняется с объектом JSON, содержащим ключ. В противном случае promise выполняется с ArrayBuffer, содержащим ключ. Возможные значения:

format

строка, описывающая формат данных для экспорта ключа; возможны следующие значения:

raw

формат необработанных данных

pkcs8

формат PKCS #8

spki

формат SubjectPublicKeyInfo

jwk

формат JSON Web Key (JWK) (начиная с 0.7.10)

key

CryptoKey, содержащий экспортируемый ключ

сrypto.subtle.generateKey(algorithm, extractable, usage)

Генерирует новый ключ для симметричных алгоритмов или пару ключей для алгоритмов с открытым ключом (начиная с 0.7.10). Возвращает Promise, который выполняется с сгенерированным ключом в виде объекта CryptoKey или CryptoKeyPair. Возможные значения:

algorithm

объект-словарь, определяющий тип генерируемого ключа и дополнительные параметры, специфичные для алгоритма:

• для RSASSA-PKCS1-v1_5, RSA-PSS или RSA-OAEP передайте объект со следующими ключами:
  • name — строка, значение которой должно быть RSASSA-PKCS1-v1_5, RSA-PSS или RSA-OAEP, в зависимости от используемого алгоритма
  • hash — строка, содержащая название используемой функции digest; возможные значения: SHA-256, SHA-384 или SHA-512
• для ECDSA передайте объект со следующими ключами:
  • name — строка, значение которой должно быть ECDSA
  • namedCurve — строка, содержащая название используемой эллиптической кривой; возможные значения: P-256, P-384 или P-521
• для HMAC передайте объект со следующими ключами:
  • name — строка, значение которой должно быть HMAC
  • hash — строка, содержащая название используемой функции digest; возможные значения: SHA-256, SHA-384 или SHA-512
  • length (необязательный параметр) — число, задающее длину ключа в битах. Если параметр не указан, длина ключа равна длине дайджеста, полученного выбранной функцией хеширования.
• для AES-CTR, AES-CBC, AES-GCM или AES-KW (начиная с 0.9.7) передайте строку с идентификатором алгоритма или объект вида { "name": "ALGORITHM" }, где ALGORITHM — название алгоритма
• для ECDH передайте объект со следующими ключами (начиная с 0.9.1):
  • name — строка, значение которой должно быть ECDH
  • namedCurve — строка, содержащая название используемой эллиптической кривой; возможные значения: P-256, P-384 или P-521
• для Ed25519 передайте строку Ed25519 или объект вида { "name": "Ed25519" } (начиная с 0.9.7)
• для X25519 передайте строку X25519 или объект вида { "name": "X25519" } (начиная с 0.9.7)

extractable

логическое значение, указывающее, можно ли экспортировать ключ

usage

array, указывающий возможные операции с ключом:

encrypt

ключ для шифрования сообщений

decrypt

ключ для расшифрования сообщений

sign

ключ для подписания сообщений

verify

ключ для проверки подписей

deriveKey

ключ для получения нового ключа

deriveBits

ключ для получения битов

wrapKey

ключ для обертывания ключа

unwrapKey

ключ для развертывания ключа

сrypto.subtle.importKey(format, keyData, algorithm, extractable, keyUsages)

Импортирует ключ: принимает ключ во внешнем переносимом формате и возвращает объект CryptoKey. Возвращает Promise, который выполняется с импортированным ключом в виде объекта CryptoKey. Возможные значения:

format

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

raw

формат необработанных данных

pkcs8

формат PKCS #8

spki

формат SubjectPublicKeyInfo

jwk

формат JSON Web Key (JWK) (начиная с 0.7.10)

keyData

объект ArrayBuffer, TypedArray или DataView, содержащий ключ в указанном формате

algorithm

объект-словарь, определяющий тип импортируемого ключа и предоставляющий дополнительные параметры, специфичные для алгоритма:

• для RSASSA-PKCS1-v1_5, RSA-PSS или RSA-OAEP передайте объект со следующими ключами:
  • name — строка; должно быть задано значение RSASSA-PKCS1-v1_5, RSA-PSS или RSA-OAEP в зависимости от используемого алгоритма
  • hash — строка, задающая имя используемой функции digest. Возможные значения: SHA-1, SHA-256, SHA-384 или SHA-512
• для ECDSA передайте объект со следующими ключами:
  • name — строка; должно быть задано значение ECDSA
  • namedCurve — строка, задающая имя используемой эллиптической кривой. Возможные значения: P-256, P-384 или P-521
• для HMAC передайте объект со следующими ключами:
  • name — строка; должно быть задано значение HMAC
  • hash — строка, задающая имя используемой функции digest. Возможные значения: SHA-256, SHA-384 или SHA-512
  • length (необязательный параметр) — число, задающее длину ключа в битах. Если параметр не указан, длина ключа равна длине дайджеста, созданного выбранной функцией дайджеста.
• для AES-CTR, AES-CBC, AES-GCM или AES-KW (начиная с 0.9.7) передайте строку с идентификатором алгоритма или объект вида { "name": "ALGORITHM" }, где ALGORITHM — имя алгоритма
• для PBKDF2 передайте строку PBKDF2
• для HKDF передайте строку HKDF
• для ECDH передайте объект со следующими ключами (начиная с 0.9.1):
  • name — строка; должно быть задано значение ECDH
  • namedCurve — строка, задающая имя используемой эллиптической кривой. Возможные значения: P-256, P-384 или P-521
• для Ed25519 передайте строку Ed25519 или объект вида { "name": "Ed25519" } (начиная с 0.9.7)
• для X25519 передайте строку X25519 или объект вида { "name": "X25519" } (начиная с 0.9.7)

extractable

логическое значение, указывающее, можно ли экспортировать ключ

keyUsages

объект array, указывающий возможные действия с ключом:

encrypt

ключ для шифрования сообщений

decrypt

ключ для расшифровки сообщений

sign

ключ для подписания сообщений

verify

ключ для проверки подписей

deriveKey

ключ для получения нового ключа

deriveBits

ключ для получения битов

wrapKey

ключ для обёртывания ключа

unwrapKey

ключ для развёртывания ключа

сrypto.subtle.sign(algorithm, key, data)

Возвращает signature в виде Promise, который выполняется с объектом ArrayBuffer, содержащим подпись. Возможные значения:

algorithm

строка или объект, задающий используемый алгоритм подписи и его параметры:

• для RSASSA-PKCS1-v1_5 передайте строку с идентификатором алгоритма или объект вида { "name": "ALGORITHM" }
• для RSA-PSS передайте объект со следующими ключами:
  • name — строка; должно быть задано значение RSA-PSS
  • saltLength — длинное значение integer, задающее длину используемой случайной соли в байтах
• для ECDSA передайте объект со следующими ключами:
  • name — строка; должно быть задано значение ECDSA
  • hash — идентификатор используемого алгоритма дайджеста. Возможные значения: SHA-256, SHA-384 или SHA-512
• для HMAC передайте строку с идентификатором алгоритма или объект вида { "name": "ALGORITHM" }
• для Ed25519 передайте строку Ed25519 или объект вида { "name": "Ed25519" } (начиная с 0.9.7)

key

объект CryptoKey — ключ, используемый для подписания. Если алгоритм обозначает криптосистему с открытым ключом, это закрытый ключ.

data

объект ArrayBuffer, TypedArray или DataView, содержащий данные для подписания

сrypto.subtle.verify(algorithm, key, signature, data)

Проверяет цифровую подпись и возвращает Promise, который выполняется с логическим значением: true, если подпись действительна, иначе false. Возможные значения:

algorithm

строка или объект, задающий используемый алгоритм и его параметры:

• для RSASSA-PKCS1-v1_5 передайте строку с идентификатором алгоритма или объект вида { "name": "ALGORITHM" }
• для RSA-PSS передайте объект со следующими ключами:
  • name — строка; должно быть задано значение RSA-PSS
  • saltLength — длинное значение integer, задающее длину используемой случайной соли в байтах
• для ECDSA передайте объект со следующими ключами:
  • name — строка; должно быть задано значение ECDSA
  • hash — идентификатор используемого алгоритма дайджеста. Возможные значения: SHA-256, SHA-384 или SHA-512
• для HMAC передайте строку с идентификатором алгоритма или объект вида { "name": "ALGORITHM" }
• для Ed25519 передайте строку Ed25519 или объект вида { "name": "Ed25519" } (начиная с 0.9.7)

key

объект CryptoKey — ключ, используемый для проверки. Для симметричного алгоритма это секретный ключ, а для системы с открытым ключом — открытый ключ.

signature

объект ArrayBuffer, TypedArray или DataView, содержащий проверяемую подпись

data

объект ArrayBuffer, TypedArray или DataView, содержащий данные, подпись которых требуется проверить

сrypto.subtle.wrapKey(format, key, wrappingKey, wrapAlgorithm)

Обёртывает ключ: экспортирует ключ во внешний переносимый формат, а затем шифрует экспортированный ключ (начиная с 0.9.7). Возвращает Promise, который выполняется с объектом ArrayBuffer, содержащим зашифрованный экспортированный ключ. Возможные значения:

format

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

raw

формат необработанных данных

pkcs8

формат PKCS #8

spki

формат SubjectPublicKeyInfo

jwk

формат JSON Web Key (JWK)

key

объект CryptoKey, содержащий оборачиваемый ключ. Для ключа должно быть установлено значение true свойства CryptoKey.extractable.

wrappingKey

объект CryptoKey, содержащий ключ, используемый для шифрования экспортированного ключа. Для ключа должно быть задано назначение wrapKey.

wrapAlgorithm

объект, задающий алгоритм шифрования экспортированного ключа и любые необходимые дополнительные параметры:

• для AES-CBC, AES-CTR или AES-GCM передайте соответствующие параметры алгоритма, как описано в сrypto.subtle.encrypt()
• для AES-KW передайте строку AES-KW или объект вида { "name": "AES-KW" }
• для RSA-OAEP передайте соответствующие параметры алгоритма, как описано в сrypto.subtle.encrypt()

сrypto.subtle.unwrapKey(format, wrappedKey, unwrappingKey, unwrapAlgorithm, unwrappedKeyAlgorithm, extractable, keyUsages)

Разворачивает ключ: расшифровывает обёрнутый ключ и создаёт объект CryptoKey на основе результата (начиная с 0.9.7). Возвращает Promise, который выполняется с развёрнутым ключом в виде объекта CryptoKey. Возможные значения:

format

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

raw

формат необработанных данных

pkcs8

формат PKCS #8

spki

формат SubjectPublicKeyInfo

jwk

формат JSON Web Key (JWK)

wrappedKey

объект ArrayBuffer, TypedArray или DataView, содержащий обёрнутый ключ в указанном формате

unwrappingKey

объект CryptoKey, содержащий ключ, используемый для расшифровки обёрнутого ключа. Для ключа должно быть задано назначение unwrapKey.

unwrapAlgorithm

объект, задающий алгоритм расшифровки обёрнутого ключа и любые необходимые дополнительные параметры:

• для AES-CBC, AES-CTR или AES-GCM передайте соответствующие параметры алгоритма, как описано в сrypto.subtle.encrypt()
• для AES-KW передайте строку AES-KW или объект вида { "name": "AES-KW" }
• для RSA-OAEP передайте соответствующие параметры алгоритма, как описано в сrypto.subtle.encrypt()

unwrappedKeyAlgorithm

объект-словарь, определяющий тип разворачиваемого ключа и предоставляющий дополнительные параметры, специфичные для алгоритма. Применяются те же описания алгоритмов, что и в сrypto.subtle.importKey().

extractable

логическое значение, указывающее, можно ли экспортировать ключ

keyUsages

объект array, указывающий возможные действия с ключом:

encrypt

ключ для шифрования сообщений

decrypt

ключ для расшифровки сообщений

sign

ключ для подписания сообщений

verify

ключ для проверки подписей

deriveKey

ключ для получения нового ключа

deriveBits

ключ для получения битов

wrapKey

ключ для обёртывания ключа

unwrapKey

ключ для развёртывания ключа

CryptoKey

Объект CryptoKey представляет собой криптографический key, полученный одним из методов SubtleCrypto: сrypto.subtle.generateKey(), сrypto.subtle.deriveKey(), сrypto.subtle.importKey().

CryptoKey.algorithm

возвращает объект с описанием алгоритма, для которого можно использовать этот ключ, и любых связанных с ним дополнительных параметров (начиная с 0.8.0); только для чтения

CryptoKey.extractable

логическое значение: true, если ключ можно экспортировать (начиная с 0.8.0); только для чтения

CryptoKey.type

строковое значение, указывающее тип ключа, представленного объектом; только для чтения. Возможные значения:

secret

Этот ключ является секретным ключом для симметричного алгоритма.

private

Этот ключ является закрытой частью CryptoKeyPair асимметричного алгоритма

public

Этот ключ является открытой частью CryptoKeyPair асимметричного алгоритма.

CryptoKey.usages

Массив строк, указывающих, для чего можно использовать этот ключ (начиная с 0.8.0); только для чтения. Возможные значения массива:

encrypt

ключ для шифрования сообщений

decrypt

ключ для расшифровки сообщений

sign

ключ для подписания сообщений

verify

ключ для проверки подписей

deriveKey

ключ для получения нового ключа

deriveBits

ключ для получения битов

CryptoKeyPair

CryptoKeyPair — объект-словарь WebCrypto API, представляющий пару асимметричных ключей.

CryptoKeyPair.privateKey

Объект CryptoKey, представляющий закрытый ключ.

CryptoKeyPair.publicKey

Объект CryptoKey, представляющий открытый ключ.

njs

Объект njs является глобальным объектом, представляющим текущий экземпляр виртуальной машины (начиная с 0.2.0).

njs.version

Возвращает строку с текущей версией njs (например, «0.7.4»).

njs.version_number

Возвращает число, соответствующее текущей версии njs. Например, версия «0.7.4» возвращается как 0x000704 (начиная с 0.7.4).

njs.dump(value)

Возвращает строковое представление значения с форматированием для удобного чтения.

njs.memoryStats

Объект, содержащий статистику памяти для текущего экземпляра виртуальной машины (начиная с 0.7.8).

size

объём памяти в байтах, выделенной пулу памяти njs операционной системой.

njs.on(event, callback)

Регистрирует функцию обратного вызова для указанного события виртуальной машины (начиная с 0.5.2). Событие задаётся одной из следующих строк:

exit

вызывается перед уничтожением виртуальной машины. Функция обратного вызова вызывается без аргументов.

process

Объект process — глобальный объект, предоставляющий информацию о текущем процессе (0.3.3).

process.argv

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

process.env

Возвращает объект, содержащий пользовательское окружение.

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

process.kill(pid, number | string)

Отправляет сигнал процессу, идентифицируемому по pid. Имена сигналов задаются числами или строками, например 'SIGINT' или 'SIGHUP'. Дополнительные сведения см. в kill(2).

process.pid

Возвращает PID текущего процесса.

process.ppid

Возвращает PID текущего родительского процесса.

String

По умолчанию все строки в njs являются строками Unicode. Они соответствуют строкам ECMAScript, содержащим символы Unicode. До версии 0.8.0 также поддерживались байтовые строки.

Байтовые строки

Начиная с версии 0.8.0, поддержка байтовых строк и методов байтовых строк удалена. При работе с последовательностями байтов следует использовать объект Buffer и свойства Buffer, такие как r.requestBuffer и r.rawVariables.

Байтовые строки содержат последовательность байтов и используются для сериализации строк Unicode во внешние данные и десериализации данных из внешних источников. Например, метод toUTF8() сериализует строку Unicode в байтовую строку с использованием кодировки UTF-8:

>> '£'.toUTF8().toString('hex')
'c2a3'  /* C2 A3 is the UTF-8 representation of 00A3 ('£') code point */

Метод toBytes() сериализует строку Unicode с кодовыми точками не выше 255 в байтовую строку; в противном случае возвращается null:

>> '£'.toBytes().toString('hex')
'a3'  /* a3 is a byte equal to 00A3 ('£') code point  */

String.bytesFrom(array | string, encoding)

Метод устарел в версии 0.4.4 и был удалён в версии 0.8.0. Вместо него следует использовать метод Buffer.from:

>> Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]).toString()
'buffer'

>> Buffer.from('YnVmZmVy', 'base64').toString()
'buffer'

До версии 0.4.4 создавал байтовую строку из массива октетов или из строки в кодировке (0.2.3); в качестве кодировки можно было указать hex, base64 и base64url.

String.prototype.fromBytes(start[, end])

Свойство устарело в версии 0.7.7 и было удалено в версии 0.8.0. До версии 0.7.7 возвращало новую строку Unicode, полученную из байтовой строки, в которой каждый байт заменялся соответствующей кодовой точкой Unicode.

String.prototype.fromUTF8(start[, end])

Свойство устарело в версии 0.7.7 и было удалено в версии 0.8.0. Вместо него следует использовать метод TextDecoder. До версии 0.7.7 преобразовывало байтовую строку с корректной строкой UTF-8 в строку Unicode; в противном случае возвращалось null.

String.prototype.toBytes(start[, end])

Свойство устарело в версии 0.7.7 и было удалено в версии 0.8.0. До версии 0.7.7 сериализовало строку Unicode в байтовую строку и возвращало null, если в строке обнаруживался символ с кодом больше 255.

String.prototype.toString(encoding)

Свойство устарело в версии 0.7.7 и было удалено в версии 0.8.0. До версии 0.7.7 кодировало строку в hex, base64 или base64url:

>>  'αβγδ'.toString('base64url')
'zrHOss6zzrQ'

До версии 0.4.3 можно было кодировать только байтовую строку:

>>  'αβγδ'.toUTF8().toString('base64url')
'zrHOss6zzrQ'

String.prototype.toUTF8(start[, end])

Свойство устарело в версии 0.7.7 и было удалено в версии 0.8.0. Вместо него следует использовать метод TextEncoder. До версии 0.7.7 сериализовало строку Unicode в байтовую строку с использованием кодировки UTF-8:

>> 'αβγδ'.toUTF8().length
8
>> 'αβγδ'.length
4

Веб-API

Декодер текста

TextDecoder преобразует поток байтов в поток кодовых точек (0.4.3).

TextDecoder([[encoding], options])

Создаёт новый объект TextDecoder для указанной encoding; в настоящее время поддерживается только UTF-8. options — это словарь TextDecoderOptions со свойством:

fatal

логический флаг, указывающий, должен ли TextDecoder.decode() генерировать исключение TypeError при обнаружении ошибки кодирования; по умолчанию — false.

TextDecoder.prototype.encoding

Возвращает строку с названием кодировки, используемой объектом TextDecoder(); только для чтения.

TextDecoder.prototype.fatal

Логический флаг: true, если режим обработки ошибок является критическим; только для чтения.

TextDecoder.prototype.ignoreBOM

Логический флаг: true, если маркер порядка байтов игнорируется; только для чтения.

TextDecoder.prototype.decode(buffer, [options])

Возвращает строку с текстом, декодированным из buffer объектом TextDecoder(). Буфер может быть ArrayBuffer. options — это словарь TextDecodeOptions со свойством:

stream

логический флаг, указывающий, будут ли дополнительные данные переданы в последующих вызовах decode(): true при обработке данных по частям и false для последней части или если данные не разделены на части. По умолчанию — false.

>> (new TextDecoder()).decode(new Uint8Array([206,177,206,178]))
αβ

Кодировщик текста

Объект TextEncoder преобразует поток кодовых точек в поток байтов в кодировке UTF-8 (0.4.3).

TextEncoder()

Возвращает новый объект TextEncoder, который будет создавать поток байтов в кодировке UTF-8.

TextEncoder.prototype.encode(string)

Кодирует string в Uint8Array с текстом в кодировке UTF-8.

TextEncoder.prototype.encodeInto(string, uint8Array)

Кодирует string в UTF-8, помещает результат в целевой объект Uint8Array и возвращает объект-словарь, отображающий ход кодирования. Объект-словарь содержит два элемента:

read

количество кодовых единиц UTF-16 исходного string, преобразованных в UTF-8

written

количество байтов, изменённых в целевом объекте Uint8Array

таймеры

clearTimeout(timeout)

Отменяет объект timeout, созданный с помощью setTimeout().

setTimeout(function, milliseconds[, argument1, argumentN])

Вызывает function по истечении указанного количества milliseconds. Указанной функции можно передать один или несколько необязательных arguments. Возвращает объект timeout.

function handler(v)
{
    // ...
}

t = setTimeout(handler, 12);

// ...

clearTimeout(t);

Глобальные функции

atob(encodedData)

Декодирует строку данных, закодированную с помощью кодировки Base64. Параметр encodedData — это двоичная строка, содержащая данные, закодированные в Base64. Возвращает строку, содержащую данные, декодированные из encodedData.

Аналогичный метод btoa() можно использовать для кодирования и передачи данных, которые иначе могут вызвать проблемы при обмене, а затем для декодирования данных с помощью метода atob(). Например, можно кодировать, передавать и декодировать управляющие символы, такие как символы ASCII со значениями от 0 до 31.

const encodedData = btoa("text to encode"); // encode a string
const decodedData = atob(encodedData); // decode the string

btoa(stringToEncode)

Создаёт строку ASCII в кодировке Base64 из двоичной строки. Параметр stringToEncode — это двоичная строка для кодирования. Возвращает строку ASCII, содержащую представление stringToEncode в Base64.

Метод можно использовать для кодирования данных, которые иначе могут вызвать проблемы при обмене, передать их, а затем декодировать с помощью метода atob(). Например, можно кодировать управляющие символы, такие как символы ASCII со значениями от 0 до 31.

const encodedData = btoa("text to encode"); // encode a string
const decodedData = atob(encodedData); // decode the string

встроенные модули

Buffer

Buffer.alloc(size[, fill[, encoding]]))

Выделяет новый Buffer заданного размера size. Если fill не указан, Buffer будет заполнен нулями. Если указан fill, выделенный Buffer будет инициализирован вызовом buf.fill(fill). Если указаны fill и encoding, выделенный Buffer будет инициализирован вызовом buf.fill(fill, encoding).

Параметр fill может быть типа string, Buffer, Uint8Array или integer.

Buffer.allocUnsafe(size)

Работает так же, как Buffer.alloc(), но выделенная для буфера память не инициализируется; содержимое нового буфера неизвестно и может включать конфиденциальные данные.

Buffer.byteLength(value[, encoding])

Возвращает длину указанного значения в байтах при кодировании с помощью encoding. Значение может быть типа string, Buffer, TypedArray, DataView или ArrayBuffer. Если значение имеет тип string, параметр encoding задаёт его кодировку и может принимать значения utf8, hex, base64, base64url; по умолчанию используется utf8.

Buffer.compare(buffer1, buffer2)

Сравнивает buffer1 с buffer2 при сортировке массивов экземпляров Buffer. Возвращает 0, если buffer1 совпадает с buffer2, 1, если buffer2 должно предшествовать buffer1 при сортировке, или -1, если buffer2 должно следовать за buffer1 при сортировке.

Buffer.concat(list[, totalLength])

Возвращает новый Buffer, полученный путём объединения всех экземпляров Buffer в списке. Если список пуст или его общая длина равна 0, возвращается новый Buffer нулевой длины. Если totalLength не указан, его значение вычисляется путём сложения длин экземпляров Buffer в списке. Если totalLength указан, его значение преобразуется в беззнаковое целое число. Если общая длина буферов в списке превышает totalLength, результат усекается до totalLength.

Buffer.from(array)

Выделяет новый Buffer, используя массив байтов в диапазоне 0 – 255. Элементы массива за пределами этого диапазона усекаются.

Buffer.from(arrayBuffer, byteOffset[, length]])

Создаёт представление ArrayBuffer без копирования базовой памяти. Необязательные аргументы byteOffset и length задают диапазон памяти внутри arrayBuffer, который будет использоваться совместно с Buffer.

Buffer.from(buffer)

Копирует переданные данные буфера в новый экземпляр Buffer.

Buffer.from(object[, offsetOrEncoding[, length]])

Для объектов, функция valueOf() которых возвращает значение, не строго равное самому объекту, возвращает Buffer.from(object.valueOf(), offsetOrEncoding, length).

Buffer.from(string[, encoding])

Создаёт новый Buffer с string. Параметр encoding задаёт кодировку символов, используемую при преобразовании строки в байты. Кодировка может быть utf8, hex, base64, base64url; по умолчанию используется utf8.

Buffer.isBuffer(object)

Логическое значение: возвращает true, если object является Buffer.

Buffer.isEncoding(encoding)

Логическое значение: возвращает true, если кодировка является именем поддерживаемой кодировки символов.

buffer[index]

Оператор индексирования, с помощью которого можно получить и задать октет в позиции index в buffer. Значения соответствуют отдельным байтам, поэтому допустимый диапазон значений составляет от 0 до 255 (десятичная система).

buf.buffer

Базовый объект ArrayBuffer, на основе которого создан этот объект Buffer.

buf.byteOffset

Целое число, задающее byteOffset объекта ArrayBuffer, лежащего в основе буферов.

buf.compare(target[, targetStart[, targetEnd[, sourceStart[, sourceEnd]]]])

Сравнивает буфер с target и возвращает число, указывающее, предшествует ли буфер target, следует за ним или совпадает с ним в порядке сортировки. Сравнение выполняется на основе фактической последовательности байтов каждого Buffer. Параметр targetStart — целое число, задающее смещение внутри target, с которого начинается сравнение; по умолчанию равно 0. Параметр targetEnd — целое число, задающее смещение внутри target, на котором заканчивается сравнение; по умолчанию равно target.length. Параметр sourceStart — целое число, задающее смещение внутри буфера, с которого начинается сравнение; по умолчанию равно 0. Параметр sourceEnd — целое число, задающее смещение внутри буфера, на котором заканчивается сравнение (не включая этот байт); по умолчанию равно buf.length.

buf.copy(target[, targetStart[, sourceStart[, sourceEnd]]])

Копирует данные из области буфера в область target, даже если целевая область памяти перекрывается с буфером. Параметр target — это объект типа Buffer или Uint8Array, в который выполняется копирование.

Параметр targetStart — целое число, задающее смещение в целевом объекте, с которого начинается запись; по умолчанию равно 0. Параметр sourceStart — целое число, задающее смещение в буфере, с которого начинается копирование; по умолчанию равно 0. Параметр sourceEnd — целое число, задающее смещение в буфере, на котором заканчивается копирование (не включая этот байт); по умолчанию равно buf.length.

buf.equals(otherBuffer)

Логическое значение: возвращает true, если Buffer и otherBuffer содержат в точности одинаковые байты.

buf.fill(value[, offset[, end]][, encoding])

Заполняет Buffer указанным значением value. Если offset и end не указаны, заполняется весь Buffer. Параметр value преобразуется в uint32, если он не является значением типа string, Buffer или integer. Если полученное целое число больше 255, Buffer заполняется значением value и 255.

buf.includes(value[, byteOffset][, encoding])

Эквивалентно buf.indexOf() !== -1; возвращает true, если value найдено в Buffer.

buf.indexOf(value[, byteOffset][, encoding])

Возвращает целое число — индекс первого вхождения value в Buffer или -1, если Buffer не содержит это значение. Параметр value может быть строкой типа string с указанным encoding (по умолчанию utf8), значением типа Buffer, Unit8Array или числом от 0 до 255.

buf.lastIndexOf(value[, byteOffset][, encoding])

Работает так же, как buf.indexOf(), но находит последнее вхождение value, а не первое. Параметр value может быть строкой, Buffer или целым числом от 1 до 255. Если value — пустая строка или пустой Buffer, возвращается byteOffset.

buf.length

Возвращает количество байтов в Buffer.

buf.readIntBE(offset, byteLength)

Считывает byteLength из buf по указанному offset и интерпретирует результат как знаковое число в дополнительном коде с порядком байтов от старшего к младшему, поддерживающее точность до 48 бит. Параметр byteLength — целое число от 1 до 6, задающее количество считываемых байтов.

Также поддерживаются аналогичные методы: buf.readInt8([offset]), buf.readInt16BE([offset]), buf.readInt32BE([offset]).

buf.readIntLE(offset, byteLength)

Считывает byteLength из buf по указанному offset и интерпретирует результат как знаковое число в дополнительном коде с порядком байтов от младшего к старшему, поддерживающее точность до 48 бит. Параметр byteLength — целое число от 1 до 6, задающее количество считываемых байтов.

Также поддерживаются аналогичные методы: buf.readInt8([offset]), buf.readInt16LE([offset]), buf.readInt32LE([offset]).

buf.readUIntBE(offset, byteLength)

Считывает byteLength из buf по указанному offset и интерпретирует результат как целое число с порядком байтов от старшего к младшему, поддерживающее точность до 48 бит. Параметр byteLength — целое число от 1 до 6, задающее количество считываемых байтов.

Также поддерживаются аналогичные методы: buf.readUInt8([offset]), buf.readUInt16BE([offset]), buf.readUInt32BE([offset]).

buf.readUIntLE(offset, byteLength)

Считывает byteLength из buf по указанному offset и интерпретирует результат как целое число с порядком байтов от младшего к старшему, поддерживающее точность до 48 бит. Параметр byteLength — целое число от 1 до 6, задающее количество считываемых байтов.

Также поддерживаются аналогичные методы: buf.readUInt8([offset]), buf.readUInt16LE([offset]), buf.readUInt32LE([offset]).

buf.readDoubleBE([offset])

Считывает 64-битное число с плавающей точкой двойной точности с порядком байтов от старшего к младшему из buf по указанному offset.

buf.readDoubleLE([offset])

Считывает 64-битное число с плавающей точкой двойной точности с порядком байтов от младшего к старшему из buf по указанному offset.

buf.readFloatBE([offset])

Считывает 32-битное число с плавающей точкой с порядком байтов от старшего к младшему из buf по указанному offset.

buf.readFloatLE([offset])

Считывает 32-битное число с плавающей точкой с порядком байтов от младшего к старшему из buf по указанному offset.

buf.subarray([start[, end]])

Возвращает новый buf, ссылающийся на ту же область памяти, что и исходный, но со смещением и обрезанный по значениям start и end. Если end больше, чем buf.length, возвращается тот же результат, что и при значении end, равном buf.length.

buf.slice([start[, end]])

Возвращает новый buf, ссылающийся на ту же область памяти, что и исходный, но со смещением и обрезанный по значениям start и end. Метод несовместим с Uint8Array.prototype.slice(), суперклассом Buffer. Чтобы скопировать срез, используйте Uint8Array.prototype.slice().

buf.swap16()

Интерпретирует buf как массив беззнаковых 16-битных чисел и меняет порядок байтов на месте. Вызывает ошибку, если buf.length не кратно 2.

buf.swap32()

Интерпретирует buf как массив беззнаковых 32-битных чисел и меняет порядок байтов на месте. Вызывает ошибку, если buf.length не кратно 4.

buf.swap64()

Интерпретирует buf как массив 64-битных чисел и меняет порядок байтов на месте. Вызывает ошибку, если buf.length не кратно 8.

buf.toJSON()

Возвращает представление buf. в формате JSON. JSON.stringify() неявно вызывает эту функцию при преобразовании экземпляра Buffer в строку.

buf.toString([encoding[, start[, end]]])

Декодирует buf в строку согласно указанной кодировке символов encoding, которая может быть utf8, hex, base64, base64url. Параметры start и end можно передать, чтобы декодировать только часть Buffer.

buf.write(string[, offset[, length]][, encoding])

Записывает string в buf по смещению offset согласно кодировке символов encoding. Параметр length задаёт количество записываемых байтов. Если в Buffer недостаточно места для всей строки, будет записана только её часть; частично закодированные символы при этом записаны не будут. Параметр encoding может принимать значения utf8, hex, base64, base64url.

buf.writeIntBE(value, offset, byteLength)

Записывает byteLength байтов значения value в buf по указанному offset, используя порядок байтов от старшего к младшему. Поддерживает точность до 48 бит. Параметр byteLength — целое число от 1 до 6, задающее количество считываемых байтов.

Также поддерживаются следующие аналогичные методы: buf.writeInt8, buf.writeInt16BE, buf.writeInt32BE.

buf.writeIntLE(value, offset, byteLength)

Записывает byteLength байтов значения value в buf по указанному offset, используя порядок байтов от младшего к старшему. Поддерживает точность до 48 бит. Параметр byteLength — целое число от 1 до 6, задающее количество считываемых байтов.

Также поддерживаются следующие аналогичные методы: buf.writeInt8, buf.writeInt16LE, buf.writeInt32LE.

buf.writeUIntBE(value, offset, byteLength)

Записывает byteLength байтов значения value в buf по указанному offset, используя порядок байтов от старшего к младшему. Поддерживает точность до 48 бит. Параметр byteLength — целое число от 1 до 6, задающее количество считываемых байтов.

Также поддерживаются следующие аналогичные методы: buf.writeUInt8, buf.writeUInt16BE, buf.writeUInt32BE.

buf.writeUIntLE(value, offset, byteLength)

Записывает byteLength байтов значения value в buf по указанному offset, используя порядок байтов от младшего к старшему. Поддерживает точность до 48 бит. Параметр byteLength — целое число от 1 до 6, задающее количество считываемых байтов.

Также поддерживаются следующие аналогичные методы: buf.writeUInt8, buf.writeUInt16LE, buf.writeUInt32LE.

buf.writeDoubleBE(value, [offset])

Записывает value в buf по указанному offset, используя порядок байтов от старшего к младшему.

buf.writeDoubleLE(value, [offset])

Записывает value в buf по указанному offset, используя порядок байтов от младшего к старшему.

buf.writeFloatBE(value, [offset])

Записывает value в buf по указанному offset, используя порядок байтов от старшего к младшему.

buf.writeFloatLE(value, [offset])

Записывает value в buf по указанному offset, используя порядок байтов от младшего к старшему.

Криптография

Начиная с версии 0.7.0, расширенный API криптографии доступен через глобальный объект crypto.

Модуль Crypto предоставляет поддержку криптографических функций. Объект модуля Crypto импортируется с помощью import crypto from 'crypto'.

Начиная с версии 0.9.7, для работы модуля Crypto требуется OpenSSL; для хеширования используется OpenSSL EVP, благодаря чему JavaScript-коду доступны все алгоритмы дайджестов, поддерживаемые подключённой библиотекой OpenSSL.

crypto.createHash(algorithm)

Создаёт и возвращает объект Hash, который можно использовать для формирования хеш-дайджестов с помощью указанного algorithm. Алгоритмом может быть md5, sha1, sha256, sha384, sha512 или любой другой алгоритм дайджеста, поддерживаемый подключённой библиотекой OpenSSL (начиная с версии 0.9.7). До версии 0.9.7 поддерживались только md5, sha1 и sha256.

crypto.createHmac(algorithm, secret key)

Создаёт и возвращает объект HMAC, использующий указанные algorithm и secret key. Алгоритмом может быть md5, sha1, sha256, sha384, sha512 или любой другой алгоритм дайджеста, поддерживаемый подключённой библиотекой OpenSSL (начиная с версии 0.9.7). До версии 0.9.7 поддерживались только md5, sha1 и sha256.

Hash

hash.update(data)

Дополняет содержимое хеша указанным data.

hash.digest([encoding])

Вычисляет дайджест всех данных, переданных с помощью hash.update(). Кодировкой может быть hex, base64 или base64url. Если кодировка не указана, возвращается объект Buffer (0.4.4).

До версии (0.4.4) вместо объекта Buffer возвращалась байтовая строка.

hash.copy()

Создаёт копию текущего состояния хеша (начиная с версии 0.7.12).

import crypto from 'crypto';

crypto.createHash('sha1').update('A').update('B').digest('base64url');
/* BtlFlCqiamG-GMPiK_GbvKjdK10 */

HMAC

hmac.update(data)

Дополняет содержимое HMAC указанным data.

hmac.digest([encoding])

Вычисляет дайджест HMAC всех данных, переданных с помощью hmac.update(). Кодировкой может быть hex, base64 или base64url. Если кодировка не указана, возвращается объект Buffer (0.4.4).

До версии 0.4.4 вместо объекта Buffer возвращалась байтовая строка.

import crypto from 'crypto';

crypto.createHmac('sha1', 'secret.key').update('AB').digest('base64url');
/* Oglm93xn23_MkiaEq_e9u8zk374 */

Файловая система

Модуль File System предоставляет операции для работы с файлами.

Объект модуля импортируется с помощью import fs from 'fs'. Начиная с версии 0.3.9, асинхронные версии методов файловой системы доступны через объект fs.promises после импорта с помощью import fs from 'fs':

import fs from 'fs';

fs.promises.readFile("/file/path").then((data) => {
    /* <file data> */
});

accessSync(path[, mode])

Синхронно проверяет разрешения для файла или каталога, указанного в path (0.3.9). Если проверка завершается неудачно, возвращается ошибка, в противном случае метод возвращает undefined.

mode

необязательное целое число, указывающее проверки доступности, которые необходимо выполнить; по умолчанию — fs.constants.F_OK

try {
    fs.accessSync('/file/path', fs.constants.R_OK | fs.constants.W_OK);
    console.log('has access');
} catch (e) {
    console.log('no access');)
}

appendFileSync(filename, data[, options])

Синхронно добавляет указанные data в файл с заданным filename. Ожидается, что data будет строкой или объектом Buffer (0.4.4). Если файл не существует, он будет создан. Параметр options должен быть объектом со следующими ключами:

mode

параметр режима; по умолчанию — 0o666

flag

флаг файловой системы; по умолчанию — a

closeSync(fd)

Закрывает файловый дескриптор fd, представленный целым числом, который используется методом. Возвращает undefined.

existsSync(path)

Логическое значение: возвращает true, если указанный path существует. (0.8.2)

fstatSync(fd)

Получает объект fs.Stats для файлового дескриптора (0.7.7). Параметр fd — целое число, представляющее используемый методом файловый дескриптор.

lstatSync(path[, options])

Синхронно получает объект fs.Stats для символической ссылки, на которую указывает path (0.7.1). Параметр options должен быть объектом со следующими ключами:

throwIfNoEntry

логическое значение, указывающее, следует ли выбрасывать исключение, если запись файловой системы не существует, вместо возврата undefined; по умолчанию — false.

mkdirSync(path[, options])

Синхронно создает каталог по указанному path (0.4.2). Параметр options должен быть integer, задающим режим, либо объектом со следующими ключами:

mode

параметр режима; по умолчанию — 0o777.

openSync(path[, flags[, mode]])

Возвращает целое число, представляющее файловый дескриптор открытого файла path (0.7.7).

flags

флаг файловой системы; по умолчанию — r

mode

параметр режима; по умолчанию — 0o666

promises.open(path[, flags[, mode]])

Возвращает объект FileHandle, представляющий открытый файл path (0.7.7).

flags

флаг файловой системы; по умолчанию — r

mode

параметр режима; по умолчанию — 0o666

readdirSync(path[, options])

Синхронно считывает содержимое каталога по указанному path (0.4.2). Параметр options должен быть строкой, задающей кодировку, либо объектом со следующими ключами:

encoding

кодировка; по умолчанию — utf8. В качестве кодировки можно указать utf8 и buffer (0.4.4).

withFileTypes

если задано значение true, массив файлов будет содержать объекты fs.Dirent; по умолчанию — false.

readFileSync(filename[, options])

Синхронно возвращает содержимое файла с заданным filename. Параметр options содержит string, задающий кодировку. Если кодировка указана, возвращается строка, в противном случае возвращается объект Buffer (0.4.4).

До версии 0.4.4, если кодировка не была указана, возвращалась байтовая строка.

В противном случае options должен быть объектом со следующими ключами:

encoding

кодировка; по умолчанию не указана. В качестве кодировки можно указать utf8, hex (0.4.4), base64 (0.4.4), base64url (0.4.4).

flag

флаг файловой системы; по умолчанию — r

import fs from 'fs';

var file = fs.readFileSync('/file/path.tar.gz');
console.log(file.slice(0,2).toString('hex')) /* '1f8b' */

readlinkSync(path[, options])

Синхронно получает содержимое символической ссылки path с помощью readlink(2) (0.8.7). Аргумент options может быть строкой, задающей кодировку, или объектом со свойством encoding, задающим используемую кодировку символов. Если encoding — buffer, результат возвращается как объект Buffer, в противном случае — как строка.

readSync(fd, buffer, offset[, length[, position]])

Считывает содержимое файла с помощью файлового дескриптора fd и возвращает количество прочитанных байтов (0.7.7).

buffer

значением buffer может быть Buffer, TypedArray или DataView

offset

integer, представляющее позицию в буфере, с которой следует записать данные

length

integer, представляющее количество байтов для чтения

position

задает начальную позицию чтения в файле; значение может быть integer или null; по умолчанию — null. Если position имеет значение null, данные считываются с текущей позиции файла, и позиция файла обновляется. Если позиция является integer, позиция файла не изменяется

realpathSync(path[, options])

Синхронно вычисляет каноническое имя пути, разрешая ., .. и символические ссылки с помощью realpath(3). Аргумент options может быть строкой, задающей кодировку, или объектом со свойством encoding, задающим кодировку символов для пути, передаваемого обратному вызову (0.3.9).

renameSync(oldPath, newPath)

Синхронно переименовывает файл или перемещает его из oldPath в newPath (0.3.4).

import fs from 'fs';

fs.renameSync('hello.txt', 'HelloWorld.txt');

rmdirSync(path)

Синхронно удаляет каталог по указанному path (0.4.2).

statSync(path,[ options])

Синхронно получает объект fs.Stats для указанного path (0.7.1). path может быть string или buffer. Параметр options должен быть объектом со следующими ключами:

throwIfNoEntry

логическое значение, указывающее, следует ли выбрасывать исключение, если запись файловой системы не существует, вместо возврата undefined; по умолчанию — true.

symlinkSync(target, path)

Синхронно создает ссылку с именем path, указывающую на target, с помощью symlink(2) (0.3.9). Относительные целевые пути отсчитываются от родительского каталога ссылки.

unlinkSync(path)

Синхронно удаляет ссылку на файл по path (0.3.9).

writeFileSync(filename, data[, options])

Синхронно записывает data в файл с заданным filename. Ожидается, что data будет строкой или объектом Buffer (0.4.4). Если файл не существует, он будет создан; если файл существует, он будет заменен. Параметр options должен быть объектом со следующими ключами:

mode

параметр режима; по умолчанию — 0o666

flag

флаг файловой системы; по умолчанию — w

import fs from 'fs';

fs.writeFileSync('hello.txt', 'Hello world');

writeSync(fd, buffer, offset[, length[, position]])

Записывает буфер в файл с помощью файлового дескриптора и возвращает количество записанных байтов number (0.7.7).

fd

integer, представляющее файловый дескриптор

buffer

значением buffer может быть Buffer, TypedArray или DataView

offset

integer, определяющее часть буфера для записи; по умолчанию — 0

length

integer, задающее количество байтов для записи; по умолчанию — смещение, равное Buffer.byteLength

position

задает смещение от начала файла, по которому следует записать эти данные; может быть integer или null; по умолчанию — null. См. также pwrite(2).

writeSync(fd, string[, position[, encoding]])

Записывает string в файл с помощью файлового дескриптора fd и возвращает количество записанных байтов number (0.7.7).

fd

integer, представляющее файловый дескриптор

position

задает смещение от начала файла, по которому следует записать эти данные; может быть integer или null; по умолчанию — null. См. также pwrite(2)

encoding

это string; по умолчанию — utf8

fs.Dirent

fs.Dirent представляет собой запись каталога — файл или подкаталог. Если readdirSync() вызывается с параметром withFileTypes, результирующий массив содержит объекты fs.Dirent.

• dirent.isBlockDevice() — возвращает true, если объект fs.Dirent описывает блочное устройство.
• dirent.isCharacterDevice() — возвращает true, если объект fs.Dirent описывает символьное устройство.
• dirent.isDirectory() — возвращает true, если объект fs.Dirent описывает каталог файловой системы.
• dirent.isFIFO() — возвращает true, если объект fs.Dirent описывает канал FIFO (первым пришел — первым вышел).
• dirent.isFile() — возвращает true, если объект fs.Dirent описывает обычный файл.
• dirent.isSocket() — возвращает true, если объект fs.Dirent описывает сокет.
• dirent.isSymbolicLink() — возвращает true, если объект fs.Dirent описывает символическую ссылку.
• dirent.name — имя файла, на который ссылается объект fs.Dirent.

fs.FileHandle

Объект FileHandle является оболочкой для числового файлового дескриптора (0.7.7). Экземпляры объекта FileHandle создаются методом fs.promises.open(). Если FileHandle не закрыт с помощью метода filehandle.close(), он попытается автоматически закрыть файловый дескриптор, помогая предотвратить утечки памяти. Не полагайтесь на такое поведение, поскольку оно может быть ненадежным. Вместо этого всегда явно закрывайте FileHandle.

filehandle.close()

Закрывает файловый дескриптор после завершения всех ожидающих операций с ним. Возвращает promise, который при успешном выполнении разрешается значением undefined.

filehandle.fd

Числовой файловый дескриптор, которым управляет объект FileHandle.

filehandle.read(buffer, offset[, length[, position]])

Считывает данные из файла и сохраняет их в указанном буфере.

buffer

буфер, который будет заполнен считанными данными из файла; значением может быть Buffer, TypedArray или DataView

offset

integer, задающее позицию в буфере, с которой начинается заполнение

length

integer, задающее количество байтов для чтения

position

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

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

bytesRead

integer, представляющее количество прочитанных байтов

buffer

ссылка на переданный аргумент буфера; может быть Buffer, TypedArray или DataView

filehandle.stat()

Возвращает promise, который разрешается объектом fs.Stats для файла.

filehandle.write(buffer, offset[, length[, position]])

Записывает буфер в файл.

buffer

значением buffer может быть Buffer, TypedArray или DataView

offset

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

length

integer, задающее количество записываемых байтов из буфера; по умолчанию — смещение, равное Buffer.byteLength

position

смещение от начала файла, по которому следует записать данные из буфера; может быть integer или null; по умолчанию — null. Если position не является number, данные записываются в текущую позицию. Подробности см. в документации POSIX по pwrite(2).

Возвращает Promise, который разрешается объектом с двумя свойствами:

bytesWritten

integer, представляющее количество записанных байтов

buffer

ссылка на записанный буфер; это может быть Buffer, TypedArray или DataView

Небезопасно использовать filehandle.write() несколько раз для одного файла, не дождавшись выполнения или отклонения промиса.

filehandle.write(string[, position[, encoding]])

Записывает string в файл.

position

смещение от начала файла, по которому следует записать данные из буфера; может быть integer или null; по умолчанию — null. Если position не является number, данные записываются в текущую позицию. Подробности см. в документации POSIX по pwrite(2).

encoding

ожидаемая кодировка строки; по умолчанию — utf8

Возвращает Promise, который разрешается объектом с двумя свойствами:

bytesWritten

integer, представляющее количество записанных байтов

buffer

ссылка на записанный буфер; это может быть Buffer, TypedArray или DataView

Небезопасно использовать filehandle.write() несколько раз для одного файла, не дождавшись выполнения или отклонения промиса.

fs.Stats

Объект fs.Stats предоставляет сведения о файле. Этот объект возвращается методами fs.statSync() и fs.lstatSync().

• stats.isBlockDevice() — возвращает true, если объект fs.Stats описывает блочное устройство.
• stats.isDirectory() — возвращает true, если объект fs.Stats описывает каталог файловой системы.
• stats.isFIFO() — возвращает true, если объект fs.Stats описывает канал FIFO (первым пришел — первым вышел).
• stats.isFile() — возвращает true, если объект fs.Stats описывает обычный файл.
• stats.isSocket() — возвращает true, если объект fs.Stats описывает сокет.
• stats.isSymbolicLink() — возвращает true, если объект fs.Stats описывает символическую ссылку.
• stats.dev — числовой идентификатор устройства, содержащего файл.
• stats.ino — специфичный для файловой системы номер Inode файла.
• stats.mode — битовое поле, описывающее тип файла и режим доступа.
• stats.nlink — количество жестких ссылок на файл.
• stats.uid — числовой идентификатор пользователя, владеющего файлом (POSIX).
• stats.gid — числовой идентификатор группы, владеющей файлом (POSIX).
• stats.rdev — числовой идентификатор устройства, если файл представляет устройство.
• stats.size — размер файла в байтах.
• stats.blksize — размер блока файловой системы для операций ввода-вывода.
• stats.blocks — количество блоков, выделенных для этого файла.
• stats.atimeMs — временная метка последнего обращения к файлу, выраженная в миллисекундах с начала эпохи POSIX.
• stats.mtimeMs — временная метка последнего изменения файла, выраженная в миллисекундах с начала эпохи POSIX.
• stats.ctimeMs — временная метка последнего изменения метаданных файла, выраженная в миллисекундах с начала эпохи POSIX.
• stats.birthtimeMs — временная метка создания файла, выраженная в миллисекундах с начала эпохи POSIX.
• stats.atime — временная метка последнего обращения к файлу.
• stats.mtime — временная метка последнего изменения файла.
• stats.ctime — временная метка последнего изменения метаданных файла.
• stats.birthtime — временная метка создания файла.

Константы доступа к файлам

Метод access() может принимать следующие флаги. Эти флаги экспортируются объектом fs.constants:

• F_OK — указывает, что файл виден вызывающему процессу; используется по умолчанию, если режим не задан
• R_OK — указывает, что вызывающий процесс может читать файл
• W_OK — указывает, что вызывающий процесс может записывать в файл
• X_OK — указывает, что вызывающий процесс может выполнять файл

Флаги файловой системы

Параметр flag может принимать следующие значения:

• a — открыть файл для добавления данных. Если файл не существует, он будет создан
• ax — то же, что и a, но вызовет ошибку, если файл уже существует
• a+ — открыть файл для чтения и добавления данных. Если файл не существует, он будет создан
• ax+ — то же, что и a+, но вызовет ошибку, если файл уже существует
• as — открыть файл для добавления данных в синхронном режиме. Если файл не существует, он будет создан
• as+ — открыть файл для чтения и добавления данных в синхронном режиме. Если файл не существует, он будет создан
• r — открыть файл для чтения. Если файл не существует, возникнет исключение
• r+ — открыть файл для чтения и записи. Если файл не существует, возникнет исключение
• rs+ — открыть файл для чтения и записи в синхронном режиме. Указывает операционной системе обходить локальный кэш файловой системы
• w — открыть файл для записи. Если файл не существует, он будет создан. Если файл существует, он будет заменен
• wx — то же, что и w, но вызовет ошибку, если файл уже существует
• w+ — открыть файл для чтения и записи. Если файл не существует, он будет создан. Если файл существует, он будет заменен
• wx+ — то же, что и w+, но вызовет ошибку, если файл уже существует

Строка запроса

Модуль Query String обеспечивает поддержку разбора и форматирования строк запроса URL (0.4.3). Объект модуля Query String импортируется с помощью import qs from 'querystring'.

querystring.decode()

является псевдонимом querystring.parse().

querystring.encode()

является псевдонимом querystring.stringify().

querystring.escape(string)

Выполняет URL-кодирование заданного string и возвращает экранированную строку запроса. Метод используется методом querystring.stringify() и не должен вызываться напрямую.

querystring.parse(string[, separator[, equal[, options]]])

Разбирает строку запроса URL и возвращает объект.

Параметр separator — подстрока-разделитель пар ключ-значение в строке запроса; по умолчанию — «&».

Параметр equal — подстрока-разделитель ключей и значений в строке запроса; по умолчанию — «=».

Параметр options должен быть объектом со следующими ключами:

decodeURIComponent function

Функция, используемая для декодирования символов, закодированных в формате percent-encoding в строке запроса; по умолчанию — querystring.unescape()

maxKeys number

максимальное количество ключей для разбора; по умолчанию — 1000. Значение 0 снимает ограничение на количество ключей.

По умолчанию предполагается, что символы строки запроса, закодированные в формате percent-encoding, используют кодировку UTF-8; недопустимые последовательности UTF-8 заменяются символом замены U+FFFD.

Например, для следующей строки запроса

'foo=bar&abc=xyz&abc=123'

результат будет следующим:

{
  foo: 'bar',
  abc: ['xyz', '123']
}

querystring.stringify(object[, separator[, equal[, options]]])

Сериализует объект и возвращает строку запроса URL.

Параметр separator — подстрока-разделитель пар ключ-значение в строке запроса; по умолчанию — «&».

Параметр equal — подстрока-разделитель ключей и значений в строке запроса; по умолчанию — «=».

Параметр options должен быть объектом со следующими ключами:

encodeURIComponent function

Функция для преобразования небезопасных для URL символов в строке запроса в формат percent-encoding; по умолчанию — querystring.escape().

По умолчанию символы строки запроса, требующие кодирования в формате percent-encoding, кодируются в UTF-8. Если требуется другая кодировка, следует указать параметр encodeURIComponent.

Например, для следующей команды

querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], 123: '' });

строка запроса будет такой:

'foo=bar&baz=qux&baz=quux&123='

querystring.unescape(string)

Декодирует символы string, закодированные в URL в формате percent-encoding, и возвращает неэкранированную строку запроса. Метод используется методом querystring.parse() и не должен вызываться напрямую.

XML

Модуль XML позволяет работать с XML-документами (начиная с версии 0.7.10). Объект модуля XML импортируется с помощью import xml from 'xml'.

Пример:

import xml from 'xml';

let data = `<note><to b="bar" a= "foo" >Tove</to><from>Jani</from></note>`;
let doc = xml.parse(data);

console.log(doc.note.to.$text) /* 'Tove' */
console.log(doc.note.to.$attr$b) /* 'bar' */
console.log(doc.note.$tags[1].$text) /* 'Jani' */

let dec = new TextDecoder();
let c14n = dec.decode(xml.exclusiveC14n(doc.note));
console.log(c14n) /* '<note><to a="foo" b="bar">Tove</to><from>Jani</from></note>' */

c14n = dec.decode(xml.exclusiveC14n(doc.note.to));
console.log(c14n) /* '<to a="foo" b="bar">Tove</to>' */

c14n = dec.decode(xml.exclusiveC14n(doc.note, doc.note.to /* excluding 'to' */));
console.log(c14n) /* '<note><from>Jani</from></note>' */

parse(string | Buffer)

Разбирает строку или Buffer как XML-документ и возвращает объект-обёртку XMLDoc, представляющий разобранный XML-документ.

c14n(root_node[, excluding_node])

Канонизирует root_node и его дочерние узлы в соответствии с Canonical XML Version 1.1. root_node может быть объектом-обёрткой XMLNode или XMLDoc для XML-структуры. Возвращает объект Buffer, содержащий канонизированный результат.

excluding_node

позволяет исключить часть документа из результата

exclusiveC14n(root_node[, excluding_node[, withComments [,prefix_list]]])

Канонизирует root_node и его дочерние узлы в соответствии с Exclusive XML Canonicalization Version 1.0.

root_node

является объектом-обёрткой XMLNode или XMLDoc для XML-структуры

excluding_node

позволяет исключить из результата часть документа, соответствующую узлу и его дочерним узлам

withComments

логическое значение, по умолчанию — false. Если true, канонизация соответствует Exclusive XML Canonicalization Version 1.0. Возвращает объект Buffer, содержащий канонизированный результат.

prefix_list

необязательная строка со списком через пробел префиксов пространств имён, которые также следует включить в результат

serialize()

То же, что и xml.c14n() (начиная с версии 0.7.11).

serializeToString()

То же, что и xml.c14n(), но результат возвращается в виде string (начиная с версии 0.7.11).

XMLDoc

Объект-обёртка XMLDoc для XML-структуры — корневой узел документа.

doc.$root

корневой элемент документа по его имени или undefined

doc.abc

первый корневой тег с именем abc в виде объекта-обёртки XMLNode

XMLNode

Объект-обёртка XMLNode для узла XML-тега.

node.abc

то же, что и node.$tag$abc

node.$attr$abc

значение атрибута узла abc; доступно для записи начиная с версии 0.7.11

node.$attr$abc=xyz

то же, что и node.setAttribute('abc', xyz) (начиная с версии 0.7.11)

node.$attrs

объект-обёртка XMLAttr для всех атрибутов узла

node.$name

имя узла

node.$ns

пространство имён узла

node.$parent

родительский узел текущего узла

node.$tag$abc

первый дочерний тег узла с именем abc; доступно для записи начиная с версии 0.7.11

node.$tags

массив всех дочерних тегов

node.$tags = [node1, node2, ...]

то же, что и node.removeChildren(); node.addChild(node1); node.addChild(node2) (начиная с версии 0.7.11).

node.$tags$abc

все дочерние теги узла с именем abc; доступно для записи начиная с версии 0.7.11

node.$text

содержимое узла; доступно для записи начиная с версии 0.7.11

node.$text = 'abc'

то же, что и node.setText('abc') (начиная с версии 0.7.11)

node.addChild(nd)

добавляет XMLNode в качестве дочернего узла (начиная с версии 0.7.11). Перед добавлением в узел nd рекурсивно копируется

node.removeAllAttributes()

удаляет все атрибуты узла (начиная с версии 0.7.11)

node.removeAttribute(attr_name)

удаляет атрибут с именем attr_name (начиная с версии 0.7.11)

node.removeChildren(tag_name)

удаляет все дочерние теги с именем tag_name (начиная с версии 0.7.11). Если tag_name отсутствует, удаляются все дочерние теги

node.removeText()

удаляет текстовое значение узла (0.7.11)

node.setAttribute(attr_name, value)

задаёт значение для attr_name (начиная с версии 0.7.11). Если значение равно null, атрибут с именем attr_name удаляется

node.setText(value)

задаёт текстовое значение узла (начиная с версии 0.7.11). Если значение равно null, текст узла удаляется.

XMLAttr

Объект-обёртка XMLAttrs для атрибутов XML-узла.

attr.abc

значение атрибута abc

zlib

Модуль zlib предоставляет функции сжатия с использованием алгоритмов “deflate” и “inflate” (начиная с версии 0.7.12). Объект модуля zlib импортируется с помощью import zlib from 'zlib'.

deflateRawSync(string | Buffer[, options])

Сжимает данные с помощью алгоритма “deflate”, переданные в виде строки или Buffer, и не добавляет заголовок zlib. Значение буфера может быть Buffer, TypedArray или DataView. Options — необязательный объект, содержащий параметры zlib. Возвращает экземпляр Buffer со сжатыми данными.

deflateSync(string | Buffer[, options])

Сжимает данные с помощью алгоритма “deflate”, переданные в виде строки или Buffer. Значение Buffer может быть Buffer, TypedArray или DataView. Options — необязательный объект, содержащий параметры zlib. Возвращает экземпляр Buffer со сжатыми данными.

inflateRawSync(string | Buffer)

Распаковывает необработанный поток с помощью алгоритма “deflate”. Возвращает экземпляр Buffer с распакованными данными.

inflateSync(string | Buffer)

Распаковывает поток с помощью алгоритма “deflate”. Возвращает экземпляр Buffer с распакованными данными.

параметры zlib

• chunkSize — целое число; значение по умолчанию — 1024
• dictionary — это Buffer, TypedArray или DataView; по умолчанию — пустое значение
• level — целое число; только для сжатия, см. уровни сжатия zlib
• memLevel — целое число от 1 до 9; только для сжатия
• strategy — целое число; только для сжатия, см. стратегии сжатия zlib
• windowBits — целое число от -15 до -9 для необработанных данных и от 9 до 15 для обычного потока

уровни сжатия zlib

стратегии сжатия zlib