@speclynx/apidom-overlay 4.5.0 → 4.7.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.7.0](https://github.com/speclynx/apidom/compare/v4.6.0...v4.7.0) (2026-04-12)
+
+### Features
+
+- **overlay:** generic targets, export defaults, scoped opts ([#236](https://github.com/speclynx/apidom/issues/236)) ([7df6dc7](https://github.com/speclynx/apidom/commit/7df6dc79d18e4c71ceb17037a45f9ba069fdcaf1))
+
+# [4.6.0](https://github.com/speclynx/apidom/compare/v4.5.0...v4.6.0) (2026-04-12)
+
+### Features
+
+- **overlay:** add tracing and restructure into realms ([#234](https://github.com/speclynx/apidom/issues/234)) ([3ae47c6](https://github.com/speclynx/apidom/commit/3ae47c6f8916b70db15704ade73af63210813c8c))
+
 # [4.5.0](https://github.com/speclynx/apidom/compare/v4.4.0...v4.5.0) (2026-04-12)
 
 ### Features

package/README.md

@@ -124,6 +124,61 @@ The implementation follows [Overlay 1.1.0](https://spec.openapis.org/overlay/v1.
 | `remove: true` | Removes matched nodes; when combined with `update`, the update has no effect |
 | Action ordering | Applied sequentially — each action modifies the result of the previous |
 
+## Tracing
+
+Overlay application supports tracing to inspect what each action did during application.
+Pass a trace object via the `trace` option — it will be populated in place with step-by-step
+information about every action applied.
+
+```js
+import { applyOverlayApiDOM } from '@speclynx/apidom-overlay';
+
+const trace = {};
+const result = applyOverlayApiDOM(overlay, target, { trace });
+
+console.log(trace.failed);   // false
+console.log(trace.message);  // 'Overlay was successfully applied'
+
+for (const action of trace.actions) {
+  console.log(action.target);          // '$.info.title'
+  console.log(action.type);            // 'update' | 'copy' | 'remove' | 'noop'
+  console.log(action.matchCount);      // 1
+  console.log(action.normalizedPaths); // ["$['info']['title']"]
+  console.log(action.success);         // true
+}
+```
+
+When an action fails, the trace captures the error before it is re-thrown:
+
+```js
+const trace = {};
+try {
+  applyOverlayApiDOM(overlay, target, { trace });
+} catch (error) {
+  console.log(trace.failed);                // true
+  console.log(trace.failedAt);              // index of the failed action
+  console.log(trace.message);               // error message
+  console.log(trace.actions[trace.failedAt].error); // the OverlayError instance
+}
+```
+
+Tracing works across all API levels — ApiDOM elements, file/URL, and POJO:
+
+```js
+// single action (ApiDOM)
+const trace = {};
+applyActionApiDOM(action, target, { trace });
+console.log(trace.actions[0].type); // 'update'
+
+// file/URL
+const trace = {};
+await applyOverlay('/path/to/overlay.yaml', undefined, { trace });
+
+// POJO
+const trace = {};
+applyOverlayPOJO(overlay, target, { trace });
+```
+
 ## Options
 
 ### ApplyOptions
@@ -135,6 +190,7 @@ Passed to `applyActionApiDOM`, `applyOverlayApiDOM`, and `applyOverlay`:
 | `deepmerge` | `DeepMergeUserOptions` | `{}` | Custom [deepmerge options](https://github.com/speclynx/apidom/blob/main/packages/apidom-core/src/merge/deepmerge.ts) from `@speclynx/apidom-core`. Default `customMerge` enforces Overlay spec type compatibility. |
 | `strict` | `boolean` | `false` | When `true`, throws `OverlayError` if any action's target JSONPath matches zero nodes. |
 | `immutable` | `boolean` | `true` | When `true` (default), returns a new element without mutating the input. Set to `false` for in-place mutation. |
+| `trace` | `OverlayTrace` | — | When provided, populated in place with action-by-action trace data. See [Tracing](#tracing). |
 
 ### ApplyOverlayOptions
 

package/dist/apidom-overlay.browser.js

@@ -11,7 +11,7 @@
 return /******/ (() => { // webpackBootstrap
 /******/ 	var __webpack_modules__ = ({
 
-/***/ 4433
+/***/ 28216
 (__unused_webpack_module, __webpack_exports__, __webpack_require__) {
 
 "use strict";
@@ -33,6 +33,8 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_7__ = __webpack_require__(26432);
 /* harmony import */ var _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_8__ = __webpack_require__(18436);
 /* harmony import */ var _validate_ts__WEBPACK_IMPORTED_MODULE_9__ = __webpack_require__(24338);
+/* harmony import */ var _trace_TraceBuilder_ts__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(90563);
+
 
 
 
@@ -44,6 +46,10 @@ __webpack_require__.r(__webpack_exports__);
  * @public
  */
 
+/**
+ * Internal options that carry the tracer instance.
+ */
+
 const defaultApplyOptions = {
   immutable: true,
   strict: false
@@ -185,6 +191,8 @@ const applyRemoveAction = (normalizedPaths, targetElement, options = defaultAppl
  * @public
  */
 const applyAction = (actionElement, targetElement, options = defaultApplyOptions) => {
+  const internalOpts = options;
+  const tracer = internalOpts.tracer ?? (options.trace ? new _trace_TraceBuilder_ts__WEBPACK_IMPORTED_MODULE_10__["default"](options.trace) : undefined);
   const actionValidation = (0,_validate_ts__WEBPACK_IMPORTED_MODULE_9__.validateAction)(actionElement);
   if (!actionValidation.valid) throw actionValidation.error;
   const targetExpression = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_3__["default"])(actionElement.target);
@@ -198,24 +206,53 @@ const applyAction = (actionElement, targetElement, options = defaultApplyOptions
   });
   if (matches.length === 0) {
     if (options.strict) {
-      throw new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_8__["default"](`Action target "${targetExpression}" matched zero nodes (strict mode)`, {
+      const error = new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_8__["default"](`Action target "${targetExpression}" matched zero nodes (strict mode)`, {
         action: actionElement
       });
+      tracer?.action({
+        target: targetExpression,
+        type: 'noop',
+        matchCount: 0,
+        normalizedPaths: [],
+        success: false,
+        error
+      });
+      throw error;
     }
+    tracer?.action({
+      target: targetExpression,
+      type: 'noop',
+      matchCount: 0,
+      normalizedPaths: []
+    });
     return targetElement;
   }
   try {
     // remove action
     const removeValue = actionElement.removeField;
     if (removeValue !== undefined && (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_3__["default"])(removeValue) === true) {
-      return applyRemoveAction(normalizedPaths, targetElement, options);
+      const result = applyRemoveAction(normalizedPaths, targetElement, options);
+      tracer?.action({
+        target: targetExpression,
+        type: 'remove',
+        matchCount: matches.length,
+        normalizedPaths
+      });
+      return result;
     }
 
     // update action
     if (actionElement.update !== undefined) {
       const nodesValidation = (0,_validate_ts__WEBPACK_IMPORTED_MODULE_9__.validateTargetNodes)(matches);
       if (!nodesValidation.valid) throw nodesValidation.error;
-      return applyUpdateAction(normalizedPaths, actionElement.update, targetElement, options);
+      const result = applyUpdateAction(normalizedPaths, actionElement.update, targetElement, options);
+      tracer?.action({
+        target: targetExpression,
+        type: 'update',
+        matchCount: matches.length,
+        normalizedPaths
+      });
+      return result;
     }
 
     // copy action
@@ -223,14 +260,35 @@ const applyAction = (actionElement, targetElement, options = defaultApplyOptions
       const nodesValidation = (0,_validate_ts__WEBPACK_IMPORTED_MODULE_9__.validateTargetNodes)(matches);
       if (!nodesValidation.valid) throw nodesValidation.error;
       const copyExpression = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_3__["default"])(actionElement.copy);
-      return applyCopyAction(normalizedPaths, copyExpression, targetElement, options);
+      const result = applyCopyAction(normalizedPaths, copyExpression, targetElement, options);
+      tracer?.action({
+        target: targetExpression,
+        type: 'copy',
+        matchCount: matches.length,
+        normalizedPaths
+      });
+      return result;
     }
+    tracer?.action({
+      target: targetExpression,
+      type: 'noop',
+      matchCount: matches.length,
+      normalizedPaths
+    });
     return targetElement;
   } catch (error) {
     // enrich OverlayError with action context, preserving original stack
     if (error instanceof _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_8__["default"] && !error.action) {
       error.action = actionElement;
     }
+    tracer?.action({
+      target: targetExpression,
+      type: 'noop',
+      matchCount: matches.length,
+      normalizedPaths,
+      success: false,
+      error: error instanceof _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_8__["default"] ? error : undefined
+    });
     throw error;
   }
 };
@@ -248,21 +306,28 @@ const applyOverlay = (overlayElement, targetElement, options = defaultApplyOptio
   }
   let target;
   if (targetElement instanceof _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"]) {
-    if (targetElement.api === undefined) {
-      throw new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_8__["default"]('Target ParseResultElement contains no API element');
+    if (targetElement.result === undefined) {
+      throw new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_8__["default"]('Target ParseResultElement contains no result element');
     }
-    target = targetElement.api;
+    target = targetElement.result;
   } else {
     target = targetElement;
   }
   if (!(0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isArrayElement)(overlay.actions)) {
     return targetElement;
   }
+  const tracer = options.trace ? new _trace_TraceBuilder_ts__WEBPACK_IMPORTED_MODULE_10__["default"](options.trace) : undefined;
+  const internalOptions = tracer ? {
+    ...options,
+    tracer
+  } : options;
   for (const action of overlay.actions) {
-    target = applyAction(action, target, options);
+    target = applyAction(action, target, internalOptions);
   }
   if (targetElement instanceof _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"]) {
-    targetElement.replaceResult(target);
+    if (target !== targetElement.result) {
+      targetElement.replaceResult(target);
+    }
     return targetElement;
   }
   return target;
@@ -270,7 +335,7 @@ const applyOverlay = (overlayElement, targetElement, options = defaultApplyOptio
 
 /***/ },
 
-/***/ 56019
+/***/ 83942
 (__unused_webpack_module, __webpack_exports__, __webpack_require__) {
 
 "use strict";
@@ -282,7 +347,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(10404);
 /* harmony import */ var _speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(44673);
 /* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(35957);
-/* harmony import */ var _apidom_ts__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(4433);
+/* harmony import */ var _apidom_ts__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(28216);
 
 
 
@@ -293,29 +358,30 @@ __webpack_require__.r(__webpack_exports__);
  *
  * @public
  */
-const applyAction = (action, target) => (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_1__["default"])((0,_apidom_ts__WEBPACK_IMPORTED_MODULE_3__.applyAction)((0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_2__.refractAction)(action), (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.refract)(target)));
+const applyAction = (action, target, options) => (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_1__["default"])((0,_apidom_ts__WEBPACK_IMPORTED_MODULE_3__.applyAction)((0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_2__.refractAction)(action), (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.refract)(target), options));
 
 /**
  * Applies an entire overlay document (POJO) to a target (POJO).
  *
  * @public
  */
-const applyOverlay = (overlay, target) => (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_1__["default"])((0,_apidom_ts__WEBPACK_IMPORTED_MODULE_3__.applyOverlay)((0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_2__.refractOverlay1)(overlay), (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.refract)(target)));
+const applyOverlay = (overlay, target, options) => (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_1__["default"])((0,_apidom_ts__WEBPACK_IMPORTED_MODULE_3__.applyOverlay)((0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_2__.refractOverlay1)(overlay), (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.refract)(target), options));
 
 /***/ },
 
-/***/ 54687
+/***/ 42768
 (__unused_webpack_module, __webpack_exports__, __webpack_require__) {
 
 "use strict";
 __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
-/* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__)
+/* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__),
+/* harmony export */   defaultOptions: () => (/* binding */ defaultOptions)
 /* harmony export */ });
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(96911);
 /* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(26432);
 /* harmony import */ var _speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(29807);
-/* harmony import */ var _apidom_ts__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(4433);
+/* harmony import */ var _apidom_ts__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(28216);
 /* harmony import */ var _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(18436);
 
 
@@ -327,7 +393,7 @@ __webpack_require__.r(__webpack_exports__);
  * @public
  */
 
-const defaultOptions = {
+const defaultReferenceOptions = {
   parse: {
     parserOpts: {
       strict: false,
@@ -351,6 +417,15 @@ const defaultOptions = {
   }
 };
 
+/**
+ * @public
+ */
+const defaultOptions = {
+  immutable: false,
+  strict: false,
+  reference: defaultReferenceOptions
+};
+
 /**
  * Applies an overlay document from a file/URL to its target document.
  *
@@ -360,27 +435,23 @@ const defaultOptions = {
  *
  * @param overlayURI - URI to the overlay document (file path or URL)
  * @param targetURI - URI to the target document; if omitted, uses the overlay's `extends` field
- * @param options - apidom-reference options + overlay merge options
+ * @param options - overlay apply options; reference options live under `options.reference`
  * @returns ParseResultElement with the modified target document
  *
  * @public
  */
-const applyOverlay = async (overlayURI, targetURI, options = {
-  immutable: false,
-  strict: false
-}) => {
-  const mergedOptions = (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.mergeOptions)(defaultOptions, options);
+const applyOverlay = async (overlayURI, targetURI, options = defaultOptions) => {
+  const mergedRefOptions = (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.mergeOptions)(defaultReferenceOptions, options.reference ?? {});
 
   // parse the overlay document along with document attached to `extends` field (if present)
-  const overlayParseResult = await (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.parse)(overlayURI, mergedOptions);
+  const overlayParseResult = await (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.parse)(overlayURI, mergedRefOptions);
   const overlayElement = overlayParseResult.api;
   if (!(0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_1__.isOverlay1Element)(overlayElement)) {
     throw new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_4__["default"](`Failed to parse overlay document "${overlayURI}"`);
   }
   let targetParseResult;
   if (targetURI) {
-    const targetOptions = (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.mergeOptions)(defaultOptions, options);
-    targetParseResult = await (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.parse)(targetURI, targetOptions);
+    targetParseResult = await (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.parse)(targetURI, mergedRefOptions);
   } else {
     const extendsElement = overlayElement.get('extends');
     targetParseResult = extendsElement?.meta?.get('parseResult');
@@ -396,6 +467,58 @@ const applyOverlay = async (overlayURI, targetURI, options = {
 
 /***/ },
 
+/***/ 90563
+(__unused_webpack_module, __webpack_exports__, __webpack_require__) {
+
+"use strict";
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__)
+/* harmony export */ });
+/**
+ * Collects trace entries during overlay application.
+ * Instantiated internally when `options.trace` is provided.
+ */
+class TraceBuilder {
+  #trace;
+  constructor(trace) {
+    this.#trace = trace;
+    this.#trace.actions = [];
+    this.#trace.failed = false;
+    this.#trace.failedAt = -1;
+    this.#trace.message = 'Overlay was successfully applied';
+  }
+  action(step) {
+    const {
+      target,
+      type,
+      matchCount,
+      normalizedPaths,
+      success = true,
+      error
+    } = step;
+    const position = this.#trace.actions.length;
+    this.#trace.actions.push({
+      target,
+      type,
+      matchCount,
+      normalizedPaths,
+      success,
+      ...(error !== undefined ? {
+        error
+      } : {})
+    });
+    if (!success) {
+      this.#trace.failed = true;
+      this.#trace.failedAt = position;
+      this.#trace.message = error?.message ?? 'Action failed';
+    }
+  }
+}
+/* harmony default export */ const __WEBPACK_DEFAULT_EXPORT__ = (TraceBuilder);
+
+/***/ },
+
 /***/ 18436
 (__unused_webpack_module, __webpack_exports__, __webpack_require__) {
 
@@ -100897,16 +101020,17 @@ var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   OverlayError: () => (/* reexport safe */ _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_4__["default"]),
-/* harmony export */   applyActionApiDOM: () => (/* reexport safe */ _apply_apidom_ts__WEBPACK_IMPORTED_MODULE_0__.applyAction),
-/* harmony export */   applyActionPOJO: () => (/* reexport safe */ _apply_pojo_ts__WEBPACK_IMPORTED_MODULE_2__.applyAction),
-/* harmony export */   applyOverlay: () => (/* reexport safe */ _apply_uri_ts__WEBPACK_IMPORTED_MODULE_1__["default"]),
-/* harmony export */   applyOverlayApiDOM: () => (/* reexport safe */ _apply_apidom_ts__WEBPACK_IMPORTED_MODULE_0__.applyOverlay),
-/* harmony export */   applyOverlayPOJO: () => (/* reexport safe */ _apply_pojo_ts__WEBPACK_IMPORTED_MODULE_2__.applyOverlay),
+/* harmony export */   applyActionApiDOM: () => (/* reexport safe */ _apply_realms_apidom_ts__WEBPACK_IMPORTED_MODULE_0__.applyAction),
+/* harmony export */   applyActionPOJO: () => (/* reexport safe */ _apply_realms_pojo_ts__WEBPACK_IMPORTED_MODULE_2__.applyAction),
+/* harmony export */   applyOverlay: () => (/* reexport safe */ _apply_realms_uri_ts__WEBPACK_IMPORTED_MODULE_1__["default"]),
+/* harmony export */   applyOverlayApiDOM: () => (/* reexport safe */ _apply_realms_apidom_ts__WEBPACK_IMPORTED_MODULE_0__.applyOverlay),
+/* harmony export */   applyOverlayPOJO: () => (/* reexport safe */ _apply_realms_pojo_ts__WEBPACK_IMPORTED_MODULE_2__.applyOverlay),
+/* harmony export */   defaultApplyOverlayOptions: () => (/* reexport safe */ _apply_realms_uri_ts__WEBPACK_IMPORTED_MODULE_1__.defaultOptions),
 /* harmony export */   validateAction: () => (/* reexport safe */ _validate_ts__WEBPACK_IMPORTED_MODULE_3__.validateAction)
 /* harmony export */ });
-/* harmony import */ var _apply_apidom_ts__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(4433);
-/* harmony import */ var _apply_uri_ts__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(54687);
-/* harmony import */ var _apply_pojo_ts__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(56019);
+/* harmony import */ var _apply_realms_apidom_ts__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(28216);
+/* harmony import */ var _apply_realms_uri_ts__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(42768);
+/* harmony import */ var _apply_realms_pojo_ts__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(83942);
 /* harmony import */ var _validate_ts__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(24338);
 /* harmony import */ var _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(18436);