@speclynx/apidom-overlay 5.1.0 → 5.2.1

package/CHANGELOG.md

@@ -3,6 +3,31 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [5.2.1](https://github.com/speclynx/apidom/compare/v5.2.0...v5.2.1) (2026-08-29)
+
+**Note:** Version bump only for package @speclynx/apidom-overlay
+
+# [5.2.0](https://github.com/speclynx/apidom/compare/v5.1.1...v5.2.0) (2026-08-29)
+
+**Note:** Version bump only for package @speclynx/apidom-overlay
+
+## [5.1.1](https://github.com/speclynx/apidom/compare/v5.1.0...v5.1.1) (2026-08-19)
+
+### Bug Fixes
+
+- **overlay:** apply root-target updates in place ([da41593](https://github.com/speclynx/apidom/commit/da4159322ba53af8595628ae74e11285c8272915)), closes [#471](https://github.com/speclynx/apidom/issues/471)
+- **overlay:** clone the parse result under immutable apply ([203d2b5](https://github.com/speclynx/apidom/commit/203d2b53323d9b6d9a77e6b180de005600b067e6)), closes [#475](https://github.com/speclynx/apidom/issues/475)
+- **overlay:** clone update value per matched target ([cb98f2b](https://github.com/speclynx/apidom/commit/cb98f2b68a6b1a0831b608f7734895a164b97f0b)), closes [#460](https://github.com/speclynx/apidom/issues/460)
+- **overlay:** clone update values emitted by diff ([31b8db9](https://github.com/speclynx/apidom/commit/31b8db9205636a2c79c27a64e57c5da4ba9a14fb)), closes [#469](https://github.com/speclynx/apidom/issues/469)
+- **overlay:** honour the immutable default for partial options ([5730aed](https://github.com/speclynx/apidom/commit/5730aedd7c21b256dc41e8f408a36fbf4f09d01a))
+- **overlay:** restore the result marker after a root replacement ([#482](https://github.com/speclynx/apidom/issues/482)) ([9227cfc](https://github.com/speclynx/apidom/commit/9227cfc5a287b1d63afb704df4906d41c4984d99)), closes [#481](https://github.com/speclynx/apidom/issues/481)
+- **overlay:** return an independent tree from no-op apply ([eb545b8](https://github.com/speclynx/apidom/commit/eb545b8eb53214102d2cbe3975efead1974e6bd5)), closes [#470](https://github.com/speclynx/apidom/issues/470)
+- **overlay:** snapshot copy source before updating targets ([bb6ee06](https://github.com/speclynx/apidom/commit/bb6ee06937a6fa296eb6e29dcab1cf6e5c1f9106)), closes [#470](https://github.com/speclynx/apidom/issues/470)
+
+### Performance Improvements
+
+- **overlay:** skip the throwaway clone in the POJO realm ([07c5a81](https://github.com/speclynx/apidom/commit/07c5a818d874f4d492fe8a958bf495351c54b625))
+
 # [5.1.0](https://github.com/speclynx/apidom/compare/v5.0.2...v5.1.0) (2026-08-09)
 
 **Note:** Version bump only for package @speclynx/apidom-overlay

package/README.md

@@ -38,7 +38,9 @@ const yaml = toYAML(result.api, { preserveStyle: true });
 ### Applying to ApiDOM elements
 
 `applyOverlayApiDOM` applies an entire overlay document to a target element. Accepts `Overlay1Element`
-or `ParseResultElement`. Immutable by default — returns a new element.
+or `ParseResultElement`. Immutable by default. Returns a new element, even when no action
+changes anything. When the target is a `ParseResultElement`, a new parse result is returned
+and the one passed in is left untouched.
 
 ```js
 import { refract } from '@speclynx/apidom-datamodel';
@@ -200,7 +202,6 @@ The diff walks both element trees recursively and generates [JSONPath (RFC 9535)
 | Root structural type change | Throws `OverlayError`. Overlay has no mechanism to replace the root node. |
 | Array insert-at-position | Overlay 1.x has no insert primitive. Positional diffing cascades replacements + appends, which is always correct but may be verbose for large array reorderings. |
 | Array item structural type change | Handled via tail-reconstruct: items from the first type-mismatched index onward are removed and re-appended. Always correct, but produces more actions than a minimal diff. |
-| Shared element references | Action `update` values reference elements from the right document directly. Mutating the right document after calling `diff` will affect the returned overlay. |
 | Reverse diff | The overlay carries no "before" value. It cannot be reversed without the original document. |
 
 ## Overlay spec semantics
@@ -283,7 +284,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. |
+| `immutable` | `boolean` | `true`<br>(`false` in `applyOverlay`) | When `true`, the target is cloned once up front and actions are applied to the clone, so the returned element is always independent of the input, including when no action changes anything. For a `ParseResultElement` target the new parse result shares the children no action can reach, such as annotations. Set to `false` for in-place mutation. The one case that cannot be applied in place is a `target: $` action replacing a primitive root with a differently typed value — there the return value is the only carrier, so always use it. |
 | `trace` | `OverlayTrace` | — | When provided, populated in place with action-by-action trace data. See [Tracing](#tracing). |
 
 ### ApplyOverlayOptions