fix(overlay): honour the immutable default for partial options

defaultApplyOptions only applied when the options argument was omitted
entirely, so any partial object, applyAction(action, target, { strict:
true }) or just { trace }, left options.immutable undefined, which read
as falsy and applied the action in place. Callers passing a single
unrelated option silently mutated their own document, contradicting the
documented `immutable: true` default.

The applying entry points now merge the caller's options over the
defaults through withDefaults() and read the fields plainly. The uri
realm documents the opposite default, so it passes its own fallback down
explicitly rather than relying on undefined.

Signed-off-by: Vladimir Gorej <vladimir.gorej@gmail.com>

Author: char0n

packages/apidom-overlay/src/apply/realms/apidom.ts

@@ -39,6 +39,18 @@ interface InternalApplyOptions extends ApplyOptions {
 
 const defaultApplyOptions: ApplyOptions = { immutable: true, strict: false };
 
+/**
+ * Merges caller options over the defaults. A partial options object leaves the
+ * fields it omits undefined, which must still mean the documented defaults.
+ * `immutable` is spelled out because it is the only default that is not falsy,
+ * so a caller forwarding an undefined value must not end up mutating in place.
+ */
+const withDefaults = <T extends ApplyOptions>(options: T): T => ({
+  ...defaultApplyOptions,
+  ...options,
+  immutable: options.immutable ?? defaultApplyOptions.immutable,
+});
+
 /**
  * Default customMerge that enforces Overlay spec type compatibility.
  * Throws OverlayError on incompatible type combinations.
@@ -126,7 +138,8 @@ export const applyUpdateAction = (
   targetElement: Element,
   options: ApplyOptions = defaultApplyOptions,
 ): Element => {
-  let result = options.immutable ? cloneDeep(targetElement) : targetElement;
+  const opts = withDefaults(options);
+  let result = opts.immutable ? cloneDeep(targetElement) : targetElement;
 
   for (const normalizedPath of normalizedPaths) {
     /**
@@ -141,7 +154,7 @@ export const applyUpdateAction = (
 
     if (resolved === null) {
       // targeting root
-      result = mergeValue(result, clonedUpdateValue, options);
+      result = mergeValue(result, clonedUpdateValue, opts);
       continue;
     }
 
@@ -150,16 +163,12 @@ export const applyUpdateAction = (
     if (isObjectElement(parent)) {
       const current = parent.get(key as string);
       if (current !== undefined) {
-        parent.set(key as string, mergeValue(current, clonedUpdateValue, options));
+        parent.set(key as string, mergeValue(current, clonedUpdateValue, opts));
       }
     } else if (isArrayElement(parent)) {
       const current = parent.get(key as number);
       if (current !== undefined) {
-        (parent.content as Element[])[key as number] = mergeValue(
-          current,
-          clonedUpdateValue,
-          options,
-        );
+        (parent.content as Element[])[key as number] = mergeValue(current, clonedUpdateValue, opts);
       }
     }
   }
@@ -201,7 +210,8 @@ export const applyRemoveAction = (
   targetElement: Element,
   options: ApplyOptions = defaultApplyOptions,
 ): Element => {
-  const result = options.immutable ? cloneDeep(targetElement) : targetElement;
+  const opts = withDefaults(options);
+  const result = opts.immutable ? cloneDeep(targetElement) : targetElement;
   // reverse document order so higher array indices are removed first (avoids index shifting)
   const sorted = [...normalizedPaths].reverse();
 

packages/apidom-overlay/src/apply/realms/uri.ts

@@ -97,7 +97,10 @@ const applyOverlay = async (
   }
 
   // apply overlay actions to the target (returns targetParseResult with result replaced)
-  return applyOverlayApiDOM(overlayParseResult, targetParseResult, options) as ParseResultElement;
+  return applyOverlayApiDOM(overlayParseResult, targetParseResult, {
+    ...options,
+    immutable: options.immutable ?? defaultOptions.immutable,
+  }) as ParseResultElement;
 };
 
 export default applyOverlay;

packages/apidom-overlay/test/apply/realms/apidom.ts

@@ -504,6 +504,33 @@ describe('applyAction', function () {
     });
   });
 
+  context('partial options object', function () {
+    specify('should keep the immutable default when other options are passed', function () {
+      const action = refractAction({
+        target: '$.info',
+        update: { description: 'Added' },
+      });
+      const target = refract({ info: { title: 'Original' } });
+
+      const result = applyAction(action, target, { strict: true });
+
+      assert.strictEqual((toValue(result) as AnyJson).info.description, 'Added');
+      assert.isUndefined((toValue(target) as AnyJson).info.description);
+    });
+
+    specify('should keep the immutable default when immutable is undefined', function () {
+      const action = refractAction({
+        target: '$.info',
+        update: { description: 'Added' },
+      });
+      const target = refract({ info: { title: 'Original' } });
+
+      applyAction(action, target, { immutable: undefined });
+
+      assert.isUndefined((toValue(target) as AnyJson).info.description);
+    });
+  });
+
   context('mutable mode', function () {
     specify('should mutate original target on update', function () {
       const action = refractAction({
@@ -751,6 +778,22 @@ describe('applyOverlayApiDOM', function () {
     });
   });
 
+  context('partial options object', function () {
+    specify('should keep the immutable default when other options are passed', function () {
+      const overlay = refractOverlay1({
+        overlay: '1.1.0',
+        info: { title: 'Test', version: '1.0.0' },
+        actions: [{ target: '$.info', update: { description: 'Added' } }],
+      });
+      const target = refract({ info: { title: 'Original' } });
+
+      const result = applyOverlayApiDOM(overlay, target, { strict: true });
+
+      assert.strictEqual((toValue(result) as AnyJson).info.description, 'Added');
+      assert.isUndefined((toValue(target) as AnyJson).info.description);
+    });
+  });
+
   context('empty actions', function () {
     specify('should return target unchanged', function () {
       const overlay = refractOverlay1({