Improved typings compatibility

README.md

@@ -8,7 +8,7 @@
 * Semantically similar to the [native](https://github.com/zeromq/libzmq) ØMQ library, while sticking to JavaScript idioms.
 * Use modern JavaScript and Node.js features such as `async`/`await` and async iterators.
 * High performance.
-* Fully usable with TypeScript (3.6+).
+* Fully usable with TypeScript (3+).
 
 ### Useful links
 
@@ -26,6 +26,7 @@
    * [Push/Pull](#pushpull)
    * [Pub/Sub](#pubsub)
    * [Req/Rep](#reqrep)
+   * [TypeScript](#typescript)
    * [More examples](#more-examples)
    * [Compatibility layer for version 4/5](#compatibility-layer-for-version-45)
 * [Contribution](#contribution)
@@ -228,6 +229,29 @@ async function run() {
 run()
 ```
 
+## TypeScript
+
+The library provides typings for TypeScript version 3.0.x and later.
+
+
+ * _Requirements_
+  * TypeScript version >= 3
+  * [compilerOptions](https://www.typescriptlang.org/docs/handbook/compiler-options.html)
+    for TypeScript version < 3.6:
+    * either set `compilerOptions.target` to `esnext` or later (e.g. `es2018`)
+    * or add the following, or similar, libraries to `compilerOptions.lib`
+      (and include their corresponding polyfills if needed):
+      `es2015`, `ESNext.AsyncIterable`
+ * _Example Usage_
+  ```typescript
+  import { Request } from "zeromq"
+  // or as namespace
+  import * as zmq from "zeromq"
+
+  const reqSock = new Request()
+  //...
+  const repSock = new zmq.Reply()
+  ```
 
 ## More examples
 

package.json

@@ -4,6 +4,13 @@
   "description": "Next-generation ZeroMQ bindings for Node.js",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
+  "typesVersions": {
+    ">=3.6": {
+      "lib/*": [
+        "lib/ts3.6/*"
+      ]
+    }
+  },
   "gypfile": true,
   "repository": {
     "type": "git",
@@ -15,6 +22,7 @@
   "devDependencies": {
     "@gnd/typedoc": "^0.15.0-0",
     "@types/chai": ">= 4.1",
+    "@types/fs-extra": "^8.0.1",
     "@types/mocha": ">= 5.2",
     "@types/node": ">= 8.0",
     "@types/semver": ">= 0",
@@ -27,6 +35,7 @@
     "eslint": "^6.7.2",
     "eslint-config-prettier": "^6.7.0",
     "eslint-plugin-prettier": "^3.1.1",
+    "fs-extra": "^8.1.0",
     "gunzip-maybe": "^1.4.1",
     "mocha": ">= 4.0",
     "node-addon-api": "nodejs/node-addon-api",
@@ -35,6 +44,7 @@
     "prettier": "^1.19.1",
     "semver": ">= 0",
     "tar-fs": "^2.0.0",
+    "ts-morph": "^6.0.2",
     "ts-node": ">= 7",
     "typescript": ">= 3.6",
     "weak-napi": ">= 1.0"
@@ -63,11 +73,11 @@
   ],
   "scripts": {
     "install": "node-gyp-build",
-    "ci:compile": "tsc --project tsconfig-build.json",
+    "ci:compile": "tsc --project tsconfig-build.json && node script/ci/downlevel-dts.js",
     "ci:doc": "typedoc --out docs --name zeromq.js --excludeProtected --excludePrivate --excludeNotExported --excludeExternals --externalPattern 'src/+(draft|native|compat).ts' --tsconfig tsconfig-build.json --mode file",
     "ci:prebuild": "prebuildify --napi --strip",
     "dev:build": "rm -f vendor/* && touch vendor/.gitkeep && cp node_modules/node-addon-api/{*.h,LICENSE.md} vendor && prebuildify --napi --build-from-source --debug",
-    "dev:test": "tsc --project tsconfig-build.json && mocha && script/format.sh && rm -f tmp/*",
+    "dev:test": "tsc --project tsconfig-build.json && node script/ci/downlevel-dts.js && mocha && script/format.sh && rm -f tmp/*",
     "dev:bench": "node --expose-gc test/bench"
   },
   "keywords": [

script/ci/downlevel-dts.js

@@ -0,0 +1,183 @@
+// Based on web-streams-polyfill/build/downlevel-dts (MIT licensed) by Mattias Buelens, Diwank Singh Tomer
+// https://github.com/MattiasBuelens/web-streams-polyfill/blob/57d83d0372428532fab83f8d252a5aad950892da/build/downlevel-dts.js
+// Based on downlevel-dts (MIT licensed) by Nathan Shively-Sanders
+// https://github.com/sandersn/downlevel-dts/blob/e7d1cb5aced5686826fe8aac4d4af2f745a9ef60/index.js
+
+/* eslint-env node */
+
+const {Project, ts} = require("ts-morph")
+const path = require("path")
+const fs = require("fs-extra")
+
+const project = new Project()
+const inputDir = project.addDirectoryAtPath(path.join(__dirname, "../../lib/"))
+
+// Create output directory
+fs.emptyDirSync(path.join(inputDir.getPath().toString(), "ts3.6"))
+const ts36Dir = inputDir.createDirectory("ts3.6")
+project.saveSync()
+
+// Down-level all *.d.ts files in input directory
+const files = inputDir.addSourceFilesAtPaths("*.d.ts")
+for (const f of files) {
+  // Create copy for TypeScript 3.6+
+  copyTypingsFile(f, ts36Dir)
+  downlevelTS36(f)
+  downlevelTS34(f)
+  // Original file will be overwritten by down-leveled file when saved
+}
+project.saveSync()
+
+/**
+ * Copy typings source file *.d.ts to target dir
+ */
+function copyTypingsFile(f, targetDir) {
+  const cf = f.copyToDirectory(targetDir, {overwrite: true})
+  const srcPath = f.getDirectoryPath()
+  const targetPath = targetDir.getPath()
+  revertModulePathChange(cf.getImportDeclarations(), srcPath, targetPath)
+  revertModulePathChange(cf.getExportDeclarations(), srcPath, targetPath)
+}
+
+/**
+ * HELPER for reverting changed relative paths for import/export declarations in
+ * copied files, so they to not point to the source-directory but the other
+ * copied files in the target directory.
+ *
+ * For example:
+ * [original in srcDir]         from "./<module-file>"
+ * [after copied to targetDir]  from "../<module-file>"
+ * [reverted in targetDir]      from "./<module-file>"
+ */
+function revertModulePathChange(importExportDecl, srcDir, targetDir) {
+  const absSrcDir = path.resolve(srcDir)
+  for (const decl of importExportDecl) {
+    if (!decl.isModuleSpecifierRelative()) {
+      continue
+    }
+    const declPath = decl.getModuleSpecifierValue()
+    if (!declPath) {
+      continue
+    }
+    const absDeclPath = path.resolve(path.join(targetDir, declPath))
+    if (absDeclPath.indexOf(absSrcDir) === 0) {
+      decl.setModuleSpecifier(relativeModulePath(absDeclPath, targetDir))
+    }
+  }
+}
+
+/**
+ * Down-level TypeScript 3.6 types in the given source file
+ */
+function downlevelTS36(f) {
+  // Replace get/set accessors with (read-only) properties
+  const gs = f.getDescendantsOfKind(ts.SyntaxKind.GetAccessor)
+  for (const g of gs) {
+    const comment = getLeadingComments(g)
+    const s = g.getSetAccessor()
+    const returnTypeNode = g.getReturnTypeNode()
+    const returnType = returnTypeNode ? returnTypeNode.getText() : "any"
+    g.replaceWithText(
+      `${comment}${getModifiersText(g)}${
+        s ? "" : "readonly "
+      }${g.getName()}: ${returnType};`,
+    )
+    if (s) {
+      s.remove()
+    }
+  }
+  const ss = f.getDescendantsOfKind(ts.SyntaxKind.SetAccessor)
+  for (const s of ss) {
+    const g = s.getGetAccessor()
+    if (!g) {
+      const comment = getLeadingComments(s)
+      const firstParam = s.getParameters()[0]
+      const firstParamTypeNode = firstParam && firstParam.getTypeNode()
+      const firstParamType = firstParamTypeNode
+        ? firstParamTypeNode.getText()
+        : "any"
+      s.replaceWithText(
+        `${comment}${getModifiersText(s)}${s.getName()}: ${firstParamType};`,
+      )
+    }
+  }
+}
+
+/**
+ * Down-level TypeScript 3.4 types in the given source file
+ */
+function downlevelTS34(f) {
+  // Replace "es2018.asynciterable" with "esnext.asynciterable" in lib references
+  const refs = f.getLibReferenceDirectives()
+  for (const r of refs) {
+    if (r.getFileName() === "es2018.asynciterable") {
+      f.replaceText([r.getPos(), r.getEnd()], "esnext.asynciterable")
+    }
+  }
+  downlevelEs2018(f)
+}
+
+/**
+ * Down-level es2018 to esnext library in the given source file
+ */
+function downlevelEs2018(f) {
+  // Replace AsyncIterator<T1,T2> with AsyncIterator<T1>
+  const typeParams = f.getDescendantsOfKind(ts.SyntaxKind.TypeReference)
+  for (const t of typeParams) {
+    if (t.wasForgotten()) {
+      continue
+    }
+    const typeName = t.getTypeName().getText()
+    if (typeName === "AsyncIterator") {
+      const params = t.getTypeArguments()
+      if (params.length > 1) {
+        t.replaceWithText(`${typeName}<${params[0].getText()}>`)
+      }
+    }
+  }
+}
+
+function getModifiersText(node) {
+  const modifiersText = node
+    .getModifiers()
+    .map(m => m.getText())
+    .join(" ")
+  return modifiersText.length > 0 ? modifiersText + " " : ""
+}
+
+function getLeadingComments(node) {
+  const t = node.getText()
+  const tlen = t.length
+  const ct = node.getText(true)
+  const ctlen = ct.length
+  // if no comment, or comment not leading, return empty string:
+  if (tlen === ctlen || ct.indexOf(t) !== ctlen - tlen) {
+    return ""
+  }
+  // remove indentation (execept 1 space for "stars-aligning") of comment lines,
+  // since they will be re-indented on insertion
+  // (and remove all leading whitespaces from non-comment lines)
+  return ct
+    .replace(t, "")
+    .replace(/(\r?\n)\s+ /gm, "$1 ")
+    .replace(/(\r?\n)\s+$/gm, "$1")
+}
+
+function relativeModulePath(fromAbsModulePath, toAbsTargetDir) {
+  const fromModDir = path.dirname(fromAbsModulePath)
+  const revertedPath = path.resolve(
+    fromModDir,
+    path.relative(fromModDir, toAbsTargetDir),
+  )
+  let relMod = path.relative(
+    revertedPath,
+    path.join(revertedPath, path.basename(fromAbsModulePath)),
+  )
+  if (!/^\./.test(relMod)) {
+    relMod = "./" + relMod
+  }
+  if (path.sep === "/") {
+    return relMod
+  }
+  return relMod.replace(/\\/g, "/")
+}

test/typings-compatibility/template/README.md

@@ -0,0 +1,27 @@
+# template files for typescript compile test
+
+the tsc versions test is for ensuring the library can be used in projects
+with supported typescript versions
+
+the test cases are specified in `test/unit/tsc-versions-test.ts`
+
+during the test, temporary directories are created for the corresponding
+typescript version x.x.x:
+```
+test/tsc-versions/ts-x.x.x/
+    package.json
+    tsconfig.json
+    <modified copy of typings-test.ts>
+```
+
+the file `typings-test.ts` is copied from `test/unit/typings-test.ts`
+and only its `import` statement for `zmq` is changed from
+```typescript
+// from:
+import * as zmq from "../../src"
+// modified to:
+import * as zmq from "../../../"
+```
+
+relevant fields in `package.json` and `tsconfig.json` are set according to the
+test case definition when they are copied to the temporary directory

test/typings-compatibility/template/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "test-typings-ts-x.x.x",
+  "version": "0.0.0",
+  "description": "template for testing typings in ts projects with specific ts version",
+  "main": "typings-test.ts",
+  "scripts": {
+    "test": "echo TypeScript && tsc --version && tsc --project tsconfig.json"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "x.x.x"
+  }
+}

test/typings-compatibility/template/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "exclude": ["*.d.ts"],
+  "compilerOptions": {
+    "target": "esXXX",
+    "noEmit": true,
+    "strict": true,
+    "module": "commonjs",
+    "types": ["node", "mocha"]
+  }
+}