@speclynx/apidom-overlay 4.5.0 → 4.7.0

package/types/apidom-overlay.d.ts

@@ -6,6 +6,26 @@ import { Element as Element_2 } from '@speclynx/apidom-datamodel';
 import { MemberElement } from '@speclynx/apidom-datamodel';
 import { Overlay1Element } from '@speclynx/apidom-ns-overlay-1';
 import { ParseResultElement } from '@speclynx/apidom-datamodel';
+import type { PartialDeep } from 'type-fest';
+
+/**
+ * Trace entry for a single overlay action application.
+ *
+ * @public
+ */
+export declare interface ActionTrace {
+    readonly target: string;
+    readonly type: ActionTraceType;
+    readonly matchCount: number;
+    readonly normalizedPaths: string[];
+    readonly success: boolean;
+    readonly error?: OverlayError;
+}
+
+/**
+ * @public
+ */
+export declare type ActionTraceType = 'update' | 'copy' | 'remove' | 'noop';
 
 /**
  * Applies a single overlay action to a target element.
@@ -20,7 +40,7 @@ export declare const applyActionApiDOM: (actionElement: ActionElement, targetEle
  *
  * @public
  */
-export declare const applyActionPOJO: (action: Record<string, unknown>, target: Record<string, unknown>) => unknown;
+export declare const applyActionPOJO: (action: Record<string, unknown>, target: Record<string, unknown>, options?: ApplyOptions) => unknown;
 
 /**
  * @public
@@ -29,6 +49,7 @@ export declare interface ApplyOptions {
     readonly deepmerge?: DeepMergeUserOptions;
     readonly strict?: boolean;
     readonly immutable?: boolean;
+    readonly trace?: OverlayTrace;
 }
 
 /**
@@ -40,7 +61,7 @@ export declare interface ApplyOptions {
  *
  * @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
@@ -58,7 +79,8 @@ export declare const applyOverlayApiDOM: <T extends Element_2 | ParseResultEleme
 /**
  * @public
  */
-export declare interface ApplyOverlayOptions extends Partial<ApiDOMReferenceOptions>, ApplyOptions {
+export declare interface ApplyOverlayOptions extends ApplyOptions {
+    readonly reference?: PartialDeep<ApiDOMReferenceOptions>;
 }
 
 /**
@@ -66,7 +88,12 @@ export declare interface ApplyOverlayOptions extends Partial<ApiDOMReferenceOpti
  *
  * @public
  */
-export declare const applyOverlayPOJO: (overlay: Record<string, unknown>, target: Record<string, unknown>) => unknown;
+export declare const applyOverlayPOJO: (overlay: Record<string, unknown>, target: Record<string, unknown>, options?: ApplyOptions) => unknown;
+
+/**
+ * @public
+ */
+export declare const defaultApplyOverlayOptions: ApplyOverlayOptions;
 
 /**
  * @public
@@ -87,6 +114,19 @@ export declare interface OverlayErrorOptions {
     readonly [key: string]: unknown;
 }
 
+/**
+ * Top-level trace container populated during overlay application.
+ * Pass as `trace` option — it will be mutated in place.
+ *
+ * @public
+ */
+export declare interface OverlayTrace {
+    actions: ActionTrace[];
+    failed: boolean;
+    failedAt: number;
+    message: string;
+}
+
 /**
  * Validates that an ActionElement has the correct shape per the Overlay spec.
  *