Improve types for visitor keys (#18095)

src/language-js/utils/index.js

@@ -15,8 +15,8 @@ import isNodeMatches from "./is-node-matches.js";
 import isTsKeywordType from "./is-ts-keyword-type.js";
 
 /**
- * @import * as Estree from "../types/estree.js"
- * @import AstPath from "../../common/ast-path.js"
+@import * as Estree from "../types/estree.js"
+@import AstPath from "../../common/ast-path.js"
 */
 
 /**

src/utils/ast-utils.js

@@ -1,14 +1,13 @@
 import isObject from "./is-object.js";
 
 /**
- * @typedef {NonNullable<object>} Node
- * @typedef {(unknown) => string[]} GetVisitorKeys
- * @typedef {(unknown) => boolean} Predicate
+@import {GetVisitorKeys, Node} from "../utils/create-get-visitor-keys.js"
+@typedef {(node: Node) => boolean} Predicate
 */
 
 /**
- * @param {Node} node
- * @param {{getVisitorKeys: GetVisitorKeys, filter?: Predicate}} options
+@param {Node} node
+@param {{getVisitorKeys: GetVisitorKeys, filter?: Predicate}} options
 */
 function* getChildren(node, options) {
   const { getVisitorKeys, filter = () => true } = options;
@@ -30,8 +29,8 @@ function* getChildren(node, options) {
 }
 
 /**
- * @param {Node} node
- * @param {{getVisitorKeys: GetVisitorKeys, filter?: Predicate}} options
+@param {Node} node
+@param {{getVisitorKeys: GetVisitorKeys, filter?: Predicate}} options
 */
 function* getDescendants(node, options) {
   const queue = [node];
@@ -46,16 +45,16 @@ function* getDescendants(node, options) {
 }
 
 /**
- * @param {Node} node
- * @param {{getVisitorKeys: GetVisitorKeys}} options
+@param {Node} node
+@param {{getVisitorKeys: GetVisitorKeys}} options
 */
 function isLeaf(node, options) {
   return getChildren(node, options).next().done;
 }
 
 /**
- * @param {Node} node
- * @param {{getVisitorKeys: GetVisitorKeys, predicate: Predicate}} options
+@param {Node} node
+@param {{getVisitorKeys: GetVisitorKeys, predicate: Predicate}} options
 */
 function hasDescendant(node, { getVisitorKeys, predicate }) {
   for (const descendant of getDescendants(node, { getVisitorKeys })) {

src/utils/create-get-visitor-keys.js

@@ -1,8 +1,20 @@
 import toFastProperties from "to-fast-properties";
 
+/**
+@typedef {(node: Node) => VisitorKeys} GetVisitorKeys
+@typedef {NonNullable<object>} Node
+@typedef {readonly string[]} VisitorKeys
+*/
+
+/**
+@param {Record<string, VisitorKeys>} visitorKeys
+@param {string} [typeProperty="type"]
+@returns {GetVisitorKeys}
+*/
 function createGetVisitorKeys(visitorKeys, typeProperty = "type") {
   toFastProperties(visitorKeys);
 
+  /** @type {GetVisitorKeys} */
   function getVisitorKeys(node) {
     const type = node[typeProperty];