From 8dd44b269a8f5ec7afaef84febaed5f446c03533 Mon Sep 17 00:00:00 2001 From: Jakub Jirutka Date: Thu, 29 Oct 2020 12:50:05 +0000 Subject: [PATCH] Types: refactored working with TypeScript API description. --- 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(-) create mode 100644 ts/README.md create mode 100644 ts/index.d.ts diff --git a/auto/make b/auto/make index c085e95d..5c910a7f 100644 --- a/auto/make +++ b/auto/make @@ -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_config.h \\ $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 --git a/auto/sources b/auto/sources index 418a4d61..b7c0a465 100644 --- a/auto/sources +++ b/auto/sources @@ -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 --git a/ts/README.md b/ts/README.md new file mode 100644 index 00000000..774fd462 --- /dev/null +++ b/ts/README.md @@ -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 +/// +``` + +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 --git a/ts/index.d.ts b/ts/index.d.ts new file mode 100644 index 00000000..8a324cc6 --- /dev/null +++ b/ts/index.d.ts @@ -0,0 +1,4 @@ +/// +/// +/// +/// diff --git a/ts/ngx_http_js_module.d.ts b/ts/ngx_http_js_module.d.ts index 0440b7f4..c6b94e4f 100644 --- a/ts/ngx_http_js_module.d.ts +++ b/ts/ngx_http_js_module.d.ts @@ -1,4 +1,4 @@ -/// +/// interface NginxHTTPArgs { readonly [prop: string]: NjsByteString; diff --git a/ts/ngx_stream_js_module.d.ts b/ts/ngx_stream_js_module.d.ts index 67e24dfa..46aa76dd 100644 --- a/ts/ngx_stream_js_module.d.ts +++ b/ts/ngx_stream_js_module.d.ts @@ -1,4 +1,4 @@ -/// +/// interface NginxStreamVariables { readonly 'binary_remote_addr'?: NjsByteString; diff --git a/ts/njs_shell.d.ts b/ts/njs_shell.d.ts index ce3e3148..e8180258 100644 --- a/ts/njs_shell.d.ts +++ b/ts/njs_shell.d.ts @@ -1,4 +1,4 @@ -/// +/// interface Console { log(...args: any[]): void; diff --git a/ts/package.json b/ts/package.json index 5bc34d31..e7b2eb77 100644 --- a/ts/package.json +++ b/ts/package.json @@ -6,7 +6,8 @@ "lint": "tsc" }, "files": [ - "**/*.d.ts" + "**/*.d.ts", + "COMMITHASH" ], "types": "index.d.ts", "repository": { -- 2.47.3