Mercurial > hg > nginx-site

changeset 2541:0e6bbd8138c4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added article about TypeScript in njs.
author Yaroslav Zhuravlev <yar@nginx.com>
date Fri, 15 May 2020 16:22:43 +0100
parents b686736680e3
children bde7cd9a1173
files xml/en/GNUmakefile xml/en/docs/njs/index.xml xml/en/docs/njs/typescript.xml xml/ru/GNUmakefile xml/ru/docs/njs/index.xml xml/ru/docs/njs/typescript.xml
diffstat 6 files changed, 260 insertions(+), 10 deletions(-) [+]
line wrap: on
line diff
--- a/xml/en/GNUmakefile
+++ b/xml/en/GNUmakefile
@@ -130,6 +130,7 @@ REFS =									\
 		njs/install						\
 		njs/reference						\
 		njs/node_modules					\
+		njs/typescript						\
 
 TOP =									\
 		download						\
--- a/xml/en/docs/njs/index.xml
+++ b/xml/en/docs/njs/index.xml
@@ -9,7 +9,7 @@
 <article name="njs scripting language"
         link="/en/docs/njs/index.html"
         lang="en"
-        rev="28"
+        rev="29"
         toc="no">
 
 <section id="summary">
@@ -50,10 +50,6 @@ The compliance is still <link doc="compa
 </listitem>
 
 <listitem>
-<link doc="node_modules.xml"/>
-</listitem>
-
-<listitem>
 <link doc="compatibility.xml"/>
 </listitem>
 
@@ -80,6 +76,20 @@ ngx_stream_js_module</link>
 </list>
 </para>
 
+<para>
+<list type="bullet">
+
+<listitem>
+<link doc="typescript.xml"/>
+</listitem>
+
+<listitem>
+<link doc="node_modules.xml"/>
+</listitem>
+
+</list>
+</para>
+
 </section>
 
 
new file mode 100644
--- /dev/null
+++ b/xml/en/docs/njs/typescript.xml
@@ -0,0 +1,114 @@
+<?xml version="1.0"?>
+
+<!--
+  Copyright (C) Nginx, Inc.
+  -->
+
+<!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
+
+<article name="Writing njs code using TypeScript definition files"
+        link="/en/docs/njs/typescript.html"
+        lang="en"
+        rev="1">
+
+<section>
+
+<para>
+<link url="https://www.typescriptlang.org">TypeScript</link> is
+a typed superset of JavaScript
+that compiles to plain JavaScript.
+</para>
+
+<para>
+TypeScript supports definition files that contain
+type information of existing JavaScript libraries.
+This enables other programs to use the values defined in the files
+as if they were statically typed TypeScript entities.
+</para>
+
+<para>
+njs provides TypeScript definition files for its
+<link doc="reference.xml">API</link> which can be used to:
+<list type="bullet">
+
+<listitem>
+Get autocompletion and API check in an editor
+</listitem>
+
+<listitem>
+Write njs type-safe code
+</listitem>
+
+</list>
+</para>
+
+</section>
+
+
+<section id="get" name="Compiling TypeScript definition files">
+
+<para>
+<example>
+$ hg clone http://hg.nginx.org/njs
+$ cd njs &amp;&amp; ./configure &amp;&amp; make ts
+$ ls build/ts/
+njs_core.d.ts
+njs_shell.d.ts
+ngx_http_js_module.d.ts
+ngx_stream_js_module.d.ts
+</example>
+</para>
+
+</section>
+
+
+<section id="autocomplete" name="API checks and autocompletions">
+
+<para>
+Put <literal>*.d.ts</literal> files to a place where you editor can find it.
+</para>
+
+<para>
+<literal>test.js</literal>:
+<example>
+/// &lt;reference path="ngx_http_js_module.d.ts" /&gt;
+/**
+ * @param {NginxHTTPRequest} r
+ * */
+function content_handler(r) {
+    r.headersOut['content-type'] = 'text/plain';
+    r.return(200, "Hello");
+}
+</example>
+</para>
+
+</section>
+
+
+<section id="write" name="Writing njs type-safe code">
+
+<para>
+<literal>test.ts</literal>:
+<example>
+/// &lt;reference path="ngx_http_js_module.d.ts" /&gt;
+function content_handler(r: NginxHTTPRequest) {
+    r.headersOut['content-type'] = 'text/plain';
+    r.return(200, "Hello from TypeScript");
+}
+</example>
+TypeScript installation:
+<example>
+# npm install -g typescript
+</example>
+TypeScript compilation:
+<example>
+$ tsc test.ts
+$ cat test.js
+</example>
+The resulting <literal>test.js</literal> file can be used directly with njs.
+</para>
+
+</section>
+
+
+</article>
--- a/xml/ru/GNUmakefile
+++ b/xml/ru/GNUmakefile
@@ -112,6 +112,7 @@ REFS =									\
 		njs/examples						\
 		njs/install						\
 		njs/reference						\
+		njs/typescript						\
 
 TOP =									\
 		download						\
--- a/xml/ru/docs/njs/index.xml
+++ b/xml/ru/docs/njs/index.xml
@@ -9,7 +9,7 @@
 <article name="Сценарный язык njs"
         link="/ru/docs/njs/index.html"
         lang="ru"
-        rev="28"
+        rev="29"
         toc="no">
 
 <section id="summary">
@@ -51,10 +51,6 @@ njs совместим с
 </listitem>
 
 <listitem>
-<link doc="node_modules.xml">Использование модулей Node.js в njs</link>
-</listitem>
-
-<listitem>
 <link doc="compatibility.xml"/>
 </listitem>
 
@@ -81,6 +77,20 @@ ngx_stream_js_module</link>
 </list>
 </para>
 
+<para>
+<list type="bullet">
+
+<listitem>
+<link doc="typescript.xml"/>
+</listitem>
+
+<listitem>
+<link doc="node_modules.xml">Использование модулей Node.js в njs</link>
+</listitem>
+
+</list>
+</para>
+
 </section>
 
 
new file mode 100644
--- /dev/null
+++ b/xml/ru/docs/njs/typescript.xml
@@ -0,0 +1,114 @@
+<?xml version="1.0"?>
+
+<!--
+  Copyright (C) Nginx, Inc.
+  -->
+
+<!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
+
+<article name="Создание кода njs при помощи файлов деклараций TypeScript"
+        link="/en/docs/njs/typescript.html"
+        lang="en"
+        rev="1">
+
+<section>
+
+<para>
+<link url="https://www.typescriptlang.org">TypeScript</link>&mdash;это
+типизированное подмножество JavaScript,
+которое компилируется в обычный JavaScript.
+</para>
+
+<para>
+TypeScript поддерживает файлы деклараций, в которых содержится
+типизированная информация существующих библиотек JavaScript.
+С их помощью программы могут использовать значения в файлах также,
+если бы эти значения были статически типизированными сущностями TypeScript.
+</para>
+
+<para>
+В njs файлы деклараций TypeScript предоставляются для 
+<link doc="reference.xml">API</link> и могут использоваться при:
+<list type="bullet">
+
+<listitem>
+автозаполнении и проверки API в редакторе
+</listitem>
+
+<listitem>
+создании типобезопасного njs-кода.
+</listitem>
+
+</list>
+</para>
+
+</section>
+
+
+<section id="get" name="Компиляция файлов деклараций TypeScript">
+
+<para>
+<example>
+$ hg clone http://hg.nginx.org/njs
+$ cd njs &amp;&amp; ./configure &amp;&amp; make ts
+$ ls build/ts/
+njs_core.d.ts
+njs_shell.d.ts
+ngx_http_js_module.d.ts
+ngx_stream_js_module.d.ts
+</example>
+</para>
+
+</section>
+
+
+<section id="autocomplete" name="Проверка API и автозаполнение">
+
+<para>
+Файлы деклараций <literal>*.d.ts</literal> необходимо поместить в место,
+доступное редактору:
+</para>
+
+<para>
+<literal>test.js</literal>:
+<example>
+/// &lt;reference path="ngx_http_js_module.d.ts" /&gt;
+/**
+ * @param {NginxHTTPRequest} r
+ * */
+function content_handler(r) {
+    r.headersOut['content-type'] = 'text/plain';
+    r.return(200, "Hello");
+}
+</example>
+</para>
+
+</section>
+
+
+<section id="write" name="Создание типобезопасного njs кода">
+
+<para>
+<literal>test.ts</literal>:
+<example>
+/// &lt;reference path="ngx_http_js_module.d.ts" /&gt;
+function content_handler(r: NginxHTTPRequest) {
+    r.headersOut['content-type'] = 'text/plain';
+    r.return(200, "Hello from TypeScript");
+}
+</example>
+Установка TypeScript:
+<example>
+# npm install -g typescript
+</example>
+Компиляция TypeScript:
+<example>
+$ tsc test.ts
+$ cat test.js
+</example>
+Созданный файл <literal>test.js</literal> может использоваться напрямую в njs.
+</para>
+
+</section>
+
+</article>