Improve types for visitor keys (#18095)

src/language-js/utils/index.js

@@ -15,9 +15,9 @@ 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"
+*/
 
 /**
  * @param {Estree.Node} node

src/utils/ast-utils.js

@@ -1,15 +1,14 @@
 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;
   const isMatchedNode = (node) => isObject(node) && filter(node);
@@ -30,9 +29,9 @@ 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];
   for (let index = 0; index < queue.length; index++) {
@@ -46,17 +45,17 @@ 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 })) {
     if (predicate(descendant)) {

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];