@speclynx/apidom-reference 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)
 
 ### Bug Fixes

package/dist/apidom-reference.browser.js

@@ -589,9 +589,9 @@ const getElementID = element => {
   // handle both raw string (new format) and StringElement (legacy Refract without __meta_raw__)
   return (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.isElement)(id) ? (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_2__["default"])(id) : id;
 };
-const hasElementID = element => {
-  if (!element.hasMetaProperty('id')) return false;
-  const id = getElementID(element);
+const hasElementID = path => {
+  if (!path.node.hasMetaProperty('id')) return false;
+  const id = getElementID(path.node);
   return typeof id === 'string' && id !== '';
 };
 
@@ -605,8 +605,8 @@ const evaluate = (elementID, element) => {
   } = evaluate;
   // warm the cache
   if (!cache.has(element)) {
-    const elementsWithID = (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_3__.filter)(element, hasElementID);
-    cache.set(element, Array.from(elementsWithID));
+    const pathsWithID = (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_3__.filter)(element, hasElementID);
+    cache.set(element, pathsWithID.map(path => path.node));
   }
 
   // search for the matching element
@@ -3987,7 +3987,8 @@ class OpenAPI3_0DereferenceVisitor {
       if ((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__.isStringElement)(linkElement.operationId)) {
         const operationId = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_5__["default"])(linkElement.operationId);
         const reference = await this.toReference(_util_url_ts__WEBPACK_IMPORTED_MODULE_17__.unsanitize(this.reference.uri));
-        operationElement = (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_8__.find)(reference.value.result, e => (0,_speclynx_apidom_ns_openapi_3_0__WEBPACK_IMPORTED_MODULE_12__.isOperationElement)(e) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__.isElement)(e.operationId) && e.operationId.equals(operationId));
+        const operationPath = (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_8__.find)(reference.value.result, path => (0,_speclynx_apidom_ns_openapi_3_0__WEBPACK_IMPORTED_MODULE_12__.isOperationElement)(path.node) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__.isElement)(path.node.operationId) && path.node.operationId.equals(operationId));
+        operationElement = operationPath?.node;
         // OperationElement not found by its operationId
         if ((0,ramda_adjunct__WEBPACK_IMPORTED_MODULE_1__["default"])(operationElement)) {
           throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_7__["default"](`OperationElement(operationId=${operationId}) not found`, {
@@ -4247,15 +4248,13 @@ const parse = anchor => {
  */
 const evaluate = (anchor, element) => {
   const token = parse(anchor);
-
+  const resultPath = (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_3__.find)(element,
   // @ts-ignore
-  const result = (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_3__.find)(element, e => (0,_speclynx_apidom_ns_json_schema_2020_12__WEBPACK_IMPORTED_MODULE_4__.isJSONSchemaElement)(e) && (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_2__["default"])(e.$anchor) === token);
-  if ((0,ramda_adjunct__WEBPACK_IMPORTED_MODULE_0__["default"])(result)) {
+  path => (0,_speclynx_apidom_ns_json_schema_2020_12__WEBPACK_IMPORTED_MODULE_4__.isJSONSchemaElement)(path.node) && (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_2__["default"])(path.node.$anchor) === token);
+  if ((0,ramda_adjunct__WEBPACK_IMPORTED_MODULE_0__["default"])(resultPath)) {
     throw new _errors_EvaluationJsonSchema$anchorError_ts__WEBPACK_IMPORTED_MODULE_6__["default"](`Evaluation failed on token: "${token}"`);
   }
-
-  // @ts-ignore
-  return result;
+  return resultPath.node;
 };
 
 
@@ -4300,12 +4299,12 @@ const evaluate = (uri, element) => {
     cache
   } = evaluate;
   const uriStrippedHash = _util_url_ts__WEBPACK_IMPORTED_MODULE_5__.stripHash(uri);
-  const isJSONSchemaElementWith$id = e => (0,_speclynx_apidom_ns_json_schema_2020_12__WEBPACK_IMPORTED_MODULE_2__.isJSONSchemaElement)(e) && typeof e.$id !== 'undefined';
+  const isJSONSchemaElementWith$id = path => (0,_speclynx_apidom_ns_json_schema_2020_12__WEBPACK_IMPORTED_MODULE_2__.isJSONSchemaElement)(path.node) && typeof path.node.$id !== 'undefined';
 
   // warm the cache
   if (!cache.has(element)) {
-    const schemaObjectElements = (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_1__.filter)(element, isJSONSchemaElementWith$id);
-    cache.set(element, Array.from(schemaObjectElements));
+    const schemaObjectPaths = (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_1__.filter)(element, isJSONSchemaElementWith$id);
+    cache.set(element, schemaObjectPaths.map(path => path.node));
   }
 
   // search for the matching schema
@@ -5006,7 +5005,8 @@ class OpenAPI3_1DereferenceVisitor {
       if ((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__.isStringElement)(linkElement.operationId)) {
         const operationId = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_7__["default"])(linkElement.operationId);
         const reference = await this.toReference(_util_url_ts__WEBPACK_IMPORTED_MODULE_23__.unsanitize(this.reference.uri));
-        operationElement = (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_10__.find)(reference.value.result, e => (0,_speclynx_apidom_ns_openapi_3_1__WEBPACK_IMPORTED_MODULE_16__.isOperationElement)(e) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__.isElement)(e.operationId) && e.operationId.equals(operationId));
+        const operationPath = (0,_speclynx_apidom_traverse__WEBPACK_IMPORTED_MODULE_10__.find)(reference.value.result, path => (0,_speclynx_apidom_ns_openapi_3_1__WEBPACK_IMPORTED_MODULE_16__.isOperationElement)(path.node) && (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_3__.isElement)(path.node.operationId) && path.node.operationId.equals(operationId));
+        operationElement = operationPath?.node;
         // OperationElement not found by its operationId
         if ((0,ramda_adjunct__WEBPACK_IMPORTED_MODULE_2__["default"])(operationElement)) {
           throw new _speclynx_apidom_error__WEBPACK_IMPORTED_MODULE_9__["default"](`OperationElement(operationId=${operationId}) not found`, {
@@ -96777,7 +96777,9 @@ class Path {
    *
    * @example
    * // For a path to $.paths['/pets'].get in an OpenAPI document:
+   * ```
    * path.getPathKeys(); // => ['paths', '/pets', 'get']
+   * ```
    */
   getPathKeys() {
     const keys = [];
@@ -96812,18 +96814,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();
@@ -97033,15 +97039,15 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _traversal_mjs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(72078);
 
 /**
- * Finds all elements matching the predicate.
+ * Finds all paths whose elements match the predicate.
  * @public
  */
 const filter = (element, predicate) => {
   const result = [];
   (0,_traversal_mjs__WEBPACK_IMPORTED_MODULE_0__.traverse)(element, {
     enter(path) {
-      if (predicate(path.node)) {
-        result.push(path.node);
+      if (predicate(path)) {
+        result.push(path);
       }
     }
   });
@@ -97067,7 +97073,7 @@ __webpack_require__.r(__webpack_exports__);
  * @public
  */
 /**
- * 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
  */
@@ -97092,7 +97098,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
@@ -97115,15 +97121,15 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _traversal_mjs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(72078);
 
 /**
- * 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_mjs__WEBPACK_IMPORTED_MODULE_0__.traverse)(element, {
     enter(path) {
-      if (predicate(path.node)) {
-        result = path.node;
+      if (predicate(path)) {
+        result = path;
         path.stop();
       }
     }
@@ -97142,9 +97148,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__(25162);
-/* harmony import */ var _traversal_mjs__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(72078);
-
+/* harmony import */ var _traversal_mjs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(72078);
 
 /**
  * @public
@@ -97153,7 +97157,7 @@ __webpack_require__.r(__webpack_exports__);
  * @public
  */
 /**
- * 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) => {
@@ -97161,15 +97165,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_mjs__WEBPACK_IMPORTED_MODULE_1__.traverse)(element, {
+  (0,_traversal_mjs__WEBPACK_IMPORTED_MODULE_0__.traverse)(element, {
     enter(path) {
-      if (predicate(path.node)) {
-        callback(path.node);
+      if (predicate(path)) {
+        callback(path);
       }
     }
   });
@@ -97218,11 +97222,11 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _filter_mjs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(75247);
 
 /**
- * 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_mjs__WEBPACK_IMPORTED_MODULE_0__["default"])(element, el => !predicate(el));
+  return (0,_filter_mjs__WEBPACK_IMPORTED_MODULE_0__["default"])(element, path => !predicate(path));
 };
 /* harmony default export */ const __WEBPACK_DEFAULT_EXPORT__ = (reject);
 
@@ -97239,7 +97243,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _find_mjs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(44860);
 
 /**
- * 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) => {