feat: setup downleveled types for typescript@4.2 and above

.eslintrc.js

@@ -21,7 +21,9 @@ module.exports = {
     '@typescript-eslint',
     'rulesdir',
   ],
-  ignorePatterns: ['dist', 'es', 'src/apis', 'docs/api', 'test/environment/ledger/browser'],
+  ignorePatterns: [
+    'dist', 'es', 'src/apis', 'docs/api', 'test/environment/ledger/browser', 'types-legacy',
+  ],
   rules: {
     'rulesdir/tsdoc-syntax': 'error',
     'no-spaced-func': 'off',

.gitignore

@@ -21,7 +21,7 @@ debug/
 /coverage
 coverage.*
 .nyc_output/
-/examples/**/package-lock.json
+/**/package-lock.json
 /examples/**/dist
 /examples/**/artifacts
 .history
@@ -30,3 +30,4 @@ site
 /src/apis/
 /tooling/autorest/compiler-swagger.yaml
 /test/environment/ledger/browser
+/types-legacy

docs/compatibility.md

@@ -16,7 +16,7 @@ This package is expected to work in these environments:
 | create-react-native-app@3 (webpack@4) | mjs build is not compatible with webpack@4 [cra-webpack-4]                    |
 | meteor@2                              |                                                                               |
 | jest@27.5.1                           | requires an environment where Buffer is instanceof Uint8Array [jest]          |
-| typescript                            | requires `tsconfig.json` adjustments [typescript]                             |
+| typescript>=4.1, ideally >=4.7        | requires `tsconfig.json` adjustments [typescript]                             |
 | vite@3                                | requires `build.target: 'es2020'` and `bigint: true` in vite.config.js [vite] |
 
 [webpack-4]: https://github.com/webpack/webpack/issues/7482#issuecomment-394884837

docs/index.md

@@ -80,6 +80,7 @@ This may be done in `tsconfig.json`:
   }
 }
 ```
+SDK uses modern features available since typescript@4.7. Though SDK is still compatible with typescript@4.1 and above using types generated separately, but these types are less accurate.
 
 ## Command Line Interface (CLI)
 If you don't need to include specific functionality into your application and just want to use or play around with features the SDK provides you can make use of the [💻 CLI](https://github.com/aeternity/aepp-cli-js) and follow the instructions mentioned there.

package.json

@@ -4,6 +4,18 @@
   "description": "SDK for the æternity blockchain",
   "main": "dist/aepp-sdk.js",
   "types": "es/index.d.ts",
+  "typesVersions": {
+    "<4.5": {
+      "es/index.d.ts": [
+        "./types-legacy/ts4.2/index.d.ts"
+      ]
+    },
+    "<4.7": {
+      "es/index.d.ts": [
+        "./types-legacy/ts4.5/index.d.ts"
+      ]
+    }
+  },
   "module": "es/index.mjs",
   "browser": {
     "dist/aepp-sdk.js": "./dist/aepp-sdk.browser.js"
@@ -15,9 +27,10 @@
   },
   "sideEffects": false,
   "scripts": {
-    "build:es": "tsc && babel src --config-file ./babel.esm.config.js --out-dir es --extensions .js,.ts --out-file-extension .mjs --source-maps true",
+    "build:types": "tsc && node tooling/downlevel/run.mjs",
+    "build:es": "babel src --config-file ./babel.esm.config.js --out-dir es --extensions .js,.ts --out-file-extension .mjs --source-maps true",
     "build:api": "node tooling/autorest/compiler-prepare.mjs && npx autorest tooling/autorest/compiler.yaml --output-artifact:code-model-v4 && npx autorest tooling/autorest/node.yaml --output-artifact:code-model-v4",
-    "build": "npm run build:api && webpack && npm run build:es",
+    "build": "npm run build:api && webpack && npm run build:types && npm run build:es",
     "docs:examples": "node tooling/docs/examples-to-md.js examples/node/*.mjs",
     "docs:api": "typedoc",
     "commitlint": "commitlint --from develop",
@@ -97,6 +110,7 @@
     "chai": "^4.3.7",
     "chai-as-promised": "^7.1.1",
     "cross-fetch": "^3.1.5",
+    "downlevel-dts": "github:aeternity/downlevel-dts",
     "eslint": "^8.28.0",
     "eslint-config-airbnb-base": "^15.0.0",
     "eslint-config-airbnb-typescript": "^17.0.0",
@@ -118,6 +132,7 @@
   },
   "files": [
     "dist",
+    "types-legacy",
     "src",
     "es"
   ],

test/environment/typescript/main.ts

@@ -0,0 +1,3 @@
+import * as Sdk from '@aeternity/aepp-sdk';
+
+console.log('Sdk', Sdk);

test/environment/typescript/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "typescript-test",
+  "version": "1.0.0",
+  "description": "",
+  "main": "main.ts",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@aeternity/aepp-sdk": "file:../../.."
+  },
+  "devDependencies": {
+    "typescript": "4.1"
+  }
+}

test/environment/typescript/run.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+set -e
+
+# revisit --ignore-scripts after solving https://github.com/npm/cli/issues/4202
+sed -i '' 's/"prepare"/"rem-prepare"/g' ../../../package.json
+
+for i in {9..1}
+do
+  echo "Try typescript@4.$i"
+  npm i "typescript@4.$i" -D --no-audit
+  npx tsc
+done
+
+sed -i '' 's/"rem-prepare"/"prepare"/g' ../../../package.json

test/environment/typescript/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "target": "es2016",
+    "moduleResolution": "node",
+    "noEmit": true,
+    "typeRoots": [
+      "./node_modules/@types",
+      "../../../src/typings"
+    ]
+  }
+}

test/examples.sh

@@ -8,6 +8,11 @@ echo Run environment/node.mjs
 echo Run environment/node.ts
 ./test/environment/node.ts
 
+echo Check typescript
+cd ./test/environment/typescript/
+./run.sh
+cd ../../..
+
 run_node_example () {
   echo Run $1
   cat ./examples/node/$1 | sed -e "s|@aeternity/aepp-sdk|./es/index.mjs|" | node --input-type=module

tooling/downlevel/globals-ts4.2.d.ts

@@ -0,0 +1,16 @@
+/**
+ * required for TS\@4.4 and below
+ * copied from https://github.com/microsoft/TypeScript/blob/f6628a4573cd37c26912f78de3d08cd1dbf687a5/lib/lib.es5.d.ts#L1530-L1539
+ * Recursively unwraps the "awaited type" of a type. Non-promise "thenables" should resolve to
+ * `never`. This emulates the behavior of `await`.
+ */
+type Awaited<T> =
+  // special case for `null | undefined` when not in `--strictNullChecks` mode
+  T extends null | undefined ? T :
+    // `await` only unwraps object types with a callable `then`. Non-object types are not unwrapped
+    T extends object & { then: (onfulfilled: infer F, ...args: infer _) => any } ?
+      // if the argument to `then` is callable, extracts the first argument
+      F extends ((value: infer V, ...args: infer _2) => any) ?
+        Awaited<V> : // recursively unwrap the value
+        never : // the argument to `then` was not callable
+      T; // non-object or non-thenable

tooling/downlevel/run.mjs

@@ -0,0 +1,15 @@
+import { copyFileSync, appendFileSync } from 'fs';
+import { spawnSync } from 'child_process';
+
+const run = (...args) => {
+  const { error } = spawnSync('npx', args, { stdio: 'inherit', shell: true });
+  if (error) throw error;
+};
+
+console.log('Generating types for typescript@4.2');
+run('downlevel-dts', 'es', 'types-legacy/ts4.2', '--to=4.2');
+copyFileSync('tooling/downlevel/globals-ts4.2.d.ts', 'types-legacy/ts4.2/globals.d.ts');
+appendFileSync('types-legacy/ts4.2/index.d.ts', 'import \'./globals\';\n');
+
+console.log('Generating types for typescript@4.5');
+run('downlevel-dts', 'es', 'types-legacy/ts4.5', '--to=4.5');

tsconfig.eslint.json

@@ -1,6 +1,8 @@
 {
   "extends": "./tsconfig.json",
   "include": [
-    "test/**/*"
+    "src/**/*",
+    "test/**/*",
+    "tooling/**/*"
   ]
 }