[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