@speclynx/apidom-overlay 5.1.0 → 5.2.1

package/src/apply/realms/pojo.mjs

@@ -5,13 +5,25 @@ import { applyAction as applyActionApiDOM, applyOverlay as applyOverlayApiDOM }
 /**
  * Applies a single overlay action (POJO) to a target (POJO).
  *
+ * The refracted target never escapes this function and the result is converted
+ * straight back to a POJO, so it is applied in place.
+ *
  * @public
  */
-export const applyAction = (action, target, options) => toValue(applyActionApiDOM(refractAction(action), refract(target), options));
+export const applyAction = (action, target, options) => toValue(applyActionApiDOM(refractAction(action), refract(target), {
+  ...options,
+  immutable: false
+}));
 
 /**
  * Applies an entire overlay document (POJO) to a target (POJO).
  *
+ * The refracted target never escapes this function and the result is converted
+ * straight back to a POJO, so it is applied in place.
+ *
  * @public
  */
-export const applyOverlay = (overlay, target, options) => toValue(applyOverlayApiDOM(refractOverlay1(overlay), refract(target), options));
+export const applyOverlay = (overlay, target, options) => toValue(applyOverlayApiDOM(refractOverlay1(overlay), refract(target), {
+  ...options,
+  immutable: false
+}));

package/src/apply/realms/uri.cjs

@@ -81,7 +81,10 @@ const applyOverlay = async (overlayURI, targetURI, options = defaultOptions) =>
     throw new _OverlayError.default('No target specified: provide targetURI or set the "extends" field in the overlay document');
   }
 
-  // apply overlay actions to the target (returns targetParseResult with result replaced)
-  return (0, _apidom.applyOverlay)(overlayParseResult, targetParseResult, options);
+  // apply overlay actions to the target (mutable by default: targetParseResult with result replaced)
+  return (0, _apidom.applyOverlay)(overlayParseResult, targetParseResult, {
+    ...options,
+    immutable: options.immutable ?? defaultOptions.immutable
+  });
 };
 var _default = exports.default = applyOverlay;

package/src/apply/realms/uri.mjs

@@ -73,7 +73,10 @@ const applyOverlay = async (overlayURI, targetURI, options = defaultOptions) =>
     throw new OverlayError('No target specified: provide targetURI or set the "extends" field in the overlay document');
   }
 
-  // apply overlay actions to the target (returns targetParseResult with result replaced)
-  return applyOverlayApiDOM(overlayParseResult, targetParseResult, options);
+  // apply overlay actions to the target (mutable by default: targetParseResult with result replaced)
+  return applyOverlayApiDOM(overlayParseResult, targetParseResult, {
+    ...options,
+    immutable: options.immutable ?? defaultOptions.immutable
+  });
 };
 export default applyOverlay;

package/src/diff/realms/apidom.cjs

@@ -23,7 +23,13 @@ const defaultDiffOptions = {
 const createUpdateAction = (segments, value) => {
   const action = new _apidomNsOverlay.ActionElement();
   action.target = new _apidomDatamodel.StringElement(_apidomJsonPath.NormalizedPath.from(segments));
-  action.update = value;
+  /**
+   * Every update value is built from nodes of the right document. Cloning here
+   * keeps the emitted overlay independent of the right document in both
+   * directions, and keeps two overlays diffed against the same right document
+   * from sharing element instances with each other.
+   */
+  action.update = (0, _apidomDatamodel.cloneDeep)(value);
   return action;
 };
 const createRemoveAction = segments => {
@@ -146,8 +152,6 @@ const diffArrays = (left, right, segments, actions) => {
  * - Array items with a structural type change are handled via tail-reconstruct
  *   (remove tail + re-append from right), producing more actions than a minimal diff.
  * - The overlay carries no "before" value, so it cannot be reversed without the original document.
- * - Action `update` values reference elements from `rightElement` directly. Mutating `rightElement`
- *   after calling `diff` will affect the returned overlay.
  *
  * @public
  */

package/src/diff/realms/apidom.mjs

@@ -1,4 +1,4 @@
-import { ObjectElement, ArrayElement, StringElement, BooleanElement, isObjectElement, isArrayElement } from '@speclynx/apidom-datamodel';
+import { ObjectElement, ArrayElement, StringElement, BooleanElement, isObjectElement, isArrayElement, cloneDeep } from '@speclynx/apidom-datamodel';
 import { NormalizedPath } from '@speclynx/apidom-json-path';
 import { ActionElement, Overlay1Element, InfoElement, OverlayElement, ActionsElement } from '@speclynx/apidom-ns-overlay-1';
 import OverlayError from "../../errors/OverlayError.mjs";
@@ -15,7 +15,13 @@ const defaultDiffOptions = {
 const createUpdateAction = (segments, value) => {
   const action = new ActionElement();
   action.target = new StringElement(NormalizedPath.from(segments));
-  action.update = value;
+  /**
+   * Every update value is built from nodes of the right document. Cloning here
+   * keeps the emitted overlay independent of the right document in both
+   * directions, and keeps two overlays diffed against the same right document
+   * from sharing element instances with each other.
+   */
+  action.update = cloneDeep(value);
   return action;
 };
 const createRemoveAction = segments => {
@@ -138,8 +144,6 @@ const diffArrays = (left, right, segments, actions) => {
  * - Array items with a structural type change are handled via tail-reconstruct
  *   (remove tail + re-append from right), producing more actions than a minimal diff.
  * - The overlay carries no "before" value, so it cannot be reversed without the original document.
- * - Action `update` values reference elements from `rightElement` directly. Mutating `rightElement`
- *   after calling `diff` will affect the returned overlay.
  *
  * @public
  */

package/types/apidom-overlay.d.ts

@@ -29,7 +29,13 @@ export declare type ActionTraceType = 'update' | 'copy' | 'remove' | 'noop';
 
 /**
  * Applies a single overlay action to a target element.
- * Immutable — returns a new element with the action applied.
+ *
+ * Immutable by default. The target is cloned once up front and the action is
+ * applied to the clone, so the returned element is always independent of the
+ * input, including when the action changes nothing. Pass `immutable: false` to
+ * apply the action in place; the one shape that cannot be applied in place is
+ * a `target: $` action replacing a primitive root with a differently typed
+ * value, so the return value is authoritative in both modes.
  *
  * @public
  */
@@ -38,6 +44,9 @@ export declare const applyActionApiDOM: (actionElement: ActionElement, targetEle
 /**
  * Applies a single overlay action (POJO) to a target (POJO).
  *
+ * The refracted target never escapes this function and the result is converted
+ * straight back to a POJO, so it is applied in place.
+ *
  * @public
  */
 export declare const applyActionPOJO: (action: Record<string, unknown>, target: Record<string, unknown>, options?: ApplyOptions) => unknown;
@@ -70,7 +79,22 @@ export declare const applyOverlay: (overlayURI: string, targetURI?: string, opti
 
 /**
  * Applies an entire overlay document to a target element.
- * Immutable — returns a new element with all actions applied sequentially.
+ *
+ * Immutable by default. The target is cloned once up front and all actions are
+ * applied to the clone sequentially, so the returned element is always
+ * independent of the input, including when no action changes anything. Pass
+ * `immutable: false` to apply the actions in place; the one shape that cannot
+ * be applied in place is a `target: $` action replacing a primitive root with
+ * a differently typed value, so the return value is authoritative in both
+ * modes.
+ *
+ * When the target is a `ParseResultElement`, a new parse result is returned
+ * carrying the new tree as its result element; the caller's parse result and
+ * its result element are left untouched. Every other child — annotations, and
+ * an `api` element that is not the result element itself — is shared with the
+ * input rather than copied, since no overlay action can reach it.
+ * Under `immutable: false` the caller's parse result is updated in place
+ * instead, with its result element replaced by the new tree.
  *
  * @public
  */
@@ -86,6 +110,9 @@ export declare interface ApplyOverlayOptions extends ApplyOptions {
 /**
  * Applies an entire overlay document (POJO) to a target (POJO).
  *
+ * The refracted target never escapes this function and the result is converted
+ * straight back to a POJO, so it is applied in place.
+ *
  * @public
  */
 export declare const applyOverlayPOJO: (overlay: Record<string, unknown>, target: Record<string, unknown>, options?: ApplyOptions) => unknown;
@@ -113,8 +140,6 @@ export declare const defaultDiffOverlayOptions: DiffOverlayOptions;
  * - Array items with a structural type change are handled via tail-reconstruct
  *   (remove tail + re-append from right), producing more actions than a minimal diff.
  * - The overlay carries no "before" value, so it cannot be reversed without the original document.
- * - Action `update` values reference elements from `rightElement` directly. Mutating `rightElement`
- *   after calling `diff` will affect the returned overlay.
  *
  * @public
  */