<?xml version="1.0"?>

<!--
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">

<article name="Reference"
        link="/en/docs/njs/reference.html"
        lang="en"
        rev="121">

<section id="summary">

<para>
<link doc="index.xml">njs</link> provides objects, methods and properties
for extending nginx functionality.
</para>

<para>
This reference contains only njs specific properties, methods and modules
not compliant with ECMAScript.
Definitions of njs properties and methods compliant with ECMAScript
can be found in
<link url="http://www.ecma-international.org/ecma-262/">ECMAScript
specification</link>.
List of all njs properties and methods can be found in
<link doc="compatibility.xml">Compatibility</link>.
</para>

</section>


<section id="http_stream" name="nginx objects">


<section id="http" name="HTTP Request">

<para>
<table width="100%">
<tr><td><link id="r_args"><literal>r.args{}</literal></link></td></tr>
<tr><td><link id="r_done"><literal>r.done()</literal></link></td></tr>
<tr><td><link id="r_error"><literal>r.error()</literal></link></td></tr>
<tr><td><link id="r_finish"><literal>r.finish()</literal></link></td></tr>
<tr><td><link id="r_headers_in"><literal>r.headersIn{}</literal></link></td></tr>
<tr><td><link id="r_headers_out"><literal>r.headersOut{}</literal></link></td></tr>
<tr><td><link id="r_http_version"><literal>r.httpVersion</literal></link></td></tr>
<tr><td><link id="r_internal"><literal>r.internal</literal></link></td></tr>
<tr><td><link id="r_internal_redirect"><literal>r.internalRedirect()</literal></link></td></tr>
<tr><td><link id="r_log"><literal>r.log()</literal></link></td></tr>
<tr><td><link id="r_method"><literal>r.method</literal></link></td></tr>
<tr><td><link id="r_parent"><literal>r.parent</literal></link></td></tr>
<tr><td><link id="r_remote_address"><literal>r.remoteAddress</literal></link></td></tr>
<tr><td><link id="r_request_body"><literal>r.requestBody</literal></link></td></tr>
<tr><td><link id="r_request_buffer"><literal>r.requestBuffer</literal></link></td></tr>
<tr><td><link id="r_request_text"><literal>r.requestText</literal></link></td></tr>
<tr><td><link id="r_raw_headers_in"><literal>r.rawHeadersIn[]</literal></link></td></tr>
<tr><td><link id="r_raw_headers_out"><literal>r.rawHeadersOut[]</literal></link></td></tr>
<tr><td><link id="r_response_body"><literal>r.responseBody</literal></link></td></tr>
<tr><td><link id="r_response_buffer"><literal>r.responseBuffer</literal></link></td></tr>
<tr><td><link id="r_response_text"><literal>r.responseText</literal></link></td></tr>
<tr><td><link id="r_return"><literal>r.return()</literal></link></td></tr>
<tr><td><link id="r_send"><literal>r.send()</literal></link></td></tr>
<tr><td><link id="r_sendbuffer"><literal>r.sendBuffer()</literal></link></td></tr>
<tr><td><link id="r_send_header"><literal>r.sendHeader()</literal></link></td></tr>
<tr><td><link id="r_set_return_value"><literal>r.setReturnValue()</literal></link></td></tr>
<tr><td><link id="r_status"><literal>r.status</literal></link></td></tr>
<tr><td><link id="r_subrequest"><literal>r.subrequest()</literal></link></td></tr>
<tr><td><link id="r_uri"><literal>r.uri</literal></link></td></tr>
<tr><td><link id="r_raw_variables"><literal>r.rawVariables{}</literal></link></td></tr>
<tr><td><link id="r_variables"><literal>r.variables{}</literal></link></td></tr>
<tr><td><link id="r_warn"><literal>r.warn()</literal></link></td></tr>
</table>
</para>

<para>
The HTTP request object is available only in the
<link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link> module.
All string properties of the object are
<link id="string">byte strings</link>.

<list type="tag">

<tag-name id="r_args"><literal>r.args{}</literal></tag-name>
<tag-desc>
request arguments object, read-only.
<para>
The query string is returned as an object.
Since <link doc="changes.xml" id="njs0.7.6">0.7.6</link>,
duplicate keys are returned as an array,
keys are case-sensitive, both keys and values are percent-decoded.
</para>

<para>
For example, the query string
<example>
'a=1&amp;b=%32&amp;A=3&amp;b=4&amp;B=two%20words'
</example>
is converted to <literal>r.args</literal> as:
<example>
{a: "1", b: ["2", "4"], A: "3", B: "two words"}
</example>
More advanced parsing scenarios can be achieved with the
<link id="querystring">Query String</link> module
and with the
<link doc="../http/ngx_http_core_module.xml" id="var_args"><literal>$args</literal></link>
variable, for example:

<example>
import qs from 'querystring';

function args(r) {
    return qs.parse(r.variables.args);
}
</example>
The argument object
is evaluated at the first access to <literal>r.args</literal>.
If only a single argument is needed, for example <literal>foo</literal>,
<link doc="../varindex.xml">nginx variables</link> can be used:
<example>
r.variables.arg_foo
</example>
Here, <link id="r_variables">nginx variables object</link>
returns the first value for a given key,
case-insensitive, without percent-decoding.
</para>

<para>
To convert <literal>r.args</literal> back to a string,
the Query String
<link id="querystring_stringify"><literal>stringify</literal></link>
method can be used.
</para>
</tag-desc>

<tag-name id="r_done"><literal>r.done()</literal></tag-name>
<tag-desc>
after calling this function,
next data chunks will be passed to client without calling
<link doc="../http/ngx_http_js_module.xml" id="js_body_filter"/>
(<link doc="changes.xml" id="njs0.5.2">0.5.2</link>).
May be called only from the
<link doc="../http/ngx_http_js_module.xml" id="js_body_filter"/> function
</tag-desc>

<tag-name id="r_error"><literal>r.error(<value>string</value>)</literal></tag-name>
<tag-desc>
writes a <literal>string</literal> to the error log
on the <literal>error</literal> level of logging
<para>
<note>
As nginx has a
<link doc="../dev/development_guide.xml" id="logging">hardcoded</link>
maximum line length limit,
only first 2048 bytes of the string can be logged.
</note>
</para>
</tag-desc>

<tag-name id="r_finish"><literal>r.finish()</literal></tag-name>
<tag-desc>
finishes sending a response to the client
</tag-desc>

<tag-name id="r_headers_in"><literal>r.headersIn{}</literal></tag-name>
<tag-desc>
incoming headers object, read-only.
<para>
The <literal>Foo</literal> request header
can be accessed with the syntax:
<literal>headersIn.foo</literal> or <literal>headersIn['Foo']</literal>.
</para>

<para>
The
<header>Authorization</header>,
<header>Content-Length</header>,
<header>Content-Range</header>,
<header>Content-Type</header>,
<header>ETag</header>,
<header>Expect</header>,
<header>From</header>,
<header>Host</header>,
<header>If-Match</header>,
<header>If-Modified-Since</header>,
<header>If-None-Match</header>,
<header>If-Range</header>,
<header>If-Unmodified-Since</header>,
<header>Max-Forwards</header>,
<header>Proxy-Authorization</header>,
<header>Referer</header>,
<header>Transfer-Encoding</header>, and
<header>User-Agent</header>
request headers can have only one field value
(<link doc="changes.xml" id="njs0.4.1">0.4.1</link>).
Duplicate field values in <header>Cookie</header> headers
are separated by semicolon (<literal>;</literal>).
Duplicate field values in all other request headers are separated by commas.
</para>
</tag-desc>

<tag-name id="r_headers_out"><literal>r.headersOut{}</literal></tag-name>
<tag-desc>
outgoing headers object for the main request, writable.

<para>
If <literal>r.headersOut{}</literal> is the response object of
a <link id="r_subrequest">subrequest</link>, it represents response headers.
In this case, field values in
<header>Accept-Ranges</header>,
<header>Connection</header>,
<header>Content-Disposition</header>,
<header>Content-Encoding</header>,
<header>Content-Length</header>,
<header>Content-Range</header>,
<header>Date</header>,
<header>Keep-Alive</header>,
<header>Server</header>,
<header>Transfer-Encoding</header>,
<header>X-Accel-*</header>
response headers may be omitted.
</para>

<para>
The <header>Foo</header> response header
can be accessed with the syntax:
<literal>headersOut.foo</literal> or <literal>headersOut['Foo']</literal>.
</para>

<para>
Outgoing headers should be set before a response header is sent to a client,
otherwise header update will be ignored.
This means that <literal>r.headersOut{}</literal> is effectively writable in:

<list type="bullet">

<listitem>
the <link doc="../http/ngx_http_js_module.xml" id="js_content"/> handler before
<link id="r_send_header"><literal>r.sendHeader()</literal></link> or
<link id="r_return"><literal>r.return()</literal></link> are called
</listitem>

<listitem>
the <link doc="../http/ngx_http_js_module.xml" id="js_header_filter"/> handler
</listitem>

</list>
</para>

<para>
Field values of multi-value response headers
(<link doc="changes.xml" id="njs0.4.0">0.4.0</link>)
can be set with the syntax:
<example>
r.headersOut['Foo'] = ['a', 'b']
</example>
where the output will be:
<example>
Foo: a
Foo: b
</example>
All previous field values of the <header>Foo</header> response header
will be deleted.
</para>

<para>
For standard response headers
that accept only a single field value such as
<header>Content-Type</header>,
only the last element of the array will take effect.
Field values of the <header>Set-Cookie</header> response header
are always returned as an array.
Duplicate field values in
<header>Age</header>,
<header>Content-Encoding</header>,
<header>Content-Length</header>,
<header>Content-Type</header>,
<header>ETag</header>,
<header>Expires</header>,
<header>Last-Modified</header>,
<header>Location</header>,
<header>Retry-After</header>
response headers are ignored.
Duplicate field values in all other response headers
are separated by commas.
</para>
</tag-desc>

<tag-name id="r_http_version"><literal>r.httpVersion</literal></tag-name>
<tag-desc>
HTTP version, read-only
</tag-desc>

<tag-name id="r_internal"><literal>r.internal</literal></tag-name>
<tag-desc>
boolean value, true for
<link doc="../http/ngx_http_core_module.xml" id="internal">internal</link>
locations
</tag-desc>

<tag-name id="r_internal_redirect"><literal>r.internalRedirect(<value>uri</value>)</literal></tag-name>
<tag-desc>
performs an
<link doc="../dev/development_guide.xml" id="http_request_redirection">internal
redirect</link>
to the specified <literal>uri</literal>.
If the uri starts with the “<literal>@</literal>” prefix,
it is considered a named location.
Redirected requests become internal and can access the
<link doc="../http/ngx_http_core_module.xml" id="internal">internal</link>
locations.
The actual redirect happens after the handler execution is completed.
<para>
<note>
After redirect,
a new njs VM is started in the target location,
the VM in the original location is stopped.
Values of <link doc="../varindex.xml">nginx variables</link> are kept
and can be used to pass information to the target location.
Since <link doc="changes.xml" id="njs0.5.3">0.5.3</link>,
the variable declared with the <literal>js_var</literal> directive for
<link doc="../http/ngx_http_js_module.xml" id="js_var">http</link> or
<link doc="../stream/ngx_stream_js_module.xml" id="js_var">stream</link>
can be used.
</note>
</para>

<para>
<note>
Since <link doc="changes.xml" id="njs0.7.4">0.7.4</link>,
the method accepts escaped URIs.
</note>
</para>

</tag-desc>

<tag-name id="r_log"><literal>r.log(<value>string</value>)</literal></tag-name>
<tag-desc>
writes a <literal>string</literal> to the error log
on the <literal>info</literal> level of logging
<para>
<note>
As nginx has a
<link doc="../dev/development_guide.xml" id="logging">hardcoded</link>
maximum line length limit,
only first 2048 bytes of the string can be logged.
</note>
</para>
</tag-desc>

<tag-name id="r_method"><literal>r.method</literal></tag-name>
<tag-desc>
HTTP method, read-only
</tag-desc>

<tag-name id="r_parent"><literal>r.parent</literal></tag-name>
<tag-desc>
references the parent request object
</tag-desc>

<tag-name id="r_remote_address"><literal>r.remoteAddress</literal></tag-name>
<tag-desc>
client address, read-only
</tag-desc>

<tag-name id="r_request_body"><literal>r.requestBody</literal></tag-name>
<tag-desc>
the property was made obsolete in
<link doc="changes.xml" id="njs0.5.0">0.5.0</link>
and was removed in <link doc="changes.xml" id="njs0.8.0">0.8.0</link>.
The <link id="r_request_buffer"><literal>r.requestBuffer</literal></link> or
<link id="r_request_text"><literal>r.requestText</literal></link> property
should be used instead.
</tag-desc>

<tag-name id="r_request_buffer"><literal>r.requestBuffer</literal></tag-name>
<tag-desc>
client request body if it has not been written to a temporary file
(since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
To ensure that the client request body is in memory,
its size should be limited by
<link doc="../http/ngx_http_core_module.xml" id="client_max_body_size"/>,
and a sufficient buffer size should be set using
<link doc="../http/ngx_http_core_module.xml" id="client_body_buffer_size"/>.
The property is available only in the
<link doc="../http/ngx_http_js_module.xml" id="js_content"/> directive.
</tag-desc>

<tag-name id="r_request_text"><literal>r.requestText</literal></tag-name>
<tag-desc>
the same as <link id="r_request_buffer"><literal>r.requestBuffer</literal></link>,
but returns a <literal>string</literal>.
Note that
it may convert bytes invalid in UTF-8 encoding into the replacement character.
</tag-desc>

<tag-name id="r_raw_headers_in"><literal>r.rawHeadersIn[]</literal></tag-name>
<tag-desc>
returns an array of key-value pairs
exactly as they were received from the client
(<link doc="changes.xml" id="njs0.4.1">0.4.1</link>).
<para>
For example, with the following request headers:
<example>
Host: localhost
Foo:  bar
foo:  bar2
</example>
the output of <literal>r.rawHeadersIn</literal> will be:
<example>
[
    ['Host', 'localhost'],
    ['Foo', 'bar'],
    ['foo', 'bar2']
]
</example>
All <literal>foo</literal> headers
can be collected with the syntax:
<example>
r.rawHeadersIn.filter(v=>v[0].toLowerCase() == 'foo').map(v=>v[1])
</example>
the output will be:
<example>
['bar', 'bar2']
</example>
Header field names are not converted to lower case,
duplicate field values are not merged.
</para>
</tag-desc>

<tag-name id="r_raw_headers_out"><literal>r.rawHeadersOut[]</literal></tag-name>
<tag-desc>
returns an array of key-value pairs of response headers
(<link doc="changes.xml" id="njs0.4.1">0.4.1</link>).
Header field names are not converted to lower case,
duplicate field values are not merged.
</tag-desc>

<tag-name id="r_response_body"><literal>r.responseBody</literal></tag-name>
<tag-desc>
the property was made obsolete in
<link doc="changes.xml" id="njs0.5.0">0.5.0</link>
and was removed in <link doc="changes.xml" id="njs0.8.0">0.8.0</link>.
The <link id="r_response_buffer"><literal>r.responseBuffer</literal></link>
or
the <link id="r_response_text"><literal>r.responseText</literal></link>
property
should be used instead.
</tag-desc>

<tag-name id="r_response_buffer"><literal>r.responseBuffer</literal></tag-name>
<tag-desc>
holds the <link id="r_subrequest">subrequest</link> response body,
read-only
(since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
The size of <literal>r.responseBuffer</literal> is limited by the
<link doc="../http/ngx_http_core_module.xml" id="subrequest_output_buffer_size"/>
directive.
</tag-desc>

<tag-name id="r_response_text"><literal>r.responseText</literal></tag-name>
<tag-desc>
the same as <link id="r_response_buffer"><literal>r.responseBuffer</literal></link>
but returns a string
(since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
Note that
it may convert bytes invalid in UTF-8 encoding into the replacement character.
</tag-desc>

<tag-name id="r_return"><literal>r.return(status[,
string | Buffer])</literal></tag-name>
<tag-desc>
sends the entire response
with the specified <literal>status</literal> to the client.
The response can be a string or Buffer
(<link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
<para>
It is possible to specify either a redirect URL
(for codes 301, 302, 303, 307, and 308)
or the response body text (for other codes) as the second argument
</para>
</tag-desc>

<tag-name id="r_send"><literal>r.send(string
| Buffer)</literal></tag-name>
<tag-desc>
sends a part of the response body to the client.
The data sent can be a string or Buffer
(<link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
</tag-desc>

<tag-name id="r_sendbuffer"><literal>r.sendBuffer(<value>data</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
adds data to the chain of data chunks to be forwarded to the next body filter
(<link doc="changes.xml" id="njs0.5.2">0.5.2</link>).
The actual forwarding happens later,
when the all the data chunks of the current chain are processed.
<para>
The data can be a string or Buffer.
The <literal>options</literal> is an object used
to override nginx buffer flags derived from an incoming data chunk buffer.
The flags can be overridden with the following flags:
<list type="tag">

<tag-name><literal>last</literal></tag-name>
<tag-desc>
boolean,
true if the buffer is the last buffer
</tag-desc>

<tag-name><literal>flush</literal></tag-name>
<tag-desc>
boolean,
true if the buffer should have the <literal>flush</literal> flag
</tag-desc>
</list>
</para>
The method may be called only from the
<link doc="../http/ngx_http_js_module.xml" id="js_body_filter"/> function.
</tag-desc>

<tag-name id="r_send_header"><literal>r.sendHeader()</literal></tag-name>
<tag-desc>
sends the HTTP headers to the client
</tag-desc>

<tag-name id="r_set_return_value"><literal>r.setReturnValue(<value>value</value>)</literal></tag-name>
<tag-desc>
sets the return value of the
<link doc="../http/ngx_http_js_module.xml" id="js_set"/> handler
(<link doc="changes.xml" id="njs0.7.0">0.7.0</link>).
Unlike an ordinary return statement,
this method should be used when the handler is JS async function.
For example:
<example>
async function js_set(r) {
    const digest = await crypto.subtle.digest('SHA-256', r.headersIn.host);
    r.setReturnValue(digest);
}
</example>
</tag-desc>

<tag-name id="r_status"><literal>r.status</literal></tag-name>
<tag-desc>
status, writable
</tag-desc>

<tag-name id="r_subrequest"><literal>r.subrequest(<value>uri</value>[,
<value>options</value>[, <value>callback</value>]])</literal></tag-name>
<tag-desc>
creates a subrequest with the given <literal>uri</literal> and
<literal>options</literal>, and installs
an optional completion <literal>callback</literal>.

<para>
A
<link doc="../dev/development_guide.xml.xml" id="http_subrequests">subrequest</link>
shares its input headers with the client request.
To send headers different from original headers to a proxied server, the
<link doc="../http/ngx_http_proxy_module.xml" id="proxy_set_header"/>
directive can be used.
To send a completely new set of headers to a proxied server, the
<link doc="../http/ngx_http_proxy_module.xml" id="proxy_pass_request_headers"/>
directive can be used.
</para>

<para>
If <literal>options</literal> is a string, then it
holds the subrequest arguments string.
Otherwise, <literal>options</literal> is expected to be
an object with the following keys:
<list type="tag">
<tag-name><literal>args</literal></tag-name>
<tag-desc>
arguments string, by default an empty string is used
</tag-desc>
<tag-name><literal>body</literal></tag-name>
<tag-desc>
request body,
by default the request body of the parent request object is used
</tag-desc>

<tag-name><literal>method</literal></tag-name>
<tag-desc>
HTTP method, by default the <literal>GET</literal> method is used
</tag-desc>

<tag-name><literal>detached</literal></tag-name>
<tag-desc>
boolean flag (<link doc="changes.xml" id="njs0.3.9">0.3.9</link>),
if <literal>true</literal>, the created subrequest is a detached subrequest.
Responses to detached subrequests are ignored.
Unlike ordinary subrequests, a detached subrequest
can be created inside a variable handler.
The <literal>detached</literal> flag and callback argument
are mutually exclusive.
</tag-desc>

</list>
</para>

<para>
The completion <literal>callback</literal> receives
a <link id="http">subrequest response object</link> with methods and properties
identical to the parent request object.
</para>

<para>
Since <link doc="changes.xml" id="njs0.3.8">0.3.8</link>,
if a <literal>callback</literal> is not provided,
the <literal>Promise</literal> object
that resolves to the <link id="http">subrequest response object</link>
is returned.
</para>

<para>
For example, to view all response headers in the subrequest:
<example>
async function handler(r) [
    let reply = await r.subrequest('/path');

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

    r.return(200);
}
</example>
</para>

</tag-desc>

<tag-name id="r_uri"><literal>r.uri</literal></tag-name>
<tag-desc>
current <link doc="../http/ngx_http_core_module.xml" id="var_uri">URI</link>
in request,
<link doc="../http/ngx_http_core_module.xml" id="location">normalized</link>,
read-only
</tag-desc>

<tag-name id="r_raw_variables"><literal>r.rawVariables{}</literal></tag-name>
<tag-desc>
nginx <link id="r_variables">variables</link> as Buffers,
writable
(since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
</tag-desc>

<tag-name id="r_variables"><literal>r.variables{}</literal></tag-name>
<tag-desc>
<link doc="../varindex.xml">nginx variables</link> object, writable
(since <link doc="changes.xml" id="njs0.2.8">0.2.8</link>).

<para>
For example, to get the <literal>$foo</literal> variable,
one of the following syntax can be used:
<example>
r.variables['foo']
r.variables.foo
</example>
nginx treats variables referenced in <literal>nginx.conf</literal>
and unreferenced variables differently.
When a variable is referenced, it may be cacheable,
but when it is unreferenced it is always uncacheable.
For example, when the
<link doc="../http/ngx_http_core_module.xml" id="var_request_id">$request_id</link>
variable is only accessed from njs,
it has a new value every time it is evaluated.
But, when the
<link doc="../http/ngx_http_core_module.xml" id="var_request_id">$request_id</link>
is referenced, for example:
<example>
proxy_set_header X-Request-Id $request_id;
</example>
the <literal>r.variables.request_id</literal> returns the same value every time.
</para>

<para>
A variable is writable if:
<list type="bullet">

<listitem>
it was created using the <literal>js_var</literal> directive for
<link doc="../http/ngx_http_js_module.xml" id="js_var">http</link> or
<link doc="../stream/ngx_stream_js_module.xml" id="js_var">stream</link>
(since <link doc="changes.xml" id="njs0.5.3">0.5.3</link>)
</listitem>

<listitem>
it is referenced in nginx configuration file
</listitem>

</list>
Even so, some embedded variables still cannot be assigned a value (for example,
<link doc="../http/ngx_http_core_module.xml" id="var_http_"><literal>$http_</literal></link>).
</para>
</tag-desc>

<tag-name id="r_warn"><literal>r.warn(<value>string</value>)</literal></tag-name>
<tag-desc>
writes a <literal>string</literal> to the error log
on the <literal>warning</literal> level of logging
<para>
<note>
As nginx has a
<link doc="../dev/development_guide.xml" id="logging">hardcoded</link>
maximum line length limit,
only first 2048 bytes of the string can be logged.
</note>
</para>
</tag-desc>

</list>
</para>

</section>


<section id="stream" name="Stream Session">

<para>
<table width="100%">
<tr><td><link id="s_allow"><literal>s.allow()</literal></link></td></tr>
<tr><td><link id="s_decline"><literal>s.decline()</literal></link></td></tr>
<tr><td><link id="s_deny"><literal>s.deny()</literal></link></td></tr>
<tr><td><link id="s_done"><literal>s.done()</literal></link></td></tr>
<tr><td><link id="s_error"><literal>s.error()</literal></link></td></tr>
<tr><td><link id="s_log"><literal>s.log()</literal></link></td></tr>
<tr><td><link id="s_off"><literal>s.off()</literal></link></td></tr>
<tr><td><link id="s_on"><literal>s.on()</literal></link></td></tr>
<tr><td><link id="s_remote_address"><literal>s.remoteAddress</literal></link></td></tr>
<tr><td><link id="s_raw_variables"><literal>s.rawVariables{}</literal></link></td></tr>
<tr><td><link id="s_send"><literal>s.send()</literal></link></td></tr>
<tr><td><link id="s_send_downstream"><literal>s.sendDownstream()</literal></link></td></tr>
<tr><td><link id="s_send_upstream"><literal>s.sendUpstream()</literal></link></td></tr>
<tr><td><link id="s_status"><literal>s.status</literal></link></td></tr>
<tr><td><link id="s_set_return_value"><literal>s.setReturnValue()</literal></link></td></tr>
<tr><td><link id="s_variables"><literal>s.variables{}</literal></link></td></tr>
<tr><td><link id="s_warn"><literal>s.warn()</literal></link></td></tr>
</table>
</para>

<para>
The stream session object is available only in the
<link doc="../stream/ngx_stream_js_module.xml">ngx_stream_js_module</link>
module.
All string properties of the object are <link id="string">byte strings</link>.
</para>

<para>
<list type="tag">

<tag-name id="s_allow"><literal>s.allow()</literal></tag-name>
<tag-desc>
an alias to
<link id="s_done"><literal>s.done(0)</literal></link>
(<link doc="changes.xml" id="njs0.2.4">0.2.4</link>)
</tag-desc>

<tag-name id="s_decline"><literal>s.decline()</literal></tag-name>
<tag-desc>
an alias to
<link id="s_done"><literal>s.done(-5)</literal></link>
(<link doc="changes.xml" id="njs0.2.4">0.2.4</link>)
</tag-desc>

<tag-name id="s_deny"><literal>s.deny()</literal></tag-name>
<tag-desc>
an alias to
<link id="s_done"><literal>s.done(403)</literal></link>
(<link doc="changes.xml" id="njs0.2.4">0.2.4</link>)
</tag-desc>

<tag-name id="s_done"><literal>s.done([<value>code</value>]</literal>)</tag-name>
<tag-desc>
sets an exit <literal>code</literal> for the current
<link doc="../stream/stream_processing.xml">phase</link> handler
to a code value, by default <literal>0</literal>.
The actual finalization happens when the js handler is completed
and all pending events, for example, from
<link id="ngx_fetch"><literal>ngx.fetch()</literal></link> or
<link id="settimeout"><literal>setTimeout()</literal></link>,
are processed
(<link doc="changes.xml" id="njs0.2.4">0.2.4</link>).
<para>
Possible code values:
<list type="bullet">

<listitem>
<literal>0</literal>&mdash;
successful finalization, passing control to the next phase
</listitem>

<listitem>
<literal>-5</literal>&mdash;
undecided, passing control to the next handler of the current phase (if any)
</listitem>

<listitem>
<literal>403</literal>&mdash;
access is forbidden
</listitem>

</list>
</para>
May be called only from a phase handler function:
<link doc="../stream/ngx_stream_js_module.xml" id="js_access"><literal>js_access</literal></link>
or
<link doc="../stream/ngx_stream_js_module.xml" id="js_preread"><literal>js_preread</literal></link>.
</tag-desc>

<tag-name id="s_error"><literal>s.error(<value>string</value>)</literal></tag-name>
<tag-desc>
writes a sent <literal>string</literal> to the error log
on the <literal>error</literal> level of logging
<para>
<note>
As nginx has a
<link doc="../dev/development_guide.xml" id="logging">hardcoded</link>
maximum line length limit,
only first 2048 bytes of the string can be logged.
</note>
</para>
</tag-desc>

<tag-name id="s_log"><literal>s.log(<value>string</value>)</literal></tag-name>
<tag-desc>
writes a sent <value>string</value> to the error log
on the <literal>info</literal> level of logging
<para>
<note>
As nginx has a
<link doc="../dev/development_guide.xml" id="logging">hardcoded</link>
maximum line length limit,
only first 2048 bytes of the string can be logged.
</note>
</para>
</tag-desc>

<tag-name id="s_off"><literal>s.off(<value>eventName</value>)</literal></tag-name>
<tag-desc>
unregisters the callback set by the <link id="s_on">s.on()</link> method
(<link doc="changes.xml" id="njs0.2.4">0.2.4</link>)
</tag-desc>

<tag-name id="s_on"><literal>s.on(<value>event</value>,
<value>callback</value>)</literal></tag-name>
<tag-desc>
registers a <literal>callback</literal>
for the specified <literal>event</literal>
(<link doc="changes.xml" id="njs0.2.4">0.2.4</link>).

<para>
An <literal>event</literal> may be one of the following strings:
<list type="tag">
<tag-name><literal>upload</literal></tag-name>
<tag-desc>
new data (string) from a client
</tag-desc>

<tag-name><literal>download</literal></tag-name>
<tag-desc>
new data (string) to a client
</tag-desc>

<tag-name><literal>upstream</literal></tag-name>
<tag-desc>
new data (Buffer) from a client
(since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
</tag-desc>

<tag-name><literal>downstream</literal></tag-name>
<tag-desc>
new data (Buffer) to a client
(since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
</tag-desc>

</list>
</para>

<para>
The completion callback has the following prototype:
<literal>callback(data, flags)</literal>, where
<literal>data</literal> is string or Buffer (depending on the event type)
<literal>flags</literal> is an object
with the following properties:
<list type="tag">
<tag-name id="s_on_callback_last"><literal>last</literal></tag-name>
<tag-desc>
a boolean value, true if data is a last buffer.
</tag-desc>

</list>
</para>
</tag-desc>

<tag-name id="s_remote_address"><literal>s.remoteAddress</literal></tag-name>
<tag-desc>
client address, read-only
</tag-desc>

<tag-name id="s_raw_variables"><literal>s.rawVariables</literal></tag-name>
<tag-desc>
nginx <link id="s_variables">variables</link> as Buffers,
writable
(since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
</tag-desc>

<tag-name id="s_send"><literal>s.send(<value>data</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
adds data to the chain of data chunks that will be forwarded in
the forward direction:
in download callback to a client; in upload to an upstream server
(<link doc="changes.xml" id="njs0.2.4">0.2.4</link>).
The actual forwarding happens later,
when the all the data chunks of the current chain are processed.
<para>
The data can be a string or Buffer
(<link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
The <literal>options</literal> is an object used
to override nginx buffer flags derived from an incoming data chunk buffer.
The flags can be overridden with the following flags:
<list type="tag">

<tag-name><literal>last</literal></tag-name>
<tag-desc>
boolean,
true if the buffer is the last buffer
</tag-desc>

<tag-name><literal>flush</literal></tag-name>
<tag-desc>
boolean,
true if the buffer should have the <literal>flush</literal> flag
</tag-desc>
</list>
</para>
The method can be called multiple times per callback invocation.
</tag-desc>

<tag-name id="s_send_downstream"><literal>s.sendDownstream()</literal></tag-name>
<tag-desc>
is identical to <link id="s_send">s.send()</link>,
except for it always sends data to a client
(since <link doc="changes.xml" id="njs0.7.8">0.7.8</link>).
</tag-desc>

<tag-name id="s_send_upstream"><literal>s.sendUpstream()</literal></tag-name>
<tag-desc>
is identical to <link id="s_send">s.send()</link>,
except for it always sends data from a client
(since <link doc="changes.xml" id="njs0.7.8">0.7.8</link>).
</tag-desc>

<tag-name id="s_status"><literal>s.status</literal></tag-name>
<tag-desc>
session status code, an alias to the
<link doc="../stream/ngx_stream_core_module.xml" id="var_status"><literal>$status</literal></link>
variable,
read only
(since <link doc="changes.xml" id="njs0.5.2">0.5.2</link>)
</tag-desc>

<tag-name id="s_set_return_value"><literal>s.setReturnValue(<value>value</value>)</literal></tag-name>
<tag-desc>
sets the return value of the
<link doc="../stream/ngx_stream_js_module.xml" id="js_set"/> handler
(<link doc="changes.xml" id="njs0.7.0">0.7.0</link>).
Unlike an ordinary return statement,
this method should be used when the handler is JS async function.
For example:
<example>
async function js_set(r) {
    const digest = await crypto.subtle.digest('SHA-256', r.headersIn.host);
    r.setReturnValue(digest);
}
</example>
</tag-desc>

<tag-name id="s_variables"><literal>s.variables{}</literal></tag-name>
<tag-desc>
<link doc="../varindex.xml">nginx variables</link> object, writable
(since <link doc="changes.xml" id="njs0.2.8">0.2.8</link>).
A variable can be writable only
if it is referenced in nginx configuration file.
Even so, some embedded variables still cannot be assigned a value.
</tag-desc>

<tag-name id="s_warn"><literal>s.warn(<value>string</value>)</literal></tag-name>
<tag-desc>
writes a sent <literal>string</literal> to the error log
on the <literal>warning</literal> level of logging
<para>
<note>
As nginx has a
<link doc="../dev/development_guide.xml" id="logging">hardcoded</link>
maximum line length limit,
only first 2048 bytes of the string can be logged.
</note>
</para>
</tag-desc>

</list>
</para>

</section>


<section id="periodic_session" name="Periodic Session">

<para>
<table width="100%">
<tr><td><link id="periodic_session_raw_variables"><literal>PeriodicSession.rawVariables{}</literal></link></td></tr>
<tr><td><link id="periodic_session_variables"><literal>PeriodicSession.variables{}</literal></link></td></tr>
</table>
</para>

<para>
The <literal>Periodic Session</literal> object is provided as the first argument
for the <literal>js_periodic</literal> handler for
<link doc="../http/ngx_http_js_module.xml" id="js_periodic">http</link>
and
<link doc="../stream/ngx_stream_js_module.xml" id="js_periodic">stream</link>
(since <link doc="changes.xml" id="njs0.8.1">0.8.1</link>).
</para>

<para>
<list type="tag">

<tag-name id="periodic_session_raw_variables"><literal>PeriodicSession.rawVariables{}</literal></tag-name>
<tag-desc>
nginx <link id="periodic_session_variables">variables</link> as Buffers,
writable.
</tag-desc>

<tag-name id="periodic_session_variables"><literal>PeriodicSession.variables{}</literal></tag-name>
<tag-desc>
<link doc="../varindex.xml">nginx variables</link> object, writable.
</tag-desc>

</list>
</para>

</section>


<section id="headers" name="Headers">

<para>
<table width="100%">
<tr><td><link id="headers_constructor"><literal>Headers()</literal></link></td></tr>
<tr><td><link id="headers_append"><literal>Headers.append()</literal></link></td></tr>
<tr><td><link id="headers_delete"><literal>Headers.delete()</literal></link></td></tr>
<tr><td><link id="headers_get"><literal>Headers.get()</literal></link></td></tr>
<tr><td><link id="headers_getall"><literal>Headers.getAll()</literal></link></td></tr>
<tr><td><link id="headers_foreach"><literal>Headers.forEach()</literal></link></td></tr>
<tr><td><link id="headers_has"><literal>Headers.has()</literal></link></td></tr>
<tr><td><link id="headers_set"><literal>Headers.set()</literal></link></td></tr>
</table>
</para>

<para>
The <literal>Headers</literal> interface of the
<link id="ngx_fetch"><literal>Fetch API</literal></link>
is available since <link doc="changes.xml" id="njs0.5.1">0.5.1</link>.
</para>

<para>
A new <literal>Headers</literal> object can be created using the
<link id="headers_constructor"><literal>Headers()</literal></link> constructor:
(since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>):

<list type="tag">

<tag-name id="headers_constructor"><literal>Headers([<value>init</value>])</literal></tag-name>
<tag-desc>

<list type="tag">

<tag-name><literal>init</literal></tag-name>
<tag-desc>
An object containing HTTP headers for
prepopulating the <literal>Headers</literal> object,
can be a <literal>string</literal>,
an <literal>array</literal> of name-value pairs,
or an existing <literal>Headers</literal> object.
</tag-desc>

</list>
</tag-desc>

</list>
</para>

<para>
A new <literal>Headers</literal> object can be created
with the following properties and methods:

<list type="tag">

<tag-name id="headers_append"><literal>append()</literal></tag-name>
<tag-desc>
Appends a new value into an existing header in the
<literal>Headers</literal> object,
or adds the header if it does not already exist
(since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>).
</tag-desc>

<tag-name id="headers_delete"><literal>delete()</literal></tag-name>
<tag-desc>
Deletes a header from the <literal>Headers</literal> object
(since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>).
</tag-desc>

<tag-name id="headers_get"><literal>get()</literal></tag-name>
<tag-desc>
Returns a string containing the values of all headers with the specified name
separated by a comma and a space.
</tag-desc>

<tag-name id="headers_getall"><literal>getAll(<value>name</value>)</literal></tag-name>
<tag-desc>
Returns an array containing the values of all headers with the specified name.
</tag-desc>

<tag-name id="headers_foreach"><literal>forEach()</literal></tag-name>
<tag-desc>
Executes a provided function once for each key/value pair
in the <literal>Headers</literal> object
(since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>).
</tag-desc>

<tag-name id="headers_has"><literal>has()</literal></tag-name>
<tag-desc>
Returns a boolean value
indicating whether a header with the specified name exists.
</tag-desc>

<tag-name id="headers_set"><literal>set()</literal></tag-name>
<tag-desc>
Sets a new value for an existing header inside
the <literal>Headers</literal> object,
or adds the header if it does not already exist
(since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>).
</tag-desc>

</list>
</para>

</section>


<section id="request" name="Request">

<para>
<table width="100%">
<tr><td><link id="request_constructor"><literal>Request()</literal></link></td></tr>
<tr><td><link id="request_arraybuffer"><literal>Request.arrayBuffer()</literal></link></td></tr>
<tr><td><link id="request_bodyused"><literal>Request.bodyUsed</literal></link></td></tr>
<tr><td><link id="request_cache"><literal>Request.cache</literal></link></td></tr>
<tr><td><link id="request_credentials"><literal>Request.credentials</literal></link></td></tr>
<tr><td><link id="request_headers"><literal>Request.headers</literal></link></td></tr>
<tr><td><link id="request_json"><literal>Request.json()</literal></link></td></tr>
<tr><td><link id="request_method"><literal>Request.method</literal></link></td></tr>
<tr><td><link id="request_mode"><literal>Request.mode</literal></link></td></tr>
<tr><td><link id="request_text"><literal>Request.text()</literal></link></td></tr>
<tr><td><link id="request_url"><literal>Request.url</literal></link></td></tr>
</table>
</para>

<para>
The <literal>Request</literal> interface of the
<link id="ngx_fetch"><literal>Fetch API</literal></link>
is available since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>.
</para>

<para>
A new <literal>Request</literal> object can be created using the
<link id="request_constructor"><literal>Request()</literal></link> constructor:

<list type="tag">

<tag-name id="request_constructor"><literal>Request[<value>resource</value>[,
<value>options</value>]])</literal></tag-name>
<tag-desc>

Creates a <literal>Request</literal> object to fetch
that can be passed later to
<link id="ngx_fetch"><literal>ngx.fetch()</literal></link>.
The <literal>resource</literal> can be a URL
or an existing <literal>Request</literal> object.
The <literal>options</literal> is an optional argument
that is expected to be an object with the following keys:

<list type="tag">

<tag-name><literal>body</literal></tag-name>
<tag-desc>
The request body, by default is empty.
</tag-desc>

<tag-name><literal>headers</literal></tag-name>
<tag-desc>
The response headers object&mdash;
the object containing HTTP headers for
prepopulating the <link id="headers"><literal>Headers</literal></link> object,
can be a <literal>string</literal>,
an <literal>array</literal> of name-value pairs,
or an existing <link id="headers"><literal>Headers</literal></link> object.
</tag-desc>

<tag-name><literal>method</literal></tag-name>
<tag-desc>
The HTTP method, by default the GET method is used.
</tag-desc>

</list>
</tag-desc>

</list>
</para>

<para>
A new <literal>Request</literal> object can be created
with the following properties and methods:

<list type="tag">

<tag-name id="request_arraybuffer"><literal>arrayBuffer()</literal></tag-name>
<tag-desc>
Returns a <literal>Promise</literal> that resolves with
an <literal>ArrayBuffer</literal>.
</tag-desc>

<tag-name id="request_bodyused"><literal>bodyUsed</literal></tag-name>
<tag-desc>
A boolean value, <literal>true</literal>
if the body was used in the request.
</tag-desc>

<tag-name id="request_cache"><literal>cache</literal></tag-name>
<tag-desc>
Contains the cache mode of the request.
</tag-desc>

<tag-name id="request_credentials"><literal>credentials</literal></tag-name>
<tag-desc>
Contains the credentials of the request,
by default is <literal>same-origin</literal>.
</tag-desc>

<tag-name id="request_headers"><literal>headers</literal></tag-name>
<tag-desc>
The <link id="headers"><literal>Headers</literal></link> read-only object
associated with the
<link id="request"><literal>Request</literal></link>.
</tag-desc>

<tag-name id="request_json"><literal>json()</literal></tag-name>
<tag-desc>
Returns a <literal>Promise</literal> that resolves with
the result of parsing the request body as JSON.
</tag-desc>

<tag-name id="request_method"><literal>method</literal></tag-name>
<tag-desc>
Contains the request method.
</tag-desc>

<tag-name id="request_mode"><literal>mode</literal></tag-name>
<tag-desc>
Contains the mode of the request.
</tag-desc>

<tag-name id="request_text"><literal>text()</literal></tag-name>
<tag-desc>
Returns a <literal>Promise</literal> that resolves with a
string representation of the request body.
</tag-desc>

<tag-name id="request_url"><literal>url</literal></tag-name>
<tag-desc>
Contains the URL of the request.
</tag-desc>

</list>
</para>

</section>


<section id="response" name="Response">

<para>
<table width="100%">
<tr><td><link id="response_constructor"><literal>Response()</literal></link></td></tr>
<tr><td><link id="response_arraybuffer"><literal>Response.arrayBuffer()</literal></link></td></tr>
<tr><td><link id="response_bodyused"><literal>Response.bodyUsed</literal></link></td></tr>
<tr><td><link id="response_headers"><literal>Response.headers</literal></link></td></tr>
<tr><td><link id="response_json"><literal>Response.json()</literal></link></td></tr>
<tr><td><link id="response_ok"><literal>Response.ok</literal></link></td></tr>
<tr><td><link id="response_redirect"><literal>Response.redirected</literal></link></td></tr>
<tr><td><link id="response_status"><literal>Response.status</literal></link></td></tr>
<tr><td><link id="response_statustext"><literal>Response.statusText</literal></link></td></tr>
<tr><td><link id="response_text"><literal>Response.text()</literal></link></td></tr>
<tr><td><link id="response_type"><literal>Response.type</literal></link></td></tr>
<tr><td><link id="response_url"><literal>Response.url</literal></link></td></tr>
</table>
</para>

<para>
The <literal>Response</literal> interface is available since
<link doc="changes.xml" id="njs0.5.1">0.5.1</link>.
</para>

<para>
A new <literal>Response</literal> object can be created using the
<link id="response_constructor"><literal>Response()</literal></link> constructor
(since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>):

<list type="tag">

<tag-name id="response_constructor"><literal>Response[<value>body</value>[,
<value>options</value>]])</literal></tag-name>
<tag-desc>
Creates a <literal>Response</literal> object.
The <literal>body</literal> is an optional argument,
can be a <literal>string</literal> or a <literal>buffer</literal>,
by default is <literal>null</literal>.
The <literal>options</literal> is an optional argument
that is expected to be an object with the following keys:

<list type="tag">

<tag-name><literal>headers</literal></tag-name>
<tag-desc>
The response headers object&mdash;
the object containing HTTP headers for
prepopulating the <link id="headers"><literal>Headers</literal></link> object,
can be a <literal>string</literal>,
an <literal>array</literal> of name-value pairs,
or an existing <link id="headers"><literal>Headers</literal></link> object.
</tag-desc>

<tag-name><literal>status</literal></tag-name>
<tag-desc>
The status code of the response.
</tag-desc>

<tag-name><literal>statusText</literal></tag-name>
<tag-desc>
The status message corresponding to the status code.
</tag-desc>

</list>
</tag-desc>

</list>
</para>

<para>
A new <literal>Response()</literal> object can be created
with the following properties and methods:

<list type="tag">

<tag-name id="response_arraybuffer"><literal>arrayBuffer()</literal></tag-name>
<tag-desc>
Takes a <literal>Response</literal> stream and reads it to completion.
Returns a <literal>Promise</literal> that resolves with
an <literal>ArrayBuffer</literal>.
</tag-desc>

<tag-name id="response_bodyused"><literal>bodyUsed</literal></tag-name>
<tag-desc>
A boolean value, <literal>true</literal>
if the body was read.
</tag-desc>

<tag-name id="response_headers"><literal>headers</literal></tag-name>
<tag-desc>
The <link id="headers"><literal>Headers</literal></link> read-only object
associated with the
<link id="response"><literal>Response</literal></link>.
</tag-desc>

<tag-name id="response_json"><literal>json()</literal></tag-name>
<tag-desc>
Takes a <literal>Response</literal> stream and reads it to completion.
Returns a <literal>Promise</literal> that resolves with
the result of parsing the body text as JSON.
</tag-desc>

<tag-name id="response_ok"><literal>ok</literal></tag-name>
<tag-desc>
A boolean value, <literal>true</literal>
if the response was successful (status codes between 200–299).
</tag-desc>

<tag-name id="response_redirect"><literal>redirected</literal></tag-name>
<tag-desc>
A boolean value, <literal>true</literal>
if the response is the result of a redirect.
</tag-desc>

<tag-name id="response_status"><literal>status</literal></tag-name>
<tag-desc>
The status code of the response.
</tag-desc>

<tag-name id="response_statustext"><literal>statusText</literal></tag-name>
<tag-desc>
The status message corresponding to the status code.
</tag-desc>

<tag-name id="response_text"><literal>text()</literal></tag-name>
<tag-desc>
Takes a <literal>Response</literal> stream and reads it to completion.
Returns a <literal>Promise</literal> that resolves with a string.
</tag-desc>

<tag-name id="response_type"><literal>type</literal></tag-name>
<tag-desc>
The type of the response.
</tag-desc>

<tag-name id="response_url"><literal>url</literal></tag-name>
<tag-desc>
The URL of the response.
</tag-desc>

</list>
</para>

</section>


<section id="ngx" name="ngx">

<para>
<table width="100%">
<tr><td><link id="ngx_build"><literal>ngx.build</literal></link></td></tr>
<tr><td><link id="ngx_conf_file_path"><literal>ngx.conf_file_path</literal></link></td></tr>
<tr><td><link id="ngx_conf_prefix"><literal>ngx.conf_prefix</literal></link></td></tr>
<tr><td><link id="ngx_error_log_path"><literal>ngx.error_log_path</literal></link></td></tr>
<tr><td><link id="ngx_fetch"><literal>ngx.fetch()</literal></link></td></tr>
<tr><td><link id="ngx_log"><literal>ngx.log()</literal></link></td></tr>
<tr><td><link id="ngx_prefix"><literal>ngx.prefix</literal></link></td></tr>
<tr><td><link id="ngx_version"><literal>ngx.version</literal></link></td></tr>
<tr><td><link id="ngx_version_number"><literal>ngx.version_number</literal></link></td></tr>
<tr><td><link id="ngx_worker_id"><literal>ngx.worker_id</literal></link></td></tr>
</table>
</para>

<para>
The <literal>ngx</literal> global object is available
since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>.
<list type="tag">

<tag-name id="ngx_build"><literal>ngx.build</literal></tag-name>
<tag-desc>
a string containing an optional nginx build name, corresponds to the
<link doc="../configure.xml" id="build"><literal>--build=name</literal></link>
argument
of the <link doc="../configure.xml">configure</link> script,
by default is <literal>""</literal>
(<link doc="changes.xml" id="njs0.8.0">0.8.0</link>)
</tag-desc>

<tag-name id="ngx_conf_file_path"><literal>ngx.conf_file_path</literal></tag-name>
<tag-desc>
a string containing the file path to current nginx configuration file
(<link doc="changes.xml" id="njs0.8.0">0.8.0</link>)
</tag-desc>

<tag-name id="ngx_conf_prefix"><literal>ngx.conf_prefix</literal></tag-name>
<tag-desc>
a string containing the file path to
<link doc="../configure.xml" id="conf_path">nginx configuration prefix</link>&mdash;
the directory where nginx is currently looking for configuration
(<link doc="changes.xml" id="njs0.7.8">0.7.8</link>)
</tag-desc>

<tag-name id="ngx_error_log_path"><literal>ngx.error_log_path</literal></tag-name>
<tag-desc>
a string containing the file path to the current
<link doc="../ngx_core_module.xml" id="error_log">error log</link> file
(<link doc="changes.xml" id="njs0.8.0">0.8.0</link>)
</tag-desc>

<tag-name id="ngx_fetch"><literal>ngx.fetch(<value>resource</value>,
[<value>options</value>])</literal></tag-name>
<tag-desc>
<para>
Makes a request to fetch a <value>resource</value>
(<link doc="changes.xml" id="njs0.5.1">0.5.1</link>), which can be an
URL or the <link id="request"><literal>Request</literal></link> object
(<link doc="changes.xml" id="njs0.7.10">0.7.10</link>).
Returns a <literal>Promise</literal> that resolves with
the <link id="response"><literal>Response</literal></link> object.
Since <link doc="changes.xml" id="njs0.7.0">0.7.0</link>,
the <literal>https://</literal> scheme is supported,
redirects are not handled.
</para>

<para>
If the URL in the <value>resource</value> is specified as a domain name,
it is determined using a
<link doc="../http/ngx_http_core_module.xml" id="resolver"/>.
If the <literal>https://</literal> scheme is specified, the
<link doc="../http/ngx_http_js_module.xml" id="js_fetch_trusted_certificate"/>
directive should be configured
for the authentication of the <value>resource</value>'s HTTPS server.
</para>

<para>
The <literal>options</literal> parameter is expected to be an object
with the following keys:
<list type="tag">

<tag-name id="fetch_body"><literal>body</literal></tag-name>
<tag-desc>
request body,
by default is empty
</tag-desc>

<tag-name id="fetch_buffer_size"><literal>buffer_size</literal></tag-name>
<tag-desc>
the buffer size for reading the response,
by default is <literal>4096</literal>
</tag-desc>

<tag-name id="fetch_headers"><literal>headers</literal></tag-name>
<tag-desc>
request <link id="headers">headers</link> object
</tag-desc>

<tag-name id="fetch_get"><literal>max_response_body_size</literal></tag-name>
<tag-desc>
the maximum size of the response body in bytes,
by default is <literal>32768</literal>
</tag-desc>

<tag-name id="fetch_method"><literal>method</literal></tag-name>
<tag-desc>
HTTP method,
by default the <literal>GET</literal> method is used
</tag-desc>

<tag-name id="fetch_verify"><literal>verify</literal></tag-name>
<tag-desc>
enables or disables verification of the HTTPS server certificate,
by default is <literal>true</literal>
(<link doc="changes.xml" id="njs0.7.0">0.7.0</link>)
</tag-desc>

</list>
Example:
<example>
let reply = await ngx.fetch('http://nginx.org/');
let body = await reply.text();

r.return(200, body);
</example>
</para>
</tag-desc>

<tag-name id="ngx_log"><literal>ngx.log</literal>(<value>level</value>,
<value>message</value>)</tag-name>
<tag-desc>
writes a message to the error log with the specified level of logging.
The <value>level</value> parameter specifies one of the log levels,
the <value>message</value> parameter can be a string or Buffer.
The following log levels can be specified:
<literal>ngx.INFO</literal>,
<literal>ngx.WARN</literal>, and
<literal>ngx.ERR</literal>.
<para>
<note>
As nginx has a
<link doc="../dev/development_guide.xml" id="logging">hardcoded</link>
maximum line length limit,
only first 2048 bytes of the string can be logged.
</note>
</para>
</tag-desc>

<tag-name id="ngx_prefix"><literal>ngx.prefix</literal></tag-name>
<tag-desc>
a string containing the file path to
<link doc="../configure.xml" id="prefix">nginx prefix</link>&mdash;
a directory that keeps server files
(<link doc="changes.xml" id="njs0.8.0">0.8.0</link>)
</tag-desc>

<tag-name id="ngx_version"><literal>ngx.version</literal></tag-name>
<tag-desc>
a string containing nginx version,
for example: <literal>1.25.0</literal>
(<link doc="changes.xml" id="njs0.8.0">0.8.0</link>)
</tag-desc>

<tag-name id="ngx_version_number"><literal>ngx.version_number</literal></tag-name>
<tag-desc>
a number containing nginx version,
for example: <literal>1025000</literal>
(<link doc="changes.xml" id="njs0.8.0">0.8.0</link>)
</tag-desc>

<tag-name id="ngx_worker_id"><literal>ngx.worker_id</literal></tag-name>
<tag-desc>
a number that corresponds to nginx internal worker id,
the value is between <literal>0</literal> and the value specified in the
<link doc="../ngx_core_module.xml" id="worker_processes"/> directive
(<link doc="changes.xml" id="njs0.8.0">0.8.0</link>)
</tag-desc>

</list>
</para>

</section>

<section id="ngx_shared" name="ngx.shared">

<para>
The <literal>ngx.shared</literal> global object is available
since <link doc="changes.xml" id="njs0.8.0">0.8.0</link>.
</para>


<section id="dict" name="SharedDict">
<para>
<table width="100%">
<tr><td><link id="dict_add"><literal>ngx.shared.SharedDict.add()</literal></link></td></tr>
<tr><td><link id="dict_capacity"><literal>ngx.shared.SharedDict.capacity</literal></link></td></tr>
<tr><td><link id="dict_clear"><literal>ngx.shared.SharedDict.clear()</literal></link></td></tr>
<tr><td><link id="dict_delete"><literal>ngx.shared.SharedDict.delete()</literal></link></td></tr>
<tr><td><link id="dict_freespace"><literal>ngx.shared.SharedDict.freeSpace()</literal></link></td></tr>
<tr><td><link id="dict_get"><literal>ngx.shared.SharedDict.get()</literal></link></td></tr>
<tr><td><link id="dict_has"><literal>ngx.shared.SharedDict.has()</literal></link></td></tr>
<tr><td><link id="dict_incr"><literal>ngx.shared.SharedDict.incr()</literal></link></td></tr>
<tr><td><link id="dict_items"><literal>ngx.shared.SharedDict.items()</literal></link></td></tr>
<tr><td><link id="dict_keys"><literal>ngx.shared.SharedDict.keys()</literal></link></td></tr>
<tr><td><link id="dict_name"><literal>ngx.shared.SharedDict.name</literal></link></td></tr>
<tr><td><link id="dict_pop"><literal>ngx.shared.SharedDict.pop()</literal></link></td></tr>
<tr><td><link id="dict_replace"><literal>ngx.shared.SharedDict.replace()</literal></link></td></tr>
<tr><td><link id="dict_set"><literal>ngx.shared.SharedDict.set()</literal></link></td></tr>
<tr><td><link id="dict_size"><literal>ngx.shared.SharedDict.size()</literal></link></td></tr>
<tr><td><link id="dict_type"><literal>ngx.shared.SharedDict.type</literal></link></td></tr>
</table>
</para>

<para>
The shared dictionary object is available
since <link doc="changes.xml" id="njs0.8.0">0.8.0</link>.
The shared dictionary name, type, and size
are set with the <literal>js_shared_dict_zone</literal> directive in
<link doc="../http/ngx_http_js_module.xml" id="js_shared_dict_zone">http</link>
or
<link doc="../stream/ngx_stream_js_module.xml" id="js_shared_dict_zone">stream</link>.
</para>

<para>
A <literal>SharedDict()</literal> object
has the following properties and methods:
<list type="tag">

<tag-name id="dict_add"><literal>ngx.shared.SharedDict.add(<value>key</value>,
<value>value</value>)</literal></tag-name>
<tag-desc>
Sets the <literal>value</literal>
for the specified <literal>key</literal> in the dictionary
only if the key does not exist yet.
The <literal>key</literal> is a string representing
the key of the item to add,
the <literal>value</literal> is the value of the item to add.
Returns <literal>true</literal> if the value has been successfully added
to  the <literal>SharedDict</literal> dictionary,
<literal>false</literal> if the key already exists in the dictionary.
Throws <literal>SharedMemoryError</literal> if
there is not enough free space in the <literal>SharedDict</literal> dictionary.
Throws <literal>TypeError</literal> if the <literal>value</literal> is
of a different type than expected by this dictionary.
</tag-desc>

<tag-name id="dict_capacity"><literal>ngx.shared.SharedDict.capacity</literal></tag-name>
<tag-desc>
Returns the capacity of the <literal>SharedDict</literal> dictionary,
corresponds to the <literal>size</literal> parameter of
<literal>js_shared_dict_zone</literal> directive in
<link doc="../http/ngx_http_js_module.xml" id="js_shared_dict_zone">http</link>
or
<link doc="../stream/ngx_stream_js_module.xml" id="js_shared_dict_zone">stream</link>.
</tag-desc>

<tag-name id="dict_clear"><literal>ngx.shared.SharedDict.clear()</literal></tag-name>
<tag-desc>
Removes all items from the <literal>SharedDict</literal> dictionary.
</tag-desc>

<tag-name id="dict_delete"><literal>ngx.shared.SharedDict.delete(<value>key</value>)</literal></tag-name>
<tag-desc>
Removes the item associated with the specified key
from the <literal>SharedDict</literal> dictionary,
<literal>true</literal> if the item in the dictionary existed and was removed,
<literal>false</literal> otherwise.
</tag-desc>

<tag-name id="dict_freespace"><literal>ngx.shared.SharedDict.freeSpace()</literal></tag-name>
<tag-desc>
Returns the free page size in bytes.
If the size is zero, the <literal>SharedDict</literal> dictionary
will still accept new values if there is space in the occupied pages.
</tag-desc>

<tag-name id="dict_get"><literal>ngx.shared.SharedDict.get(<value>key</value>)</literal></tag-name>
<tag-desc>
Retrieves the item by its <literal>key</literal>,
returns the value associated with the <literal>key</literal>
or <literal>undefined</literal> if there is none.
</tag-desc>

<tag-name id="dict_has"><literal>ngx.shared.SharedDict.has(<value>key</value>)</literal></tag-name>
<tag-desc>
Searches for an item by its <literal>key</literal>,
returns <literal>true</literal> if such item exists or
<literal>false</literal> otherwise.
</tag-desc>

<tag-name id="dict_incr"><literal>ngx.shared.SharedDict.incr(<value>key</value>,<value>delta</value>[,<value>init</value>])</literal></tag-name>
<tag-desc>
Increments the integer value associated with the <literal>key</literal>
by <literal>delta</literal>.
If the key does not exist,
the item will be initialized to <literal>init</literal>.
The <literal>key</literal> is a string,
the <literal>delta</literal> is the number
to increment or decrement the value by,
the <literal>init</literal> is a number to initialize the item with
if it does not exist, by default is <literal>0</literal>.
Returns the new value.
Throws <literal>SharedMemoryError</literal> if
there is not enough free space in the <literal>SharedDict</literal> dictionary.
Throws <literal>TypeError</literal> if this dictionary does not expect numbers.
<note>
This method can be used only if the dictionary type was declared with
<literal>type=number</literal> parameter of the
<literal>js_shared_dict_zone</literal> directive in
<link doc="../http/ngx_http_js_module.xml" id="js_shared_dict_zone">http</link>
or
<link doc="../stream/ngx_stream_js_module.xml" id="js_shared_dict_zone">stream</link>.
</note>
</tag-desc>

<tag-name id="dict_items"><literal>ngx.shared.SharedDict.items([<value>maxCount</value>])</literal></tag-name>
<tag-desc>
Returns an array of the <literal>SharedDict</literal> dictionary
key-value items (since <link doc="changes.xml" id="njs0.8.1">0.8.1</link>).
The <literal>maxCount</literal> parameter
sets maximum number of items to retrieve,
by default is <literal>1024</literal>.

</tag-desc>

<tag-name id="dict_keys"><literal>ngx.shared.SharedDict.keys([<value>maxCount</value>])</literal></tag-name>
<tag-desc>
Returns an array of the <literal>SharedDict</literal> dictionary keys.
The <literal>maxCount</literal> parameter
sets maximum number of keys to retrieve,
by default is <literal>1024</literal>.
</tag-desc>

<tag-name id="dict_name"><literal>ngx.shared.SharedDict.name</literal></tag-name>
<tag-desc>
Returns the name of the <literal>SharedDict</literal> dictionary,
corresponds to the <literal>zone=</literal> parameter of
<literal>js_shared_dict_zone</literal> directive in
<link doc="../http/ngx_http_js_module.xml" id="js_shared_dict_zone">http</link>
or
<link doc="../stream/ngx_stream_js_module.xml" id="js_shared_dict_zone">stream</link>.
</tag-desc>

<tag-name id="dict_pop"><literal>ngx.shared.SharedDict.pop(<value>key</value>)</literal></tag-name>
<tag-desc>
Removes the item associated with the specified <literal>key</literal>
from the <literal>SharedDict</literal> dictionary,
returns the value associated with the <literal>key</literal>
or <literal>undefined</literal> if there is none.
</tag-desc>

<tag-name id="dict_replace"><literal>ngx.shared.SharedDict.replace(<value>key</value>,
<value>value</value>)</literal></tag-name>
<tag-desc>
Replaces the <literal>value</literal>
for the specified <literal>key</literal> only if the key already exists,
returns <literal>true</literal> if the value was successfully replaced,
<literal>false</literal> if the key does not exist
in the <literal>SharedDict</literal> dictionary.
Throws <literal>SharedMemoryError</literal> if
there is not enough free space in the <literal>SharedDict</literal> dictionary.
Throws <literal>TypeError</literal> if the <literal>value</literal> is
of a different type than expected by this dictionary.
</tag-desc>

<tag-name id="dict_set"><literal>ngx.shared.SharedDict.set(<value>key</value>,
<value>value</value>)</literal></tag-name>
<tag-desc>
Sets the <literal>value</literal> for the specified <literal>key</literal>,
returns this <literal>SharedDict</literal> dictionary (for method chaining).
</tag-desc>

<tag-name id="dict_size"><literal>ngx.shared.SharedDict.size()</literal></tag-name>
<tag-desc>
Returns the number of items for the <literal>SharedDict</literal> dictionary.
</tag-desc>

<tag-name id="dict_type"><literal>ngx.shared.SharedDict.type</literal></tag-name>
<tag-desc>
Returns <literal>string</literal> or <literal>number</literal> that
corresponds to the <literal>SharedDict</literal> dictionary type
set by the <literal>type=</literal> parameter of
<literal>js_shared_dict_zone</literal> directive in
<link doc="../http/ngx_http_js_module.xml" id="js_shared_dict_zone">http</link>
or
<link doc="../stream/ngx_stream_js_module.xml" id="js_shared_dict_zone">stream</link>.
</tag-desc>

</list>
</para>

</section>

</section>

</section>


<section id="builtin_objects" name="built-in objects">


<section id="console" name="console">

<para>
<table width="100%">
<tr><td><link id="console_error"><literal>console.error()</literal></link></td></tr>
<tr><td><link id="console_info"><literal>console.info()</literal></link></td></tr>
<tr><td><link id="console_log"><literal>console.log()</literal></link></td></tr>
<tr><td><link id="console_time"><literal>console.time()</literal></link></td></tr>
<tr><td><link id="console_time_end"><literal>console.timeEnd()</literal></link></td></tr>
<tr><td><link id="console_warn"><literal>console.warn()</literal></link></td></tr>
</table>
</para>

<para>
The <literal>console</literal> object is available
in nginx since <link doc="changes.xml" id="njs0.8.2">0.8.2</link>,
in CLI since <link doc="changes.xml" id="njs0.2.6">0.2.6</link>.
<list type="tag">

<tag-name id="console_error"><literal>console.error(<value>msg</value>[, <value>msg2</value> ...])</literal></tag-name>
<tag-desc>
Outputs one or more error messages.
The message may be a string or an object.
</tag-desc>

<tag-name id="console_info"><literal>console.info(<value>msg</value>[, <value>msg2</value> ...])</literal></tag-name>
<tag-desc>
Outputs one or more info messages.
The message may be a string or an object.
</tag-desc>

<tag-name id="console_log"><literal>console.log(<value>msg</value>[, <value>msg2</value> ...])</literal></tag-name>
<tag-desc>
Outputs one or more log messages.
The message may be a string or an object.
</tag-desc>

<tag-name id="console_time"><literal>console.time(<value>label</value>)</literal></tag-name>
<tag-desc>
Starts a timer that can track how long an operation takes.
The <literal>label</literal> parameter allows naming different timers.
If <link id="console_time_end"><literal>console.timeEnd()</literal></link>
with the same name is called,
the time that elapsed since the timer was started will be output,
in milliseconds.
</tag-desc>

<tag-name id="console_time_end"><literal>console.timeEnd(<value>label</value>)</literal></tag-name>
<tag-desc>
Stops a timer previously started by
<link id="console_time"><literal>console.time()</literal></link>
The <literal>label</literal> parameter allows naming different timers.
</tag-desc>

<tag-name id="console_warn"><literal>console.warn(<value>msg</value>[, <value>msg2</value> ...])</literal></tag-name>
<tag-desc>
Outputs one or more warning messages.
The message may be a string or an object.
</tag-desc>

</list>
</para>

</section>


<section id="builtin_crypto" name="crypto">

<para>
<table width="100%">
<tr><td><link id="crypto_get_random_values"><literal>сrypto.getRandomValues()</literal></link></td></tr>
<tr><td><link id="crypto_subtle_encrypt"><literal>сrypto.subtle.encrypt()</literal></link></td></tr>
<tr><td><link id="crypto_subtle_decrypt"><literal>сrypto.subtle.decrypt()</literal></link></td></tr>
<tr><td><link id="crypto_subtle_derive_bits"><literal>сrypto.subtle.deriveBits()</literal></link></td></tr>
<tr><td><link id="crypto_subtle_derive_key"><literal>сrypto.subtle.deriveKey()</literal></link></td></tr>
<tr><td><link id="crypto_subtle_digest"><literal>сrypto.subtle.digest()</literal></link></td></tr>
<tr><td><link id="crypto_subtle_export_key"><literal>сrypto.subtle.exportKey()</literal></link></td></tr>
<tr><td><link id="crypto_subtle_generate_key"><literal>сrypto.subtle.generateKey()</literal></link></td></tr>
<tr><td><link id="crypto_subtle_import_key"><literal>сrypto.subtle.importKey()</literal></link></td></tr>
<tr><td><link id="crypto_subtle_sign"><literal>сrypto.subtle.sign()</literal></link></td></tr>
<tr><td><link id="crypto_subtle_verify"><literal>сrypto.subtle.verify()</literal></link></td></tr>
</table>
</para>

<para>
The <literal>crypto</literal> object is a global object
that allows using cryptographic functionality
(since <link doc="changes.xml" id="njs0.7.0">0.7.0</link>).
</para>

<para>
<list type="tag">

<tag-name id="crypto_get_random_values"><literal>сrypto.getRandomValues</literal>(<link id="crypto_get_random_values_array"><literal>typedArray</literal></link>)</tag-name>
<tag-desc>
Gets cryptographically strong random values.
Returns the same array passed as <literal>typedArray</literal>
but with its contents replaced with the newly generated random numbers.
Possible values:

<list type="tag">
<tag-name id="crypto_get_random_values_array"><literal>typedArray</literal></tag-name>
<tag-desc>
can be
<literal>Int8Array</literal>,
<literal>Int16Array</literal>,
<literal>Uint16Array</literal>,
<literal>Int32Array</literal>, or
<literal>Uint32Array</literal>
</tag-desc>
</list>

</tag-desc>

<tag-name id="crypto_subtle_encrypt"><literal>сrypto.subtle.encrypt</literal>(<link id="crypto_encrypt_alg"><literal>algorithm</literal></link>,
<link id="crypto_encrypt_key"><literal>key</literal></link>,
<link id="crypto_encrypt_data"><literal>data</literal></link>)</tag-name>
<tag-desc>
Encrypts <link id="crypto_encrypt_data"><literal>data</literal></link>
using the provided
<link id="crypto_encrypt_algorithm"><literal>algorithm</literal></link> and
<link id="crypto_encrypt_key"><literal>key</literal></link>.
Returns a <literal>Promise</literal> that fulfills with
an <literal>ArrayBuffer</literal> containing the ciphertext.
Possible values:

<list type="tag">
<tag-name id="crypto_encrypt_alg"><literal>algorithm</literal></tag-name>
<tag-desc>
an object that specifies
the algorithm to be used and any extra parameters if required:

<list type="bullet">
<listitem id="rsa_oaep_params">
for <literal>RSA-OAEP</literal>,
pass the object with the following keys:

<list type="bullet">

<listitem>
<literal>name</literal> is a string,
should be set to <literal>RSA-OAEP</literal>:
<para>
<example>
crypto.subtle.encrypt({name: "RSA-OAEP"}, key, data)
</example>
</para>
</listitem>
</list>

</listitem>

<listitem id="aes_ctr_params">
for <literal>AES-CTR</literal>,
pass the object with the following keys:

<list type="bullet">

<listitem>
<literal>name</literal> is a string,
should be set to <literal>AES-CTR</literal>
</listitem>

<listitem>
<literal>counter</literal> is an
<literal>ArrayBuffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal> —
the initial value of the counter block,
must be 16 bytes long (the AES block size).
The rightmost length bits of this block are used for the counter,
and the rest is used for the nonce.
For example, if length is set to 64,
then the first half of counter is the nonce
and the second half is used for the counter
</listitem>

<listitem>
<literal>length</literal> is the number of bits in the counter block
that are used for the actual counter.
The counter must be big enough that it doesn't wrap.
</listitem>
</list>

</listitem>

<listitem id="aes_cbc_params">
for <literal>AES-CBC</literal>, pass the object with the following keys:

<list type="bullet">

<listitem>
<literal>name</literal> is a string,
should be set to <literal>AES-CBC</literal>
</listitem>

<listitem>
<literal>iv</literal> or the initialization vector, is an
<literal>ArrayBuffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>,
must be 16 bytes, unpredictable,
and preferably cryptographically random.
However, it need not be secret,
for example, it may be transmitted unencrypted along with the ciphertext.
</listitem>
</list>

</listitem>

<listitem id="aes_gcm_params">
for <literal>AES-GCM</literal>, pass the object with the following keys:

<list type="bullet">

<listitem>
<literal>name</literal> is a string,
should be set to <literal>AES-GCM</literal>
</listitem>

<listitem>
<literal>iv</literal> or the initialization vector, is an
<literal>ArrayBuffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>,
must be 16 bytes,
and must be unique for every encryption operation carried out with a given key
</listitem>

<listitem>
<literal>additionalData</literal> (optional) is an
<literal>ArrayBuffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
that contains additional data that
will not be encrypted but will be authenticated along with the encrypted data.
If <literal>additionalData</literal> is specified,
then the same data must be specified in the corresponding call to
<literal>decrypt()</literal>:
if the data given to the <literal>decrypt()</literal> call
does not match the original data,
the decryption will throw an exception.
The bit length of <literal>additionalData</literal>
must be smaller than <literal>2^64 - 1</literal>.
</listitem>

<listitem>
<literal>tagLength</literal> (optional, default is <literal>128</literal>) -
a <literal>number</literal> that determines the size in bits
of the authentication tag generated in the encryption operation
and used for authentication in the corresponding decryption
Possible values:
<literal>32</literal>,
<literal>64</literal>,
<literal>96</literal>,
<literal>104</literal>,
<literal>112</literal>,
<literal>120</literal>, or
<literal>128</literal>.
The AES-GCM specification recommends that it should be
<literal>96</literal>,
<literal>104</literal>,
<literal>112</literal>,
<literal>120</literal>, or
<literal>128</literal>,
although
<literal>32</literal> or
<literal>64</literal>
bits may be acceptable in some applications.
</listitem>
</list>

</listitem>
</list>

</tag-desc>

<tag-name id="crypto_encrypt_key"><literal>key</literal></tag-name>
<tag-desc>
a <link id="cryptokey"><literal>CryptoKey</literal></link> that contains
the key to be used for encryption
</tag-desc>

<tag-name id="crypto_encrypt_data"><literal>data</literal></tag-name>
<tag-desc>
an
<literal>ArrayBuffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
that contains
the data to be encrypted (also known as the plaintext)
</tag-desc>
</list>

</tag-desc>

<tag-name id="crypto_subtle_decrypt"><literal>сrypto.subtle.decrypt</literal>(<link id="crypto_decrypt_alg"><literal>algorithm</literal></link>,
<link id="crypto_decrypt_key"><literal>key</literal></link>,
<link id="crypto_decrypt_data"><literal>data</literal></link>)</tag-name>
<tag-desc>
Decrypts encrypted data.
Returns a <literal>Promise</literal> with the decrypted data.
Possible values:

<list type="tag">

<tag-name id="crypto_decrypt_alg"><literal>algorithm</literal></tag-name>
<tag-desc>
an object
that specifies the algorithm to be used, and any extra parameters as required.
The values given for the extra parameters must match
those passed into the corresponding <literal>encrypt()</literal> call.

<list type="bullet">
<listitem>
for <literal>RSA-OAEP</literal>,
pass the object with the following keys:

<list type="bullet">

<listitem>
<literal>name</literal> is a string,
should be set to <literal>RSA-OAEP</literal>:
<para>
<example>
crypto.subtle.encrypt({name: "RSA-OAEP"}, key, data)
</example>
</para>
</listitem>
</list>
</listitem>

<listitem>
for <literal>AES-CTR</literal>,
pass the object with the following keys:

<list type="bullet">

<listitem>
<literal>name</literal> is a string,
should be set to <literal>AES-CTR</literal>
</listitem>

<listitem>
<literal>counter</literal> is an
<literal>ArrayBuffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal> —
the initial value of the counter block,
must be 16 bytes long (the AES block size).
The rightmost length bits of this block are used for the counter,
and the rest is used for the nonce.
For example, if length is set to 64,
then the first half of counter is the nonce
and the second half is used for the counter.
</listitem>

<listitem>
<literal>length</literal> is the number of bits in the counter block
that are used for the actual counter.
The counter must be big enough that it doesn't wrap.
</listitem>
</list>

</listitem>

<listitem>
for <literal>AES-CBC</literal>, pass the object with the following keys:

<list type="bullet">

<listitem>
<literal>name</literal> is a string,
should be set to <literal>AES-CBC</literal>
</listitem>

<listitem>
<literal>iv</literal> or the initialization vector, is an
<literal>ArrayBuffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>,
must be 16 bytes, unpredictable,
and preferably cryptographically random.
However, it need not be secret
(for example, it may be transmitted unencrypted along with the ciphertext).
</listitem>
</list>

</listitem>

<listitem>
for <literal>AES-GCM</literal>, pass the object with the following keys:

<list type="bullet">

<listitem>
<literal>name</literal> is a string,
should be set to <literal>AES-GCM</literal>
</listitem>

<listitem>
<literal>iv</literal> or the initialization vector, is an
<literal>ArrayBuffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>,
must be 16 bytes,
and must be unique for every encryption operation carried out with a given key
</listitem>

<listitem>
<literal>additionalData</literal> (optional) is an
<literal>ArrayBuffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
that contains additional data that
will not be encrypted but will be authenticated along with the encrypted data.
If <literal>additionalData</literal> is specified,
then the same data must be specified in the corresponding call to
<literal>decrypt()</literal>:
if the data given to the <literal>decrypt()</literal> call
does not match the original data,
the decryption will throw an exception.
The bit length of <literal>additionalData</literal>
must be smaller than <literal>2^64 - 1</literal>.
</listitem>

<listitem>
<literal>tagLength</literal> (optional, default is <literal>128</literal>) -
a <literal>number</literal> that determines the size in bits
of the authentication tag generated in the encryption operation
and used for authentication in the corresponding decryption.
Possible values:
<literal>32</literal>,
<literal>64</literal>,
<literal>96</literal>,
<literal>104</literal>,
<literal>112</literal>,
<literal>120</literal>, or
<literal>128</literal>.
The AES-GCM specification recommends that it should be
<literal>96</literal>,
<literal>104</literal>,
<literal>112</literal>,
<literal>120</literal>, or
<literal>128</literal>,
although
<literal>32</literal> or
<literal>64</literal>
bits may be acceptable in some applications.
</listitem>
</list>

</listitem>
</list>

</tag-desc>

<tag-name id="crypto_decrypt_key"><literal>key</literal></tag-name>
<tag-desc>
a <link id="cryptokey"><literal>CryptoKey</literal></link>
that contains the key to be used for decryption.
If <literal>RSA-OAEP</literal> is used, this is the
<literal>privateKey</literal> property of the
<link id="cryptokeypair"><literal>CryptoKeyPair</literal></link> object.
</tag-desc>

<tag-name id="crypto_decrypt_data"><literal>data</literal></tag-name>
<tag-desc>
an
<literal>ArrayBuffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
that contains the data to be decrypted (also known as ciphertext)
</tag-desc>
</list>

</tag-desc>

<tag-name id="crypto_subtle_derive_bits"><literal>сrypto.subtle.deriveBits</literal>(<link id="crypto_derive_bits_alg"><literal>algorithm</literal></link>,
<link id="crypto_derive_bits_basekey"><literal>baseKey</literal></link>,
<link id="crypto_derive_bits_length"><literal>length</literal></link>)</tag-name>
<tag-desc>
Derives an array of bits from a base key.
Returns a <literal>Promise</literal>
which will be fulfilled with an
<literal>ArrayBuffer</literal> that contains the derived bits.
Possible values:

<list type="tag">
<tag-name id="crypto_derive_bits_alg"><literal>algorithm</literal></tag-name>
<tag-desc>
is an object that defines the derivation algorithm to use:

<list type="bullet">
<listitem id="hkdf_params">
for <literal>HKDF</literal>,
pass the object with the following keys:

<list type="bullet">

<listitem>
<literal>name</literal> is a string,
should be set to <literal>HKDF</literal>
</listitem>

<listitem>
<literal>hash</literal> is a string with the digest algorithm to use:
<literal>SHA-1</literal>,
<literal>SHA-256</literal>,
<literal>SHA-384</literal>, or
<literal>SHA-512</literal>
</listitem>

<listitem>
<literal>salt</literal> is an
<literal>ArrayBuffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
that represents random or pseudo-random value
with the same length as the output of the <literal>digest</literal> function.
Unlike the input key material passed into <literal>deriveKey()</literal>,
salt does not need to be kept secret.
</listitem>

<listitem>
<literal>info</literal> is an
<literal>ArrayBuffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
that represents application-specific contextual information
used to bind the derived key to an application or context,
and enables deriving different keys for different contexts
while using the same input key material.
This property is required but may be an empty buffer.
</listitem>
</list>

</listitem>

<listitem id="pbkdf2_params">
for <literal>PBKDF2</literal>,
pass the object with the following keys:

<list type="bullet">

<listitem>
<literal>name</literal> is a string,
should be set to <literal>PBKDF2</literal>
</listitem>

<listitem>
<literal>hash</literal> is a string with the digest algorithm to use:
<literal>SHA-1</literal>,
<literal>SHA-256</literal>,
<literal>SHA-384</literal>, or
<literal>SHA-512</literal>
</listitem>

<listitem>
<literal>salt</literal> is an
<literal>ArrayBuffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
that represents random or pseudo-random value
of at least <literal>16</literal> bytes.
Unlike the input key material passed into <literal>deriveKey()</literal>,
salt does not need to be kept secret.
</listitem>

<listitem>
<literal>iterations</literal> is a <literal>number</literal>
that represents the number of times the hash function will be executed
in <literal>deriveKey()</literal>
</listitem>
</list>

</listitem>
</list>

</tag-desc>

<tag-name id="crypto_derive_bits_basekey"><literal>baseKey</literal></tag-name>
<tag-desc>
is a <link id="cryptokey"><literal>CryptoKey</literal></link>
that represents the input to the derivation algorithm
- the initial key material for the derivation function:
for example, for <literal>PBKDF2</literal> it might be a password,
imported as a <link id="cryptokey"><literal>CryptoKey</literal></link> using
<link id="crypto_subtle_import_key"><literal>сrypto.subtle.importKey()</literal></link>
</tag-desc>

<tag-name id="crypto_derive_bits_length"><literal>length</literal></tag-name>
<tag-desc>
is a number representing the number of bits to derive.
For browsers compatibility,
the number should be a multiple of <literal>8</literal>
</tag-desc>
</list>

</tag-desc>

<tag-name id="crypto_subtle_derive_key"><literal>сrypto.subtle.deriveKey</literal>(<link id="crypto_derive_key_alg"><literal>algorithm</literal></link>,
<link id="crypto_derive_key_basekey"><literal>baseKey</literal></link>,
<link id="crypto_derive_key_derivedkeyalg"><literal>derivedKeyAlgorithm</literal></link>,
<link id="crypto_derive_key_extractable"><literal>extractable</literal></link>,
<link id="crypto_derive_key_keyusages"><literal>keyUsages</literal></link>)</tag-name>
<tag-desc>
Derives a secret key from a master key.
Possible values:

<list type="tag">
<tag-name id="crypto_derive_key_alg"><literal>algorithm</literal></tag-name>
<tag-desc>
is an object that defines the derivation algorithm to use:

<list type="bullet">
<listitem>
for <literal>HKDF</literal>,
pass the object with the following keys:

<list type="bullet">

<listitem>
<literal>name</literal> is a string,
should be set to <literal>HKDF</literal>
</listitem>

<listitem>
<literal>hash</literal> is a string with the digest algorithm to use:
<literal>SHA-1</literal>,
<literal>SHA-256</literal>,
<literal>SHA-384</literal>, or
<literal>SHA-512</literal>
</listitem>

<listitem>
<literal>salt</literal> is an
<literal>ArrayBuffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
that represents random or pseudo-random value
with the same length as the output of the <literal>digest</literal> function.
Unlike the input key material passed into <literal>deriveKey()</literal>,
salt does not need to be kept secret.
</listitem>

<listitem>
<literal>info</literal> is an
<literal>ArrayBuffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
that represents application-specific contextual information
used to bind the derived key to an application or context,
and enables deriving different keys for different contexts
while using the same input key material.
This property is required but may be an empty buffer.
</listitem>
</list>

</listitem>

<listitem>
for <literal>PBKDF2</literal>,
pass the object with the following keys:

<list type="bullet">

<listitem>
<literal>name</literal> is a string,
should be set to <literal>PBKDF2</literal>
</listitem>

<listitem>
<literal>hash</literal> is a string with the digest algorithm to use:
<literal>SHA-1</literal>,
<literal>SHA-256</literal>,
<literal>SHA-384</literal>, or
<literal>SHA-512</literal>
</listitem>

<listitem>
<literal>salt</literal> is an
<literal>ArrayBuffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
that represents random or pseudo-random value
of at least <literal>16</literal> bytes.
Unlike the input key material passed into <literal>deriveKey()</literal>,
salt does not need to be kept secret.
</listitem>

<listitem>
<literal>iterations</literal> is a <literal>number</literal>
that represents the number of times the hash function will be executed
in <literal>deriveKey()</literal>
</listitem>
</list>

</listitem>
</list>

</tag-desc>

<tag-name id="crypto_derive_key_basekey"><literal>baseKey</literal></tag-name>
<tag-desc>
is a <link id="cryptokey"><literal>CryptoKey</literal></link>
that represents the input to the derivation algorithm
- the initial key material for the derivation function:
for example, for <literal>PBKDF2</literal> it might be a password,
imported as a <link id="cryptokey"><literal>CryptoKey</literal></link> using
<link id="crypto_subtle_import_key"><literal>сrypto.subtle.importKey()</literal></link>.
</tag-desc>

<tag-name id="crypto_derive_key_derivedkeyalg"><literal>derivedKeyAlgorithm</literal></tag-name>
<tag-desc>
is an object
that defines the algorithm the derived key will be used for:

<list type="bullet">
<listitem>
for <literal>HMAC</literal>,
pass the object with the following keys:

<list type="bullet">

<listitem>
<literal>name</literal> is a string,
should be set to <literal>HMAC</literal>
</listitem>

<listitem>
<literal>hash</literal> is a string with the name of the digest function to use:
<literal>SHA-1</literal>,
<literal>SHA-256</literal>,
<literal>SHA-384</literal>, or
<literal>SHA-512</literal>
</listitem>

<listitem>
<literal>length</literal> (optional) is a <literal>number</literal>
that represents the length in bits of the key.
If not specified, the length of the key is equal to
the block size of the chozen hash function
</listitem>
</list>

</listitem>

<listitem>
for
<literal>AES-CTR</literal>,
<literal>AES-CBC</literal>, or
<literal>AES-GCM</literal>,
pass the object with the following keys:

<list type="bullet">

<listitem>
<literal>name</literal> is a string,
should be set to
<literal>AES-CTR</literal>,
<literal>AES-CBC</literal>, or
<literal>AES-GCM</literal>,
depending on the algorithm used
</listitem>

<listitem>
<literal>length</literal> is a <literal>number</literal> that represents
the length in bits of the key to generate:
<literal>128</literal>,
<literal>192</literal>, or
<literal>256</literal>
</listitem>
</list>

</listitem>
</list>

</tag-desc>

<tag-name id="crypto_derive_key_extractable"><literal>extractable</literal></tag-name>
<tag-desc>
is a boolean value
that indicates whether it will be possible to export the key
</tag-desc>

<tag-name id="crypto_derive_key_keyusages"><literal>keyUsages</literal></tag-name>
<tag-desc>
is an <literal>Array</literal>
that indicates what can be done with the derived key.
The key usages must be allowed by the algorithm
set in <literal>derivedKeyAlgorithm</literal>.
Possible values:
<list type="tag">

<tag-name><literal>encrypt</literal></tag-name>
<tag-desc>
key for encrypting messages
</tag-desc>

<tag-name><literal>decrypt</literal></tag-name>
<tag-desc>
key for decrypting messages
</tag-desc>

<tag-name><literal>sign</literal></tag-name>
<tag-desc>
key for signing messages
</tag-desc>

<tag-name><literal>verify</literal></tag-name>
<tag-desc>
key for verifying signatures
</tag-desc>

<tag-name><literal>deriveKey</literal></tag-name>
<tag-desc>
key for deriving a new key
</tag-desc>

<tag-name><literal>deriveBits</literal></tag-name>
<tag-desc>
key for deriving bits
</tag-desc>

<tag-name><literal>wrapKey</literal></tag-name>
<tag-desc>
key for wrapping a key
</tag-desc>

<tag-name><literal>unwrapKey</literal></tag-name>
<tag-desc>
key for unwrapping a key
</tag-desc>
</list>

</tag-desc>
</list>

</tag-desc>

<tag-name id="crypto_subtle_digest"><literal>сrypto.subtle.digest</literal>(<link id="crypto_digest_alg"><literal>algorithm</literal></link>,
<link id="crypto_digest_data"><literal>data</literal></link>)</tag-name>
<tag-desc>
Generates a digest of the given data.
Takes as its arguments an identifier for the digest algorithm to use
and the data to digest.
Returns a <literal>Promise</literal> which will be fulfilled with the digest.
Possible values:

<list type="tag">
<tag-name id="crypto_digest_alg"><literal>algorithm</literal></tag-name>
<tag-desc>
is a string that defines the hash function to use:
<literal>SHA-1</literal> (not for cryptographic applications),
<literal>SHA-256</literal>,
<literal>SHA-384</literal>, or
<literal>SHA-512</literal>
</tag-desc>

<tag-name id="crypto_digest_data"><literal>data</literal></tag-name>
<tag-desc>
is an
<literal>ArrayBuffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
that contains the data to be digested
</tag-desc>
</list>

</tag-desc>

<tag-name id="crypto_subtle_export_key"><literal>сrypto.subtle.exportKey</literal>(<link id="crypto_export_key_format"><literal>format</literal></link>,
<link id="crypto_export_key_keydata"><literal>key</literal></link>)</tag-name>
<tag-desc>
Exports a key: takes a key as
a <link id="cryptokey"><literal>CryptoKey</literal></link> object
and returns the key in an external, portable format
(since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>).
If the <literal>format</literal> was <literal>jwk</literal>,
then the <literal>Promise</literal> fulfills with a JSON object
containing the key.
Otherwise, the promise fulfills with an
<literal>ArrayBuffer</literal> containing the key.
Possible values:
<list type="tag">

<tag-name id="crypto_export_key_format"><literal>format</literal></tag-name>
<tag-desc>
a string that describes the data format in which the key should be exported,
can be the following:
<list type="tag">

<tag-name><literal>raw</literal></tag-name>
<tag-desc>
the raw data format
</tag-desc>

<tag-name><literal>pkcs8</literal></tag-name>
<tag-desc>
the
<link url="https://datatracker.ietf.org/doc/html/rfc5208">PKCS #8</link>
format
</tag-desc>

<tag-name><literal>spki</literal></tag-name>
<tag-desc>
the
<link url="https://datatracker.ietf.org/doc/html/rfc5280#section-4.1">SubjectPublicKeyInfo</link>
format
</tag-desc>

<tag-name><literal>jwk</literal></tag-name>
<tag-desc>
the
<link url="https://datatracker.ietf.org/doc/html/rfc7517">JSON Web Key</link>
(JWK) format (since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>)
</tag-desc>

</list>
</tag-desc>

<tag-name id="crypto_export_key_keydata"><literal>key</literal></tag-name>
<tag-desc>
the <link id="cryptokey"><literal>CryptoKey</literal></link>
that contains the key to be exported
</tag-desc>
</list>

</tag-desc>

<tag-name id="crypto_subtle_generate_key"><literal>сrypto.subtle.generateKey</literal>(<link id="crypto_generate_key_alg"><literal>algorithm</literal></link>,
<link id="crypto_generate_key_extractable"><literal>extractable</literal></link>,
<link id="crypto_generate_key_usage"><literal>usage</literal></link>)</tag-name>
<tag-desc>
Generates a new key for symmetric algorithms
or key pair for public-key algorithms
(since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>).
Returns a <literal>Promise</literal> that fulfills with the generated key
as
a <link id="cryptokey"><literal>CryptoKey</literal></link>
or <link id="cryptokeypair"><literal>CryptoKeyPair</literal></link> object.
Possible values:
<list type="tag">

<tag-name id="crypto_generate_key_alg"><literal>algorithm</literal></tag-name>
<tag-desc>
a dictionary object that defines the type of key to generate
and provides extra algorithm-specific parameters:

<list type="bullet">
<listitem>
for
<literal>RSASSA-PKCS1-v1_5</literal>,
<literal>RSA-PSS</literal>, or
<literal>RSA-OAEP</literal>,
pass the object with the following keys:

<list type="bullet">
<listitem>
<literal>name</literal> is a string, should be set to
<literal>RSASSA-PKCS1-v1_5</literal>,
<literal>RSA-PSS</literal>, or
<literal>RSA-OAEP</literal>,
depending on the used algorithm
</listitem>

<listitem>
<literal>hash</literal> is a string that represents
the name of the <literal>digest</literal> function to use, can be
<literal>SHA-256</literal>,
<literal>SHA-384</literal>, or
<literal>SHA-512</literal>
</listitem>
</list>

</listitem>

<listitem>
for
<literal>ECDSA</literal>,
pass the object with the following keys:

<list type="bullet">
<listitem>
<literal>name</literal> is a string, should be set to <literal>ECDSA</literal>
</listitem>

<listitem>
<literal>namedCurve</literal> is a string that represents
the name of the elliptic curve to use, may be
<literal>P-256</literal>,
<literal>P-384</literal>, or
<literal>P-521</literal>
</listitem>

</list>
</listitem>

<listitem>
for
<literal>HMAC</literal>,
pass the object with the following keys:

<list type="bullet">
<listitem>
<literal>name</literal> is a string, should be set to <literal>HMAC</literal>
</listitem>


<listitem>
<literal>hash</literal> is a string that represents
the name of the <literal>digest</literal> function to use, can be
<literal>SHA-256</literal>,
<literal>SHA-384</literal>, or
<literal>SHA-512</literal>
</listitem>

<listitem>
<literal>length</literal> (optional) is a number that represents
the length in bits of the key.
If omitted, the length of the key is equal to the length of the digest
generated by the chosen digest function.
</listitem>
</list>

</listitem>

<listitem>
for
<literal>AES-CTR</literal>,
<literal>AES-CBC</literal>, or
<literal>AES-GCM</literal>,
pass the string identifying the algorithm or an object
of the form <literal>{ "name": "ALGORITHM" }</literal>,
where <literal>ALGORITHM</literal> is the name of the algorithm
</listitem>

</list>
</tag-desc>

<tag-name id="crypto_generate_key_extractable"><literal>extractable</literal></tag-name>
<tag-desc>
boolean value that indicates if it is possible to export the key
</tag-desc>

<tag-name id="crypto_generate_key_usage"><literal>usage</literal></tag-name>
<tag-desc>
an <literal>array</literal> that indicates possible actions with the key:
<list type="tag">

<tag-name><literal>encrypt</literal></tag-name>
<tag-desc>
key for encrypting messages
</tag-desc>

<tag-name><literal>decrypt</literal></tag-name>
<tag-desc>
key for decrypting messages
</tag-desc>

<tag-name><literal>sign</literal></tag-name>
<tag-desc>
key for signing messages
</tag-desc>

<tag-name><literal>verify</literal></tag-name>
<tag-desc>
key for verifying signatures
</tag-desc>

<tag-name><literal>deriveKey</literal></tag-name>
<tag-desc>
key for deriving a new key
</tag-desc>

<tag-name><literal>deriveBits</literal></tag-name>
<tag-desc>
key for deriving bits
</tag-desc>

<tag-name><literal>wrapKey</literal></tag-name>
<tag-desc>
key for wrapping a key
</tag-desc>

<tag-name><literal>unwrapKey</literal></tag-name>
<tag-desc>
key for unwrapping a key
</tag-desc>
</list>

</tag-desc>
</list>

</tag-desc>

<tag-name id="crypto_subtle_import_key"><literal>сrypto.subtle.importKey</literal>(<link id="crypto_import_key_format"><literal>format</literal></link>,
<link id="crypto_import_key_keydata"><literal>keyData</literal></link>,
<link id="crypto_import_key_alg"><literal>algorithm</literal></link>,
<link id="crypto_import_key_extractable"><literal>extractable</literal></link>,
<link id="crypto_import_key_keyusages"><literal>keyUsages</literal></link>)</tag-name>
<tag-desc>
Imports a key: takes as input a key in an external, portable format
and gives a <link id="cryptokey"><literal>CryptoKey</literal></link> object.
Returns a <literal>Promise</literal> that fulfills with the imported key
as a <link id="cryptokey"><literal>CryptoKey</literal></link> object.
Possible values:
<list type="tag">

<tag-name id="crypto_import_key_format"><literal>format</literal></tag-name>
<tag-desc>
a string that describes the data format of the key to import,
can be the following:
<list type="tag">

<tag-name><literal>raw</literal></tag-name>
<tag-desc>
the raw data format
</tag-desc>

<tag-name><literal>pkcs8</literal></tag-name>
<tag-desc>
the
<link url="https://datatracker.ietf.org/doc/html/rfc5208">PKCS #8</link>
format
</tag-desc>

<tag-name><literal>spki</literal></tag-name>
<tag-desc>
the
<link url="https://datatracker.ietf.org/doc/html/rfc5280#section-4.1">SubjectPublicKeyInfo</link>
format
</tag-desc>

<tag-name><literal>jwk</literal></tag-name>
<tag-desc>
the
<link url="https://datatracker.ietf.org/doc/html/rfc7517">JSON Web Key</link>
(JWK) format (since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>)
</tag-desc>

</list>

</tag-desc>

<tag-name id="crypto_import_key_keydata"><literal>keyData</literal></tag-name>
<tag-desc>
the
<literal>ArrayBuffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
object that contains the key in the given format
</tag-desc>

<tag-name id="crypto_import_key_alg"><literal>algorithm</literal></tag-name>
<tag-desc>
a dictionary object that defines the type of key to import
and provides extra algorithm-specific parameters:

<list type="bullet">
<listitem>
for
<literal>RSASSA-PKCS1-v1_5</literal>,
<literal>RSA-PSS</literal>, or
<literal>RSA-OAEP</literal>,
pass the object with the following keys:

<list type="bullet">
<listitem>
<literal>name</literal> is a string, should be set to
<literal>RSASSA-PKCS1-v1_5</literal>,
<literal>RSA-PSS</literal>, or
<literal>RSA-OAEP</literal>,
depending on the used algorithm
</listitem>

<listitem>
<literal>hash</literal> is a string that represents
the name of the <literal>digest</literal> function to use, can be
<literal>SHA-1</literal>,
<literal>SHA-256</literal>,
<literal>SHA-384</literal>, or
<literal>SHA-512</literal>
</listitem>
</list>

</listitem>

<listitem>
for
<literal>ECDSA</literal>,
pass the object with the following keys:

<list type="bullet">
<listitem>
<literal>name</literal> is a string, should be set to <literal>ECDSA</literal>
</listitem>

<listitem>
<literal>namedCurve</literal> is a string that represents
the name of the elliptic curve to use, may be
<literal>P-256</literal>,
<literal>P-384</literal>, or
<literal>P-521</literal>
</listitem>

</list>
</listitem>

<listitem>
for
<literal>HMAC</literal>,
pass the object with the following keys:

<list type="bullet">
<listitem>
<literal>name</literal> is a string, should be set to <literal>HMAC</literal>
</listitem>


<listitem>
<literal>hash</literal> is a string that represents
the name of the <literal>digest</literal> function to use, can be
<literal>SHA-256</literal>,
<literal>SHA-384</literal>, or
<literal>SHA-512</literal>
</listitem>

<listitem>
<literal>length</literal> (optional) is a number that represents
the length in bits of the key.
If omitted, the length of the key is equal to the length of the digest
generated by the chosen digest function.
</listitem>
</list>

</listitem>

<listitem>
for
<literal>AES-CTR</literal>,
<literal>AES-CBC</literal>, or
<literal>AES-GCM</literal>,
pass the string identifying the algorithm or an object
of the form <literal>{ "name": "ALGORITHM" }</literal>,
where <literal>ALGORITHM</literal> is the name of the algorithm
</listitem>

<listitem>
for
<literal>PBKDF2</literal>,
pass the <literal>PBKDF2</literal> string
</listitem>

<listitem>
for
<literal>HKDF</literal>,
pass the <literal>HKDF</literal> string
</listitem>

</list>
</tag-desc>

<tag-name id="crypto_import_key_extractable"><literal>extractable</literal></tag-name>
<tag-desc>
boolean value that indicates if it is possible to export the key
</tag-desc>

<tag-name id="crypto_import_key_keyusages"><literal>keyUsages</literal></tag-name>
<tag-desc>
an <literal>array</literal> that indicates possible actions with the key:
<list type="tag">

<tag-name><literal>encrypt</literal></tag-name>
<tag-desc>
key for encrypting messages
</tag-desc>

<tag-name><literal>decrypt</literal></tag-name>
<tag-desc>
key for decrypting messages
</tag-desc>

<tag-name><literal>sign</literal></tag-name>
<tag-desc>
key for signing messages
</tag-desc>

<tag-name><literal>verify</literal></tag-name>
<tag-desc>
key for verifying signatures
</tag-desc>

<tag-name><literal>deriveKey</literal></tag-name>
<tag-desc>
key for deriving a new key
</tag-desc>

<tag-name><literal>deriveBits</literal></tag-name>
<tag-desc>
key for deriving bits
</tag-desc>

<tag-name><literal>wrapKey</literal></tag-name>
<tag-desc>
key for wrapping a key
</tag-desc>

<tag-name><literal>unwrapKey</literal></tag-name>
<tag-desc>
key for unwrapping a key
</tag-desc>
</list>

</tag-desc>
</list>

</tag-desc>

<tag-name id="crypto_subtle_sign"><literal>сrypto.subtle.sign</literal>(<link id="crypto_sign_alg"><literal>algorithm</literal></link>,
<link id="crypto_sign_key"><literal>key</literal></link>,
<link id="crypto_sign_data"><literal>data</literal></link>)</tag-name>
<tag-desc>
Returns <literal>signature</literal> as a <literal>Promise</literal>
that fulfills with an <literal>ArrayBuffer</literal> containing the signature.
Possible values:

<list type="tag">
<tag-name id="crypto_sign_alg"><literal>algorithm</literal></tag-name>
<tag-desc>
is a string or object that specifies the signature algorithm to use
and its parameters:

<list type="bullet">

<listitem>
for <literal>RSASSA-PKCS1-v1_5</literal>,
pass the string identifying the algorithm or an object
of the form <literal>{ "name": "ALGORITHM" }</literal>
</listitem>

<listitem>
for <literal>RSA-PSS</literal>,
pass the object with the following keys:
<list type="bullet">

<listitem>
<literal>name</literal> is a string, should be set to
<literal>RSA-PSS</literal>
</listitem>

<listitem>
<literal>saltLength</literal> is a long <literal>integer</literal>
that represents the length of the random salt to use, in bytes
</listitem>

</list>
</listitem>

<listitem>
for <literal>ECDSA</literal>,
pass the object with the following keys:
<list type="bullet">

<listitem>
<literal>name</literal> is a string, should be set to
<literal>ECDSA</literal>
</listitem>

<listitem>
<literal>hash</literal> is an identifier for the digest algorithm to use,
can be
<literal>SHA-256</literal>,
<literal>SHA-384</literal>, or
<literal>SHA-512</literal>
</listitem>

</list>
</listitem>

<listitem>
for  <literal>HMAC</literal>,
pass the string identifying the algorithm or an object
of the form <literal>{ "name": "ALGORITHM" }</literal>
</listitem>
</list>

</tag-desc>

<tag-name id="crypto_sign_key"><literal>key</literal></tag-name>
<tag-desc>
is a <link id="cryptokey"><literal>CryptoKey</literal></link> object
that the key to be used for signing.
If algorithm identifies a public-key cryptosystem, this is the private key.
</tag-desc>

<tag-name id="crypto_sign_data"><literal>data</literal></tag-name>
<tag-desc>
is an
<literal>ArrayBuffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
object that contains the data to be signed
</tag-desc>
</list>

</tag-desc>


<tag-name id="crypto_subtle_verify"><literal>сrypto.subtle.verify</literal>(<link id="crypto_verify_alg"><literal>algorithm</literal></link>,
<link id="crypto_verify_key"><literal>key</literal></link>,
<link id="crypto_verify_signature"><literal>signature</literal></link>,
<link id="crypto_verify_data"><literal>data</literal></link>)</tag-name>
<tag-desc>
Verifies a digital signature,
returns a <literal>Promise</literal> that fulfills with a boolean value:
<literal>true</literal> if the signature is valid,
otherwise <literal>false</literal>.
Possible values:

<list type="tag">
<tag-name id="crypto_verify_alg"><literal>algorithm</literal></tag-name>
<tag-desc>
is a string or object that specifies the algorithm to use
and its parameters:

<list type="bullet">

<listitem>
for <literal>RSASSA-PKCS1-v1_5</literal>,
pass the string identifying the algorithm or an object
of the form <literal>{ "name": "ALGORITHM" }</literal>
</listitem>

<listitem>
for <literal>RSA-PSS</literal>,
pass the object with the following keys:
<list type="bullet">

<listitem>
<literal>name</literal> is a string, should be set to
<literal>RSA-PSS</literal>
</listitem>

<listitem>
<literal>saltLength</literal> is a long <literal>integer</literal>
that represents the length of the random salt to use, in bytes
</listitem>

</list>
</listitem>

<listitem>
for <literal>ECDSA</literal>,
pass the object with the following keys:
<list type="bullet">

<listitem>
<literal>name</literal> is a string, should be set to
<literal>ECDSA</literal>
</listitem>

<listitem>
<literal>hash</literal> is an identifier for the digest algorithm to use,
can be
<literal>SHA-256</literal>,
<literal>SHA-384</literal>, or
<literal>SHA-512</literal>
</listitem>

</list>
</listitem>

<listitem>
for  <literal>HMAC</literal>,
pass the string identifying the algorithm or an object
of the form <literal>{ "name": "ALGORITHM" }</literal>
</listitem>
</list>

</tag-desc>

<tag-name id="crypto_verify_key"><literal>key</literal></tag-name>
<tag-desc>
is a <link id="cryptokey"><literal>CryptoKey</literal></link> object
that the key to be used for verifying.
It is the secret key for a symmetric algorithm
and the public key for a public-key system.
</tag-desc>

<tag-name id="crypto_verify_signature"><literal>signature</literal></tag-name>
<tag-desc>
is an
<literal>ArrayBuffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
that contains the signature to verify
</tag-desc>

<tag-name id="crypto_verify_data"><literal>data</literal></tag-name>
<tag-desc>
is an
<literal>ArrayBuffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
object that contains the data whose signature is to be verified
</tag-desc>
</list>

</tag-desc>

</list>
</para>

</section>


<section id="cryptokey" name="CryptoKey">

<para>
<table width="100%">
<tr><td><link id="cryptokey_alg"><literal>CryptoKey.algorithm</literal></link></td></tr>
<tr><td><link id="cryptokey_extractable"><literal>CryptoKey.extractable</literal></link></td></tr>
<tr><td><link id="cryptokey_type"><literal>CryptoKey.type</literal></link></td></tr>
<tr><td><link id="cryptokey_usages"><literal>CryptoKey.usages</literal></link></td></tr>
</table>
</para>

<para>
The <literal>CryptoKey</literal> object
represents a cryptographic <literal>key</literal> obtained
from one of the <literal>SubtleCrypto</literal> methods:
<link id="crypto_subtle_generate_key"><literal>сrypto.subtle.generateKey()</literal></link>,
<link id="crypto_subtle_derive_key"><literal>сrypto.subtle.deriveKey()</literal></link>,
<link id="crypto_subtle_import_key"><literal>сrypto.subtle.importKey()</literal></link>.
</para>

<para>
<list type="tag">

<tag-name id="cryptokey_alg"><literal>CryptoKey.algorithm</literal></tag-name>
<tag-desc>
returns an object describing the algorithm for which this key can be used
and any associated extra parameters
(since <link doc="changes.xml" id="njs0.8.0">0.8.0</link>),
read-only
</tag-desc>

<tag-name id="cryptokey_extractable"><literal>CryptoKey.extractable</literal></tag-name>
<tag-desc>
a boolean value, <literal>true</literal> if the key can be exported
(since <link doc="changes.xml" id="njs0.8.0">0.8.0</link>),
read-only
</tag-desc>

<tag-name id="cryptokey_type"><literal>CryptoKey.type</literal></tag-name>
<tag-desc>
a string value that indicates which kind of key is represented by the object,
read-only.
Possible values:
<list type="tag">

<tag-name><literal>secret</literal></tag-name>
<tag-desc>
This key is a secret key for use with a symmetric algorithm.
</tag-desc>

<tag-name><literal>private</literal></tag-name>
<tag-desc>
This key is the private half of an asymmetric algorithm's
<link id="cryptokeypair"><literal>CryptoKeyPair</literal></link>
</tag-desc>

<tag-name><literal>public</literal></tag-name>
<tag-desc>
This key is the public half of an asymmetric algorithm's
<link id="cryptokeypair"><literal>CryptoKeyPair</literal></link>.
</tag-desc>

</list>
</tag-desc>

<tag-name id="cryptokey_usages"><literal>CryptoKey.usages</literal></tag-name>
<tag-desc>
An array of strings indicating what this key can be used for
(since <link doc="changes.xml" id="njs0.8.0">0.8.0</link>),
read-only.
Possible array values:
<list type="tag">

<tag-name><literal>encrypt</literal></tag-name>
<tag-desc>
key for encrypting messages
</tag-desc>

<tag-name><literal>decrypt</literal></tag-name>
<tag-desc>
key for decrypting messages
</tag-desc>

<tag-name><literal>sign</literal></tag-name>
<tag-desc>
key for signing messages
</tag-desc>

<tag-name><literal>verify</literal></tag-name>
<tag-desc>
key for verifying signatures
</tag-desc>

<tag-name><literal>deriveKey</literal></tag-name>
<tag-desc>
key for deriving a new key
</tag-desc>

<tag-name><literal>deriveBits</literal></tag-name>
<tag-desc>
key for deriving bits
</tag-desc>

</list>
</tag-desc>

</list>
</para>

</section>


<section id="cryptokeypair" name="CryptoKeyPair">

<para>
<table width="100%">
<tr><td><link id="cryptokeypair_privatekey"><literal>CryptoKeyPair.privateKey</literal></link></td></tr>
<tr><td><link id="cryptokeypair_publickey"><literal>CryptoKeyPair.publicKey</literal></link></td></tr>
</table>
</para>

<para>
The <literal>CryptoKeyPair</literal> is a dictionary object
of the <link id="builtin_crypto">WebCrypto API</link>
that represents an asymmetric key pair.
</para>

<para>
<list type="tag">

<tag-name id="cryptokeypair_privatekey"><literal>CryptoKeyPair.privateKey</literal></tag-name>
<tag-desc>
A <link id="cryptokey"><literal>CryptoKey</literal></link> object
representing the private key.
</tag-desc>

<tag-name id="cryptokeypair_publickey"><literal>CryptoKeyPair.publicKey</literal></tag-name>
<tag-desc>
A <link id="cryptokey"><literal>CryptoKey</literal></link> object
representing the public key.
</tag-desc>

</list>
</para>

</section>


<section id="njs" name="njs">

<para>
<table width="100%">
<tr><td><link id="njs_version"><literal>njs.version</literal></link></td></tr>
<tr><td><link id="njs_version_number"><literal>njs.version_number</literal></link></td></tr>
<tr><td><link id="njs_dump"><literal>njs.dump()</literal></link></td></tr>
<tr><td><link id="njs_memory_stats"><literal>njs.memoryStats</literal></link></td></tr>
<tr><td><link id="njs_on"><literal>njs.on()</literal></link></td></tr>
</table>
</para>

<para>
The <literal>njs</literal> object is a global object
that represents the current VM instance
(since <link doc="changes.xml" id="njs0.2.0">0.2.0</link>).
</para>

<para>
<list type="tag">

<tag-name id="njs_version"><literal>njs.version</literal></tag-name>
<tag-desc>
Returns a string with the current version of njs
(for example, “0.7.4”).
</tag-desc>

<tag-name id="njs_version_number"><literal>njs.version_number</literal></tag-name>
<tag-desc>
Returns a number with the current version of njs.
For example, “0.7.4” is returned as <literal>0x000704</literal>
(since <link doc="changes.xml" id="njs0.7.4">0.7.4</link>).
</tag-desc>

<tag-name id="njs_dump"><literal>njs.dump(<value>value</value>)</literal></tag-name>
<tag-desc>
Returns the pretty-print string representation for a value.
</tag-desc>

<tag-name id="njs_memory_stats"><literal>njs.memoryStats</literal></tag-name>
<tag-desc>
Object containing memory statistics for current VM instance
(since <link doc="changes.xml" id="njs0.7.8">0.7.8</link>).
<list type="tag">

<tag-name><literal>size</literal></tag-name>
<tag-desc>
amount of memory in bytes njs memory pool claimed from the operating system.
</tag-desc>

</list>
</tag-desc>

<tag-name id="njs_on"><literal>njs.on(<value>event</value>,
<value>callback</value>)</literal></tag-name>
<tag-desc>
Registers a callback for the specified VM event
(since <link doc="changes.xml" id="njs0.5.2">0.5.2</link>).
An event may be one of the following strings:
<list type="tag">

<tag-name><literal>exit</literal></tag-name>
<tag-desc>
is called before the VM is destroyed.
The callback is called without arguments.
</tag-desc>

</list>
</tag-desc>

</list>
</para>

</section>


<section id="process" name="process">

<para>
<table width="100%">
<tr><td><link id="process_argv"><literal>process.argv</literal></link></td></tr>
<tr><td><link id="process_env"><literal>process.env</literal></link></td></tr>
<tr><td><link id="process_pid"><literal>process.pid</literal></link></td></tr>
<tr><td><link id="process_ppid"><literal>process.ppid</literal></link></td></tr>
</table>
</para>

<para>
The <literal>process</literal> object is a global object
that provides information about the current process
(<link doc="changes.xml" id="njs0.3.3">0.3.3</link>).
</para>

<para>
<list type="tag">

<tag-name id="process_argv"><literal>process.argv</literal></tag-name>
<tag-desc>
Returns an array that contains the command line arguments
passed when the current process was launched.
</tag-desc>

<tag-name id="process_env"><literal>process.env</literal></tag-name>
<tag-desc>
Returns an object containing the user environment.
<note>
By default, nginx removes all environment variables inherited
from its parent process except the TZ variable.
Use the <link doc="../ngx_core_module.xml" id="env"/> directive
to preserve some of the inherited variables.
</note>
</tag-desc>

<tag-name id="process_pid"><literal>process.pid</literal></tag-name>
<tag-desc>
Returns the PID of the current process.
</tag-desc>

<tag-name id="process_ppid"><literal>process.ppid</literal></tag-name>
<tag-desc>
Returns the PID of the current parent process.
</tag-desc>

</list>
</para>

</section>


<section id="string" name="String">

<para>
By default all strings in njs are Unicode strings.
They correspond to ECMAScript strings that contain Unicode characters.
Before <link doc="changes.xml" id="njs0.8.0">0.8.0</link>,
byte strings were also supported.
</para>

<section id="byte_string" name="Byte strings">

<para>
<note>
Since <link doc="changes.xml" id="njs0.8.0">0.8.0</link>,
the support for byte strings and byte string methods were removed.
When working with byte sequence,
the <link id="buffer">Buffer</link> object
and <literal>Buffer</literal> properties, such as
<link id="r_request_buffer"><literal>r.requestBuffer</literal></link>,
<link id="r_raw_variables"><literal>r.rawVariables</literal></link>,
should be used.
</note>
</para>

<para>
Byte strings contain a sequence of bytes
and are used to serialize Unicode strings
to external data and deserialize from external sources.
For example, the <link id="string_toutf8">toUTF8()</link> method serializes
a Unicode string to a byte string using UTF-8 encoding:
<example>
>> '£'.toUTF8().toString('hex')
'c2a3'  /* C2 A3 is the UTF-8 representation of 00A3 ('£') code point */
</example>
The <link id="string_tobytes">toBytes()</link> method serializes
a Unicode string with code points up to 255 into a byte string,
otherwise, <literal>null</literal> is returned:
<example>
>> '£'.toBytes().toString('hex')
'a3'  /* a3 is a byte equal to 00A3 ('£') code point  */
</example>

<list type="tag">

<tag-name id="string_bytesfrom"><literal>String.bytesFrom(<value>array</value>
| <value>string</value>, <value>encoding</value>)</literal></tag-name>
<tag-desc>
The method was made obsolete in
<link doc="changes.xml" id="njs0.4.4">0.4.4</link>
and was removed in <link doc="changes.xml" id="njs0.8.0">0.8.0</link>.
The <literal>Buffer.from</literal> method should be used instead:
<example>
>> Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]).toString()
'buffer'

>> Buffer.from('YnVmZmVy', 'base64').toString()
'buffer'
</example>
Before <link doc="changes.xml" id="njs0.4.4">0.4.4</link>,
created a byte string either from an array that contained octets,
or from an encoded string
(<link doc="changes.xml" id="njs0.2.3">0.2.3</link>),
the encoding could be
<literal>hex</literal>,
<literal>base64</literal>, and
<literal>base64url</literal>.
</tag-desc>

<tag-name id="string_frombytes"><literal>String.prototype.fromBytes(<value>start</value>[,
<value>end</value>])</literal></tag-name>
<tag-desc>
the property was made obsolete in
<link doc="changes.xml" id="njs0.7.7">0.7.7</link>
and was removed in <link doc="changes.xml" id="njs0.8.0">0.8.0</link>.
Before <link doc="changes.xml" id="njs0.7.7">0.7.7</link>,
returned a new Unicode string from a byte string
where each byte was replaced with a corresponding Unicode code point.
</tag-desc>

<tag-name id="string_fromutf8"><literal>String.prototype.fromUTF8(<value>start</value>[,
<value>end</value>])</literal></tag-name>
<tag-desc>
the property was made obsolete in
<link doc="changes.xml" id="njs0.7.7">0.7.7</link>
and was removed in <link doc="changes.xml" id="njs0.8.0">0.8.0</link>.
The <link id="textedeoder"><literal>TextDecoder</literal></link> method
should be used instead.
Before <link doc="changes.xml" id="njs0.7.7">0.7.7</link>,
converted a byte string containing a valid UTF-8 string
into a Unicode string,
otherwise <literal>null</literal> was returned.
</tag-desc>

<tag-name id="string_tobytes"><literal>String.prototype.toBytes(<value>start</value>[,
<value>end</value>])</literal></tag-name>
<tag-desc>
the property was made obsolete in
<link doc="changes.xml" id="njs0.7.7">0.7.7</link>
and was removed in <link doc="changes.xml" id="njs0.8.0">0.8.0</link>.
Before <link doc="changes.xml" id="njs0.7.7">0.7.7</link>,
serialized a Unicode string to a byte string,
returned <literal>null</literal> if a character larger than 255 was
found in the string.
</tag-desc>

<tag-name id="string_tostring"><literal>String.prototype.toString(<value>encoding</value>)</literal></tag-name>
<tag-desc>
<para>
the property was made obsolete in
<link doc="changes.xml" id="njs0.7.7">0.7.7</link>
and was removed in <link doc="changes.xml" id="njs0.8.0">0.8.0</link>.
Before <link doc="changes.xml" id="njs0.7.7">0.7.7</link>,
encoded a string to
<literal>hex</literal>,
<literal>base64</literal>, or
<literal>base64url</literal>:
<example>
>>  'αβγδ'.toString('base64url')
'zrHOss6zzrQ'
</example>
Before version <link doc="changes.xml" id="njs0.4.3">0.4.3</link>,
only a <link id="string_tobytes">byte string</link> could be encoded:
<example>
>>  'αβγδ'.toUTF8().toString('base64url')
'zrHOss6zzrQ'
</example>
</para>
</tag-desc>

<tag-name id="string_toutf8"><literal>String.prototype.toUTF8(<value>start</value>[,
<value>end</value>])</literal></tag-name>
<tag-desc>
the property was made obsolete in
<link doc="changes.xml" id="njs0.7.7">0.7.7</link>
and was removed in <link doc="changes.xml" id="njs0.8.0">0.8.0</link>.
The <link id="textencoder"><literal>TextEncoder</literal></link> method
should be used instead.
Before <link doc="changes.xml" id="njs0.7.7">0.7.7</link>,
serialized a Unicode string
to a byte string using UTF-8 encoding:
<example>
>> 'αβγδ'.toUTF8().length
8
>> 'αβγδ'.length
4
</example>
</tag-desc>

</list>
</para>

</section>

</section>

</section>


<section id="webapi" name="web API">


<section id="textdecoder" name="Text Decoder">

<para>
<table width="100%">
<tr><td><link id="textdecoder_constructor"><literal>TextDecoder()</literal></link></td></tr>
<tr><td><link id="textdecoder_encoding"><literal>TextDecoder.prototype.encoding</literal></link></td></tr>
<tr><td><link id="textdecoder_fatal"><literal>TextDecoder.prototype.fatal</literal></link></td></tr>
<tr><td><link id="textdecoder_ignorebom"><literal>TextDecoder.prototype.ignoreBOM</literal></link></td></tr>
<tr><td><link id="textdecoder_decode"><literal>TextDecoder.prototype.decode()</literal></link></td></tr>
</table>
</para>

<para>
The <literal>TextDecoder</literal>
produces a stream of code points
from a stream of bytes
(<link doc="changes.xml" id="njs0.4.3">0.4.3</link>).
</para>

<para>
<list type="tag">

<tag-name id="textdecoder_constructor"><literal>TextDecoder([[<value>encoding</value>],
<value>options</value>])</literal></tag-name>
<tag-desc>
Creates a new <literal>TextDecoder</literal> object
for specified <literal>encoding</literal>,
currently, only UTF-8 is supported.
The <literal>options</literal> is
<literal>TextDecoderOptions</literal> dictionary with the property:

<list type="tag">

<tag-name><literal>fatal</literal></tag-name>
<tag-desc>
boolean flag indicating if
<link id="textdecoder_decode"><literal>TextDecoder.decode()</literal></link>
must throw the <value>TypeError</value> exception when
a coding error is found, by default is <literal>false</literal>.
</tag-desc>

</list>
</tag-desc>

<tag-name id="textdecoder_encoding"><literal>TextDecoder.prototype.encoding</literal></tag-name>
<tag-desc>
Returns a string with the name of the encoding used by
<link id="textdecoder"><literal>TextDecoder()</literal></link>,
read-only.
</tag-desc>

<tag-name id="textdecoder_fatal"><literal>TextDecoder.prototype.fatal</literal></tag-name>
<tag-desc>
boolean flag, <literal>true</literal> if
the error mode is fatal,
read-only.
</tag-desc>

<tag-name id="textdecoder_ignorebom"><literal>TextDecoder.prototype.ignoreBOM</literal></tag-name>
<tag-desc>
boolean flag, <literal>true</literal> if
the byte order marker is ignored,
read-only.
</tag-desc>

<tag-name id="textdecoder_decode"><literal>TextDecoder.prototype.decode(<value>buffer</value>,
[<value>options</value>])</literal></tag-name>
<tag-desc>
Returns a string with the text
decoded from the <literal>buffer</literal> by
<link id="textdecoder"><literal>TextDecoder()</literal></link>.
The buffer can be <literal>ArrayBuffer</literal>.
The <literal>options</literal> is
<literal>TextDecodeOptions</literal> dictionary with the property:

<list type="tag">

<tag-name><literal>stream</literal></tag-name>
<tag-desc>
boolean flag indicating if
additional data will follow in subsequent calls to <literal>decode()</literal>:
<literal>true</literal> if processing the data in chunks, and
<literal>false</literal> for the final chunk
or if the data is not chunked.
By default is <literal>false</literal>.
</tag-desc>

</list>
<example>
>> (new TextDecoder()).decode(new Uint8Array([206,177,206,178]))
αβ
</example>
</tag-desc>

</list>
</para>

</section>


<section id="textencoder" name="Text Encoder">

<para>
<table width="100%">
<tr><td><link id="textencoder_constructor"><literal>TextEncoder()</literal></link></td></tr>
<tr><td><link id="textencoder_encode"><literal>TextEncoder.prototype.encode()</literal></link></td></tr>
<tr><td><link id="textencoder_encodeinto"><literal>TextEncoder.prototype.encodeInto()</literal></link></td></tr>
</table>
</para>

<para>
The <literal>TextEncoder</literal> object
produces a byte stream with UTF-8 encoding
from a stream of code points
(<link doc="changes.xml" id="njs0.4.3">0.4.3</link>).
</para>

<para>
<list type="tag">

<tag-name id="textencoder_constructor"><literal>TextEncoder()</literal></tag-name>
<tag-desc>
Returns a newly constructed <literal>TextEncoder</literal>
that will generate a byte stream with UTF-8 encoding.
</tag-desc>

<tag-name id="textencoder_encode"><literal>TextEncoder.prototype.encode(<value>string</value>)</literal></tag-name>
<tag-desc>
Encodes <literal>string</literal> into a <literal>Uint8Array</literal>
with UTF-8 encoded text.
</tag-desc>

<tag-name id="textencoder_encodeinto"><literal>TextEncoder.prototype.encodeInto(<value>string</value>,
<value>uint8Array</value>)</literal></tag-name>
<tag-desc>
Encodes a <literal>string</literal> to UTF-8,
puts the result into destination <literal>Uint8Array</literal>, and
returns a dictionary object that shows the progress of the encoding.
The dictionary object contains two members:

<list type="tag">

<tag-name><literal>read</literal></tag-name>
<tag-desc>
the number of UTF-16 units of code from the source <literal>string</literal>
converted to UTF-8
</tag-desc>

<tag-name><literal>written</literal></tag-name>
<tag-desc>
the number of bytes modified in the destination <literal>Uint8Array</literal>
</tag-desc>

</list>
</tag-desc>

</list>
</para>

</section>

</section>


<section id="njs_api_timers" name="timers">

<para>
<table width="100%">
<tr><td><link id="cleartimeout"><literal>clearTimeout()</literal></link></td></tr>
<tr><td><link id="settimeout"><literal>setTimeout()</literal></link></td></tr>
</table>
</para>

<para>
<list type="tag">

<tag-name id="cleartimeout"><literal>clearTimeout(<value>timeout</value>)</literal></tag-name>
<tag-desc>
Cancels a <literal>timeout</literal> object
created by <link id="settimeout"><literal>setTimeout()</literal></link>.
</tag-desc>

<tag-name id="settimeout"><literal>setTimeout(<value>function</value>,
<value>milliseconds</value>[,
<value>argument1</value>,
<value>argumentN</value>])</literal></tag-name>
<tag-desc>
Calls a <literal>function</literal>
after a specified number of <literal>milliseconds</literal>.
One or more optional <literal>arguments</literal>
can be passed to the specified function.
Returns a <literal>timeout</literal> object.
<example>
function handler(v)
{
    // ...
}

t = setTimeout(handler, 12);

// ...

clearTimeout(t);
</example>
</tag-desc>

</list>
</para>

<section id="njs_global_functions" name="Global functions">

<para>
<table width="100%">
<tr><td><link id="atob"><literal>atob()</literal></link></td></tr>
<tr><td><link id="btoa"><literal>btoa()</literal></link></td></tr>
</table>
</para>

<para>
<list type="tag">

<tag-name id="atob"><literal>atob(<value>encodedData</value>)</literal></tag-name>
<tag-desc>
Decodes a string of data which has been encoded
using <literal>Base64</literal> encoding.
The <literal>encodedData</literal> parameter is a binary string
that contains Base64-encoded data.
Returns a string that contains decoded data from <literal>encodedData</literal>.
<para>
The similar <link id="btoa"><literal>btoa()</literal></link> method
can be used to encode and transmit data
which may otherwise cause communication problems,
then transmit it and use the <literal>atob()</literal> method
to decode the data again.
For example, you can encode, transmit, and decode control characters
such as ASCII values <literal>0</literal> through <literal>31</literal>.
<example>
const encodedData = btoa("text to encode"); // encode a string
const decodedData = atob(encodedData); // decode the string
</example>
</para>
</tag-desc>

<tag-name id="btoa"><literal>btoa(<value>stringToEncode</value>)</literal></tag-name>
<tag-desc>
Creates a Base64-encoded ASCII string from a binary string.
The <literal>stringToEncode</literal> parameter is a binary string to encode.
Returns an ASCII string containing the Base64 representation of
<literal>stringToEncode</literal>.
<para>
The method can be used to encode data
which may otherwise cause communication problems, transmit it,
then use the <link id="atob"><literal>atob()</literal></link> method
to decode the data again.
For example, you can encode control characters
such as ASCII values <literal>0</literal> through <literal>31</literal>.
<example>
const encodedData = btoa("text to encode"); // encode a string
const decodedData = atob(encodedData); // decode the string
</example>
</para>
</tag-desc>

</list>
</para>

</section>

</section>


<section id="builtin_modules" name="built-in modules">


<section id="buffer" name="Buffer">

<para>
<table width="100%">
<tr><td><link id="buffer_alloc"><literal>Buffer.alloc()</literal></link></td></tr>
<tr><td><link id="buffer_alloc_unsafe"><literal>Buffer.allocUnsafe()</literal></link></td></tr>
<tr><td><link id="buffer_bytelength"><literal>Buffer.byteLength()</literal></link></td></tr>
<tr><td><link id="buffer_compare"><literal>Buffer.compare()</literal></link></td></tr>
<tr><td><link id="buffer_concat"><literal>Buffer.concat()</literal></link></td></tr>
<tr><td><link id="buffer_from_array"><literal>Buffer.from(array)</literal></link></td></tr>
<tr><td><link id="buffer_from_arraybuffer"><literal>Buffer.from(arrayBuffer)</literal></link></td></tr>
<tr><td><link id="buffer_from_buffer"><literal>Buffer.from(buffer)</literal></link></td></tr>
<tr><td><link id="buffer_from_object"><literal>Buffer.from(object)</literal></link></td></tr>
<tr><td><link id="buffer_from_string"><literal>Buffer.from(string)</literal></link></td></tr>
<tr><td><link id="buffer_is_buffer"><literal>Buffer.isBuffer()</literal></link></td></tr>
<tr><td><link id="buffer_is_encoding"><literal>Buffer.isEncoding()</literal></link></td></tr>
<tr><td><link id="buf_index"><literal>buffer[]</literal></link></td></tr>
<tr><td><link id="buf_buffer"><literal>buf.buffer</literal></link></td></tr>
<tr><td><link id="buf_byte_offset"><literal>buf.byteOffset</literal></link></td></tr>
<tr><td><link id="buf_compare"><literal>buf.compare()</literal></link></td></tr>
<tr><td><link id="buf_copy"><literal>buf.copy()</literal></link></td></tr>
<tr><td><link id="buf_equals"><literal>buf.equals()</literal></link></td></tr>
<tr><td><link id="buf_fill"><literal>buf.fill()</literal></link></td></tr>
<tr><td><link id="buf_includes"><literal>buf.includes()</literal></link></td></tr>
<tr><td><link id="buf_indexof"><literal>buf.indexOf()</literal></link></td></tr>
<tr><td><link id="buf_lastindexof"><literal>buf.lastIndexOf()</literal></link></td></tr>
<tr><td><link id="buf_length"><literal>buf.length</literal></link></td></tr>
<tr><td><link id="buf_readintbe"><literal>buf.readIntBE()</literal></link></td></tr>
<tr><td><link id="buf_readintle"><literal>buf.readIntLE()</literal></link></td></tr>
<tr><td><link id="buf_readuintbe"><literal>buf.readUIntBE()</literal></link></td></tr>
<tr><td><link id="buf_readuintle"><literal>buf.readUIntLE()</literal></link></td></tr>
<tr><td><link id="buf_readdobulebe"><literal>buf.readDoubleBE</literal></link></td></tr>
<tr><td><link id="buf_readdobulele"><literal>buf.readDoubleLE()</literal></link></td></tr>
<tr><td><link id="buf_readfloatbe"><literal>buf.readFloatBE()</literal></link></td></tr>
<tr><td><link id="buf_readfloatle"><literal>buf.readFloatLE()</literal></link></td></tr>
<tr><td><link id="buf_subarray"><literal>buf.subarray()</literal></link></td></tr>
<tr><td><link id="buf_slice"><literal>buf.slice()</literal></link></td></tr>
<tr><td><link id="buf_swap16"><literal>buf.swap16()</literal></link></td></tr>
<tr><td><link id="buf_swap32"><literal>buf.swap32()</literal></link></td></tr>
<tr><td><link id="buf_swap64"><literal>buf.swap64()</literal></link></td></tr>
<tr><td><link id="buf_tojson"><literal>buf.toJSON()</literal></link></td></tr>
<tr><td><link id="buf_tostring"><literal>buf.toString()</literal></link></td></tr>
<tr><td><link id="buf_write"><literal>buf.write()</literal></link></td></tr>
<tr><td><link id="buf_writeintbe"><literal>buf.writeIntBE()</literal></link></td></tr>
<tr><td><link id="buf_writeintle"><literal>buf.writeIntLE()</literal></link></td></tr>
<tr><td><link id="buf_writeuintbe"><literal>buf.writeUIntBE()</literal></link></td></tr>
<tr><td><link id="buf_writeuintle"><literal>buf.writeUIntLE()</literal></link></td></tr>
<tr><td><link id="buf_writedoublebe"><literal>buf.writeDoubleBE()</literal></link></td></tr>
<tr><td><link id="buf_writedoublele"><literal>buf.writeDoubleLE()</literal></link></td></tr>
<tr><td><link id="buf_writefloatbe"><literal>buf.writeFloatBE()</literal></link></td></tr>
<tr><td><link id="buf_writefloatle"><literal>buf.writeFloatLE()</literal></link></td></tr>
</table>
</para>

<para>
<list type="tag">

<tag-name id="buffer_alloc"><literal>Buffer.alloc(<value>size</value>[,
<value>fill</value>[,
<value>encoding</value>]]))</literal></tag-name>
<tag-desc>
<para>
Allocates a new Buffer of a specified <value>size</value>.
If <value>fill</value> is not specified, the Buffer will be zero-filled.
If <value>fill</value> is specified,
the allocated Buffer will be initialized by calling
<link id="buf_fill"><literal>buf.fill(fill)</literal></link>.
If <value>fill</value> and <value>encoding</value> are specified,
the allocated Buffer will be initialized by calling
<link id="buf_fill"><literal>buf.fill(fill,
encoding)</literal></link>.
</para>

<para>
The <value>fill</value> parameter may be a
<value>string</value>,
<value>Buffer</value>,
<value>Uint8Array</value>, or
<value>integer</value>.
</para>
</tag-desc>

<tag-name id="buffer_alloc_unsafe"><literal>Buffer.allocUnsafe(<value>size</value>)</literal></tag-name>
<tag-desc>
<para>
The same as
<link id="buffer_alloc"><literal>Buffer.alloc()</literal></link>,
with the difference that the memory allocated for the buffer is not initialized,
the contents of the new buffer is unknown and may contain sensitive data.
</para>
</tag-desc>

<tag-name id="buffer_bytelength"><literal>Buffer.byteLength(<value>value</value>[,
<value>encoding</value>])</literal></tag-name>
<tag-desc>
Returns the byte length of a specified value,
when encoded using <value>encoding</value>.
The value can be a
<literal>string</literal>,
<literal>Buffer</literal>,
<literal>TypedArray</literal>,
<literal>DataView</literal>, or
<literal>ArrayBuffer</literal>.
If the value is a <value>string</value>,
the <literal>encoding</literal> parameter is its encoding, can be
<value>utf8</value>,
<value>hex</value>,
<value>base64</value>,
<value>base64url</value>;
by default is <value>utf8</value>.
</tag-desc>

<tag-name id="buffer_compare"><literal>Buffer.compare(<value>buffer1</value>,
<value>buffer2</value>)</literal></tag-name>
<tag-desc>
Compares <value>buffer1</value> with <value>buffer2</value>
when sorting arrays of Buffer instances.
Returns
<literal>0</literal> if
<value>buffer1</value> is the same as <value>buffer2</value>,
<literal>1</literal> if
<value>buffer2</value> should come before <value>buffer1</value> when sorted, or
<literal>-1</literal> if
<value>buffer2</value> should come after <value>buffer1</value> when sorted.
</tag-desc>

<tag-name id="buffer_concat"><literal>Buffer.concat(<value>list</value>[,
<value>totalLength</value>])</literal></tag-name>
<tag-desc>
Returns a new Buffer
which is the result of concatenating all the Buffer instances in the list.
If there are no items in the list or the total length is 0,
a new zero-length Buffer is returned.
If <value>totalLength</value> is not specified,
it is calculated from the Buffer instances in list by adding their lengths.
If <value>totalLength</value> is specified,
it is coerced to an unsigned integer.
If the combined length of the Buffers in list exceeds
<value>totalLength</value>,
the result is truncated to <value>totalLength</value>.
</tag-desc>

<tag-name id="buffer_from_array"><literal>Buffer.from(<value>array</value>)</literal></tag-name>
<tag-desc>
Allocates a new Buffer using an array of bytes
in the range <literal>0</literal> – <literal>255</literal>.
Array entries outside that range will be truncated.
</tag-desc>

<tag-name id="buffer_from_arraybuffer"><literal>Buffer.from(<value>arrayBuffer</value>,
<value>byteOffset</value>[,
<value>length</value>]])</literal></tag-name>
<tag-desc>
Creates a view of the <value>ArrayBuffer</value>
without copying the underlying memory.
The optional <value>byteOffset</value> and <value>length</value> arguments
specify a memory range within the <value>arrayBuffer</value>
that will be shared by the Buffer.
</tag-desc>

<tag-name id="buffer_from_buffer"><literal>Buffer.from(<value>buffer</value>)</literal></tag-name>
<tag-desc>
Copies the passed buffer data onto a new Buffer instance.
</tag-desc>

<tag-name id="buffer_from_object"><literal>Buffer.from(<value>object</value>[,
<value>offsetOrEncoding</value>[,
<value>length</value>]])</literal></tag-name>
<tag-desc>
For objects whose <literal>valueOf()</literal> function
returns a value not strictly equal to object,
returns
<literal>Buffer.from(object.valueOf()</literal>,
<literal>offsetOrEncoding</literal>,
<literal>length</literal>).
</tag-desc>

<tag-name id="buffer_from_string"><literal>Buffer.from(<value>string</value>[,
<value>encoding</value>])</literal></tag-name>
<tag-desc>
Creates a new Buffer with a <value>string</value>.
The <value>encoding</value> parameter identifies the character encoding
to be used when converting a string into bytes.
The encoding can be
<literal>utf8</literal>,
<literal>hex</literal>,
<literal>base64</literal>,
<literal>base64url</literal>;
by default is <literal>utf8</literal>.
</tag-desc>

<tag-name id="buffer_is_buffer"><literal>Buffer.isBuffer(<value>object</value>)</literal></tag-name>
<tag-desc>
A boolean value,
returns <literal>true</literal> if <value>object</value> is a Buffer.
</tag-desc>

<tag-name id="buffer_is_encoding"><literal>Buffer.isEncoding(<value>encoding</value>)</literal></tag-name>
<tag-desc>
A boolean value,
returns <literal>true</literal>
if encoding is the name of a supported character encoding.
</tag-desc>

<tag-name id="buf_index"><literal>buffer[<value>index</value>]</literal></tag-name>
<tag-desc>
The index operator that can be used to get and set the octet
at position <literal>index</literal> in <literal>buffer</literal>.
The values refer to individual bytes,
so the legal value range is between 0 and 255 (decimal).
</tag-desc>

<tag-name id="buf_buffer"><literal>buf.buffer</literal></tag-name>
<tag-desc>
The underlying <literal>ArrayBuffer</literal> object
based on which this Buffer object is created.
</tag-desc>

<tag-name id="buf_byte_offset"><literal>buf.byteOffset</literal></tag-name>
<tag-desc>
An integer,
specifying the <literal>byteOffset</literal> of the Buffers
underlying <literal>ArrayBuffer</literal> object.
</tag-desc>

<tag-name id="buf_compare"><literal>buf.compare(<value>target</value>[,
<value>targetStart</value>[,
<value>targetEnd</value>[,
<value>sourceStart</value>[,
<value>sourceEnd</value>]]]])</literal></tag-name>
<tag-desc>
Compares buffer with <value>target</value> and returns a number
indicating whether buffer comes before, after, or is the same
as <value>target</value> in sort order.
Comparison is based on the actual sequence of bytes in each Buffer.
The <literal>targetStart</literal> is an integer specifying
the offset within <value>target</value> at which to begin comparison,
by default is 0.
The <literal>targetEnd</literal> is an integer specifying
the offset within <value>target</value> at which to end comparison,
by default is <literal>target.length</literal>.
The <literal>sourceStart</literal> is an integer specifying
the offset within buffer at which to begin comparison,
by default is 0.
The <literal>sourceEnd</literal> is an integer specifying
the offset within buffer at which to end comparison (not inclusive),
by default is <literal>buf.length</literal>.
</tag-desc>

<tag-name id="buf_copy"><literal>buf.copy(<value>target</value>[,
<value>targetStart</value>[,
<value>sourceStart</value>[,
<value>sourceEnd</value>]]])</literal></tag-name>
<tag-desc>
Copies data from a region of buffer to a region in <value>target</value>,
even if the target memory region overlaps with buffer.
The <literal>target</literal> parameter is a
<value>Buffer</value> or <value>Uint8Array</value> to copy into.

<para>
The <literal>targetStart</literal> is an integer specifying
the offset within target at which to begin writing,
by default is 0.
The <literal>sourceStart</literal> is an integer specifying
the offset within buffer from which to begin copying,
by default is 0.
The <literal>sourceEnd</literal> is an integer specifying
the offset within buffer at which to stop copying (not inclusive)
by default is <value>buf.length</value>.
</para>
</tag-desc>

<tag-name id="buf_equals"><literal>buf.equals(<value>otherBuffer</value>)</literal></tag-name>
<tag-desc>
A boolean value,
returns <literal>true</literal> if both Buffer and <value>otherBuffer</value>
have exactly the same bytes.
</tag-desc>

<tag-name id="buf_fill"><literal>buf.fill(<value>value</value>[,
<value>offset</value>[,
<value>end</value>]][,
<value>encoding</value>])</literal></tag-name>
<tag-desc>
Fills the Buffer with the specified <value>value</value>.
If the <value>offset</value> and <value>end</value> are not specified,
the entire Buffer will be filled.
The <value>value</value> is coerced to <value>uint32</value> if it is not a
<literal>string</literal>,
<literal>Buffer</literal>, or
<literal>integer</literal>.
If the resulting integer is greater than 255,
the Buffer will be filled with <value>value</value> and 255.
</tag-desc>

<tag-name id="buf_includes"><literal>buf.includes(<value>value</value>[,
<value>byteOffset</value>][,
<value>encoding</value>])</literal></tag-name>
<tag-desc>
Equivalent to
<link id="buf_indexof"><literal>buf.indexOf()</literal></link>
<literal>!== -1</literal>,
returns <literal>true</literal> if the <value>value</value> was found
in Buffer.
</tag-desc>

<tag-name id="buf_indexof"><literal>buf.indexOf(<value>value</value>[,
<value>byteOffset</value>][,
<value>encoding</value>])</literal></tag-name>
<tag-desc>
Returns an integer which is the index of the first occurrence of
<value>value</value> in Buffer, or <value>-1</value>
if Buffer does not contain value.
The <value>value</value> can be a
<literal>string</literal> with specified <value>encoding</value>
(by default <value>utf8</value>),
<literal>Buffer</literal>,
<literal>Unit8Array</literal>,
or a number between 0 and 255.
</tag-desc>

<tag-name id="buf_lastindexof"><literal>buf.lastIndexOf(<value>value</value>[,
<value>byteOffset</value>][,
<value>encoding</value>])</literal></tag-name>
<tag-desc>
The same as
<link id="buf_indexof"><literal>buf.indexOf()</literal></link>,
except the last occurrence of the <value>value</value> is found
instead of the first occurrence.
The <value>value</value> can be a string, Buffer, or
integer between 1 and 255.
If the <value>value</value> is an empty string or empty Buffer,
<literal>byteOffset</literal> will be returned.
</tag-desc>

<tag-name id="buf_length"><literal>buf.length</literal></tag-name>
<tag-desc>
Returns the number of bytes in Buffer.
</tag-desc>

<tag-name id="buf_readintbe"><literal>buf.readIntBE(<value>offset</value>,
<value>byteLength</value>)</literal></tag-name>
<tag-desc>
Reads the <value>byteLength</value> from <literal>buf</literal>
at the specified <value>offset</value>
and interprets the result as a big-endian,
two's complement signed value supporting up to 48 bits of accuracy.
The <value>byteLength</value> parameter is an integer between 1 and 6
specifying the number of bytes to read.
<para>
The similar methods are also supported:
<literal>buf.readInt8([offset])</literal>,
<literal>buf.readInt16BE([offset])</literal>,
<literal>buf.readInt32BE([offset])</literal>.
</para>
</tag-desc>

<tag-name id="buf_readintle"><literal>buf.readIntLE(<value>offset</value>,
<value>byteLength</value>)</literal></tag-name>
<tag-desc>
Reads the <value>byteLength</value> from <literal>buf</literal>
at the specified <value>offset</value>
and interprets the result as a little-endian,
two's complement signed value supporting up to 48 bits of accuracy.
The <value>byteLength</value> parameter is an integer between 1 and 6
specifying the number of bytes to read.
<para>
The similar methods are also supported:
<literal>buf.readInt8([offset])</literal>,
<literal>buf.readInt16LE([offset])</literal>,
<literal>buf.readInt32LE([offset])</literal>.
</para>
</tag-desc>

<tag-name id="buf_readuintbe"><literal>buf.readUIntBE(<value>offset</value>,
<value>byteLength</value>)</literal></tag-name>
<tag-desc>
Reads the <value>byteLength</value> from <literal>buf</literal>
at the specified <value>offset</value>
and interprets the result as a big-endian
integer supporting up to 48 bits of accuracy.
The <value>byteLength</value> parameter is an integer between 1 and 6
specifying the number of bytes to read.
<para>
The similar methods are also supported:
<literal>buf.readUInt8([offset])</literal>,
<literal>buf.readUInt16BE([offset])</literal>,
<literal>buf.readUInt32BE([offset])</literal>.
</para>
</tag-desc>

<tag-name id="buf_readuintle"><literal>buf.readUIntLE(<value>offset</value>,
<value>byteLength</value>)</literal></tag-name>
<tag-desc>
Reads the <value>byteLength</value> from <literal>buf</literal>
at the specified <value>offset</value>
and interprets the result as a little-endian
integer supporting up to 48 bits of accuracy.
The <value>byteLength</value> parameter is an integer between 1 and 6
specifying the number of bytes to read.
<para>
The similar methods are also supported:
<literal>buf.readUInt8([offset])</literal>,
<literal>buf.readUInt16LE([offset])</literal>,
<literal>buf.readUInt32LE([offset])</literal>.
</para>
</tag-desc>

<tag-name id="buf_readdobulebe"><literal>buf.readDoubleBE</literal>([<value>offset</value>])</tag-name>
<tag-desc>
Reads a 64-bit, big-endian double from <literal>buf</literal>
at the specified <value>offset</value>.
</tag-desc>

<tag-name id="buf_readdobulele"><literal>buf.readDoubleLE</literal>([<value>offset</value>])</tag-name>
<tag-desc>
Reads a 64-bit, little-endian double from <literal>buf</literal>
at the specified <value>offset</value>.
</tag-desc>

<tag-name id="buf_readfloatbe"><literal>buf.readFloatBE</literal>([<value>offset</value>])</tag-name>
<tag-desc>
Reads a 32-bit, big-endian float from <literal>buf</literal>
at the specified <value>offset</value>.
</tag-desc>

<tag-name id="buf_readfloatle"><literal>buf.readFloatLE</literal>([<value>offset</value>])</tag-name>
<tag-desc>
Reads a 32-bit, little-endian float from <literal>buf</literal>
at the specified <value>offset</value>.
</tag-desc>

<tag-name id="buf_subarray"><literal>buf.subarray([<value>start</value>[,
<value>end</value>]])</literal></tag-name>
<tag-desc>
Returns a new <literal>buf</literal>
that references the same memory as the original,
but offset and cropped by
<value>start</value> and <value>end</value>.
If <value>end</value> is greater than
<link id="buf_length"><literal>buf.length</literal></link>,
the same result as that of end equal to
<link id="buf_length"><literal>buf.length</literal></link>
is returned.
</tag-desc>

<tag-name id="buf_slice"><literal>buf.slice([<value>start</value>[,
<value>end</value>]])</literal></tag-name>
<tag-desc>
Returns a new <literal>buf</literal>
that references the same memory as the original,
but offset and cropped by the
<value>start</value> and <value>end</value> values.
The method is not compatible with the
<literal>Uint8Array.prototype.slice()</literal>,
which is a superclass of Buffer.
To copy the slice, use
<literal>Uint8Array.prototype.slice()</literal>.
</tag-desc>

<tag-name id="buf_swap16"><literal>buf.swap16</literal>()</tag-name>
<tag-desc>
Interprets <literal>buf</literal> as an array of unsigned 16-bit numbers
and swaps the byte order in-place.
Throws an error if
<link id="buf_length"><literal>buf.length</literal></link>
is not a multiple of 2.
</tag-desc>

<tag-name id="buf_swap32"><literal>buf.swap32</literal>()</tag-name>
<tag-desc>
Interprets <literal>buf</literal> as an array of unsigned 32-bit numbers
and swaps the byte order in-place.
Throws an error if
<link id="buf_length"><literal>buf.length</literal></link>
is not a multiple of 4.
</tag-desc>

<tag-name id="buf_swap64"><literal>buf.swap64</literal>()</tag-name>
<tag-desc>
Interprets <literal>buf</literal> as an array of 64-bit numbers
and swaps byte order in-place.
Throws an error if
<link id="buf_length"><literal>buf.length</literal></link>
is not a multiple of 8.
</tag-desc>

<tag-name id="buf_tojson"><literal>buf.toJSON</literal>()</tag-name>
<tag-desc>
Returns a JSON representation of <literal>buf.</literal>
<literal>JSON.stringify()</literal>
implicitly calls this function when stringifying a Buffer instance.
</tag-desc>

<tag-name id="buf_tostring"><literal>buf.toString([<value>encoding</value>[,
<value>start</value>[,
<value>end</value>]]])</literal></tag-name>
<tag-desc>
Decodes <literal>buf</literal> to a string
according to the specified character <value>encoding</value>
which can be <value>utf8</value>,
<value>hex</value>,
<value>base64</value>,
<value>base64url</value>.
The <value>start</value> and <value>end</value> parameters
may be passed to decode only a subset of Buffer.
</tag-desc>

<tag-name id="buf_write"><literal>buf.write(<value>string</value>[,
<value>offset</value>[,
<value>length</value>]][,
<value>encoding</value>])</literal></tag-name>
<tag-desc>
Writes a <value>string</value> to <literal>buf</literal>
at <value>offset</value>
according to the character <value>encoding</value>.
The <value>length</value> parameter is the number of bytes to write.
If Buffer did not contain enough space to fit the entire string,
only part of string will be written,
however, partially encoded characters will not be written.
The <value>encoding</value> can be
<value>utf8</value>,
<value>hex</value>,
<value>base64</value>,
<value>base64url</value>.
</tag-desc>

<tag-name id="buf_writeintbe"><literal>buf.writeIntBE(<value>value</value>,
<value>offset</value>,
<value>byteLength</value>)</literal></tag-name>
<tag-desc>
Writes <value>byteLength</value> bytes of <value>value</value>
to <literal>buf</literal>
at the specified <value>offset</value> as big-endian.
Supports up to 48 bits of accuracy.
The <value>byteLength</value> parameter is an integer between 1 and 6
specifying the number of bytes to read.
<para>
The following similar methods are also supported:
<literal>buf.writeInt8</literal>,
<literal>buf.writeInt16BE</literal>,
<literal>buf.writeInt32BE</literal>.
</para>
</tag-desc>

<tag-name id="buf_writeintle"><literal>buf.writeIntLE(<value>value</value>,
<value>offset</value>,
<value>byteLength</value>)</literal></tag-name>
<tag-desc>
Writes <value>byteLength</value> bytes of <value>value</value>
to <literal>buf</literal>
at the specified <value>offset</value> as little-endian.
Supports up to 48 bits of accuracy.
The <value>byteLength</value> parameter is an integer between 1 and 6
specifying the number of bytes to read.
<para>
The following similar methods are also supported:
<literal>buf.writeInt8</literal>,
<literal>buf.writeInt16LE</literal>,
<literal>buf.writeInt32LE</literal>.
</para>
</tag-desc>

<tag-name id="buf_writeuintbe"><literal>buf.writeUIntBE(<value>value</value>,
<value>offset</value>,
<value>byteLength</value>)</literal></tag-name>
<tag-desc>
Writes <value>byteLength</value> bytes of <value>value</value>
to <literal>buf</literal>
at the specified <value>offset</value> as big-endian.
Supports up to 48 bits of accuracy.
The <value>byteLength</value> parameter is an integer between 1 and 6
specifying the number of bytes to read.
<para>
The following similar methods are also supported:
<literal>buf.writeUInt8</literal>,
<literal>buf.writeUInt16BE</literal>,
<literal>buf.writeUInt32BE</literal>.
</para>
</tag-desc>

<tag-name id="buf_writeuintle"><literal>buf.writeUIntLE(<value>value</value>,
<value>offset</value>,
<value>byteLength</value>)</literal></tag-name>
<tag-desc>
Writes <value>byteLength</value> bytes of <value>value</value>
to <literal>buf</literal>
at the specified <value>offset</value> as little-endian.
Supports up to 48 bits of accuracy.
The <value>byteLength</value> parameter is an integer between 1 and 6
specifying the number of bytes to read.
<para>
The following similar methods are also supported:
<literal>buf.writeUInt8</literal>,
<literal>buf.writeUInt16LE</literal>,
<literal>buf.writeUInt32LE</literal>.
</para>
</tag-desc>

<tag-name id="buf_writedoublebe"><literal>buf.writeDoubleBE(<value>value</value>,
[<value>offset</value>])</literal></tag-name>
<tag-desc>
Writes the <value>value</value> to <literal>buf</literal>
at the specified <value>offset</value> as big-endian.
</tag-desc>

<tag-name id="buf_writedoublele"><literal>buf.writeDoubleLE(<value>value</value>,
[<value>offset</value>])</literal></tag-name>
<tag-desc>
Writes the <value>value</value> to <literal>buf</literal>
at the specified <value>offset</value> as little-endian.
</tag-desc>

<tag-name id="buf_writefloatbe"><literal>buf.writeFloatBE(<value>value</value>,
[<value>offset</value>])</literal></tag-name>
<tag-desc>
Writes the <value>value</value> to <literal>buf</literal>
at the specified <value>offset</value> as big-endian.
</tag-desc>

<tag-name id="buf_writefloatle"><literal>buf.writeFloatLE(<value>value</value>,
[<value>offset</value>])</literal></tag-name>
<tag-desc>
Writes the <value>value</value> to <literal>buf</literal>
at the specified <value>offset</value> as little-endian.
</tag-desc>

</list>
</para>

</section>


<section id="crypto" name="Crypto">

<para>
<table width="100%">
<tr><td><link id="crypto_createhash"><literal>crypto.createHash()</literal></link></td></tr>
<tr><td><link id="crypto_createhmac"><literal>crypto.createHmac()</literal></link></td></tr>
</table>
</para>

<para>
<note>
Since <link doc="changes.xml" id="njs0.7.0">0.7.0</link>,
extended crypto API is available as a global
<link id="builtin_crypto">crypto</link> object.
</note>
The Crypto module provides cryptographic functionality support.
The Crypto module object is returned by <literal>require('crypto')</literal>.
</para>

<para>
<list type="tag">

<tag-name id="crypto_createhash"><literal>crypto.createHash(<value>algorithm</value>)</literal></tag-name>
<tag-desc>
Creates and returns a <link id="crypto_hash">Hash</link> object
that can be used to generate hash digests
using the given <value>algorithm</value>.
The algorithm can be
<literal>md5</literal>,
<literal>sha1</literal>, and
<literal>sha256</literal>.
</tag-desc>

<tag-name id="crypto_createhmac"><literal>crypto.createHmac(<value>algorithm</value>,
<value>secret key</value>)</literal></tag-name>
<tag-desc>
Creates and returns an <link id="crypto_hmac">HMAC</link> object that uses
the given <value>algorithm</value> and <value>secret key</value>.
The algorithm can be
<literal>md5</literal>,
<literal>sha1</literal>, and
<literal>sha256</literal>.
</tag-desc>

</list>
</para>


<section id="crypto_hash" name="Hash">

<para>
<table width="100%">
<tr><td><link id="crypto_hash_update"><literal>hash.update()</literal></link></td></tr>
<tr><td><link id="crypto_hash_digest"><literal>hash.digest()</literal></link></td></tr>
</table>
</para>

<para>
<list type="tag">

<tag-name id="crypto_hash_update"><literal>hash.update(<value>data</value>)</literal></tag-name>
<tag-desc>
Updates the hash content with the given <value>data</value>.
</tag-desc>

<tag-name id="crypto_hash_digest"><literal>hash.digest([<value>encoding</value>])</literal></tag-name>
<tag-desc>
Calculates the digest of all of the data passed using
<literal>hash.update()</literal>.
The encoding can be
<literal>hex</literal>,
<literal>base64</literal>, and
<literal>base64url</literal>.
If encoding is not provided, a Buffer object
(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>) is returned.
<note>
Before version (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>),
a byte string was returned instead of a Buffer object.
</note>
</tag-desc>

<tag-name id="crypto_hash_copy"><literal>hash.copy()</literal></tag-name>
<tag-desc>
Makes a copy of the current state of the hash
(since <link doc="changes.xml" id="njs0.7.12">0.7.12</link>).
</tag-desc>

</list>
</para>

<para>
<example>
>> var cr = require('crypto')
undefined

>> cr.createHash('sha1').update('A').update('B').digest('base64url')
'BtlFlCqiamG-GMPiK_GbvKjdK10'
</example>
</para>

</section>


<section id="crypto_hmac" name="HMAC">

<para>
<table width="100%">
<tr><td><link id="crypto_hmac_update"><literal>hmac.update()</literal></link></td></tr>
<tr><td><link id="crypto_hmac_digest"><literal>hmac.digest()</literal></link></td></tr>
</table>
</para>

<para>
<list type="tag">

<tag-name id="crypto_hmac_update"><literal>hmac.update(<value>data</value>)</literal></tag-name>
<tag-desc>
Updates the HMAC content with the given <value>data</value>.
</tag-desc>

<tag-name id="crypto_hmac_digest"><literal>hmac.digest([<value>encoding</value>])</literal></tag-name>
<tag-desc>
Calculates the HMAC digest of all of the data passed using
<literal>hmac.update()</literal>.
The encoding can be
<literal>hex</literal>,
<literal>base64</literal>, and
<literal>base64url</literal>.
If encoding is not provided, a Buffer object
(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>) is returned.
<note>
Before version <link doc="changes.xml" id="njs0.4.4">0.4.4</link>,
a byte string was returned instead of a Buffer object.
</note>
</tag-desc>
</list>
</para>

<para>
<example>
>> var cr = require('crypto')
undefined

>> cr.createHmac('sha1', 'secret.key').update('AB').digest('base64url')
'Oglm93xn23_MkiaEq_e9u8zk374'
</example>
</para>

</section>

</section>


<section id="njs_api_fs" name="File System">

<para>
<table width="100%">
<tr><td><link id="fs_accesssync"><literal>fs.accessSync()</literal></link></td></tr>
<tr><td><link id="fs_appendfilesync"><literal>fs.appendFileSync()</literal></link></td></tr>
<tr><td><link id="fs_closesync"><literal>fs.closeSync()</literal></link></td></tr>
<tr><td><link id="fs_existssync"><literal>fs.existsSync()</literal></link></td></tr>
<tr><td><link id="fs_fstatsync"><literal>fs.fstatSync()</literal></link></td></tr>
<tr><td><link id="fs_lstatsync"><literal>fs.lstatSync()</literal></link></td></tr>
<tr><td><link id="fs_mkdirsync"><literal>fs.mkdirSync()</literal></link></td></tr>
<tr><td><link id="fs_opensync"><literal>fs.openSync()</literal></link></td></tr>
<tr><td><link id="fs_promises_open"><literal>fs.promises.open()</literal></link></td></tr>
<tr><td><link id="fs_readdirsync"><literal>fs.readdirSync()</literal></link></td></tr>
<tr><td><link id="fs_readfilesync"><literal>fs.readFileSync()</literal></link></td></tr>
<tr><td><link id="fs_readsync"><literal>fs.readSync()</literal></link></td></tr>
<tr><td><link id="fs_realpathsync"><literal>fs.realpathSync()</literal></link></td></tr>
<tr><td><link id="fs_renamesync"><literal>fs.renameSync()</literal></link></td></tr>
<tr><td><link id="fs_rmdirsync"><literal>fs.rmdirSync()</literal></link></td></tr>
<tr><td><link id="fs_statsync"><literal>fs.statSync()</literal></link></td></tr>
<tr><td><link id="fs_symlinksync"><literal>fs.symlinkSync()</literal></link></td></tr>
<tr><td><link id="fs_unlinksync"><literal>fs.unlinkSync()</literal></link></td></tr>
<tr><td><link id="fs_writefilesync"><literal>fs.writeFileSync()</literal></link></td></tr>
<tr><td><link id="fs_writesync_buf"><literal>fs.writeSync()</literal></link></td></tr>
<tr><td><link id="fs_writesync_str"><literal>fs.writeSync()</literal></link></td></tr>
</table>
</para>

<para>
<table width="100%">
<tr><td><link id="fs_dirent"><literal>fs.Dirent</literal></link></td></tr>
<tr><td><link id="fs_filehandle"><literal>fs.FileHandle</literal></link></td></tr>
<tr><td><link id="fs_stats"><literal>fs.Stats</literal></link></td></tr>
<tr><td><link id="access_const"><literal>File Access Constants</literal></link></td></tr>
<tr><td><link id="njs_api_fs_flags"><literal>File System Flags</literal></link></td></tr>
</table>
</para>

<para>
The File System module provides operations with files.
</para>

<para>
The module object is returned by <literal>require('fs')</literal>.
Since <link doc="changes.xml" id="njs0.3.9">0.3.9</link>,
promissified versions of file system methods are available through
<literal>require('fs').promises</literal> object:
<example>
> var fs = require('fs').promises;
undefined
> fs.readFile("/file/path").then((data)=>console.log(data))
&lt;file data&gt;
</example>
<list type="tag">

<tag-name id="fs_accesssync"><literal>accessSync(<value>path</value>[,
<value>mode</value>])</literal></tag-name>
<tag-desc>
Synchronously tests permissions for a file or directory
specified in the <literal>path</literal>
(<link doc="changes.xml" id="njs0.3.9">0.3.9</link>).
If the check fails, an error will be returned,
otherwise, the method will return undefined.
<list type="tag">

<tag-name><literal>mode</literal></tag-name>
<tag-desc>
an optional integer
that specifies the accessibility checks to be performed,
by default is <link id="access_const"><literal>fs.constants.F_OK</literal></link>
<example>
try {
    fs.accessSync('/file/path', fs.constants.R_OK | fs.constants.W_OK);
    console.log('has access');
} catch (e) {
    console.log('no access');)
}
</example>
</tag-desc>

</list>
</tag-desc>

<tag-name id="fs_appendfilesync"><literal>appendFileSync(<value>filename</value>,
<value>data</value>[, <value>options</value>])</literal></tag-name>
<tag-desc>
Synchronously appends specified <literal>data</literal>
to a file with provided <literal>filename</literal>.
The <literal>data</literal> is expected to be a string
or a Buffer object (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>).
If the file does not exist, it will be created.
The <literal>options</literal> parameter is expected to be
an object with the following keys:
<list type="tag">

<tag-name><literal>mode</literal></tag-name>
<tag-desc>
mode option, by default is <literal>0o666</literal>
</tag-desc>

<tag-name><literal>flag</literal></tag-name>
<tag-desc>
file system <link id="njs_api_fs_flags">flag</link>,
by default is <literal>a</literal>
</tag-desc>

</list>
</tag-desc>

<tag-name id="fs_closesync"><literal>closeSync(<value>fd</value>)</literal></tag-name>
<tag-desc>
Closes the <literal>fd</literal> file descriptor represented by an integer
used by the method.
Returns <literal>undefined</literal>.
</tag-desc>

<tag-name id="fs_existssync"><literal>existsSync(<value>path</value>)</literal></tag-name>
<tag-desc>
Boolean value, returns
<literal>true</literal> if the specified <value>path</value> exists.
(<link doc="changes.xml" id="njs0.8.2">0.8.2</link>)
</tag-desc>

<tag-name id="fs_fstatsync"><literal>fstatSync(<value>fd</value>)</literal></tag-name>
<tag-desc>
Retrieves the <link id="fs_stats"><literal>fs.Stats</literal></link> object
for the file descriptor
(<link doc="changes.xml" id="njs0.7.7">0.7.7</link>).
The <literal>fd</literal> parameter is an integer
representing the file descriptor used by the method.
</tag-desc>

<tag-name id="fs_lstatsync"><literal>lstatSync(<value>path</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
Synchronously retrieves
the <link id="fs_stats"><literal>fs.Stats</literal></link> object
for the symbolic link referred to by <literal>path</literal>
(<link doc="changes.xml" id="njs0.7.1">0.7.1</link>).
The <literal>options</literal> parameter is expected to be
an object with the following keys:
<list type="tag">
<tag-name><literal>throwIfNoEntry</literal></tag-name>
<tag-desc>
a boolean value which indicates
whether an exception is thrown if no file system entry exists,
rather than returning <literal>undefined</literal>,
by default is <literal>false</literal>.
</tag-desc>
</list>
</tag-desc>

<tag-name id="fs_mkdirsync"><literal>mkdirSync(<value>path</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
Synchronously creates a directory at the specified <literal>path</literal>
(<link doc="changes.xml" id="njs0.4.2">0.4.2</link>).
The <literal>options</literal> parameter is expected to be an
<literal>integer</literal> that specifies
the <link id="fs_mkdirsync_mode">mode</link>,
or an object with the following keys:
<list type="tag">

<tag-name id="fs_mkdirsync_mode"><literal>mode</literal></tag-name>
<tag-desc>
mode option, by default is <literal>0o777</literal>.
</tag-desc>

</list>
</tag-desc>

<tag-name id="fs_opensync"><literal>openSync(<value>path</value>[,
<value>flags</value>[, <value>mode</value>]])</literal></tag-name>
<tag-desc>
Returns an integer
representing the file descriptor for the opened file <literal>path</literal>
(<link doc="changes.xml" id="njs0.7.7">0.7.7</link>).
<list type="tag">

<tag-name><literal>flags</literal></tag-name>
<tag-desc>
file system <link id="njs_api_fs_flags">flag</link>,
by default is <literal>r</literal>
</tag-desc>

<tag-name><literal>mode</literal></tag-name>
<tag-desc>
mode option, by default is <literal>0o666</literal>
</tag-desc>

</list>
</tag-desc>

<tag-name id="fs_promises_open"><literal>promises.open(<value>path</value>[,
<value>flags</value>[, <value>mode</value>]])</literal></tag-name>
<tag-desc>
Returns a <link id="fs_filehandle"><literal>FileHandle</literal></link> object
representing the opened file <literal>path</literal>
(<link doc="changes.xml" id="njs0.7.7">0.7.7</link>).
<list type="tag">

<tag-name><literal>flags</literal></tag-name>
<tag-desc>
file system <link id="njs_api_fs_flags">flag</link>,
by default is <literal>r</literal>
</tag-desc>

<tag-name><literal>mode</literal></tag-name>
<tag-desc>
mode option, by default is <literal>0o666</literal>
</tag-desc>

</list>
</tag-desc>

<tag-name id="fs_readdirsync"><literal>readdirSync(<value>path</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
Synchronously reads the contents of a directory
at the specified <literal>path</literal>
(<link doc="changes.xml" id="njs0.4.2">0.4.2</link>).
The <literal>options</literal> parameter is expected to be
a string that specifies <link id="fs_readdirsync_encoding">encoding</link>
or an object with the following keys:
<list type="tag">

<tag-name id="fs_readdirsync_encoding"><literal>encoding</literal></tag-name>
<tag-desc>
encoding, by default is <literal>utf8</literal>.
The encoding can be <literal>utf8</literal> and <literal>buffer</literal>
(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>).
</tag-desc>

<tag-name id="fs_readdirsync_withfiletypes"><literal>withFileTypes</literal></tag-name>
<tag-desc>
if set to <literal>true</literal>, the files array will contain
<link id="fs_dirent"><literal>fs.Dirent</literal></link> objects,
by default is <literal>false</literal>.
</tag-desc>

</list>
</tag-desc>

<tag-name id="fs_readfilesync"><literal>readFileSync(<value>filename</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
Synchronously returns the contents of the file
with provided <literal>filename</literal>.
The <literal>options</literal> parameter holds
<literal>string</literal> that specifies encoding.
If an encoding is specified, a string is returned,
otherwise, a Buffer object
(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>) is returned.
<note>
Before version <link doc="changes.xml" id="njs0.4.4">0.4.4</link>,
a <link id="string_tobytes">byte string</link> was returned
if encoding was not specified.
</note>
Otherwise, <literal>options</literal> is expected to be
an object with the following keys:
<list type="tag">

<tag-name><literal>encoding</literal></tag-name>
<tag-desc>
encoding, by default is not specified.
The encoding can be <literal>utf8</literal>,
<literal>hex</literal>
(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>),
<literal>base64</literal>
(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>),
<literal>base64url</literal>
(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>).
</tag-desc>

<tag-name><literal>flag</literal></tag-name>
<tag-desc>
file system <link id="njs_api_fs_flags">flag</link>,
by default is <literal>r</literal>
</tag-desc>

</list>
<example>
>> var fs = require('fs')
undefined
>> var file = fs.readFileSync('/file/path.tar.gz')
undefined
>> var gzipped = file.slice(0,2).toString('hex') === '1f8b'; gzipped
true
</example>
</tag-desc>

<tag-name id="fs_readsync"><literal>readSync(<value>fd</value>,
<value>buffer</value>, <value>offset</value>[,
<value>length</value>[, <value>position</value>]])</literal></tag-name>
<tag-desc>
Reads the content of a file path using file descriptor <literal>fd</literal>,
returns the number of bytes read
(<link doc="changes.xml" id="njs0.7.7">0.7.7</link>).

<list type="tag">

<tag-name><literal>buffer</literal></tag-name>
<tag-desc>
the <literal>buffer</literal> value can be a
<literal>Buffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
</tag-desc>

<tag-name><literal>offset</literal></tag-name>
<tag-desc>
is an <literal>integer</literal> representing
the position in buffer to write the data to
</tag-desc>

<tag-name><literal>length</literal></tag-name>
<tag-desc>
is an <literal>integer</literal> representing
the number of bytes to read
</tag-desc>

<tag-name><literal>position</literal></tag-name>
<tag-desc>
specifies where to begin reading from in the file,
the value can be
<literal>integer</literal> or
<literal>null</literal>,
by default is <literal>null</literal>.
If <literal>position</literal> is <literal>null</literal>,
data will be read from the current file position,
and the file position will be updated.
If position is an <literal>integer</literal>,
the file position will be unchanged
</tag-desc>
</list>

</tag-desc>

<tag-name id="fs_realpathsync"><literal>realpathSync(<value>path</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
Synchronously computes the canonical pathname by resolving
<literal>.</literal>, <literal>..</literal> and symbolic links using
<link url="http://man7.org/linux/man-pages/man3/realpath.3.html">realpath(3)</link>.
The <literal>options</literal> argument can be a string specifying an encoding,
or an object with an encoding property specifying the character encoding
to use for the path passed to the callback
(<link doc="changes.xml" id="njs0.3.9">0.3.9</link>).
</tag-desc>

<tag-name id="fs_renamesync"><literal>renameSync(<value>oldPath</value>,
<value>newPath</value>)</literal></tag-name>
<tag-desc>
Synchronously changes the name or location of a file from
<literal>oldPath</literal> to <literal>newPath</literal>
(<link doc="changes.xml" id="njs0.3.4">0.3.4</link>).
<example>
>> var fs = require('fs')
undefined
>> var file = fs.renameSync('hello.txt', 'HelloWorld.txt')
undefined
</example>
</tag-desc>

<tag-name id="fs_rmdirsync"><literal>rmdirSync(<value>path</value>)</literal></tag-name>
<tag-desc>
Synchronously removes a directory at the specified <literal>path</literal>
(<link doc="changes.xml" id="njs0.4.2">0.4.2</link>).
</tag-desc>

<tag-name id="fs_statsync"><literal>statSync(<value>path</value>,[
<value>options</value>])</literal></tag-name>
<tag-desc>
Synchronously retrieves
the <link id="fs_stats"><literal>fs.Stats</literal></link> object
for the specified <literal>path</literal>
(<link doc="changes.xml" id="njs0.7.1">0.7.1</link>).
The <literal>path</literal> can be a
<literal>string</literal> or
<literal>buffer</literal>.
The <literal>options</literal> parameter is expected to be
an object with the following keys:
<list type="tag">
<tag-name><literal>throwIfNoEntry</literal></tag-name>
<tag-desc>
a boolean value which indicates whether
an exception is thrown if no file system entry exists
rather than returning <literal>undefined</literal>,
by default is <literal>true</literal>.
</tag-desc>
</list>
</tag-desc>

<tag-name id="fs_symlinksync"><literal>symlinkSync(<value>target</value>,
<value>path</value>)</literal></tag-name>
<tag-desc>
Synchronously creates the link called <literal>path</literal>
pointing to <literal>target</literal> using
<link url="http://man7.org/linux/man-pages/man2/symlink.2.html">symlink(2)</link>
(<link doc="changes.xml" id="njs0.3.9">0.3.9</link>).
Relative targets are relative to the link’s parent directory.
</tag-desc>

<tag-name id="fs_unlinksync"><literal>unlinkSync(<value>path</value>)</literal></tag-name>
<tag-desc>
Synchronously unlinks a file by <literal>path</literal>
(<link doc="changes.xml" id="njs0.3.9">0.3.9</link>).
</tag-desc>

<tag-name id="fs_writefilesync"><literal>writeFileSync(<value>filename</value>,
<value>data</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
Synchronously writes <literal>data</literal> to a file
with provided <literal>filename</literal>.
The <literal>data</literal> is expected to be a string
or a Buffer object (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>).
If the file does not exist, it will be created,
if the file exists, it will be replaced.
The <literal>options</literal> parameter is expected to be
an object with the following keys:
<list type="tag">
<tag-name><literal>mode</literal></tag-name>
<tag-desc>
mode option, by default is <literal>0o666</literal>
</tag-desc>

<tag-name><literal>flag</literal></tag-name>
<tag-desc>
file system <link id="njs_api_fs_flags">flag</link>,
by default is <literal>w</literal>
</tag-desc>

</list>
<example>
>> var fs = require('fs')
undefined
>> var file = fs.writeFileSync('hello.txt', 'Hello world')
undefined
</example>
</tag-desc>

<tag-name id="fs_writesync_buf"><literal>writeSync(<value>fd</value>,
<value>buffer</value>, <value>offset</value>[,
<value>length</value>[, <value>position</value>]])</literal></tag-name>
<tag-desc>
Writes a buffer to a file using file descriptor,
returns the <literal>number</literal> of bytes written
(<link doc="changes.xml" id="njs0.7.7">0.7.7</link>).

<list type="tag">

<tag-name><literal>fd</literal></tag-name>
<tag-desc>
an <literal>integer</literal> representing the file descriptor
</tag-desc>

<tag-name><literal>buffer</literal></tag-name>
<tag-desc>
the <literal>buffer</literal> value can be a
<literal>Buffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
</tag-desc>

<tag-name><literal>offset</literal></tag-name>
<tag-desc>
is an <literal>integer</literal> that determines
the part of the buffer to be written,
by default <literal>0</literal>
</tag-desc>

<tag-name><literal>length</literal></tag-name>
<tag-desc>
is an <literal>integer</literal> specifying the number of bytes to write,
by default is an offset of
<link id="buffer_bytelength">Buffer.byteLength</link>
</tag-desc>

<tag-name><literal>position</literal></tag-name>
<tag-desc>
refers to the offset from the beginning of the file
where this data should be written,
can be an
<literal>integer</literal> or
<literal>null</literal>,
by default is <literal>null</literal>.
See also
<link url="https://man7.org/linux/man-pages/man2/write.2.html">pwrite(2)</link>.
</tag-desc>
</list>

</tag-desc>

<tag-name id="fs_writesync_str"><literal>writeSync(<value>fd</value>,
<value>string</value>[,
<value>position</value>[,
<value>encoding</value>]])</literal></tag-name>
<tag-desc>
Writes a <literal>string</literal> to a file
using file descriptor <literal>fd</literal>,
returns the <literal>number</literal> of bytes written
(<link doc="changes.xml" id="njs0.7.7">0.7.7</link>).

<list type="tag">

<tag-name><literal>fd</literal></tag-name>
<tag-desc>
is an <literal>integer</literal> representing a file descriptor
</tag-desc>

<tag-name><literal>position</literal></tag-name>
<tag-desc>
refers to the offset from the beginning of the file
where this data should be written,
can be an
<literal>integer</literal> or
<literal>null</literal>, by default is <literal>null</literal>.
See also
<link url="https://man7.org/linux/man-pages/man2/write.2.html">pwrite(2)</link>
</tag-desc>

<tag-name><literal>encoding</literal></tag-name>
<tag-desc>
is a <literal>string</literal>,
by default is <literal>utf8</literal>
</tag-desc>
</list>

</tag-desc>

</list>
</para>


<section id="fs_dirent" name="fs.Dirent">

<para>
<literal>fs.Dirent</literal> is a representation of a directory entry&mdash;
a file or a subdirectory.
When
<link id="fs_readdirsync"><literal>readdirSync()</literal></link>
is called with the
<link id="fs_readdirsync_withfiletypes"><literal>withFileTypes</literal></link>
option,
the resulting array contains <literal>fs.Dirent</literal> objects.

<list type= "bullet" compact="no">

<listitem>
<literal>dirent.isBlockDevice()</literal>&mdash;returns
<literal>true</literal> if the <literal>fs.Dirent</literal> object describes
a block device.
</listitem>

<listitem>
<literal>dirent.isCharacterDevice()</literal>&mdash;returns
<literal>true</literal> if the <literal>fs.Dirent</literal> object describes
a character device.
</listitem>

<listitem>
<literal>dirent.isDirectory()</literal>&mdash;returns
<literal>true</literal> if the <literal>fs.Dirent</literal> object describes
a file system directory.
</listitem>

<listitem>
<literal>dirent.isFIFO()</literal>&mdash;returns
<literal>true</literal> if the <literal>fs.Dirent</literal> object describes
a first-in-first-out (FIFO) pipe.
</listitem>

<listitem>
<literal>dirent.isFile()</literal>&mdash;returns
<literal>true</literal> if the <literal>fs.Dirent</literal> object describes
a regular file.
</listitem>

<listitem>
<literal>dirent.isSocket()</literal>&mdash;returns
<literal>true</literal> if the <literal>fs.Dirent</literal> object describes
a socket.
</listitem>

<listitem>
<literal>dirent.isSymbolicLink()</literal>&mdash;returns
<literal>true</literal> if the <literal>fs.Dirent</literal> object describes
a symbolic link.
</listitem>

<listitem>
<literal>dirent.name</literal>&mdash;
the name of the file <literal>fs.Dirent</literal> object refers to.
</listitem>

</list>
</para>

</section>


<section id="fs_filehandle" name="fs.FileHandle">

<para>
<table width="100%">
<tr><td><link id="filehandle_close"><literal>filehandle.close()</literal></link></td></tr>
<tr><td><link id="filehandle_fd"><literal>filehandle.fd</literal></link></td></tr>
<tr><td><link id="filehandle_read"><literal>filehandle.read()</literal></link></td></tr>
<tr><td><link id="filehandle_stat"><literal>filehandle.stat()</literal></link></td></tr>
<tr><td><link id="filehandle_write_buf"><literal>filehandle.write(<value>buf</value>)</literal></link></td></tr>
<tr><td><link id="filehandle_write_str"><literal>filehandle.write(<value>str</value>)</literal></link></td></tr>
</table>
</para>

<para>
The <literal>FileHandle</literal> object is an object wrapper
for a numeric file descriptor
(<link doc="changes.xml" id="njs0.7.7">0.7.7</link>).
Instances of the <literal>FileHandle</literal> object are created by the
<link id="fs_promises_open"><literal>fs.promises.open()</literal></link> method.
If a <literal>FileHandle</literal> is not closed using the
<link id="filehandle_close"><literal>filehandle.close()</literal></link> method,
it will try to automatically close the file descriptor,
helping to prevent memory leaks.
Please do not rely on this behavior because it can be unreliable.
Instead, always explicitly close a <literal>FileHandle</literal>.
</para>

<para>
<list type="tag">

<tag-name id="filehandle_close"><literal>filehandle.close()</literal></tag-name>
<tag-desc>
Closes the file handle after waiting for any pending operation on the handle
to complete.
Returns a <literal>promise</literal>, fulfills with undefined upon success.
</tag-desc>

<tag-name id="filehandle_fd"><literal>filehandle.fd</literal></tag-name>
<tag-desc>
The numeric file descriptor
managed by the <literal>FileHandle</literal> object.
</tag-desc>

<tag-name id="filehandle_read"><literal>filehandle.read(<value>buffer</value>,
<value>offset</value>[,
<value>length</value>[,
<value>position</value>]])</literal></tag-name>
<tag-desc>
Reads data from the file and stores that in the given buffer.

<list type="tag">

<tag-name><literal>buffer</literal></tag-name>
<tag-desc>
a buffer that will be filled with the file data read,
the value can be a
<literal>Buffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
</tag-desc>

<tag-name><literal>offset</literal></tag-name>
<tag-desc>
is an <literal>integer</literal>
representing the location in the buffer at which to start filling
</tag-desc>

<tag-name><literal>length</literal></tag-name>
<tag-desc>
is an <literal>integer</literal>
representing the number of bytes to read
</tag-desc>

<tag-name><literal>position</literal></tag-name>
<tag-desc>
the location where to begin reading data from the file,
the value can be
<literal>integer</literal>,
<literal>null</literal>.
If <literal>null</literal>, data will be read from the current file position
and the position will be updated.
If position is an <literal>integer</literal>,
the current file position will remain unchanged.
</tag-desc>
</list>

Returns a <literal>Promise</literal> which fulfills upon success
with an object with two properties:
<list type="tag">

<tag-name><literal>bytesRead</literal></tag-name>
<tag-desc>
is an <literal>integer</literal> representing the number of bytes read
</tag-desc>

<tag-name><literal>buffer</literal></tag-name>
<tag-desc>
is a reference to the passed argument in buffer, can be
<literal>Buffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
</tag-desc>
</list>

</tag-desc>

<tag-name id="filehandle_stat"><literal>filehandle.stat()</literal></tag-name>
<tag-desc>
Fulfills with an
<link id="fs_stats">fs.Stats</link> for the file,
returns a <literal>promise</literal>.
</tag-desc>

<tag-name id="filehandle_write_buf"><literal>filehandle.write(<value>buffer</value>,
<value>offset</value>[,
<value>length</value>[,
<value>position</value>]])</literal></tag-name>
<tag-desc>
Writes a buffer to the file.

<list type="tag">

<tag-name><literal>buffer</literal></tag-name>
<tag-desc>
the <literal>buffer</literal> value can be a
<literal>Buffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
</tag-desc>

<tag-name><literal>offset</literal></tag-name>
<tag-desc>
is an <literal>integer</literal> representing
the start position from within buffer where the data to write begins
</tag-desc>

<tag-name><literal>length</literal></tag-name>
<tag-desc>
is an <literal>integer</literal> representing
the number of bytes from buffer to write, by default
is an offset of
<link id="buffer_bytelength">Buffer.byteLength</link>
</tag-desc>

<tag-name><literal>position</literal></tag-name>
<tag-desc>
the offset from the beginning of the file
where the data from buffer should be written,
can be an
<literal>integer</literal> or
<literal>null</literal>,
by default is <literal>null</literal>.
If <literal>position</literal> is not a <literal>number</literal>,
the data will be written at the current position.
See the POSIX
<link url="https://man7.org/linux/man-pages/man2/write.2.html">pwrite(2)</link>
documentation for details.
</tag-desc>
</list>
Returns a <literal>Promise</literal> which is resolved with an object
containing two properties:
<list type="tag">

<tag-name><literal>bytesWritten</literal></tag-name>
<tag-desc>
is an <literal>integer</literal> representing the number of bytes written
</tag-desc>

<tag-name><literal>buffer</literal></tag-name>
<tag-desc>
a reference to the buffer written, can be a
<literal>Buffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
</tag-desc>
</list>
<para>
<note>
It is unsafe to use <literal>filehandle.write()</literal> multiple times
on the same file without waiting for the promise to be resolved or rejected.
</note>
</para>

</tag-desc>

<tag-name id="filehandle_write_str"><literal>filehandle.write(<value>string</value>[,
<value>position</value>[,
<value>encoding</value>]])</literal></tag-name>
<tag-desc>
Writes a <literal>string</literal> to the file.

<list type="tag">

<tag-name><literal>position</literal></tag-name>
<tag-desc>
the offset from the beginning of the file
where the data from buffer should be written,
can be an
<literal>integer</literal> or
<literal>null</literal>,
by default is <literal>null</literal>.
If <literal>position</literal> is not a <literal>number</literal>,
the data will be written at the current position.
See the POSIX
<link url="https://man7.org/linux/man-pages/man2/write.2.html">pwrite(2)</link>
documentation for details.
</tag-desc>

<tag-name><literal>encoding</literal></tag-name>
<tag-desc>
the expected encoding of the string, by default <literal>utf8</literal>
</tag-desc>

</list>
Returns a <literal>Promise</literal> which is resolved with an object
containing two properties:
<list type="tag">

<tag-name><literal>bytesWritten</literal></tag-name>
<tag-desc>
is an <literal>integer</literal> representing the number of bytes written
</tag-desc>

<tag-name><literal>buffer</literal></tag-name>
<tag-desc>
a reference to the buffer written, can be a
<literal>Buffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>
</tag-desc>
</list>
<para>
<note>
It is unsafe to use <literal>filehandle.write()</literal> multiple times
on the same file without waiting for the promise to be resolved or rejected.
</note>
</para>

</tag-desc>

</list>
</para>

</section>


<section id="fs_stats" name="fs.Stats">

<para>
The <literal>fs.Stats</literal> object provides information about a file.
The object is returned from
<link id="fs_statsync">fs.statSync()</link> and
<link id="fs_lstatsync">fs.lstatSync()</link>.

<list type= "bullet" compact="no">

<listitem>
<literal>stats.isBlockDevice()</literal>&mdash;returns
<literal>true</literal> if the <literal>fs.Stats</literal> object describes
a block device.
</listitem>

<listitem>
<literal>stats.isDirectory()</literal>&mdash;returns
<literal>true</literal> if the <literal>fs.Stats</literal> object describes
a file system directory.
</listitem>

<listitem>
<literal>stats.isFIFO()</literal>&mdash;returns
<literal>true</literal> if the <literal>fs.Stats</literal> object describes
a first-in-first-out (FIFO) pipe.
</listitem>

<listitem>
<literal>stats.isFile()</literal>&mdash;returns
<literal>true</literal> if the <literal>fs.Stats</literal> object describes
a regular file.
</listitem>

<listitem>
<literal>stats.isSocket()</literal>&mdash;returns
<literal>true</literal> if the <literal>fs.Stats</literal> object describes
a socket.
</listitem>

<listitem>
<literal>stats.isSymbolicLink()</literal>&mdash;returns
<literal>true</literal> if the <literal>fs.Stats</literal> object describes
a symbolic link.
</listitem>

<listitem>
<literal>stats.dev</literal>&mdash;
the numeric identifier of the device containing the file.
</listitem>

<listitem>
<literal>stats.ino</literal>&mdash;
the file system specific <literal>Inode</literal> number for the file.
</listitem>

<listitem>
<literal>stats.mode</literal>&mdash;
a bit-field describing the file type and mode.
</listitem>

<listitem>
<literal>stats.nlink</literal>&mdash;
the number of hard-links that exist for the file.
</listitem>

<listitem>
<literal>stats.uid</literal>&mdash;
the numeric user identifier of the user that owns the file (POSIX).
</listitem>

<listitem>
<literal>stats.gid</literal>&mdash;
the numeric group identifier of the group that owns the file (POSIX).
</listitem>

<listitem>
<literal>stats.rdev</literal>&mdash;
the numeric device identifier if the file represents a device.
</listitem>

<listitem>
<literal>stats.size</literal>&mdash;
the size of the file in bytes.
</listitem>

<listitem>
<literal>stats.blksize</literal>&mdash;
the file system block size for i/o operations.
</listitem>

<listitem>
<literal>stats.blocks</literal>&mdash;
the number of blocks allocated for this file.
</listitem>

<listitem>
<literal>stats.atimeMs</literal>&mdash;
the timestamp indicating the last time this file was accessed expressed
in milliseconds since the POSIX Epoch.
</listitem>

<listitem>
<literal>stats.mtimeMs</literal>&mdash;
the timestamp indicating the last time this file was modified expressed
in milliseconds since the POSIX Epoch.
</listitem>

<listitem>
<literal>stats.ctimeMs</literal>&mdash;
the timestamp indicating the last time this file was changed expressed
in milliseconds since the POSIX Epoch.
</listitem>

<listitem>
<literal>stats.birthtimeMs</literal>&mdash;
the timestamp indicating the creation time of this file expressed
in milliseconds since the POSIX Epoch.
</listitem>

<listitem>
<literal>stats.atime</literal>&mdash;
the timestamp indicating the last time this file was accessed.
</listitem>

<listitem>
<literal>stats.mtime</literal>&mdash;
the timestamp indicating the last time this file was modified.
</listitem>

<listitem>
<literal>stats.ctime</literal>&mdash;
the timestamp indicating the last time this file was changed.
</listitem>

<listitem>
<literal>stats.birthtime</literal>&mdash;
the timestamp indicating the creation time of this file.
</listitem>

</list>
</para>

</section>


<section id="access_const" name="File Access Constants">

<para>
The <link id="fs_accesssync"><literal>access()</literal></link> method
can accept the following flags.
These flags are exported by <literal>fs.constants</literal>:

<list type= "bullet" compact="no">

<listitem>
<literal>F_OK</literal>&mdash;indicates that the file
is visible to the calling process,
used by default if no mode is specified
</listitem>

<listitem>
<literal>R_OK</literal>&mdash;indicates that the file can be
read by the calling process
</listitem>

<listitem>
<literal>W_OK</literal>&mdash;indicates that the file can be
written by the calling process
</listitem>

<listitem>
<literal>X_OK</literal>&mdash;indicates that the file can be
executed by the calling process
</listitem>

</list>
</para>

</section>


<section id="njs_api_fs_flags" name="File System Flags">

<para>
The <literal>flag</literal> option can accept the following values:

<list type= "bullet" compact="no">

<listitem>
<literal>a</literal>&mdash;open a file for appending.
The file is created if it does not exist
</listitem>

<listitem>
<literal>ax</literal>&mdash;the same as <literal>a</literal>
but fails if the file already exists
</listitem>

<listitem>
<literal>a+</literal>&mdash;open a file for reading and appending.
If the file does not exist, it will be created
</listitem>

<listitem>
<literal>ax+</literal>&mdash;the same as <literal>a+</literal>
but fails if the file already exists
</listitem>

<listitem>
<literal>as</literal>&mdash;open a file for appending
in synchronous mode.
If the file does not exist, it will be created
</listitem>

<listitem>
<literal>as+</literal>&mdash;open a file for reading and appending
in synchronous mode.
If the file does not exist, it will be created
</listitem>

<listitem>
<literal>r</literal>&mdash;open a file for reading.
An exception occurs if the file does not exist
</listitem>

<listitem>
<literal>r+</literal>&mdash;open a file for reading and writing.
An exception occurs if the file does not exist
</listitem>

<listitem>
<literal>rs+</literal>&mdash;open a file for reading and writing
in synchronous mode.
Instructs the operating system to bypass the local file system cache
</listitem>

<listitem>
<literal>w</literal>&mdash;open a file for writing.
If the file does not exist, it will be created.
If the file exists, it will be replaced
</listitem>

<listitem>
<literal>wx</literal>&mdash;the same as <literal>w</literal>
but fails if the file already exists
</listitem>

<listitem>
<literal>w+</literal>&mdash;open a file for reading and writing.
If the file does not exist, it will be created.
If the file exists, it will be replaced
</listitem>

<listitem>
<literal>wx+</literal>&mdash;the same as <literal>w+</literal>
but fails if the file already exists
</listitem>

</list>
</para>

</section>

</section>


<section id="querystring" name="Query String">

<para>
<table width="100%">
<tr><td><link id="querystring_decode"><literal>querystring.decode()</literal></link></td></tr>
<tr><td><link id="querystring_encode"><literal>querystring.encode()</literal></link></td></tr>
<tr><td><link id="querystring_escape"><literal>querystring.escape()</literal></link></td></tr>
<tr><td><link id="querystring_parse"><literal>querystring.parse()</literal></link></td></tr>
<tr><td><link id="querystring_stringify"><literal>querystring.stringify()</literal></link></td></tr>
<tr><td><link id="querystring_unescape"><literal>querystring.unescape()</literal></link></td></tr>
</table>
</para>

<para>
The Query String module provides support
for parsing and formatting URL query strings
(<link doc="changes.xml" id="njs0.4.3">0.4.3</link>).
The Query String module object is returned by
<literal>require('querystring')</literal>.
</para>

<para>
<list type="tag">

<tag-name id="querystring_decode"><literal>querystring.decode()</literal></tag-name>
<tag-desc>
is an alias for
<link id="querystring_parse"><literal>querystring.parse()</literal></link>.
</tag-desc>

<tag-name id="querystring_encode"><literal>querystring.encode()</literal></tag-name>
<tag-desc>
is an alias for
<link id="querystring_stringify"><literal>querystring.stringify()</literal></link>.
</tag-desc>

<tag-name id="querystring_escape"><literal>querystring.escape(<value>string</value>)</literal></tag-name>
<tag-desc>
<para>
Performs URL encoding of the given <literal>string</literal>,
returns an escaped query string.
The method is used by
<link id="querystring_stringify"><literal>querystring.stringify()</literal></link>
and should not be used directly.
</para>
</tag-desc>

<tag-name id="querystring_parse"><literal>querystring.parse(<value>string</value>[,
<value>separator</value>[,
<value>equal</value>[,
<value>options</value>]]])</literal></tag-name>
<tag-desc>
<para>
Parses the query string URL and returns an object.
</para>

<para>
The <literal>separator</literal> parameter is a substring
for delimiting key and value pairs in the query string,
by default is “<literal>&amp;</literal>”.
</para>

<para>
The <literal>equal</literal> parameter is a substring
for delimiting keys and values in the query string,
by default is “<literal>=</literal>”.
</para>

<para>
The <literal>options</literal> parameter is expected to be
an object with the following keys:
<list type="tag">
<tag-name><literal>decodeURIComponent</literal>
<value>function</value></tag-name>
<tag-desc>
Function used
to decode percent-encoded characters in the query string,
by default is
<link id="querystring_unescape"><literal>querystring.unescape()</literal></link>
</tag-desc>

<tag-name><literal>maxKeys</literal>
<value>number</value></tag-name>
<tag-desc>
the maximum number of keys to parse,
by default is <literal>1000</literal>.
The <literal>0</literal> value removes limitations for counting keys.
</tag-desc>

</list>
By default, percent-encoded characters within the query string are assumed
to use the UTF-8 encoding,
invalid UTF-8 sequences will be replaced with
the <literal>U+FFFD</literal> replacement character.
</para>

<para>
For example, for the following query string
<example>
'foo=bar&amp;abc=xyz&amp;abc=123'
</example>
the output will be:
<example>
{
  foo: 'bar',
  abc: ['xyz', '123']
}
</example>
</para>

</tag-desc>

<tag-name id="querystring_stringify"><literal>querystring.stringify(<value>object</value>[,
<value>separator</value>[,
<value>equal</value>[,
<value>options</value>]]])</literal></tag-name>
<tag-desc>
<para>
Serializes an object and returns a URL query string.
</para>

<para>
The <literal>separator</literal> parameter is a substring
for delimiting key and value pairs in the query string,
by default is “<literal>&amp;</literal>”.
</para>

<para>
The <literal>equal</literal> parameter is a substring
for delimiting keys and values in the query string,
by default is “<literal>=</literal>”.
</para>

<para>
The <literal>options</literal> parameter is expected to be
an object with the following keys:
<list type="tag">
<tag-name><literal>encodeURIComponent</literal>
<value>function</value></tag-name>
<tag-desc>
The function to use when converting
URL-unsafe characters to percent-encoding in the query string,
by default is
<link id="querystring_escape"><literal>querystring.escape()</literal></link>.
</tag-desc>

</list>
</para>

<para>
By default, characters that require percent-encoding within the query string
are encoded as UTF-8.
If other encoding is required, then
<literal>encodeURIComponent</literal> option should be specified.
</para>

<para>
For example, for the following command
<example>
querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], 123: '' });
</example>
the query string will be:
<example>
'foo=bar&amp;baz=qux&amp;baz=quux&amp;123='
</example>
</para>

</tag-desc>

<tag-name id="querystring_unescape"><literal>querystring.unescape(<value>string</value>)</literal></tag-name>
<tag-desc>
<para>
Performs decoding of URL percent-encoded characters
of the <literal>string</literal>,
returns an unescaped query string.
The method is used by
<link id="querystring_parse"><literal>querystring.parse()</literal></link>
and should not be used directly.
</para>
</tag-desc>

</list>
</para>

</section>


<section id="xml" name="XML">

<para>
<table width="100%">
<tr><td><link id="xml_parse"><literal>xml.parse()</literal></link></td></tr>
<tr><td><link id="xml_c14n"><literal>xml.c14n()</literal></link></td></tr>
<tr><td><link id="xml_exclusivec14n"><literal>xml.exclusiveC14n()</literal></link></td></tr>
<tr><td><link id="xml_serialize"><literal>xml.serialize()</literal></link></td></tr>
<tr><td><link id="xml_serialize_tostring"><literal>xml.serializeToString()</literal></link></td></tr>
<tr><td><link id="xml_doc"><literal>XMLDoc</literal></link></td></tr>
<tr><td><link id="xml_node"><literal>XMLNode</literal></link></td></tr>
<tr><td><link id="xml_xmlattr"><literal>XMLAttr</literal></link></td></tr>
</table>
</para>

<para>
The XML module allows working with XML documents
(since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>).
The XML module object is returned by
<literal>require('xml')</literal>.
</para>

<para>
Example:
<example>
const xml = require("xml");
let data = `&lt;note&gt;&lt;to b="bar" a= "foo" &gt;Tove&lt;/to&gt;&lt;from&gt;Jani&lt;/from&gt;&lt;/note&gt;`;
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) /* '&lt;note&gt;&lt;to a="foo" b="bar"&gt;Tove&lt;/to&gt;&lt;from&gt;Jani&lt;/from&gt;&lt;/note&gt;' */

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

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

<para>
<list type="tag">

<tag-name id="xml_parse"><literal>parse(<value>string</value> |
<value>Buffer</value>)</literal></tag-name>
<tag-desc>
Parses a string or Buffer for an XML document,
returns an
<link id="xml_doc"><literal>XMLDoc</literal></link> wrapper object
representing the parsed XML document.
</tag-desc>

<tag-name id="xml_c14n"><literal>c14n(<value>root_node</value>[,
<value>excluding_node</value>])</literal></tag-name>
<tag-desc>
Canonicalizes <literal>root_node</literal> and its children according to
<link url="https://www.w3.org/TR/xml-c14n">Canonical XML Version 1.1</link>.
The <literal>root_node</literal> can be
<link id="xml_node"><literal>XMLNode</literal></link> or
<link id="xml_doc"><literal>XMLDoc</literal></link> wrapper object
around XML structure.
Returns Buffer object that contains canonicalized output.

<para>
<list type="tag">

<tag-name><literal>excluding_node</literal></tag-name>
<tag-desc>
allows omitting from the output a part of the document
</tag-desc>

</list>
</para>

</tag-desc>

<tag-name id="xml_exclusivec14n"><literal>exclusiveC14n(<value>root_node</value>[,
<value>excluding_node</value>[,
<value>withComments</value>
[,<value>prefix_list</value>]]])</literal></tag-name>
<tag-desc>
Canonicalizes <literal>root_node</literal> and its children according to
<link url="https://www.w3.org/TR/xml-exc-c14n/">Exclusive XML
Canonicalization Version 1.0</link>.

<para>
<list type="tag">

<tag-name><literal>root_node</literal></tag-name>
<tag-desc>
is
<link id="xml_node"><literal>XMLNode</literal></link> or
<link id="xml_doc"><literal>XMLDoc</literal></link> wrapper object
around XML structure
</tag-desc>

<tag-name><literal>excluding_node</literal></tag-name>
<tag-desc>
allows omitting from the output a part of the document
corresponding to the node and its children
</tag-desc>

<tag-name><literal>withComments</literal></tag-name>
<tag-desc>
a boolean value, <literal>false</literal> by default.
If <literal>true</literal>, canonicalization corresponds to
<link url="http://www.w3.org/2001/10/xml-exc-c14n#WithComments">Exclusive XML
Canonicalization Version 1.0</link>.
Returns Buffer object that contains canonicalized output.
</tag-desc>

<tag-name><literal>prefix_list</literal></tag-name>
<tag-desc>
an optional string with a space separated namespace prefixes
for namespaces that should also be included into the output
</tag-desc>

</list>
</para>

</tag-desc>

<tag-name id="xml_serialize"><literal>serialize()</literal></tag-name>
<tag-desc>
The same as
<link id="xml_c14n"><literal>xml.c14n()</literal></link>
(since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>).
</tag-desc>

<tag-name id="xml_serialize_tostring"><literal>serializeToString()</literal></tag-name>
<tag-desc>
The same as
<link id="xml_c14n"><literal>xml.c14n()</literal></link>
except it returns the result as a <literal>string</literal>
(since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>).
</tag-desc>

<tag-name id="xml_doc"><literal>XMLDoc</literal></tag-name>
<tag-desc>
An XMLDoc wrapper object around XML structure,
the root node of the document.

<para>
<list type="tag">

<tag-name id="xml_doc_root"><literal>doc.$root</literal></tag-name>
<tag-desc>
the document's root by its name or undefined
</tag-desc>

<tag-name id="xml_doc_xxx"><literal>doc.<value>abc</value></literal></tag-name>
<tag-desc>
the first root tag named <value>abc</value> as
<link id="xml_node"><literal>XMLNode</literal></link> wrapper object
</tag-desc>

</list>
</para>

</tag-desc>

<tag-name id="xml_node"><literal>XMLNode</literal></tag-name>
<tag-desc>
An XMLNode wrapper object around XML tag node.
<para>
<list type="tag">

<tag-name id="node_abc"><literal>node.<value>abc</value></literal></tag-name>
<tag-desc>
the same as
<link id="node_tag"><literal>node.$tag$<value>abc</value></literal></link>
</tag-desc>

<tag-name id="node_attr"><literal>node.$attr$<value>abc</value></literal></tag-name>
<tag-desc>
the node's attribute value of <value>abc</value>,
writable
since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>
</tag-desc>

<tag-name id="node_attr_value"><literal>node.$attr$<value>abc</value></literal>=<value>xyz</value></tag-name>
<tag-desc>
the same as
<link id="node_setattribute"><literal>node.setAttribute('<value>abc</value>',
<value>xyz</value>)</literal></link>
(since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>)
</tag-desc>

<tag-name id="node_attrs"><literal>node.$attrs</literal></tag-name>
<tag-desc>
an <link id="xml_xmlattr"><literal>XMLAttr</literal></link> wrapper object
for all attributes of the node
</tag-desc>

<tag-name id="node_name"><literal>node.$name</literal></tag-name>
<tag-desc>
the name of the node
</tag-desc>

<tag-name id="node_ns"><literal>node.$ns</literal></tag-name>
<tag-desc>
the namespace of the node
</tag-desc>

<tag-name id="node_parent"><literal>node.$parent</literal></tag-name>
<tag-desc>
the parent node of the current node
</tag-desc>

<tag-name id="node_tag"><literal>node.$tag$<value>abc</value></literal></tag-name>
<tag-desc>
the first child tag of the node named <value>abc</value>,
writable
since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>
</tag-desc>

<tag-name id="node_tags"><literal>node.$tags</literal></tag-name>
<tag-desc>
an array of all children tags
</tag-desc>

<tag-name id="node_tags_"><literal>node.$tags = [node1, node2, ...]</literal></tag-name>
<tag-desc>
the same as
<link id="node_removechildren"><literal>node.removeChildren</literal>()</link>;
<link id="node_addchild"><literal>node.addChild(<value>node1</value>)</literal></link>;
<link id="node_addchild"><literal>node.addChild(<value>node2</value>)</literal></link>
(since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>).
</tag-desc>

<tag-name id="node_tags_abc"><literal>node.$tags$<value>abc</value></literal></tag-name>
<tag-desc>
all children tags named <value>abc</value> of the node,
writable
since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>
</tag-desc>

<tag-name id="node_text"><literal>node.$text</literal></tag-name>
<tag-desc>
the content of the node,
writable
since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>
</tag-desc>

<tag-name id="node_text_abc"><literal>node.$text = 'abc' </literal></tag-name>
<tag-desc>
the same as
<link id="node_settext"><literal>node.setText('abc')</literal></link>
(since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>)
</tag-desc>

<tag-name id="node_addchild"><literal>node.addChild(<value>nd</value>)</literal></tag-name>
<tag-desc>
adds XMLNode as a child to node
(since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>).
<literal>nd</literal> is recursively copied before adding to the node
</tag-desc>

<tag-name id="node_removeallattr"><literal>node.removeAllAttributes()</literal></tag-name>
<tag-desc>
removes all attributes of the node
(since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>)
</tag-desc>

<tag-name id="node_removeattr"><literal>node.removeAttribute(<value>attr_name</value>)</literal></tag-name>
<tag-desc>
removes the attribute named <literal>attr_name</literal>
(since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>)
</tag-desc>

<tag-name id="node_removechildren"><literal>node.removeChildren(<value>tag_name</value>)</literal></tag-name>
<tag-desc>
removes all the children tags named <literal>tag_name</literal>
(since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>).
If <literal>tag_name</literal> is absent, all children tags are removed
</tag-desc>

<tag-name id="node_removetext"><literal>node.removeText()</literal></tag-name>
<tag-desc>
removes the node's text value
(<link doc="changes.xml" id="njs0.7.11">0.7.11</link>)
</tag-desc>

<tag-name id="node_setattr"><literal>node.setAttribute(<value>attr_name</value>,
<value>value</value>)</literal></tag-name>
<tag-desc>
sets a value for an <literal>attr_name</literal>
(since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>).
When the value is <literal>null</literal>,
the attribute named <literal>attr_name</literal> is deleted
</tag-desc>

<tag-name id="node_settext"><literal>node.setText(<value>value</value>)</literal></tag-name>
<tag-desc>
sets a text value for the node
(since <link doc="changes.xml" id="njs0.7.11">0.7.11</link>).
When the value is <literal>null</literal>, the text of the node is deleted.
</tag-desc>

</list>
</para>

</tag-desc>

<tag-name id="xml_xmlattr"><literal>XMLAttr</literal></tag-name>
<tag-desc>
An XMLAttrs wrapper object around XML node attributes.

<para>
<list type="tag">

<tag-name id="xmlattr_x"><literal>attr.<value>abc</value></literal></tag-name>
<tag-desc>
the attribute value of <value>abc</value>
</tag-desc>

</list>
</para>

</tag-desc>

</list>
</para>

</section>


<section id="zlib" name="zlib">

<para>
<table width="100%">
<tr><td><link id="zlib_deflaterawsync"><literal>zlib.deflateRawSync()</literal></link></td></tr>
<tr><td><link id="zlib_deflatesync"><literal>zlib.deflateSync()</literal></link></td></tr>
<tr><td><link id="zlib_inflaterawsync"><literal>zlib.inflateRawSync()</literal></link></td></tr>
<tr><td><link id="zlib_inflatesync"><literal>zlib.inflateSync()</literal></link></td></tr>
</table>
</para>

<para>
The zlib module provides compression functionality using the
“deflate” and “inflate” algorithms
(since <link doc="changes.xml" id="njs0.7.12">0.7.12</link>).
The zlib module object is returned by
<literal>require('zlib')</literal>.
</para>

<para>
<list type="tag">

<tag-name id="zlib_deflaterawsync"><literal>deflateRawSync(<value>string</value> |
<value>Buffer</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
Compresses data using the “deflate” algorithm provided as a string or Buffer
and does not append a zlib header.
The buffer value can be a
<literal>Buffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>.
<literal>Options</literal> is an optional object that contains
<link id="zlib_options"/>.
Returns Buffer instance that contains the compressed data.
</tag-desc>

<tag-name id="zlib_deflatesync"><literal>deflateSync(<value>string</value> |
<value>Buffer</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
Compresses data using the “deflate” algorithm provided as a string or Buffer.
The Buffer value can be a
<literal>Buffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>.
<literal>Options</literal> is an optional object that contains
<link id="zlib_options"/>.
Returns Buffer instance that contains the compressed data.
</tag-desc>

<tag-name id="zlib_inflaterawsync"><literal>inflateRawSync(<value>string</value> |
<value>Buffer</value>)</literal></tag-name>
<tag-desc>
Decompresses a raw stream by using the “deflate” algorithm.
Returns Buffer instance that contains the decompressed data.
</tag-desc>

<tag-name id="zlib_inflatesync"><literal>inflateSync(<value>string</value> |
<value>Buffer</value>)</literal></tag-name>
<tag-desc>
Decompresses a stream by using the “deflate” algorithm.
Returns Buffer instance that contains the decompressed data.
</tag-desc>

</list>
</para>


<section id="zlib_options" name="zlib options">

<para>
<list type= "bullet" compact="no">

<listitem>
<literal>chunkSize</literal>&mdash;is an integer,
by default is <literal>1024</literal>
</listitem>

<listitem>
<literal>dictionary</literal>&mdash;is a
<literal>Buffer</literal>,
<literal>TypedArray</literal>, or
<literal>DataView</literal>.
by default is empty
</listitem>

<listitem>
<literal>level</literal>&mdash;is an integer, compression only,
see <link id="zlib_compression_levels"/>
</listitem>

<listitem>
<literal>memLevel</literal>&mdash;is an integer
from <literal>1</literal> to <literal>9</literal>, compression only
</listitem>

<listitem>
<literal>strategy</literal>&mdash;is an integer, compression only,
see <link id="zlib_compression_strategy"/>
</listitem>

<listitem>
<literal>windowBits</literal>&mdash;is an integer
from <literal>-15</literal> to <literal>-9</literal>
for raw data,
from <literal>9</literal> to <literal>15</literal>
for an ordinary stream
</listitem>

</list>
</para>

</section>

<section id="zlib_compression_levels" name="zlib compression levels">

<para>
<table>
<tr><td>Name</td><td>Description</td></tr>
<tr><td><literal>zlib.constants.Z_NO_COMPRESSION</literal></td><td>no compression</td></tr>
<tr><td><literal>zlib.constants.Z_BEST_SPEED</literal></td><td>fastest, produces the least compression</td></tr>
<tr><td><literal>zlib.constants.Z_DEFAULT_COMPRESSION</literal></td><td>trade-off between speed and compression</td></tr>
<tr><td><literal>zlib.constants.Z_BEST_COMPRESSION</literal></td><td>slowest, produces the most compression</td></tr>
</table>
</para>

</section>

<section id="zlib_compression_strategy" name="zlib compression strategy">

<para>
<table>
<tr><td>Name</td><td>Description</td></tr>
<tr><td><literal>zlib.constants.Z_FILTERED</literal></td><td>Filtered strategy: for the data produced by a filter or predictor</td></tr>
<tr><td><literal>zlib.constants.Z_HUFFMAN_ONLY</literal></td><td>Huffman-only strategy: only Huffman encoding, no string matching</td></tr>
<tr><td><literal>zlib.constants.Z_RLE</literal></td><td>Run Length Encoding strategy: limit match distances to one, better compression of PNG image data</td></tr>
<tr><td><literal>zlib.constants.Z_FIXED</literal></td><td>Fixed table strategy: prevents the use of dynamic Huffman codes, a simpler decoder for special applications</td></tr>
<tr><td><literal>zlib.constants.Z_DEFAULT_STRATEGY</literal></td><td>Default strategy, suitable for general purpose compression</td></tr>
</table>
</para>

</section>

</section>

</section>

</article>