[njs] Types: refactored working with TypeScript API description.

Dmitry Volyntsev xeioex at nginx.com
Thu Oct 29 13:00:13 UTC 2020


details:   https://hg.nginx.org/njs/rev/a3ae0d653f49
branches:  
changeset: 1554:a3ae0d653f49
user:      Jakub Jirutka <jakub at jirutka.cz>
date:      Thu Oct 29 12:50:05 2020 +0000
description:
Types: refactored working with TypeScript API description.

diffstat:

 auto/make                    |  47 +++++++++++++++++++++-----
 auto/sources                 |   2 +
 ts/README.md                 |  79 ++++++++++++++++++++++++++++++++++++++++++++
 ts/index.d.ts                |   4 ++
 ts/ngx_http_js_module.d.ts   |   2 +-
 ts/ngx_stream_js_module.d.ts |   2 +-
 ts/njs_shell.d.ts            |   2 +-
 ts/package.json              |   3 +-
 8 files changed, 128 insertions(+), 13 deletions(-)

diffs (211 lines):

diff -r 3cc202e562e4 -r a3ae0d653f49 auto/make
--- a/auto/make	Mon Oct 19 23:18:22 2020 +0200
+++ b/auto/make	Thu Oct 29 12:50:05 2020 +0000
@@ -22,6 +22,9 @@ NJS_LINK = ${CC} ${NJS_LD_OPT}
 NJS_CFLAGS = ${NJS_CFLAGS} ${NJS_CC_OPT} ${CFLAGS}
 
 NJS_VER = $(grep NJS_VERSION src/njs.h | sed -e 's/.*"\(.*\)".*/\1/')
+NJS_TYPES_VER = \$(NJS_VER)
+
+NPM = npm
 
 default: $NJS_DEFAULT_TARGET
 
@@ -234,15 +237,6 @@ benchmark: $NJS_BUILD_DIR/njs_auto_confi
 
 	$NJS_BUILD_DIR/njs_benchmark
 
-.PHONY: ts
-ts:
-	mkdir -p $NJS_BUILD_DIR/ts/njs_modules
-	cp ts/*.d.ts $NJS_BUILD_DIR/ts/
-	cp ts/njs_modules/* $NJS_BUILD_DIR/ts/njs_modules/
-
-ts_test: ts
-	tsc ./test/ts/test.ts
-
 dist:
 	rm -rf njs-\$(NJS_VER) \\
 	&& hg archive njs-\$(NJS_VER).tar.gz \\
@@ -251,6 +245,41 @@ dist:
 	&& echo njs-\$(NJS_VER).tar.gz done
 END
 
+njs_ts_deps=`echo $NJS_TS_SRCS \
+        | sed -e "s# *\([^ ][^ ]*\)#\1$njs_regex_cont#g"`
+
+cat << END >> $NJS_MAKEFILE
+
+$NJS_BUILD_DIR/ts/package.json: $njs_ts_deps
+	cp -fr ts $NJS_BUILD_DIR/
+	cp LICENSE $NJS_BUILD_DIR/ts/
+	sed 's/\("version":\s*\)"\([^"]\+\)"/\1"\$(NJS_TYPES_VER)"/' \\
+		ts/package.json > $NJS_BUILD_DIR/ts/package.json
+
+$NJS_BUILD_DIR/ts/node_modules: $NJS_BUILD_DIR/ts/package.json
+	cd $NJS_BUILD_DIR/ts && \$(NPM) install
+	touch $NJS_BUILD_DIR/ts/node_modules
+
+$NJS_BUILD_DIR/njs-types-\$(NJS_TYPES_VER).tgz: $NJS_BUILD_DIR/ts/package.json
+	hg id -i > $NJS_BUILD_DIR/ts/COMMITHASH || true
+	cd $NJS_BUILD_DIR && \$(NPM) pack ./ts
+
+.PHONY: ts
+ts: $NJS_BUILD_DIR/ts/package.json
+
+ts_lint: $NJS_BUILD_DIR/ts/node_modules
+	cd $NJS_BUILD_DIR/ts && \$(NPM) run lint
+
+ts_test: ts
+	tsc ./test/ts/test.ts
+
+ts_publish: ts_clean $NJS_BUILD_DIR/njs-types-\$(NJS_TYPES_VER).tgz
+	cd $NJS_BUILD_DIR/ && \$(NPM) publish njs-types-\$(NJS_TYPES_VER).tgz
+
+ts_clean:
+	rm -rf $NJS_BUILD_DIR/ts
+END
+
 
 # Makefile.
 
diff -r 3cc202e562e4 -r a3ae0d653f49 auto/sources
--- a/auto/sources	Mon Oct 19 23:18:22 2020 +0200
+++ b/auto/sources	Thu Oct 29 12:50:05 2020 +0000
@@ -71,3 +71,5 @@ NJS_TEST_SRCS=" \
    src/test/njs_unit_test.c \
    src/test/njs_benchmark.c \
 "
+
+NJS_TS_SRCS=$(find ts/ -name "*.d.ts" -o -name "*.json")
diff -r 3cc202e562e4 -r a3ae0d653f49 ts/README.md
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/ts/README.md	Thu Oct 29 12:50:05 2020 +0000
@@ -0,0 +1,79 @@
+# TypeScript definitions for njs
+
+This package contains type definitions for [njs](https://github.com/nginx/njs) – NGINX JavaScript.
+
+
+## Usage
+
+Install **njs-types** from the [npm registry](https://www.npmjs.com/) into your project:
+
+```sh
+# using npm:
+npm install --save-dev njs-types
+# or using yarn:
+yarn add --dev njs-types
+```
+
+njs-types provides three entry points with global declarations for each of njs environments:
+
+* `njs_shell.d.ts` – njs shell
+* `ngx_http_js_module.d.ts` – NGINX JS HTTP Module
+* `ngx_stream_js_module.d.ts` – NGINX JS Stream Module
+
+You can either reference them using [triple-slash directive](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html) at top of your `.ts` files (adjust `path` to point into your project’s node_modules):
+
+```ts
+/// <reference path="./node_modules/njs-types/ngx_http_js_module.d.ts" />
+```
+
+or include them using the [files](https://www.typescriptlang.org/tsconfig#files) flag in your `tsconfig.json`, for example:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES5",
+    "module": "es2015",
+    "lib": [
+      "ES2015",
+      "ES2016.Array.Include",
+      "ES2017.Object",
+      "ES2017.String"
+    ],
+    "outDir": "./lib",
+    "downlevelIteration": true,
+
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitThis": true,
+    "alwaysStrict": true,
+
+    "moduleResolution": "node",
+
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+  },
+  "include": [
+    "./src",
+  ],
+  "files": [
+    "./node_modules/njs-types/ngx_http_js_module.d.ts",
+  ],
+}
+```
+
+
+## Versions
+
+njs-types is typically being released together with njs.
+Their major and minor release numbers (the first two numbers) are always aligned, but the patch version (the third number) may differ.
+That's because njs-types may be updated between njs releases and in such case the patch version is incremented.
+
+It's the same strategy as used in [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped#how-do-definitely-typed-package-versions-relate-to-versions-of-the-corresponding-library).
+The reason is that npmjs enforces [SemVer](https://semver.org/) which doesn't allow four-part version number nor provide post-release suffixes.
+
+You can find from which commit the package was built in file `COMMITHASH` inside the published package.
+It contains global revision id in the upstream repository https://hg.nginx.org/njs/ (Mercurial).
diff -r 3cc202e562e4 -r a3ae0d653f49 ts/index.d.ts
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/ts/index.d.ts	Thu Oct 29 12:50:05 2020 +0000
@@ -0,0 +1,4 @@
+/// <reference path="njs_core.d.ts" />
+/// <reference path="njs_modules/crypto.d.ts" />
+/// <reference path="njs_modules/fs.d.ts" />
+/// <reference path="njs_modules/querystring.d.ts" />
diff -r 3cc202e562e4 -r a3ae0d653f49 ts/ngx_http_js_module.d.ts
--- a/ts/ngx_http_js_module.d.ts	Mon Oct 19 23:18:22 2020 +0200
+++ b/ts/ngx_http_js_module.d.ts	Thu Oct 29 12:50:05 2020 +0000
@@ -1,4 +1,4 @@
-/// <reference path="njs_core.d.ts" />
+/// <reference path="index.d.ts" />
 
 interface NginxHTTPArgs {
     readonly [prop: string]: NjsByteString;
diff -r 3cc202e562e4 -r a3ae0d653f49 ts/ngx_stream_js_module.d.ts
--- a/ts/ngx_stream_js_module.d.ts	Mon Oct 19 23:18:22 2020 +0200
+++ b/ts/ngx_stream_js_module.d.ts	Thu Oct 29 12:50:05 2020 +0000
@@ -1,4 +1,4 @@
-/// <reference path="njs_core.d.ts" />
+/// <reference path="index.d.ts" />
 
 interface NginxStreamVariables {
     readonly 'binary_remote_addr'?: NjsByteString;
diff -r 3cc202e562e4 -r a3ae0d653f49 ts/njs_shell.d.ts
--- a/ts/njs_shell.d.ts	Mon Oct 19 23:18:22 2020 +0200
+++ b/ts/njs_shell.d.ts	Thu Oct 29 12:50:05 2020 +0000
@@ -1,4 +1,4 @@
-/// <reference path="njs_core.d.ts" />
+/// <reference path="index.d.ts" />
 
 interface Console {
     log(...args: any[]): void;
diff -r 3cc202e562e4 -r a3ae0d653f49 ts/package.json
--- a/ts/package.json	Mon Oct 19 23:18:22 2020 +0200
+++ b/ts/package.json	Thu Oct 29 12:50:05 2020 +0000
@@ -6,7 +6,8 @@
     "lint": "tsc"
   },
   "files": [
-    "**/*.d.ts"
+    "**/*.d.ts",
+    "COMMITHASH"
   ],
   "types": "index.d.ts",
   "repository": {


More information about the nginx-devel mailing list