# HG changeset patch
# User Yaroslav Zhuravlev <yar@nginx.com>
# Date 1587570851 -3600
# Node ID 407c5bd5bffc3df94470f66bf78cc6acf6e1dc46
# Parent  8cc141e0460f221fce78abe97654ecb9aaf84c32
Documented the js_import directive and corresponding changes.

Also the following changes:
- js_include is deprecated
- js_access, js_content, js_filter, js_preread, js_set
  can now accept module.function
- Example Configuration changed for both http and stream js modules.

diff --git a/xml/en/docs/http/ngx_http_js_module.xml b/xml/en/docs/http/ngx_http_js_module.xml
--- a/xml/en/docs/http/ngx_http_js_module.xml
+++ b/xml/en/docs/http/ngx_http_js_module.xml
@@ -9,7 +9,7 @@
 <module name="Module ngx_http_js_module"
         link="/en/docs/http/ngx_http_js_module.html"
         lang="en"
-        rev="19">
+        rev="20">
 
 <section id="summary">
 
@@ -32,22 +32,24 @@ Download and install instructions are av
 <section id="example" name="Example Configuration">
 
 <para>
+The example works since
+<link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>.
 <example>
 load_module modules/ngx_http_js_module.so;
 ...
 
 http {
-    js_include http.js;
+    js_import http.js;
 
-    js_set $foo     foo;
-    js_set $summary summary;
+    js_set $foo     http.foo;
+    js_set $summary http.summary;
 
     server {
         listen 8000;
 
         location / {
             add_header X-Foo $foo;
-            js_content baz;
+            js_content http.baz;
         }
 
         location = /summary {
@@ -55,7 +57,7 @@ http {
         }
 
         location = /hello {
-            js_content hello;
+            js_content http.hello;
         }
     }
 }
@@ -110,6 +112,8 @@ function baz(r) {
 function hello(r) {
     r.return(200, "Hello world!");
 }
+
+export default {foo, summary, baz, hello};
 </example>
 </para>
 
@@ -119,13 +123,44 @@ function hello(r) {
 <section id="directives" name="Directives">
 
 <directive name="js_content">
-<syntax><value>function</value></syntax>
+<syntax><value>function</value> | <value>module.function</value></syntax>
 <default/>
 <context>location</context>
 <context>limit_except</context>
 
 <para>
 Sets an njs function as a location content handler.
+Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>,
+a module function can be referenced.
+</para>
+
+</directive>
+
+
+<directive name="js_import">
+<syntax><value>module.js</value> |
+<value>export_name from module.js</value></syntax>
+<default/>
+<context>http</context>
+<appeared-in>0.4.0</appeared-in>
+
+<para>
+Imports a module that implements location and variable handlers in njs.
+The <literal>export_name</literal> is used as a namespace
+to access module functions.
+If the <literal>export_name</literal> is not specified,
+the module name will be used as a namespace.
+<example>
+js_import http.js;
+</example>
+Here, the module name <literal>http</literal> is used as a namespace
+while accessing exports.
+If the imported module contains <literal>foo()</literal>,
+<literal>http.foo</literal> is used to refer to it.
+</para>
+
+<para>
+Several <literal>js_import</literal> directives can be specified.
 </para>
 
 </directive>
@@ -137,7 +172,25 @@ Sets an njs function as a location conte
 <context>http</context>
 
 <para>
-Specifies a file that implements location and variable handlers in njs.
+Specifies a file that implements location and variable handlers in njs:
+<example>
+nginx.conf:
+js_include http.js;
+location   /version {
+    js_content version;
+}
+
+http.js:
+function version(r) {
+    r.return(200, njs.version);
+}
+</example>
+</para>
+
+<para>
+The directive is deprecated since
+<link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>,
+the <link id="js_import"/> directive should be used instead.
 </para>
 
 </directive>
@@ -159,12 +212,15 @@ Sets an additional path for njs modules.
 
 <directive name="js_set">
 <syntax>
-<value>$variable</value> <value>function</value></syntax>
+<value>$variable</value> <value>function</value> |
+<value>module.function</value></syntax>
 <default/>
 <context>http</context>
 
 <para>
 Sets an njs function for the specified variable.
+Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>,
+a module function can be referenced.
 </para>
 
 </directive>
diff --git a/xml/en/docs/stream/ngx_stream_js_module.xml b/xml/en/docs/stream/ngx_stream_js_module.xml
--- a/xml/en/docs/stream/ngx_stream_js_module.xml
+++ b/xml/en/docs/stream/ngx_stream_js_module.xml
@@ -9,7 +9,7 @@
 <module name="Module ngx_stream_js_module"
         link="/en/docs/stream/ngx_stream_js_module.html"
         lang="en"
-        rev="17">
+        rev="18">
 
 <section id="summary">
 
@@ -31,29 +31,31 @@ Download and install instructions are av
 <section id="example" name="Example Configuration">
 
 <para>
+The example works since
+<link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>.
 <example>
 load_module modules/ngx_stream_js_module.so;
 ...
 
 stream {
-    js_include stream.js;
+    js_import stream.js;
 
-    js_set $bar bar;
-    js_set $req_line req_line;
+    js_set $bar stream.bar;
+    js_set $req_line stream.req_line;
 
     server {
         listen 12345;
 
-        js_preread preread;
+        js_preread stream.preread;
         return     $req_line;
     }
 
     server {
         listen 12346;
 
-        js_access  access;
+        js_access  stream.access;
         proxy_pass 127.0.0.1:8000;
-        js_filter  header_inject;
+        js_filter  stream.header_inject;
     }
 }
 
@@ -121,6 +123,8 @@ function access(s) {
 
     s.allow();
 }
+
+export default {bar, preread, req_line, access};
 </example>
 </para>
 
@@ -130,7 +134,7 @@ function access(s) {
 <section id="directives" name="Directives">
 
 <directive name="js_access">
-<syntax><value>function</value></syntax>
+<syntax><value>function</value> | <value>module.function</value></syntax>
 <default/>
 <context>stream</context>
 <context>server</context>
@@ -138,19 +142,52 @@ function access(s) {
 <para>
 Sets an njs function which will be called at the
 <link doc="stream_processing.xml" id="access_phase">access</link> phase.
+Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>,
+a module function can be referenced.
 </para>
 
 </directive>
 
 
 <directive name="js_filter">
-<syntax><value>function</value></syntax>
+<syntax><value>function</value> | <value>module.function</value></syntax>
 <default/>
 <context>stream</context>
 <context>server</context>
 
 <para>
 Sets a data filter.
+Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>,
+a module function can be referenced.
+</para>
+
+</directive>
+
+
+<directive name="js_import">
+<syntax><value>module.js</value> |
+<value>export_name from module.js</value></syntax>
+<default/>
+<context>stream</context>
+<appeared-in>0.4.0</appeared-in>
+
+<para>
+Imports a module that implements location and variable handlers in njs.
+The <literal>export_name</literal> is used as a namespace
+to access module functions.
+If the <literal>export_name</literal> is not specified,
+the module name will be used as a namespace.
+<example>
+js_import stream.js;
+</example>
+Here, the module name <literal>stream</literal> is used as a namespace
+while accessing exports.
+If the imported module contains <literal>foo()</literal>,
+<literal>stream.foo</literal> is used to refer to it.
+</para>
+
+<para>
+Several <literal>js_import</literal> directives can be specified.
 </para>
 
 </directive>
@@ -162,7 +199,27 @@ Sets a data filter.
 <context>stream</context>
 
 <para>
-Specifies a file that implements server and variable handlers in njs.
+Specifies a file that implements server and variable handlers in njs:
+<example>
+nginx.conf:
+js_include stream.js;
+js_set     $js_addr address;
+server {
+    listen 127.0.0.1:12345;
+    return $js_addr;
+}
+
+stream.js:
+function address(s) {
+    return s.remoteAddress;
+}
+</example>
+</para>
+
+<para>
+The directive is deprecated since
+<link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>,
+the <link id="js_import"/> directive should be used instead.
 </para>
 
 </directive>
@@ -183,7 +240,7 @@ Sets an additional path for njs modules.
 
 
 <directive name="js_preread">
-<syntax><value>function</value></syntax>
+<syntax><value>function</value> | <value>module.function</value></syntax>
 <default/>
 <context>stream</context>
 <context>server</context>
@@ -191,6 +248,8 @@ Sets an additional path for njs modules.
 <para>
 Sets an njs function which will be called at the
 <link doc="stream_processing.xml" id="preread_phase">preread</link> phase.
+Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>,
+a module function can be referenced.
 </para>
 
 </directive>
@@ -198,12 +257,15 @@ Sets an njs function which will be calle
 
 <directive name="js_set">
 <syntax>
-<value>$variable</value> <value>function</value></syntax>
+<value>$variable</value> <value>function</value> |
+<value>module.function</value></syntax>
 <default/>
 <context>stream</context>
 
 <para>
 Sets an njs function for the specified variable.
+Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>,
+a module function can be referenced.
 </para>
 
 </directive>
diff --git a/xml/ru/docs/http/ngx_http_js_module.xml b/xml/ru/docs/http/ngx_http_js_module.xml
--- a/xml/ru/docs/http/ngx_http_js_module.xml
+++ b/xml/ru/docs/http/ngx_http_js_module.xml
@@ -9,7 +9,7 @@
 <module name="Модуль ngx_http_js_module"
         link="/ru/docs/http/ngx_http_js_module.html"
         lang="ru"
-        rev="19">
+        rev="20">
 
 <section id="summary">
 
@@ -32,22 +32,24 @@
 <section id="example" name="Пример конфигурации">
 
 <para>
+Пример работает начиная с версии
+<link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>.
 <example>
 load_module modules/ngx_http_js_module.so;
 ...
 
 http {
-    js_include http.js;
+    js_import http.js;
 
-    js_set $foo     foo;
-    js_set $summary summary;
+    js_set $foo     http.foo;
+    js_set $summary http.summary;
 
     server {
         listen 8000;
 
         location / {
             add_header X-Foo $foo;
-            js_content baz;
+            js_content http.baz;
         }
 
         location = /summary {
@@ -55,7 +57,7 @@ http {
         }
 
         location = /hello {
-            js_content hello;
+            js_content http.hello;
         }
     }
 }
@@ -63,7 +65,7 @@ http {
 </para>
 
 <para>
-Файл <path>http.js</path>:
+The <path>http.js</path> file:
 <example>
 function foo(r) {
     r.log("hello from foo() handler");
@@ -110,6 +112,8 @@ function baz(r) {
 function hello(r) {
     r.return(200, "Hello world!");
 }
+
+export default {foo, summary, baz, hello};
 </example>
 </para>
 
@@ -119,13 +123,45 @@ function hello(r) {
 <section id="directives" name="Директивы">
 
 <directive name="js_content">
-<syntax><value>функция</value></syntax>
+<syntax><value>функция</value> | <value>модуль.функция</value></syntax>
 <default/>
 <context>location</context>
 <context>limit_except</context>
 
 <para>
 Задаёт функцию njs в качестве обработчика содержимого location.
+Начиная с версии <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>
+можно ссылаться на функцию модуля.
+</para>
+
+</directive>
+
+
+<directive name="js_import">
+<syntax><value>модуль.js</value> |
+<value>имя_экспорта из модуль.js</value></syntax>
+<default/>
+<context>http</context>
+<appeared-in>0.4.0</appeared-in>
+
+<para>
+Импортирует модуль, позволяющий задавать обработчики location и переменных
+на njs.
+<literal>Имя_экспорта</literal> является пространством имён
+при доступе к функциям модуля.
+Если <literal>имя_экспорта</literal> не задано,
+то пространством имён будет являться имя модуля.
+<example>
+js_import http.js;
+</example>
+В примере при доступе к экспорту в качестве
+пространства имён используется имя модуля <literal>http</literal>.
+Если импортируемый модуль содержит <literal>foo()</literal>,
+то для доступа используется <literal>http.foo</literal>.
+</para>
+
+<para>
+Директив <literal>js_import</literal> может быть несколько.
 </para>
 
 </directive>
@@ -137,8 +173,25 @@ function hello(r) {
 <context>http</context>
 
 <para>
-Задаёт файл, позволяющий задавать обработчики location и переменных
-на njs.
+Задаёт файл, позволяющий задавать обработчики location и переменных на njs:
+<example>
+nginx.conf:
+js_include http.js;
+location   /version {
+    js_content version;
+}
+
+http.js:
+function version(r) {
+    r.return(200, njs.version);
+}
+</example>
+</para>
+
+<para>
+Директива устарела начиная с
+<link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>,
+вместо неё следует использовать директиву <link id="js_import"/>.
 </para>
 
 </directive>
@@ -160,12 +213,15 @@ function hello(r) {
 
 <directive name="js_set">
 <syntax>
-<value>$переменная</value> <value>функция</value></syntax>
+<value>$переменная</value> <value>функция</value> |
+<value>модуль.функция</value></syntax>
 <default/>
 <context>http</context>
 
 <para>
 Задаёт функцию njs для указанной переменной.
+Начиная с <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>
+можно ссылаться на функцию модуля.
 </para>
 
 </directive>
diff --git a/xml/ru/docs/stream/ngx_stream_js_module.xml b/xml/ru/docs/stream/ngx_stream_js_module.xml
--- a/xml/ru/docs/stream/ngx_stream_js_module.xml
+++ b/xml/ru/docs/stream/ngx_stream_js_module.xml
@@ -9,7 +9,7 @@
 <module name="Модуль ngx_stream_js_module"
         link="/ru/docs/stream/ngx_stream_js_module.html"
         lang="ru"
-        rev="17">
+        rev="18">
 
 <section id="summary">
 
@@ -31,29 +31,31 @@
 <section id="example" name="Пример конфигурации">
 
 <para>
+Пример работает начиная с версии
+<link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>.
 <example>
 load_module modules/ngx_stream_js_module.so;
 ...
 
 stream {
-    js_include stream.js;
+    js_import stream.js;
 
-    js_set $bar bar;
-    js_set $req_line req_line;
+    js_set $bar stream.bar;
+    js_set $req_line stream.req_line;
 
     server {
         listen 12345;
 
-        js_preread preread;
+        js_preread stream.preread;
         return     $req_line;
     }
 
     server {
         listen 12346;
 
-        js_access  access;
+        js_access  stream.access;
         proxy_pass 127.0.0.1:8000;
-        js_filter  header_inject;
+        js_filter  stream.header_inject;
     }
 }
 
@@ -121,6 +123,8 @@ function access(s) {
 
     s.allow();
 }
+
+export default {bar, preread, req_line, access};
 </example>
 </para>
 
@@ -130,7 +134,7 @@ function access(s) {
 <section id="directives" name="Директивы">
 
 <directive name="js_access">
-<syntax><value>функция</value></syntax>
+<syntax><value>функция</value> | <value>модуль.функция</value></syntax>
 <default/>
 <context>stream</context>
 <context>server</context>
@@ -138,19 +142,53 @@ function access(s) {
 <para>
 Задаёт функцию njs, которая будет вызываться в
 <link doc="stream_processing.xml" id="access_phase">access</link>-фазе.
+Начиная с <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>
+можно ссылаться на функцию модуля.
 </para>
 
 </directive>
 
 
 <directive name="js_filter">
-<syntax><value>функция</value></syntax>
+<syntax><value>функция</value> | <value>модуль.функция</value></syntax>
 <default/>
 <context>stream</context>
 <context>server</context>
 
 <para>
 Задаёт фильтр данных.
+Начиная с <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>
+можно ссылаться на функцию модуля.
+</para>
+
+</directive>
+
+
+<directive name="js_import">
+<syntax><value>модуль.js</value> |
+<value>имя_экспорта из модуль.js</value></syntax>
+<default/>
+<context>stream</context>
+<appeared-in>0.4.0</appeared-in>
+
+<para>
+Импортирует модуль, позволяющий задавать обработчики location и переменных
+на njs.
+<literal>Имя_экспорта</literal> является пространством имён
+при доступе к функциям модуля.
+Если <literal>имя_экспорта</literal> не задано,
+то пространством имён будет являться имя модуля.
+<example>
+js_import stream.js;
+</example>
+В примере при доступе к экспорту в качестве
+пространства имён используется имя модуля <literal>stream</literal>.
+Если импортируемый модуль содержит <literal>foo()</literal>,
+то для доступа используется <literal>stream.foo</literal>.
+</para>
+
+<para>
+Директив <literal>js_import</literal> может быть несколько.
 </para>
 
 </directive>
@@ -162,15 +200,34 @@ function access(s) {
 <context>stream</context>
 
 <para>
-Задаёт файл, который позволяет
-задавать обработчики server и переменных на njs.
+Задаёт файл, который позволяет задавать обработчики server и переменных на njs:
+<example>
+nginx.conf:
+js_include stream.js;
+js_set     $js_addr address;
+server {
+    listen 127.0.0.1:12345;
+    return $js_addr;
+}
+
+stream.js:
+function address(s) {
+    return s.remoteAddress;
+}
+</example>
+</para>
+
+<para>
+Директива устарела начиная с
+<link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>,
+вместо неё следует использовать директиву <link id="js_import"/>.
 </para>
 
 </directive>
 
 
 <directive name="js_preread">
-<syntax><value>функция</value></syntax>
+<syntax><value>функция</value> | <value>модуль.функция</value></syntax>
 <default/>
 <context>stream</context>
 <context>server</context>
@@ -178,6 +235,8 @@ function access(s) {
 <para>
 Задаёт функцию njs, которая будет вызываться в
 <link doc="stream_processing.xml" id="preread_phase">preread</link>-фазе.
+Начиная с <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>
+можно ссылаться на функцию модуля.
 </para>
 
 </directive>
@@ -199,12 +258,15 @@ function access(s) {
 
 <directive name="js_set">
 <syntax>
-<value>$переменная</value> <value>функция</value></syntax>
+<value>$переменная</value> <value>функция</value> |
+<value>модуль.функция</value></syntax>
 <default/>
 <context>stream</context>
 
 <para>
 Задаёт функцию njs для указанной переменной.
+Начиная с <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>
+можно ссылаться на функцию модуля.
 </para>
 
 </directive>