@speclynx/apidom-traverse 1.12.2

package/types/apidom-traverse.d.ts

@@ -0,0 +1,403 @@
+import { Element as Element_2 } from '@speclynx/apidom-datamodel';
+
+/**
+ * Default node clone function - creates a shallow clone of ApiDOM Elements.
+ * Uses cloneShallow from apidom-datamodel for proper handling of meta/attributes.
+ * @public
+ */
+export declare const cloneNode: <TNode>(node: TNode) => TNode;
+
+/**
+ * Finds all elements matching the predicate.
+ * @public
+ */
+export declare const filter: <T extends Element_2>(element: T, predicate: (element: Element_2) => boolean) => Element_2[];
+
+/**
+ * Find first element that satisfies the provided predicate.
+ * @public
+ */
+export declare const find: <T extends Element_2>(element: T, predicate: (element: Element_2) => boolean) => Element_2 | undefined;
+
+/**
+ * Finds the most inner node at the given offset.
+ * If includeRightBound is set, also finds nodes that end at the given offset.
+ * @public
+ */
+export declare const findAtOffset: <T extends Element_2>(element: T, options: number | FindAtOffsetOptions) => T | undefined;
+
+/**
+ * @public
+ */
+export declare interface FindAtOffsetOptions {
+    offset: number;
+    includeRightBound?: boolean;
+}
+
+/**
+ * Executes the callback on this element and all descendants.
+ * @public
+ */
+export declare const forEach: <T extends Element_2>(element: T, options: ForEachCallback | ForEachOptions) => void;
+
+/**
+ * @public
+ */
+export declare type ForEachCallback = <T extends Element_2>(element: T) => void;
+
+/**
+ * @public
+ */
+export declare interface ForEachOptions {
+    callback?: ForEachCallback;
+    predicate?: (element: Element_2) => boolean;
+}
+
+/**
+ * Default function to get traversable keys for a node.
+ * Uses predicates to handle all ApiDOM element types automatically.
+ * @public
+ */
+export declare const getNodeKeys: <TNode>(node: TNode) => readonly string[];
+
+/**
+ * Alternative node type getter using primitive type.
+ * Returns the base element class name based on the node's primitive type.
+ * E.g., ContactElement (primitive='object') -\> "ObjectElement"
+ *
+ * Use this with `nodeTypeGetter` option when you want polymorphic behavior
+ * where specific elements fall back to their primitive type handlers.
+ * @public
+ */
+export declare const getNodePrimitiveType: <TNode>(node: TNode) => string;
+
+/**
+ * Default node type getter - reads the `element` property and converts to Element class name.
+ * E.g., "string" -\> "StringElement", "openApi3_1" -\> "OpenApi3_1Element"
+ * @public
+ */
+export declare const getNodeType: <TNode>(node: TNode) => string;
+
+/**
+ * Gets the appropriate visitor function for a node type and phase.
+ * Supports pipe-separated type keys like "TypeA|TypeB".
+ * @public
+ */
+export declare const getVisitFn: <TNode>(visitor: object, type: string | undefined, isLeaving: boolean) => VisitorFn<TNode> | null;
+
+/**
+ * Default node predicate - checks if value is an ApiDOM Element.
+ * @public
+ */
+export declare const isNode: <TNode>(value: unknown) => value is TNode;
+
+/**
+ * Sync version of merged visitor.
+ * @public
+ */
+export declare interface MergedVisitor<TNode> {
+    enter?: VisitorFn<TNode>;
+    leave?: VisitorFn<TNode>;
+    [key: string]: VisitorFn<TNode> | NodeVisitor<TNode> | undefined;
+}
+
+/**
+ * Async version of merged visitor.
+ * @public
+ */
+export declare interface MergedVisitorAsync<TNode> {
+    enter?: VisitorFn<TNode>;
+    leave?: VisitorFn<TNode>;
+    [key: string]: VisitorFn<TNode> | NodeVisitor<TNode> | undefined;
+}
+
+/**
+ * Creates a new visitor instance which delegates to many visitors to run in
+ * parallel. Each visitor will be visited for each node before moving on.
+ *
+ * If a prior visitor edits a node, no following visitors will see that node.
+ * `exposeEdits=true` can be used to expose the edited node from the previous visitors.
+ * @public
+ */
+export declare const mergeVisitors: <TNode>(visitors: object[], options?: MergeVisitorsOptions<TNode>) => MergedVisitor<TNode>;
+
+/**
+ * Async version of mergeVisitors.
+ * @public
+ */
+export declare const mergeVisitorsAsync: <TNode>(visitors: object[], options?: MergeVisitorsOptions<TNode>) => MergedVisitorAsync<TNode>;
+
+/**
+ * Options for mergeVisitors.
+ * @public
+ */
+export declare interface MergeVisitorsOptions<TNode> {
+    visitFnGetter?: typeof getVisitFn;
+    nodeTypeGetter?: (node: TNode) => string | undefined;
+    exposeEdits?: boolean;
+}
+
+/**
+ * Default mutation function that handles ApiDOM structures.
+ * - MemberElement: sets parent.value
+ * - Arrays: sets parent[key]
+ * - Objects: sets parent[key] or deletes if null
+ * @public
+ */
+export declare const mutateNode: <TNode>(parent: TNode, key: PropertyKey, value: TNode | null) => void;
+
+/**
+ * Enter/leave visitor structure for a specific node type.
+ * @public
+ */
+export declare interface NodeVisitor<TNode, TVisitor = unknown> {
+    enter?: VisitorFn<TNode, TVisitor>;
+    leave?: VisitorFn<TNode, TVisitor>;
+}
+
+/**
+ * Computes upwards edges from every child to its parent.
+ * @public
+ */
+export declare const parents: <T extends Element_2>(element: T) => WeakMap<Element_2, Element_2 | undefined>;
+
+/**
+ * Path represents a node's position in the tree during traversal.
+ * Inspired by Babel's NodePath API.
+ * @public
+ */
+export declare class Path<TNode = Element_2> {
+    #private;
+    /**
+     * The current AST node.
+     */
+    node: TNode;
+    /**
+     * The key of this node in its parent.
+     * `undefined` for the root node.
+     */
+    readonly key: PropertyKey | undefined;
+    /**
+     * The index if this node is in an array.
+     * Same as `key` when parent property is an array, `undefined` otherwise.
+     */
+    readonly index: number | undefined;
+    /**
+     * The parent node.
+     * `undefined` for the root node.
+     */
+    readonly parent: TNode | undefined;
+    /**
+     * The parent Path.
+     * `null` for the root node.
+     */
+    readonly parentPath: Path<TNode> | null;
+    /**
+     * Whether this node is inside an array in the parent.
+     */
+    readonly inList: boolean;
+    constructor(node: TNode, parent: TNode | undefined, parentPath: Path<TNode> | null, key: PropertyKey | undefined, inList: boolean);
+    /**
+     * Whether skip() was called on this path.
+     */
+    get shouldSkip(): boolean;
+    /**
+     * Whether stop() was called on this path.
+     */
+    get shouldStop(): boolean;
+    /**
+     * Whether this node was removed.
+     */
+    get removed(): boolean;
+    /**
+     * Returns true if this is the root path.
+     */
+    isRoot(): boolean;
+    /**
+     * Get the depth of this path (0 for root).
+     */
+    get depth(): number;
+    /**
+     * Get all ancestor paths from immediate parent to root.
+     */
+    getAncestry(): Path<TNode>[];
+    /**
+     * Get all ancestor nodes from immediate parent to root.
+     */
+    getAncestorNodes(): TNode[];
+    /**
+     * Get the path from root as an array of keys.
+     */
+    getPathKeys(): PropertyKey[];
+    /**
+     * Find the closest ancestor path that satisfies the predicate.
+     */
+    findParent(predicate: (path: Path<TNode>) => boolean): Path<TNode> | null;
+    /**
+     * Find the closest path (including this one) that satisfies the predicate.
+     */
+    find(predicate: (path: Path<TNode>) => boolean): Path<TNode> | null;
+    /**
+     * Traverse into the current node with a new visitor.
+     * Populated by the traversal module to avoid circular imports.
+     */
+    traverse: (visitor: any, options?: any) => TNode;
+    /**
+     * Async version of traverse.
+     */
+    traverseAsync: (visitor: any, options?: any) => Promise<TNode>;
+    /**
+     * Skip traversing the children of this node.
+     */
+    skip(): void;
+    /**
+     * Stop all traversal completely.
+     */
+    stop(): void;
+    /**
+     * Replace this node with a new node.
+     */
+    replaceWith(replacement: TNode): void;
+    /**
+     * Remove this node from the tree.
+     */
+    remove(): void;
+    /**
+     * @internal
+     */
+    _getReplacementNode(): TNode | undefined;
+    /**
+     * @internal
+     */
+    _wasReplaced(): boolean;
+    /**
+     * @internal
+     */
+    _reset(): void;
+    /**
+     * Mark this path as stale (visit completed).
+     * @internal
+     */
+    _markStale(): void;
+}
+
+/**
+ * Complement of filter. Finds all elements NOT matching the predicate.
+ * @public
+ */
+export declare const reject: <T extends Element_2>(element: T, predicate: (element: Element_2) => boolean) => Element_2[];
+
+/**
+ * Tests whether at least one element passes the predicate.
+ * @public
+ */
+export declare const some: <T extends Element_2>(element: T, predicate: (element: Element_2) => boolean) => boolean;
+
+/**
+ * traverse() walks through a tree using preorder depth-first traversal, calling
+ * the visitor's enter function at each node, and calling leave after visiting
+ * that node and all its children.
+ *
+ * Visitors receive a Path object with:
+ * - `path.node` - the current node
+ * - `path.parent` - the parent node
+ * - `path.key` - key in parent
+ * - `path.parentPath` - parent Path (linked list structure)
+ * - `path.replaceWith(node)` - replace current node
+ * - `path.remove()` - remove current node
+ * - `path.skip()` - skip children (enter only)
+ * - `path.stop()` - stop all traversal
+ *
+ * When editing, the original tree is not modified. A new version with changes
+ * applied is returned.
+ *
+ * @example
+ * ```typescript
+ * const edited = traverse(ast, {
+ *   enter(path) {
+ *     console.log(path.node);
+ *     if (shouldSkip) path.skip();
+ *     if (shouldReplace) path.replaceWith(newNode);
+ *   },
+ *   leave(path) {
+ *     if (shouldRemove) path.remove();
+ *   }
+ * });
+ * ```
+ *
+ * Visitor patterns supported:
+ * 1. `{ Kind(path) {} }` - enter specific node type
+ * 2. `{ Kind: { enter(path) {}, leave(path) {} } }` - enter/leave specific type
+ * 3. `{ enter(path) {}, leave(path) {} }` - enter/leave any node
+ * 4. `{ enter: { Kind(path) {} }, leave: { Kind(path) {} } }` - parallel style
+ *
+ * @public
+ */
+export declare const traverse: <TNode>(root: TNode, visitor: object, options?: TraverseOptions<TNode>) => TNode;
+
+/**
+ * Async version of traverse().
+ * @public
+ */
+export declare const traverseAsync: <TNode>(root: TNode, visitor: object, options?: TraverseOptions<TNode>) => Promise<TNode>;
+
+/**
+ * SPDX-FileCopyrightText: Copyright (c) GraphQL Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Options for the traverse function.
+ * @public
+ */
+export declare interface TraverseOptions<TNode> {
+    /**
+     * Map of node types to their traversable keys, or a function that returns keys for a node.
+     * Defaults to predicate-based detection for ApiDOM elements.
+     */
+    keyMap?: Record<string, readonly string[]> | ((node: TNode) => readonly string[]) | null;
+    /**
+     * State object to assign to visitor during traversal.
+     */
+    state?: Record<string, unknown>;
+    /**
+     * Function to get the type of a node. Defaults to `node.type`.
+     */
+    nodeTypeGetter?: (node: TNode) => string | undefined;
+    /**
+     * Predicate to check if a value is a valid node.
+     */
+    nodePredicate?: (value: unknown) => value is TNode;
+    /**
+     * Function to clone a node. Used when edits are made in immutable mode.
+     */
+    nodeCloneFn?: (node: TNode) => TNode;
+    /**
+     * Whether to detect and skip cycles. Defaults to true.
+     */
+    detectCycles?: boolean;
+    /**
+     * If true, edits modify the original tree in place.
+     * If false (default), creates a new tree with changes applied.
+     */
+    mutable?: boolean;
+    /**
+     * Custom function for applying mutations in mutable mode.
+     * Handles ApiDOM structures (MemberElement, arrays) by default.
+     */
+    mutationFn?: (parent: TNode, key: PropertyKey, value: TNode | null) => void;
+}
+
+/**
+ * Visitor function signature - receives a Path object.
+ * @public
+ */
+export declare type VisitorFn<TNode, TVisitor = unknown> = (this: TVisitor, path: Path<TNode>) => VisitorResult<TNode>;
+
+/**
+ * Possible return values from a visitor function.
+ * @public
+ */
+export declare type VisitorResult<TNode> = void | undefined | TNode | Promise<void | undefined | TNode>;
+
+export { }