feat: make types more specific

README.md

@@ -35,7 +35,7 @@ const evk = require("eslint-visitor-keys")
 
 ### evk.KEYS
 
-> type: `{ [type: string]: string[] | undefined }`
+> type: `VisitorKeys<VisitorKeyTypes>`
 
 Visitor keys. This keys are frozen.
 
@@ -49,7 +49,7 @@ console.log(evk.KEYS.AssignmentExpression) // → ["left", "right"]
 
 ### evk.getKeys(node)
 
-> type: `(node: object) => string[]`
+> type: `(node: object) => FilteredKeysOf<node>[]`
 
 Get the visitor keys of a given AST node.
 
@@ -61,16 +61,17 @@ For example:
 
 ```js
 const node = {
+ _something: true,
  type: "AssignmentExpression",
  left: { type: "Identifier", name: "foo" },
- right: { type: "Literal", value: 0 }
+ right: { type: "Literal", value: 0 },
 }
 console.log(evk.getKeys(node)) // → ["type", "left", "right"]
 ```
 
 ### evk.unionWith(additionalKeys)
 
-> type: `(additionalKeys: object) => { [type: string]: string[] | undefined }`
+> type: `(additionalKeys: object) => VisitorKeys<VisitorKeyTypes | keyof additionalKeys>`
 
 Make the union set with `evk.KEYS` and the given keys.
 
@@ -85,6 +86,56 @@ console.log(evk.unionWith({
 })) // → { ..., MethodDefinition: ["decorators", "key", "value"], ... }
 ```
 
+## Types
+
+### VisitorKeyTypes
+
+A union of string literals representing all the keys on `evk.KEYS`:
+
+```
+"ArrayExpression" | "ArrayPattern" | ...
+```
+
+### VisitorKeys
+
+Defines the base shape of `evk.KEYS` style objects.
+
+Takes two optional inputs: `VisitorKeys<NodeTypes, Node>`
+
+* `NodeTypes` makes up the keys of `VisitorKeys`, should be the type of [ESTree] nodes
+* `Node` represents the [ESTree] nodes themselves and is used to calculate possible values of `VisitorKeys`, an array of property names which have child nodes
+
+Default inputs: `VisitorKeys<string, Record<string, unknown>>`
+
+Example: The type of `evk.KEYS` is roughly equivalent to:
+
+```ts
+VisitorKeys<VisitorKeyTypes, import("estree").Node | import("estree-jsx").Node>
+```
+
+### FilteredKeysOf\<T>
+
+Similar to `keyof T` but:
+
+* Filters away keys just like `evk.getKeys` does
+* Rather than only returning commons keys when `T` is a union it instead returns all keys
+
+Example:
+
+```ts
+FilteredKeysOf<
+ { parent: 123, abc: true, xyz: true },
+ { parent: 456, abc: true, def: true },
+>
+```
+
+equals
+
+```ts
+'abc' | 'xyz' |
+```
+
+
 ## 📰 Change log
 
 See [GitHub releases](https://github.com/eslint/eslint-visitor-keys/releases).

lib/index.js

@@ -5,53 +5,78 @@
 import KEYS from "./visitor-keys.js";
 
 /**
- * @typedef {import('./visitor-keys.js').VisitorKeys} VisitorKeys
+ * @typedef {import('./visitor-keys.js').VisitorKeyTypes} VisitorKeyTypes
+ */
+
+/* eslint-disable jsdoc/valid-types -- jsdoc-type-pratt-parser can't parse template literal types */
+/**
+ * @template T
+ * @typedef {Exclude<Extract<import('./types.js').KeyOfUnion<T>, string>, KEY_FILTER[number] | `_${string}`>} FilteredKeysOf
+ */
+/* eslint-enable jsdoc/valid-types -- jsdoc-type-pratt-parser can't parse template literal types */
+
+/**
+ * @template {string} [NodeTypes=string]
+ * @template {object} [Node=Record<string,unknown>]
+ * @typedef {Readonly<Record<NodeTypes, ReadonlyArray<FilteredKeysOf<Node>>>>} VisitorKeys
  */
 
 // List to ignore keys.
-const KEY_BLACKLIST = new Set([
+const KEY_FILTER = /** @type {const} */ ([
  "parent",
  "leadingComments",
  "trailingComments"
 ]);
 
+/* eslint-disable jsdoc/valid-types -- jsdoc-type-pratt-parser can't parse template literal types */
 /**
  * Check whether a given key should be used or not.
- * @param {string} key The key to check.
- * @returns {boolean} `true` if the key should be used.
+ * @template {string|number|symbol} K
+ * @template {string} T
+ * @param {K|T} key The key to check.
+ * @param {ReadonlyArray<T>} filterlist The list of keys to filter out.
+ * @returns {key is Exclude<Extract<K, string>, T | `_${string}`>} `true` if the key should be used.
  */
-function filterKey(key) {
- return !KEY_BLACKLIST.has(key) && key[0] !== "_";
+function isFiltered(key, filterlist) {
+ return !filterlist.includes(/** @type {T} */ (key)) && typeof key === "string" && key[0] !== "_";
 }
+/* eslint-enable jsdoc/valid-types -- jsdoc-type-pratt-parser can't parse template literal types */
 
-
-/* eslint-disable jsdoc/valid-types -- doesn't allow `readonly`.
- TODO: remove eslint-disable when https://github.com/jsdoc-type-pratt-parser/jsdoc-type-pratt-parser/issues/164 is fixed
-*/
 /**
  * Get visitor keys of a given node.
- * @param {object} node The AST node to get keys.
- * @returns {readonly string[]} Visitor keys of the node.
+ * @template {object} T
+ * @param {T} node The AST node to get keys.
+ * @returns {ReadonlyArray<FilteredKeysOf<T>>} Visitor keys of the node.
  */
 export function getKeys(node) {
- return Object.keys(node).filter(filterKey);
+
+ /** @type {FilteredKeysOf<T>[]} */
+ const result = [];
+
+ for (const key of /** @type {import('./types.js').KeyOfUnion<T>[]} */ (Object.keys(node))) {
+ if (isFiltered(key, KEY_FILTER)) {
+ result.push(key);
+ }
+ }
+ return result;
 }
-/* eslint-enable jsdoc/valid-types -- doesn't allow `readonly` */
 
 /**
  * Make the union set with `KEYS` and given keys.
- * @param {VisitorKeys} additionalKeys The additional keys.
- * @returns {VisitorKeys} The union set.
+ * @template {VisitorKeys} T
+ * @param {T} additionalKeys The additional keys.
+ * @returns {VisitorKeys<VisitorKeyTypes | Extract<keyof T, string>>} The union set.
  */
 export function unionWith(additionalKeys) {
- const retv = /** @type {{ [type: string]: ReadonlyArray<string> }} */
- (Object.assign({}, KEYS));
 
- for (const type of Object.keys(additionalKeys)) {
- if (Object.prototype.hasOwnProperty.call(retv, type)) {
+ /** @type {Record<VisitorKeyTypes | keyof T, ReadonlyArray<string>>} */
+ const retv = { ...additionalKeys, ...KEYS };
+
+ for (const type of /** @type {Array<keyof T>} */ (Object.keys(additionalKeys))) {
+ if (Object.hasOwn(KEYS, type)) {
  const keys = new Set(additionalKeys[type]);
 
- for (const key of retv[type]) {
+ for (const key of KEYS[/** @type {VisitorKeyTypes} */ (type)]) {
  keys.add(key);
  }
 

lib/types.js

@@ -0,0 +1,12 @@
+/* eslint-disable jsdoc/valid-types -- jsdoc-type-pratt-parser can't parse conditional types */
+
+/**
+ * Added here to avoid it being exported in the generated types
+ * @see https://github.com/sindresorhus/type-fest/blob/906e7e77204c65f7512f9f54b3205f25c5c0c8e5/source/keys-of-union.d.ts#L38-L40
+ * @template T
+ * @typedef {T extends unknown ? keyof T : never} KeyOfUnion
+ */
+
+/* eslint-enable jsdoc/valid-types -- jsdoc-type-pratt-parser can't parse conditional types */
+
+export default {};

lib/visitor-keys.js

@@ -1,15 +1,10 @@
-/* eslint-disable jsdoc/valid-types -- doesn't allow `readonly`.
- TODO: remove eslint-disable when https://github.com/jsdoc-type-pratt-parser/jsdoc-type-pratt-parser/issues/164 is fixed
-*/
-/**
- * @typedef {{ readonly [type: string]: ReadonlyArray<string> }} VisitorKeys
- */
-/* eslint-enable jsdoc/valid-types -- doesn't allow `readonly string[]`. TODO: check why */
+// DO NOT MODIFY - generated by ../tools/build-keys-from-ts.js
 
-/**
- * @type {VisitorKeys}
- */
-const KEYS = {
+/** @typedef {"ArrayExpression" | "ArrayPattern" | "ArrowFunctionExpression" | "AssignmentExpression" | "AssignmentPattern" | "AwaitExpression" | "BinaryExpression" | "BlockStatement" | "BreakStatement" | "CallExpression" | "CatchClause" | "ChainExpression" | "ClassBody" | "ClassDeclaration" | "ClassExpression" | "ConditionalExpression" | "ContinueStatement" | "DebuggerStatement" | "DoWhileStatement" | "EmptyStatement" | "ExperimentalRestProperty" | "ExperimentalSpreadProperty" | "ExportAllDeclaration" | "ExportDefaultDeclaration" | "ExportNamedDeclaration" | "ExportSpecifier" | "ExpressionStatement" | "ForInStatement" | "ForOfStatement" | "ForStatement" | "FunctionDeclaration" | "FunctionExpression" | "Identifier" | "IfStatement" | "ImportDeclaration" | "ImportDefaultSpecifier" | "ImportExpression" | "ImportNamespaceSpecifier" | "ImportSpecifier" | "JSXAttribute" | "JSXClosingElement" | "JSXClosingFragment" | "JSXElement" | "JSXEmptyExpression" | "JSXExpressionContainer" | "JSXFragment" | "JSXIdentifier" | "JSXMemberExpression" | "JSXNamespacedName" | "JSXOpeningElement" | "JSXOpeningFragment" | "JSXSpreadAttribute" | "JSXSpreadChild" | "JSXText" | "LabeledStatement" | "Literal" | "LogicalExpression" | "MemberExpression" | "MetaProperty" | "MethodDefinition" | "NewExpression" | "ObjectExpression" | "ObjectPattern" | "PrivateIdentifier" | "Program" | "Property" | "PropertyDefinition" | "RestElement" | "ReturnStatement" | "SequenceExpression" | "SpreadElement" | "StaticBlock" | "Super" | "SwitchCase" | "SwitchStatement" | "TaggedTemplateExpression" | "TemplateElement" | "TemplateLiteral" | "ThisExpression" | "ThrowStatement" | "TryStatement" | "UnaryExpression" | "UpdateExpression" | "VariableDeclaration" | "VariableDeclarator" | "WhileStatement" | "WithStatement" | "YieldExpression"} VisitorKeyTypes */
+
+/** @typedef {Readonly<{ [type: string]: ReadonlyArray<string> }>} VisitorKeys */
+
+const KEYS = /** @type {const} */ (/** @satisfies {VisitorKeys} */ ({
  ArrayExpression: [
  "elements"
  ],
@@ -305,14 +300,11 @@ const KEYS = {
  YieldExpression: [
  "argument"
  ]
-};
-
-// Types.
-const NODE_TYPES = Object.keys(KEYS);
+}));
 
-// Freeze the keys.
-for (const type of NODE_TYPES) {
- Object.freeze(KEYS[type]);
+// Freeze the object values.
+for (const value of Object.values(KEYS)) {
+ Object.freeze(value);
 }
 Object.freeze(KEYS);
 

package.json

@@ -16,9 +16,10 @@
  "./package.json": "./package.json"
  },
  "files": [
- "dist/index.d.ts",
- "dist/visitor-keys.d.ts",
+ "dist/*.d.ts",
+ "dist/*.d.ts.map",
  "dist/eslint-visitor-keys.cjs",
+ "dist/eslint-visitor-keys.cjs.map",
  "dist/eslint-visitor-keys.d.cts",
  "lib"
  ],
@@ -39,10 +40,10 @@
  "json-diff": "^0.7.3",
  "mocha": "^9.2.1",
  "opener": "^1.5.2",
- "rollup": "^2.70.0",
- "rollup-plugin-dts": "^4.2.3",
- "tsd": "^0.19.1",
- "typescript": "^4.6.2"
+ "rollup": "^4.12.0",
+ "rollup-plugin-dts": "^6.1.0",
+ "tsd": "^0.30.7",
+ "typescript": "^5.3.3"
  },
  "scripts": {
  "build": "npm run build:cjs && npm run build:types",

rollup.config.js

@@ -6,7 +6,9 @@ export default [
  treeshake: false,
  output: {
  format: "cjs",
- file: "dist/eslint-visitor-keys.cjs"
+ file: "dist/eslint-visitor-keys.cjs",
+ sourcemap: true,
+ sourcemapExcludeSources: true
  }
  },
  {

test-d/index.test-d.ts

@@ -1,9 +1,12 @@
 import { expectType, expectAssignable, expectError } from 'tsd';
 
-import { KEYS, getKeys, unionWith, VisitorKeys } from "../";
+import { KEYS, getKeys, unionWith, VisitorKeys, VisitorKeyTypes } from "../";
+import { KeyOfUnion } from '../lib/types';
 
 const assignmentExpression = {
+ _something: true,
  type: "AssignmentExpression",
+ parent: 'abc',
  operator: "=",
  left: {
  type: "Identifier",
@@ -25,30 +28,44 @@ const assignmentExpression = {
  range: [
  0,
  5
- ]
+ ],
+ leadingComments: 'abc',
+ trailingComments: 'abc'
 };
 
-expectType<{readonly [type: string]: readonly string[]}>(KEYS);
+const readOnlyStringKeyedObject: {
+ readonly [type: string]: readonly string[]
+} = {
+ TestInterface1: ["left", "right"],
+ TestInterface2: ["expression"]
+};
+
+expectAssignable<{readonly [type: string]: readonly string[]}>(KEYS);
+expectAssignable<VisitorKeys>(KEYS);
+expectAssignable<VisitorKeys<VisitorKeyTypes, import("estree").Node | import("estree-jsx").Node>>(KEYS);
+expectAssignable<Record<VisitorKeyTypes, ReadonlyArray<KeyOfUnion<import("estree").Node> | KeyOfUnion<import("estree-jsx").Node>>>>(KEYS);
+
+expectType<readonly ["elements"]>(KEYS.ArrayPattern);
 
-expectType<readonly string[]>(getKeys(assignmentExpression));
+expectType<readonly ("type" | "operator" | "left" | "right" | "range")[]>(getKeys(assignmentExpression));
+expectAssignable<readonly string[]>(getKeys(assignmentExpression));
+expectType<readonly string[]>(getKeys(readOnlyStringKeyedObject));
 
-expectType<{readonly [type: string]: readonly string[]}>(unionWith({
+expectType<Readonly<Record<VisitorKeyTypes | "TestInterface1" | "TestInterface2", readonly string[]>>>(unionWith({
  TestInterface1: ["left", "right"],
  TestInterface2: ["expression"]
 }));
+expectAssignable<{readonly [type: string]: readonly string[]}>(unionWith({
+ TestInterface1: ["left", "right"],
+ TestInterface2: ["expression"]
+}));
+expectType<Readonly<Record<string, readonly string[]>>>(unionWith(readOnlyStringKeyedObject));
 
-const readonlyKeys: {
- readonly [type: string]: readonly string[]
-} = {
- TestInterface1: ["left", "right"]
-};
-
-expectAssignable<VisitorKeys>(readonlyKeys);
+expectAssignable<VisitorKeys>(readOnlyStringKeyedObject);
 
-// https://github.com/SamVerschueren/tsd/issues/143
-// expectError(() => {
-// const erring: VisitorKeys = {
-// TestInterface1: ["left", "right"]
-// };
-// erring.TestInterface1 = ["badAttemptOverwrite"];
-// });
+expectError(() => {
+ const erring: VisitorKeys = {
+ TestInterface1: ["left", "right"]
+ };
+ erring.TestInterface1 = ["badAttemptOverwrite"];
+});

tools/build-keys-from-ts.js

@@ -30,21 +30,17 @@ const { promises: { writeFile } } = fs;
  writeFile(
  "./lib/visitor-keys.js",
  // eslint-disable-next-line indent -- Readability
-`/**
- * @typedef {{ readonly [type: string]: ReadonlyArray<string> }} VisitorKeys
- */
+`// DO NOT MODIFY - generated by ../tools/build-keys-from-ts.js
 
-/**
- * @type {VisitorKeys}
- */
-const KEYS = ${JSON.stringify(mergedKeys, null, 4).replace(/"(.*?)":/gu, "$1:")};
+/** @typedef {${Object.keys(mergedKeys).map(key => JSON.stringify(key)).join(" | ")}} VisitorKeyTypes */
+
+/** @typedef {Readonly<{ [type: string]: ReadonlyArray<string> }>} VisitorKeys */
 
-// Types.
-const NODE_TYPES = Object.keys(KEYS);
+const KEYS = /** @type {const} */ (/** @satisfies {VisitorKeys} */ (${JSON.stringify(mergedKeys, null, 4).replace(/"(.*?)":/gu, "$1:")}));
 
-// Freeze the keys.
-for (const type of NODE_TYPES) {
- Object.freeze(KEYS[type]);
+// Freeze the object values.
+for (const value of Object.values(KEYS)) {
+ Object.freeze(value);
 }
 Object.freeze(KEYS);