@speclynx/apidom-overlay 5.2.7 → 6.0.6

package/CHANGELOG.md

@@ -3,6 +3,52 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [6.0.6](https://github.com/speclynx/apidom/compare/v6.0.5...v6.0.6) (2026-10-15)
+
+### Bug Fixes
+
+- **release:** pass sigstore timeout as a number via publishConfig ([#603](https://github.com/speclynx/apidom/issues/603)) ([3bb44d9](https://github.com/speclynx/apidom/commit/3bb44d9a924741a1f8bbbccebae9b6a2a7cd557b)), closes [#602](https://github.com/speclynx/apidom/issues/602) [#602](https://github.com/speclynx/apidom/issues/602)
+
+## [6.0.5](https://github.com/speclynx/apidom/compare/v6.0.4...v6.0.5) (2026-10-15)
+
+**Note:** Version bump only for package @speclynx/apidom-overlay
+
+## [6.0.4](https://github.com/speclynx/apidom/compare/v6.0.3...v6.0.4) (2026-10-15)
+
+**Note:** Version bump only for package @speclynx/apidom-overlay
+
+## [6.0.3](https://github.com/speclynx/apidom/compare/v6.0.2...v6.0.3) (2026-10-15)
+
+**Note:** Version bump only for package @speclynx/apidom-overlay
+
+## [6.0.2](https://github.com/speclynx/apidom/compare/v6.0.1...v6.0.2) (2026-10-15)
+
+**Note:** Version bump only for package @speclynx/apidom-overlay
+
+## [6.0.1](https://github.com/speclynx/apidom/compare/v6.0.0...v6.0.1) (2026-10-15)
+
+**Note:** Version bump only for package @speclynx/apidom-overlay
+
+# [6.0.0](https://github.com/speclynx/apidom/compare/v5.2.7...v6.0.0) (2026-10-15)
+
+### Bug Fixes
+
+- **overlay:** guard apply against reference options ([90a51c0](https://github.com/speclynx/apidom/commit/90a51c0d55b1446bab68d1b3cae07b2f352711b6))
+- **overlay:** normalize overlay URI used for dereferencing ([627fc01](https://github.com/speclynx/apidom/commit/627fc0177749dbcdccb3df2877f85c5f3770cc94))
+- **overlay:** trace unresolvable reusable action references ([28f66b6](https://github.com/speclynx/apidom/commit/28f66b63b185c65056f3dd0647721685b8fa5fa3))
+
+### Features
+
+- **overlay:** apply reusable action references ([3518793](https://github.com/speclynx/apidom/commit/35187935737810b65e7f15c0422a20bd409add91))
+- **overlay:** dereference overlays before applying them ([ad0b84b](https://github.com/speclynx/apidom/commit/ad0b84b4c0121403d8156a3f8521ccb4cf87bc44))
+- **overlay:** emit Overlay 1.2.0 from diff by default ([56fd656](https://github.com/speclynx/apidom/commit/56fd656fd4f3da97826d6be4dd534bdc29363f97))
+
+### BREAKING CHANGES
+
+- **overlay:** applyOverlayApiDOM and applyOverlayPOJO now return a
+  Promise. Await their results. The new `reference` option configures
+  dereferencing of the overlay.
+
 ## [5.2.7](https://github.com/speclynx/apidom/compare/v5.2.6...v5.2.7) (2026-10-13)
 
 **Note:** Version bump only for package @speclynx/apidom-overlay

package/README.md

@@ -1,8 +1,8 @@
 # @speclynx/apidom-overlay
 
-`@speclynx/apidom-overlay` applies [Overlay 1.x.y](https://spec.openapis.org/overlay/v1.1.0.html) documents to API definitions
+`@speclynx/apidom-overlay` applies [Overlay 1.x.y](https://spec.openapis.org/overlay/v1.2.0.html) documents to API definitions
 and can generate overlays by diffing two API documents.
-The [Overlay Specification](https://spec.openapis.org/overlay/v1.1.0.html) defines a mechanism for modifying
+The [Overlay Specification](https://spec.openapis.org/overlay/v1.2.0.html) defines a mechanism for modifying
 existing API documents without directly editing the original, using [JSONPath (RFC 9535)](https://www.rfc-editor.org/rfc/rfc9535.html)
 expressions to target specific nodes and apply updates, copies, or removals.
 
@@ -38,17 +38,22 @@ 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, even when no action
+or `ParseResultElement`. Immutable by default. Returns a promise of 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.
 
+All overlay-level functions (`applyOverlay`, `applyOverlayApiDOM` and `applyOverlayPOJO`) are asynchronous:
+the overlay is dereferenced with [@speclynx/apidom-reference](https://github.com/speclynx/apidom/tree/main/packages/apidom-reference)
+before any action is applied, so Overlay 1.2.0 Reusable Action References are applied as the Action Objects they resolve to.
+Applying a single action (`applyActionApiDOM`, `applyActionPOJO`) stays synchronous.
+
 ```js
 import { refract } from '@speclynx/apidom-datamodel';
 import { refractOverlay1 } from '@speclynx/apidom-ns-overlay-1';
 import { applyOverlayApiDOM } from '@speclynx/apidom-overlay';
 
 const overlay = refractOverlay1({
-  overlay: '1.1.0',
+  overlay: '1.2.0',
   info: { title: 'My overlay', version: '1.0.0' },
   actions: [
     { target: '$.info', update: { description: 'Added by overlay' } },
@@ -60,7 +65,7 @@ const target = refract({
   info: { title: 'Original', version: '1.0.0' },
 });
 
-const result = applyOverlayApiDOM(overlay, target);
+const result = await applyOverlayApiDOM(overlay, target);
 ```
 
 `applyActionApiDOM` applies a single overlay action. Useful for programmatic, step-by-step application.
@@ -88,9 +93,9 @@ no need to manually refract or serialize.
 import { applyOverlayPOJO, applyActionPOJO } from '@speclynx/apidom-overlay';
 
 // full overlay
-const result = applyOverlayPOJO(
+const result = await applyOverlayPOJO(
   {
-    overlay: '1.1.0',
+    overlay: '1.2.0',
     info: { title: 'My overlay', version: '1.0.0' },
     actions: [
       { target: '$.info.title', update: 'Renamed API' },
@@ -137,7 +142,7 @@ const overlay = diffApiDOM(left, right, {
 });
 
 // overlay is an Overlay1Element — serialize or apply it directly
-const updated = applyOverlayApiDOM(overlay, left);
+const updated = await applyOverlayApiDOM(overlay, left);
 console.log(toValue(updated)); // equals toValue(right)
 ```
 
@@ -150,7 +155,7 @@ const overlay = diffPOJO(
   { info: { title: 'Old', version: '1.0.0' } },
   { info: { title: 'New', version: '2.0.0' } },
 );
-// overlay is a plain object: { overlay: '1.1.0', info: {...}, actions: [...] }
+// overlay is a plain object: { overlay: '1.2.0', info: {...}, actions: [...] }
 ```
 
 `diffOverlay` parses two documents from file paths or URLs and returns an `Overlay1Element`.
@@ -179,7 +184,7 @@ const overlay = await diffOverlay(
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `overlay` | `string` | `'1.1.0'` | Version string written to the `overlay` field. Configurable because 1.0.0 and 1.1.0 have slightly different semantics. |
+| `overlay` | `string` | `'1.2.0'` | Version string written to the `overlay` field. Generated overlays use no 1.2.0-only features, so pass `'1.1.0'` (or `'1.0.0'`) to target an older version. |
 | `info.title` | `string` | `'API diff'` | Title for the generated overlay's `info` object. |
 | `info.version` | `string` | `'0.0.0'` | Version for the generated overlay's `info` object. |
 | `info.description` | `string` | — | Optional description for the overlay's `info` object. |
@@ -198,7 +203,7 @@ The diff walks both element trees recursively and generates [JSONPath (RFC 9535)
 
 | Limitation | Details |
 |---|---|
-| Empty actions on identical documents | By default, identical inputs produce an overlay with an empty `actions` array (Overlay 1.1.0 §3 requires non-empty). Use `onEmptyDiff: 'throw'` to turn this into an `OverlayError` instead. |
+| Empty actions on identical documents | By default, identical inputs produce an overlay with an empty `actions` array (Overlay 1.x §3 requires non-empty). Use `onEmptyDiff: 'throw'` to turn this into an `OverlayError` instead. |
 | 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. |
@@ -206,7 +211,7 @@ The diff walks both element trees recursively and generates [JSONPath (RFC 9535)
 
 ## Overlay spec semantics
 
-The implementation follows [Overlay 1.1.0](https://spec.openapis.org/overlay/v1.1.0.html) merge rules:
+The implementation follows [Overlay 1.2.0](https://spec.openapis.org/overlay/v1.2.0.html) merge rules:
 
 | Scenario | Behavior |
 |---|---|
@@ -218,6 +223,8 @@ The implementation follows [Overlay 1.1.0](https://spec.openapis.org/overlay/v1.
 | Multiple targets | All must be the same type (all objects, all arrays, or all primitives) |
 | `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 |
+| Reusable Action Reference | Resolved by dereferencing the overlay before any action is applied: the reference becomes the Action from `components.actions` of the same overlay, supplying `target`, and its `description` wins. Unresolvable references reject with `OverlayError` and no action is applied |
+| `$self` | When applying from file/URL, a relative `extends` is resolved against `$self` (itself resolved against the overlay's URI) |
 
 ## Tracing
 
@@ -229,7 +236,7 @@ information about every action applied.
 import { applyOverlayApiDOM } from '@speclynx/apidom-overlay';
 
 const trace = {};
-const result = applyOverlayApiDOM(overlay, target, { trace });
+const result = await applyOverlayApiDOM(overlay, target, { trace });
 
 console.log(trace.failed);   // false
 console.log(trace.message);  // 'Overlay was successfully applied'
@@ -248,7 +255,7 @@ When an action fails, the trace captures the error before it is re-thrown:
 ```js
 const trace = {};
 try {
-  applyOverlayApiDOM(overlay, target, { trace });
+  await applyOverlayApiDOM(overlay, target, { trace });
 } catch (error) {
   console.log(trace.failed);                // true
   console.log(trace.failedAt);              // index of the failed action
@@ -257,6 +264,10 @@ try {
 }
 ```
 
+`applyOverlay`, `applyOverlayApiDOM` and `applyOverlayPOJO` dereference the overlay before any action runs.
+If that fails, for example because of an unresolvable Reusable Action Reference, the promise rejects with
+`OverlayError` and the trace object is left untouched, since no action was attempted.
+
 Tracing works across all API levels — ApiDOM elements, file/URL, and POJO:
 
 ```js
@@ -271,7 +282,7 @@ await applyOverlay('/path/to/overlay.yaml', undefined, { trace });
 
 // POJO
 const trace = {};
-applyOverlayPOJO(overlay, target, { trace });
+await applyOverlayPOJO(overlay, target, { trace });
 ```
 
 ## Options
@@ -289,8 +300,11 @@ Passed to `applyActionApiDOM`, `applyOverlayApiDOM`, and `applyOverlay`:
 
 ### ApplyOverlayOptions
 
-Extends `ApplyOptions` with all [`@speclynx/apidom-reference` options](https://github.com/speclynx/apidom/blob/main/packages/apidom-reference/README.md)
-for controlling parsing, resolving, and dereferencing of the overlay and target documents.
+Passed to `applyOverlay`, `applyOverlayApiDOM`, and `applyOverlayPOJO`. Extends `ApplyOptions` with a `reference` field:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `reference` | `PartialDeep<ReferenceOptions>` | — | [`@speclynx/apidom-reference` options](https://github.com/speclynx/apidom/blob/main/packages/apidom-reference/README.md) for dereferencing the overlay (and, in `applyOverlay`, for parsing the overlay and target documents). |
 
 ### DiffOverlayOptions
 
@@ -298,7 +312,7 @@ Passed to `diffOverlay`. Extends `DiffOptions` with a `reference` field:
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `overlay` | `string` | `'1.1.0'` | Inherited from `DiffOptions`. See [DiffOptions](#diffoptions). |
+| `overlay` | `string` | `'1.2.0'` | Inherited from `DiffOptions`. See [DiffOptions](#diffoptions). |
 | `info` | `object` | — | Inherited from `DiffOptions`. |
 | `extends` | `string` | `leftURI` | When omitted, automatically set to `leftURI` so the overlay points back to the base document. |
 | `reference` | `PartialDeep<ReferenceOptions>` | — | [`@speclynx/apidom-reference` options](https://github.com/speclynx/apidom/blob/main/packages/apidom-reference/README.md) for parsing the left and right documents. |