refactor(traverse): widen TypeScript type for visitors (#13)

Author: char0n

packages/apidom-reference/src/dereference/strategies/apidom/visitor.ts

@@ -207,9 +207,6 @@ class ApiDOMDereferenceVisitor {
       path.replaceWith(referencedElement);
     }
   }
-
-  // Index signature for Visitor compatibility
-  [key: string]: unknown;
 }
 
 export default ApiDOMDereferenceVisitor;

packages/apidom-reference/src/dereference/strategies/asyncapi-2/visitor.ts

@@ -490,9 +490,6 @@ class AsyncAPI2DereferenceVisitor {
      */
     path.replaceWith(referencedElement);
   }
-
-  // Index signature for Visitor compatibility
-  [key: string]: unknown;
 }
 
 export default AsyncAPI2DereferenceVisitor;

packages/apidom-reference/src/dereference/strategies/openapi-2/visitor.ts

@@ -633,9 +633,6 @@ class OpenAPI2DereferenceVisitor {
     path.replaceWith(mergedElement);
     return;
   }
-
-  // Index signature for Visitor compatibility
-  [key: string]: unknown;
 }
 
 export default OpenAPI2DereferenceVisitor;

packages/apidom-reference/src/dereference/strategies/openapi-3-0/visitor.ts

@@ -609,9 +609,6 @@ class OpenAPI3_0DereferenceVisitor {
      */
     path.replaceWith(exampleElementCopy);
   }
-
-  // Index signature for Visitor compatibility
-  [key: string]: unknown;
 }
 
 export default OpenAPI3_0DereferenceVisitor;

packages/apidom-reference/src/dereference/strategies/openapi-3-1/visitor.ts

@@ -904,9 +904,6 @@ class OpenAPI3_1DereferenceVisitor {
      */
     path.replaceWith(referencedElement);
   }
-
-  // Index signature for Visitor compatibility
-  [key: string]: unknown;
 }
 
 export default OpenAPI3_1DereferenceVisitor;

packages/apidom-traverse/src/index.ts

@@ -25,7 +25,6 @@ export {
 } from './visitors.ts';
 export type {
   NodeVisitor,
-  Visitor,
   MergeVisitorsOptions,
   MergedVisitor,
   MergedVisitorAsync,

packages/apidom-traverse/src/traversal.ts

@@ -10,7 +10,6 @@ import { isPromise } from 'ramda-adjunct';
 import { Path } from './Path.ts';
 import type { VisitorFn, VisitorResult } from './Path.ts';
 import { getNodeType, isNode, cloneNode, mutateNode, getVisitFn, getNodeKeys } from './visitors.ts';
-import type { Visitor } from './visitors.ts';
 
 /**
  * Options for the traverse function.
@@ -79,7 +78,7 @@ interface TraversalState<TNode> {
 
 function* traverseGenerator<TNode>(
   root: TNode,
-  visitor: Visitor<TNode>,
+  visitor: object,
   options: Required<TraverseOptions<TNode>>,
 ): Generator<VisitorCall<TNode>, TNode, VisitorResult<TNode>> {
   const {
@@ -175,7 +174,7 @@ function* traverseGenerator<TNode>(
       // Always create Path for the current node (needed for parentPath chain)
       currentPath = new Path<TNode>(node, parent, parentPath, key, inArray);
 
-      const visitFn = getVisitFn(visitor, nodeTypeGetter(node), isLeaving);
+      const visitFn = getVisitFn<TNode>(visitor, nodeTypeGetter(node), isLeaving);
 
       if (visitFn) {
         // Assign state to visitor
@@ -310,7 +309,7 @@ function* traverseGenerator<TNode>(
  */
 export const traverse = <TNode>(
   root: TNode,
-  visitor: Visitor<TNode>,
+  visitor: object,
   options: TraverseOptions<TNode> = {},
 ): TNode => {
   const resolvedOptions: Required<TraverseOptions<TNode>> = {
@@ -350,7 +349,7 @@ export const traverse = <TNode>(
  */
 export const traverseAsync = async <TNode>(
   root: TNode,
-  visitor: Visitor<TNode>,
+  visitor: object,
   options: TraverseOptions<TNode> = {},
 ): Promise<TNode> => {
   const resolvedOptions: Required<TraverseOptions<TNode>> = {

packages/apidom-traverse/src/visitors.ts

@@ -10,7 +10,7 @@ import {
 import { isPromise } from 'ramda-adjunct';
 
 import { Path } from './Path.ts';
-import type { VisitorFn } from './Path.ts';
+import type { VisitorFn, VisitorResult } from './Path.ts';
 
 /**
  * Enter/leave visitor structure for a specific node type.
@@ -21,23 +21,6 @@ export interface NodeVisitor<TNode, TVisitor = unknown> {
   leave?: VisitorFn<TNode, TVisitor>;
 }
 
-/**
- * Visitor object structure.
- * Visitors can have:
- * - `enter`/`leave` for generic callbacks
- * - Type-specific methods like `StringElement(path) {}`
- * - Type-specific enter/leave like `StringElement: { enter, leave }`
- * - Any other properties (for class-based visitors)
- *
- * Note: Class-based visitors must add `[key: string]: unknown;` index signature.
- * @public
- */
-export type Visitor<TNode> = {
-  enter?: VisitorFn<TNode> | Record<string, VisitorFn<TNode>>;
-  leave?: VisitorFn<TNode> | Record<string, VisitorFn<TNode>>;
-  [key: string]: unknown;
-};
-
 // =============================================================================
 // Default implementations for ApiDOM
 // =============================================================================
@@ -154,7 +137,7 @@ const lookup = (record: Record<string, unknown>, type: string): unknown => {
  * @public
  */
 export const getVisitFn = <TNode>(
-  visitor: Visitor<TNode>,
+  visitor: object,
   type: string | undefined,
   isLeaving: boolean,
 ): VisitorFn<TNode> | null => {
@@ -237,7 +220,7 @@ export interface MergedVisitorAsync<TNode> {
  * @public
  */
 export const mergeVisitors = <TNode>(
-  visitors: Visitor<TNode>[],
+  visitors: object[],
   options: MergeVisitorsOptions<TNode> = {},
 ): MergedVisitor<TNode> => {
   const {
@@ -253,13 +236,13 @@ export const mergeVisitors = <TNode>(
   const skipping: (symbol | TNode)[] = new Array(visitors.length).fill(internalSkipSymbol);
 
   return {
-    enter(path: Path<TNode>) {
+    enter(path: Path<TNode>): VisitorResult<TNode> {
       let currentNode = path.node;
       let hasChanged = false;
 
       for (let i = 0; i < visitors.length; i += 1) {
         if (skipping[i] === internalSkipSymbol) {
-          const visitFn = visitFnGetter(visitors[i], nodeTypeGetter(currentNode), false);
+          const visitFn = visitFnGetter<TNode>(visitors[i], nodeTypeGetter(currentNode), false);
 
           if (typeof visitFn === 'function') {
             // Create a proxy path that tracks changes per-visitor
@@ -320,12 +303,12 @@ export const mergeVisitors = <TNode>(
       return undefined;
     },
 
-    leave(path: Path<TNode>) {
+    leave(path: Path<TNode>): VisitorResult<TNode> {
       const currentNode = path.node;
 
       for (let i = 0; i < visitors.length; i += 1) {
         if (skipping[i] === internalSkipSymbol) {
-          const visitFn = visitFnGetter(visitors[i], nodeTypeGetter(currentNode), true);
+          const visitFn = visitFnGetter<TNode>(visitors[i], nodeTypeGetter(currentNode), true);
 
           if (typeof visitFn === 'function') {
             // Create a proxy path for leave phase
@@ -376,7 +359,7 @@ export const mergeVisitors = <TNode>(
  * @public
  */
 export const mergeVisitorsAsync = <TNode>(
-  visitors: Visitor<TNode>[],
+  visitors: object[],
   options: MergeVisitorsOptions<TNode> = {},
 ): MergedVisitorAsync<TNode> => {
   const {
@@ -390,13 +373,13 @@ export const mergeVisitorsAsync = <TNode>(
   const skipping: (symbol | TNode)[] = new Array(visitors.length).fill(internalSkipSymbol);
 
   return {
-    async enter(path: Path<TNode>) {
+    async enter(path: Path<TNode>): Promise<void | TNode | undefined> {
       let currentNode = path.node;
       let hasChanged = false;
 
       for (let i = 0; i < visitors.length; i += 1) {
         if (skipping[i] === internalSkipSymbol) {
-          const visitFn = visitFnGetter(visitors[i], nodeTypeGetter(currentNode), false);
+          const visitFn = visitFnGetter<TNode>(visitors[i], nodeTypeGetter(currentNode), false);
 
           if (typeof visitFn === 'function') {
             const proxyPath = createPathProxy(path, currentNode);
@@ -446,12 +429,12 @@ export const mergeVisitorsAsync = <TNode>(
       return undefined;
     },
 
-    async leave(path: Path<TNode>) {
+    async leave(path: Path<TNode>): Promise<void | TNode | undefined> {
       const currentNode = path.node;
 
       for (let i = 0; i < visitors.length; i += 1) {
         if (skipping[i] === internalSkipSymbol) {
-          const visitFn = visitFnGetter(visitors[i], nodeTypeGetter(currentNode), true);
+          const visitFn = visitFnGetter<TNode>(visitors[i], nodeTypeGetter(currentNode), true);
 
           if (typeof visitFn === 'function') {
             const proxyPath = createPathProxy(path, currentNode);