feat: Bundle JSDoc-built TypeScript declaration file (#34)

* feat: bundle JSDoc-built TypeScript declaration file

* refactor: allow undefined keys (but not for keys argument or return value of `unionWith`)

* fix: `types` and `files` location

* fix: resolve "Cannot find module" error by using `outDir`

* refactor: Shorten types with typedefs

* refactor: Remove extra `types`

* refactor: revert switch to `nodenext`

* refactor: Drop use of `KeysLooseReadonly`

* refactor: set target to `es6`

* chore: move `tsc` to build step

* test: tsd tests of declaration file

* test: exported type checks

* refactor: rename KeysStrict -> VisitorKeysWritable, and KeysStrictReadonly -> VisitorKeys

* test: fix reference to declaration file

Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>

* test: avoid exporting internal `VisitorKeysWritable` type

* refactor: Remove need for legacy code tests

Co-authored-by: Milos Djermanovic <milos.djermanovic@gmail.com>

.eslintrc.json

@@ -7,6 +7,15 @@
         "sourceType": "module",
         "ecmaVersion": 2020
     },
+    "settings": {
+        "jsdoc": {
+            "mode": "typescript",
+            "preferredTypes": {
+                "Object": "object",
+                "object<>": "Object"
+            }
+        }
+    },
     "overrides": [
         {
             "files": ["*.cjs"],

lib/index.js

@@ -4,6 +4,10 @@
  */
 import KEYS from "./visitor-keys.js";
 
+/**
+ * @typedef {{ readonly [type: string]: ReadonlyArray<string> }} VisitorKeys
+ */
+
 // List to ignore keys.
 const KEY_BLACKLIST = new Set([
     "parent",
@@ -22,8 +26,8 @@ function filterKey(key) {
 
 /**
  * Get visitor keys of a given node.
- * @param {Object} node The AST node to get keys.
- * @returns {string[]} Visitor keys of the node.
+ * @param {object} node The AST node to get keys.
+ * @returns {readonly string[]} Visitor keys of the node.
  */
 export function getKeys(node) {
     return Object.keys(node).filter(filterKey);
@@ -33,11 +37,13 @@ export function getKeys(node) {
 // eslint-disable-next-line valid-jsdoc
 /**
  * Make the union set with `KEYS` and given keys.
- * @param {Object} additionalKeys The additional keys.
- * @returns {{ [type: string]: string[] | undefined }} The union set.
+ * @param {VisitorKeys} additionalKeys The additional keys.
+ * @returns {VisitorKeys} The union set.
  */
 export function unionWith(additionalKeys) {
-    const retv = Object.assign({}, KEYS);
+    const retv = /** @type {{
+        [type: string]: ReadonlyArray<string>
+    }} */ (Object.assign({}, KEYS));
 
     for (const type of Object.keys(additionalKeys)) {
         if (Object.prototype.hasOwnProperty.call(retv, type)) {

lib/visitor-keys.js

@@ -1,3 +1,10 @@
+/**
+ * @typedef {import('./index.js').VisitorKeys} VisitorKeys
+ */
+
+/**
+ * @type {VisitorKeys}
+ */
 const KEYS = {
     AssignmentExpression: [
         "left",

package.json

@@ -4,6 +4,7 @@
   "description": "Constants and utilities about visitor keys to traverse AST.",
   "type": "module",
   "main": "dist/eslint-visitor-keys.cjs",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": [
       {
@@ -15,6 +16,8 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "dist/index.d.ts",
+    "dist/visitor-keys.d.ts",
     "dist/eslint-visitor-keys.cjs",
     "lib"
   ],
@@ -30,13 +33,17 @@
     "eslint-release": "^3.2.0",
     "mocha": "^9.0.1",
     "opener": "^1.5.2",
-    "rollup": "^2.52.1"
+    "rollup": "^2.52.1",
+    "tsd": "^0.19.1",
+    "typescript": "^4.5.5"
   },
   "scripts": {
     "prepare": "npm run build",
-    "build": "rollup -c",
+    "build": "rollup -c && npm run tsc",
     "lint": "eslint .",
-    "test": "mocha tests/lib/**/*.cjs && c8 mocha tests/lib/**/*.js",
+    "tsc": "tsc",
+    "tsd": "tsd",
+    "test": "mocha tests/lib/**/*.cjs && c8 mocha tests/lib/**/*.js && npm run tsd",
     "coverage": "c8 report --reporter lcov && opener coverage/lcov-report/index.html",
     "generate-release": "eslint-generate-release",
     "generate-alpharelease": "eslint-generate-prerelease alpha",

test-d/index.test-d.ts

@@ -0,0 +1,54 @@
+import { expectType, expectAssignable, expectError } from 'tsd';
+
+import { KEYS, getKeys, unionWith, VisitorKeys } from "../";
+
+const assignmentExpression = {
+    type: "AssignmentExpression",
+    operator: "=",
+    left: {
+        type: "Identifier",
+        name: "a",
+        range: [
+            0,
+            1
+        ]
+    },
+    right: {
+        type: "Literal",
+        value: 5,
+        raw: "5",
+        range: [
+            4,
+            5
+        ]
+    },
+    range: [
+        0,
+        5
+    ]
+};
+
+expectType<{readonly [type: string]: readonly string[]}>(KEYS);
+
+expectType<readonly string[]>(getKeys(assignmentExpression));
+
+expectType<{readonly [type: string]: readonly string[]}>(unionWith({
+    TestInterface1: ["left", "right"],
+    TestInterface2: ["expression"]
+}));
+
+const readonlyKeys: {
+    readonly [type: string]: readonly string[]
+} = {
+    TestInterface1: ["left", "right"]
+};
+
+expectAssignable<VisitorKeys>(readonlyKeys);
+
+// https://github.com/SamVerschueren/tsd/issues/143
+// expectError(() => {
+//     const erring: VisitorKeys = {
+//         TestInterface1: ["left", "right"]
+//     };
+//     erring.TestInterface1 = ["badAttemptOverwrite"];
+// });

tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "lib": ["es2020"],
+    "moduleResolution": "node",
+    "module": "esnext",
+    "resolveJsonModule": true,
+    "allowJs": true,
+    "checkJs": true,
+    "noEmit": false,
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "strict": true,
+    "target": "es6",
+    "outDir": "dist"
+  },
+  "include": ["lib/**/*.js"],
+  "exclude": ["node_modules"]
+}