@speclynx/apidom-traverse 3.2.0 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-traverse",
-  "version": "3.2.0",
+  "version": "4.0.0",
   "description": "Traversal and visitor utilities for walking and transforming ApiDOM structures.",
   "keywords": [
     "apidom",
@@ -61,10 +61,10 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.28.4",
-    "@speclynx/apidom-datamodel": "3.2.0",
-    "@speclynx/apidom-error": "3.2.0",
-    "@speclynx/apidom-json-path": "3.2.0",
-    "@speclynx/apidom-json-pointer": "3.2.0",
+    "@speclynx/apidom-datamodel": "4.0.0",
+    "@speclynx/apidom-error": "4.0.0",
+    "@speclynx/apidom-json-path": "4.0.0",
+    "@speclynx/apidom-json-pointer": "4.0.0",
     "ramda-adjunct": "^6.0.0"
   },
   "files": [
@@ -77,5 +77,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "eeb2f01cd34fb0a95617f02bc1b6683aefc028f2"
+  "gitHead": "384ff82a1bb68d015fd6801de641898b4b582876"
 }

package/types/apidom-traverse.d.ts

@@ -8,23 +8,23 @@ import { Element as Element_2 } from '@speclynx/apidom-datamodel';
 export declare const cloneNode: <TNode>(node: TNode) => TNode;
 
 /**
- * Finds all elements matching the predicate.
+ * Finds all paths whose elements match the predicate.
  * @public
  */
-export declare const filter: <T extends Element_2>(element: T, predicate: (element: Element_2) => boolean) => Element_2[];
+export declare const filter: <T extends Element_2>(element: T, predicate: (path: Path<Element_2>) => boolean) => Path<Element_2>[];
 
 /**
- * Find first element that satisfies the provided predicate.
+ * Finds first path whose element satisfies the provided predicate.
  * @public
  */
-export declare const find: <T extends Element_2>(element: T, predicate: (element: Element_2) => boolean) => Element_2 | undefined;
+export declare const find: <T extends Element_2>(element: T, predicate: (path: Path<Element_2>) => boolean) => Path<Element_2> | undefined;
 
 /**
- * Finds the most inner node at the given offset.
+ * Finds the path of 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;
+export declare const findAtOffset: <T extends Element_2>(element: T, options: number | FindAtOffsetOptions) => Path<Element_2> | undefined;
 
 /**
  * @public
@@ -35,7 +35,7 @@ export declare interface FindAtOffsetOptions {
 }
 
 /**
- * Executes the callback on this element and all descendants.
+ * Executes the callback on this element's path and all descendant paths.
  * @public
  */
 export declare const forEach: <T extends Element_2>(element: T, options: ForEachCallback | ForEachOptions) => void;
@@ -43,14 +43,14 @@ export declare const forEach: <T extends Element_2>(element: T, options: ForEach
 /**
  * @public
  */
-export declare type ForEachCallback = <T extends Element_2>(element: T) => void;
+export declare type ForEachCallback = (path: Path<Element_2>) => void;
 
 /**
  * @public
  */
 export declare interface ForEachOptions {
     callback?: ForEachCallback;
-    predicate?: (element: Element_2) => boolean;
+    predicate?: (path: Path<Element_2>) => boolean;
 }
 
 /**
@@ -232,7 +232,9 @@ export declare class Path<TNode = Element_2> {
      *
      * @example
      * // For a path to $.paths['/pets'].get in an OpenAPI document:
+     * ```
      * path.getPathKeys(); // => ['paths', '/pets', 'get']
+     * ```
      */
     getPathKeys(): PropertyKey[];
     /**
@@ -243,18 +245,22 @@ export declare class Path<TNode = Element_2> {
      *          or Normalized JSONPath like "$['paths']['/pets']['get']['responses']['200']"
      *
      * @example
+     * ```
      * // JSON Pointer examples:
      * path.formatPath(); // "" (root)
      * path.formatPath(); // "/info"
      * path.formatPath(); // "/paths/~1pets/get"
      * path.formatPath(); // "/paths/~1users~1{id}/parameters/0"
+     * ```
      *
      * @example
+     * ```
      * // JSONPath examples:
      * path.formatPath('jsonpath'); // "$" (root)
      * path.formatPath('jsonpath'); // "$['info']"
      * path.formatPath('jsonpath'); // "$['paths']['/pets']['get']"
      * path.formatPath('jsonpath'); // "$['paths']['/users/{id}']['parameters'][0]"
+     * ```
      */
     formatPath(pathFormat?: 'jsonpointer' | 'jsonpath'): string;
     /**
@@ -310,16 +316,16 @@ export declare class Path<TNode = Element_2> {
 }
 
 /**
- * Complement of filter. Finds all elements NOT matching the predicate.
+ * Complement of filter. Finds all paths whose elements do NOT match the predicate.
  * @public
  */
-export declare const reject: <T extends Element_2>(element: T, predicate: (element: Element_2) => boolean) => Element_2[];
+export declare const reject: <T extends Element_2>(element: T, predicate: (path: Path<Element_2>) => boolean) => Path<Element_2>[];
 
 /**
- * Tests whether at least one element passes the predicate.
+ * Tests whether at least one path's element passes the predicate.
  * @public
  */
-export declare const some: <T extends Element_2>(element: T, predicate: (element: Element_2) => boolean) => boolean;
+export declare const some: <T extends Element_2>(element: T, predicate: (path: Path<Element_2>) => boolean) => boolean;
 
 /**
  * traverse() walks through a tree using preorder depth-first traversal, calling

package/src/Path.cjs

@@ -1,336 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.Path = void 0;
-var _apidomDatamodel = require("@speclynx/apidom-datamodel");
-var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
-var _apidomJsonPath = require("@speclynx/apidom-json-path");
-/**
- * Possible return values from a visitor function.
- * @public
- */
-
-/**
- * Visitor function signature - receives a Path object.
- * @public
- */
-
-/**
- * Path represents a node's position in the tree during traversal.
- * Inspired by Babel's NodePath API.
- * @public
- */
-class Path {
-  /**
-   * The current AST node.
-   */
-  node;
-
-  /**
-   * The key of this node in its parent.
-   * `undefined` for the root node.
-   */
-  key;
-
-  /**
-   * The index if this node is in an array.
-   * Same as `key` when parent property is an array, `undefined` otherwise.
-   */
-  index;
-
-  /**
-   * The parent node.
-   * `undefined` for the root node.
-   */
-  parent;
-
-  /**
-   * The parent Path.
-   * `null` for the root node.
-   */
-  parentPath;
-
-  /**
-   * Whether this node is inside an array in the parent.
-   */
-  inList;
-
-  /**
-   * Internal state for traversal control.
-   */
-  #shouldSkip = false;
-  #shouldStop = false;
-  #removed = false;
-  #replaced = false;
-  #replacementNode;
-  #stale = false;
-  constructor(node, parent, parentPath, key, inList) {
-    this.node = node;
-    this.parent = parent;
-    this.parentPath = parentPath;
-    this.key = key;
-    this.index = inList && typeof key === 'number' ? key : undefined;
-    this.inList = inList;
-  }
-
-  // ===========================================================================
-  // Traversal state
-  // ===========================================================================
-
-  /**
-   * Whether skip() was called on this path.
-   */
-  get shouldSkip() {
-    return this.#shouldSkip;
-  }
-
-  /**
-   * Whether stop() was called on this path.
-   */
-  get shouldStop() {
-    return this.#shouldStop;
-  }
-
-  /**
-   * Whether this node was removed.
-   */
-  get removed() {
-    return this.#removed;
-  }
-
-  // ===========================================================================
-  // Ancestry
-  // ===========================================================================
-
-  /**
-   * Returns true if this is the root path.
-   */
-  isRoot() {
-    return this.parentPath === null;
-  }
-
-  /**
-   * Get the depth of this path (0 for root).
-   */
-  get depth() {
-    let depth = 0;
-    let current = this.parentPath;
-    while (current !== null) {
-      depth += 1;
-      current = current.parentPath;
-    }
-    return depth;
-  }
-
-  /**
-   * Get all ancestor paths from immediate parent to root.
-   */
-  getAncestry() {
-    const ancestry = [];
-    let current = this.parentPath;
-    while (current !== null) {
-      ancestry.push(current);
-      current = current.parentPath;
-    }
-    return ancestry;
-  }
-
-  /**
-   * Get all ancestor nodes from immediate parent to root.
-   */
-  getAncestorNodes() {
-    return this.getAncestry().map(p => p.node);
-  }
-
-  /**
-   * Get the semantic path from root as an array of keys.
-   * Returns logical document keys (property names, array indices) rather than
-   * internal ApiDOM structure keys.
-   *
-   * @example
-   * // For a path to $.paths['/pets'].get in an OpenAPI document:
-   * path.getPathKeys(); // => ['paths', '/pets', 'get']
-   */
-  getPathKeys() {
-    const keys = [];
-    // eslint-disable-next-line @typescript-eslint/no-this-alias
-    let current = this;
-    while (current !== null && current.key !== undefined) {
-      const {
-        key,
-        parent,
-        parentPath
-      } = current;
-      if ((0, _apidomDatamodel.isMemberElement)(parent) && key === 'value') {
-        // Inside MemberElement.value → push the member's key
-        if (!(0, _apidomDatamodel.isStringElement)(parent.key)) {
-          throw new TypeError('MemberElement.key must be a StringElement');
-        }
-        keys.unshift(parent.key.toValue());
-      } else if ((0, _apidomDatamodel.isArrayElement)(parentPath?.node) && typeof key === 'number') {
-        // Inside ArrayElement → push the numeric index
-        keys.unshift(key);
-      }
-      current = current.parentPath;
-    }
-    return keys;
-  }
-
-  /**
-   * Format path as RFC 6901 JSON Pointer or RFC 9535 Normalized JSONPath.
-   *
-   * @param pathFormat - Output format: "jsonpointer" (default) or "jsonpath"
-   * @returns JSONPointer string like "/paths/~1pets/get/responses/200"
-   *          or Normalized JSONPath like "$['paths']['/pets']['get']['responses']['200']"
-   *
-   * @example
-   * // JSON Pointer examples:
-   * path.formatPath(); // "" (root)
-   * path.formatPath(); // "/info"
-   * path.formatPath(); // "/paths/~1pets/get"
-   * path.formatPath(); // "/paths/~1users~1{id}/parameters/0"
-   *
-   * @example
-   * // JSONPath examples:
-   * path.formatPath('jsonpath'); // "$" (root)
-   * path.formatPath('jsonpath'); // "$['info']"
-   * path.formatPath('jsonpath'); // "$['paths']['/pets']['get']"
-   * path.formatPath('jsonpath'); // "$['paths']['/users/{id}']['parameters'][0]"
-   */
-  formatPath(pathFormat = 'jsonpointer') {
-    const parts = this.getPathKeys();
-
-    // Root node
-    if (parts.length === 0) {
-      return pathFormat === 'jsonpath' ? '$' : '';
-    }
-    if (pathFormat === 'jsonpath') {
-      // RFC 9535 Normalized JSONPath
-      return _apidomJsonPath.NormalizedPath.from(parts);
-    }
-
-    // RFC 6901 JSON Pointer
-    return (0, _apidomJsonPointer.compile)(parts);
-  }
-
-  /**
-   * Find the closest ancestor path that satisfies the predicate.
-   */
-  findParent(predicate) {
-    let current = this.parentPath;
-    while (current !== null) {
-      if (predicate(current)) {
-        return current;
-      }
-      current = current.parentPath;
-    }
-    return null;
-  }
-
-  /**
-   * Find the closest path (including this one) that satisfies the predicate.
-   */
-  find(predicate) {
-    if (predicate(this)) {
-      return this;
-    }
-    return this.findParent(predicate);
-  }
-
-  // ===========================================================================
-  // Nested traversal
-  // ===========================================================================
-
-  /**
-   * Traverse into the current node with a new visitor.
-   * Populated by the traversal module to avoid circular imports.
-   */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-
-  /**
-   * Async version of traverse.
-   */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-
-  // ===========================================================================
-  // Traversal control
-  // ===========================================================================
-
-  /**
-   * Skip traversing the children of this node.
-   */
-  skip() {
-    this.#shouldSkip = true;
-  }
-
-  /**
-   * Stop all traversal completely.
-   */
-  stop() {
-    this.#shouldStop = true;
-  }
-
-  // ===========================================================================
-  // Modification
-  // ===========================================================================
-
-  /**
-   * Replace this node with a new node.
-   */
-  replaceWith(replacement) {
-    if (this.#stale) {
-      console.warn('Warning: replaceWith() called on a stale Path. ' + 'This path belongs to a node whose visit has already completed. ' + 'The replacement will have no effect. ' + "To replace a parent node, do so from the parent's own visitor.");
-    }
-    this.#replaced = true;
-    this.#replacementNode = replacement;
-    this.node = replacement;
-  }
-
-  /**
-   * Remove this node from the tree.
-   */
-  remove() {
-    if (this.#stale) {
-      console.warn('Warning: remove() called on a stale Path. ' + 'This path belongs to a node whose visit has already completed. ' + 'The removal will have no effect. ' + "To remove a parent node, do so from the parent's own visitor.");
-    }
-    this.#removed = true;
-  }
-
-  // ===========================================================================
-  // Internal methods for traversal engine
-  // ===========================================================================
-
-  /**
-   * @internal
-   */
-  _getReplacementNode() {
-    return this.#replacementNode;
-  }
-
-  /**
-   * @internal
-   */
-  _wasReplaced() {
-    return this.#replaced;
-  }
-
-  /**
-   * @internal
-   */
-  _reset() {
-    this.#shouldSkip = false;
-    this.#shouldStop = false;
-    this.#removed = false;
-    this.#replaced = false;
-    this.#replacementNode = undefined;
-  }
-
-  /**
-   * Mark this path as stale (visit completed).
-   * @internal
-   */
-  _markStale() {
-    this.#stale = true;
-  }
-}
-exports.Path = Path;