@speclynx/apidom-traverse 3.2.1 → 4.0.0

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [4.0.0](https://github.com/speclynx/apidom/compare/v3.2.1...v4.0.0) (2026-03-11)
+
+### Features
+
+- **traverse:** all traverse operations work on Path and not Element ([#153](https://github.com/speclynx/apidom/issues/153)) ([67d244c](https://github.com/speclynx/apidom/commit/67d244cfd3e77f6a9db704cede50ba8e45d10b11))
+
+### BREAKING CHANGES
+
+- **traverse:** This is a breaking change as operation callbacks
+  now accept Path instead of Element. By accepting Path, full
+  context of traversal is exposed to consumer instead of just Element.
+
 ## [3.2.1](https://github.com/speclynx/apidom/compare/v3.2.0...v3.2.1) (2026-03-09)
 
 **Note:** Version bump only for package @speclynx/apidom-traverse

package/README.md

@@ -58,7 +58,7 @@ All operations use **data-first** signatures: the element comes before the predi
 
 ### filter
 
-Finds all elements matching the predicate.
+Finds all paths whose elements match the predicate.
 
 ```js
 import { ObjectElement, isNumberElement } from '@speclynx/apidom-datamodel';
@@ -66,12 +66,14 @@ import { filter } from '@speclynx/apidom-traverse';
 
 const element = new ObjectElement({ a: 'b', c: 2 });
 
-filter(element, isNumberElement); // => [NumberElement<2>]
+const paths = filter(element, (path) => isNumberElement(path.node)); // => [Path<NumberElement<2>>]
+paths[0].node; // => NumberElement<2>
+paths[0].formatPath(); // => '/c'
 ```
 
 ### find
 
-Find first element that satisfies the provided predicate.
+Finds first path whose element satisfies the provided predicate.
 
 ```js
 import { ObjectElement, isNumberElement } from '@speclynx/apidom-datamodel';
@@ -79,24 +81,29 @@ import { find } from '@speclynx/apidom-traverse';
 
 const element = new ObjectElement({ a: 'b', c: 2 });
 
-find(element, isNumberElement); // => NumberElement<2>
+const path = find(element, (path) => isNumberElement(path.node)); // => Path<NumberElement<2>>
+path.node; // => NumberElement<2>
+path.formatPath(); // => '/c'
 ```
 
 ### findAtOffset
 
-ApiDOM nodes can be associated with source maps. This function finds the most inner node at the given offset.
+ApiDOM nodes can be associated with source maps. This function 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.
 
 ```js
 import { findAtOffset } from '@speclynx/apidom-traverse';
 
-findAtOffset(elementWithSourceMaps, 3); // => returns most inner node at offset 3
+const path = findAtOffset(elementWithSourceMaps, 3); // => Path of most inner node at offset 3
+path.node; // => the element at that offset
+path.formatPath(); // => JSON Pointer to the element
+
 findAtOffset(elementWithSourceMaps, { offset: 3, includeRightBound: true });
 ```
 
 ### reject
 
-Complement of [filter](#filter). Finds all elements NOT matching the predicate.
+Complement of [filter](#filter). Finds all paths whose elements do NOT match the predicate.
 
 ```js
 import { ArrayElement, isNumberElement } from '@speclynx/apidom-datamodel';
@@ -104,12 +111,13 @@ import { reject } from '@speclynx/apidom-traverse';
 
 const element = new ArrayElement([1, 'a']);
 
-reject(element, isNumberElement); // => [ArrayElement, StringElement<'a'>]
+const paths = reject(element, (path) => isNumberElement(path.node)); // => [Path<ArrayElement>, Path<StringElement<'a'>>]
+paths.map((p) => p.node); // => [ArrayElement, StringElement<'a'>]
 ```
 
 ### some
 
-Tests whether at least one element passes the predicate.
+Tests whether at least one path's element passes the predicate.
 
 ```js
 import { ArrayElement, isNumberElement } from '@speclynx/apidom-datamodel';
@@ -117,12 +125,12 @@ import { some } from '@speclynx/apidom-traverse';
 
 const element = new ArrayElement([1, 'a']);
 
-some(element, isNumberElement); // => true
+some(element, (path) => isNumberElement(path.node)); // => true
 ```
 
 ### forEach
 
-Executes the callback on this element and all descendants.
+Executes the callback on this element's path and all descendant paths.
 
 ```js
 import { ArrayElement } from '@speclynx/apidom-datamodel';
@@ -130,7 +138,7 @@ import { forEach } from '@speclynx/apidom-traverse';
 
 const element = new ArrayElement([1, 'a']);
 
-forEach(element, console.dir); // => prints ArrayElement, NumberElement, StringElement in this order
+forEach(element, (path) => console.dir(path.node)); // => prints ArrayElement, NumberElement, StringElement
 ```
 
 The execution of the callback can be controlled further by providing a predicate.
@@ -141,7 +149,10 @@ import { forEach } from '@speclynx/apidom-traverse';
 
 const element = new ArrayElement([1, 'a']);
 
-forEach(element, { callback: console.dir, predicate: isNumberElement }); // => prints NumberElement<1>
+forEach(element, {
+  callback: (path) => console.dir(path.node),
+  predicate: (path) => isNumberElement(path.node),
+}); // => prints NumberElement<1>
 ```
 
 ### parents

package/dist/apidom-traverse.browser.js

@@ -170,7 +170,9 @@ class Path {
    *
    * @example
    * // For a path to $.paths['/pets'].get in an OpenAPI document:
+   * ```
    * path.getPathKeys(); // => ['paths', '/pets', 'get']
+   * ```
    */
   getPathKeys() {
     const keys = [];
@@ -205,18 +207,22 @@ class Path {
    *          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();
@@ -367,15 +373,15 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _traversal_ts__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(9761);
 
 /**
- * Finds all elements matching the predicate.
+ * Finds all paths whose elements match the predicate.
  * @public
  */
 const filter = (element, predicate) => {
   const result = [];
   (0,_traversal_ts__WEBPACK_IMPORTED_MODULE_0__.traverse)(element, {
     enter(path) {
-      if (predicate(path.node)) {
-        result.push(path.node);
+      if (predicate(path)) {
+        result.push(path);
       }
     }
   });
@@ -402,7 +408,7 @@ __webpack_require__.r(__webpack_exports__);
  */
 
 /**
- * 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
  */
@@ -427,7 +433,7 @@ const findAtOffset = (element, options) => {
       const endOffset = node.endOffset;
       const isWithinOffsetRange = offset >= startOffset && (offset < endOffset || includeRightBound && offset <= endOffset);
       if (isWithinOffsetRange) {
-        result.push(node);
+        result.push(path);
         return; // push to stack and dive in
       }
       path.skip(); // skip entire sub-tree
@@ -449,15 +455,15 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _traversal_ts__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(9761);
 
 /**
- * Find first element that satisfies the provided predicate.
+ * Finds first path whose element satisfies the provided predicate.
  * @public
  */
 const find = (element, predicate) => {
   let result;
   (0,_traversal_ts__WEBPACK_IMPORTED_MODULE_0__.traverse)(element, {
     enter(path) {
-      if (predicate(path.node)) {
-        result = path.node;
+      if (predicate(path)) {
+        result = path;
         path.stop();
       }
     }
@@ -475,9 +481,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__)
 /* harmony export */ });
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(5162);
-/* harmony import */ var _traversal_ts__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(9761);
-
+/* harmony import */ var _traversal_ts__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(9761);
 
 
 /**
@@ -489,7 +493,7 @@ __webpack_require__.r(__webpack_exports__);
  */
 
 /**
- * Executes the callback on this element and all descendants.
+ * Executes the callback on this element's path and all descendant paths.
  * @public
  */
 const forEach = (element, options) => {
@@ -497,15 +501,15 @@ const forEach = (element, options) => {
   let predicate;
   if (typeof options === 'function') {
     callback = options;
-    predicate = _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isElement;
+    predicate = () => true;
   } else {
     callback = options.callback ?? (() => {});
-    predicate = options.predicate ?? _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isElement;
+    predicate = options.predicate ?? (() => true);
   }
-  (0,_traversal_ts__WEBPACK_IMPORTED_MODULE_1__.traverse)(element, {
+  (0,_traversal_ts__WEBPACK_IMPORTED_MODULE_0__.traverse)(element, {
     enter(path) {
-      if (predicate(path.node)) {
-        callback(path.node);
+      if (predicate(path)) {
+        callback(path);
       }
     }
   });
@@ -551,13 +555,12 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ });
 /* harmony import */ var _filter_ts__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(706);
 
-
 /**
- * Complement of filter. Finds all elements NOT matching the predicate.
+ * Complement of filter. Finds all paths whose elements do NOT match the predicate.
  * @public
  */
 const reject = (element, predicate) => {
-  return (0,_filter_ts__WEBPACK_IMPORTED_MODULE_0__["default"])(element, el => !predicate(el));
+  return (0,_filter_ts__WEBPACK_IMPORTED_MODULE_0__["default"])(element, path => !predicate(path));
 };
 /* harmony default export */ const __WEBPACK_DEFAULT_EXPORT__ = (reject);
 
@@ -572,9 +575,8 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ });
 /* harmony import */ var _find_ts__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(9068);
 
-
 /**
- * Tests whether at least one element passes the predicate.
+ * Tests whether at least one path's element passes the predicate.
  * @public
  */
 const some = (element, predicate) => {