@speclynx/apidom-overlay 5.2.7 → 6.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-overlay",
-  "version": "5.2.7",
+  "version": "6.0.1",
   "description": "Apply Overlay 1.x.y documents to API definitions.",
   "keywords": [
     "apidom",
@@ -53,12 +53,12 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^8.0.5",
-    "@speclynx/apidom-core": "5.2.7",
-    "@speclynx/apidom-datamodel": "5.2.7",
-    "@speclynx/apidom-error": "5.2.7",
-    "@speclynx/apidom-json-path": "5.2.7",
-    "@speclynx/apidom-ns-overlay-1": "5.2.7",
-    "@speclynx/apidom-reference": "5.2.7",
+    "@speclynx/apidom-core": "6.0.1",
+    "@speclynx/apidom-datamodel": "6.0.1",
+    "@speclynx/apidom-error": "6.0.1",
+    "@speclynx/apidom-json-path": "6.0.1",
+    "@speclynx/apidom-ns-overlay-1": "6.0.1",
+    "@speclynx/apidom-reference": "6.0.1",
     "type-fest": "^5.10.0"
   },
   "files": [
@@ -71,5 +71,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "e99285824ceb947024c97a13c7827843efdaa9e0"
+  "gitHead": "d2ea4f01cac54a0d5e1030386e3b0b60664c9619"
 }

package/src/apply/realms/apidom.cjs

@@ -9,6 +9,7 @@ var _apidomDatamodel = require("@speclynx/apidom-datamodel");
 var _apidomCore = require("@speclynx/apidom-core");
 var _apidomJsonPath = require("@speclynx/apidom-json-path");
 var _apidomNsOverlay = require("@speclynx/apidom-ns-overlay-1");
+var _apidomReference = require("@speclynx/apidom-reference");
 var _OverlayError = _interopRequireDefault(require("../../errors/OverlayError.cjs"));
 var _validate = require("../../validate.cjs");
 var _TraceBuilder = _interopRequireDefault(require("../trace/TraceBuilder.cjs"));
@@ -16,6 +17,10 @@ var _TraceBuilder = _interopRequireDefault(require("../trace/TraceBuilder.cjs"))
  * @public
  */
 
+/**
+ * @public
+ */
+
 /**
  * Internal options that carry the tracer instance.
  */
@@ -342,14 +347,44 @@ const applyAction = (actionElement, targetElement, options = defaultApplyOptions
  * Under `immutable: false` the caller's parse result is updated in place
  * instead, with its result element replaced by the new tree.
  *
+ * The overlay is dereferenced first (`options.reference` configures
+ * `@speclynx/apidom-reference`), so Reusable Action References are applied as
+ * the Action Objects they resolve to. The overlay itself is never mutated.
+ *
  * @public
  */
 exports.applyAction = applyAction;
-const applyOverlay = (overlayElement, targetElement, options = defaultApplyOptions) => {
+const applyOverlay = async (overlayElement, targetElement, options = defaultApplyOptions) => {
   const overlay = overlayElement instanceof _apidomDatamodel.ParseResultElement ? overlayElement.api : overlayElement;
   if (!(0, _apidomNsOverlay.isOverlay1Element)(overlay)) {
     throw new _OverlayError.default('First argument must be an Overlay 1.x document');
   }
+
+  /**
+   * References (Overlay 1.2.0) are resolved by dereferencing before the target is
+   * touched, so an unresolvable reference fails the overlay without applying any action.
+   */
+  let dereferencedOverlay;
+  try {
+    // always immutable: dereferencing must never modify the caller's overlay
+    dereferencedOverlay = await (0, _apidomReference.dereferenceApiDOM)(overlay, {
+      ...options.reference,
+      dereference: {
+        ...options.reference?.dereference,
+        immutable: true
+      }
+    });
+  } catch (error) {
+    throw new _OverlayError.default(error.message, {
+      cause: error
+    });
+  }
+
+  // references left in place (`continueOnError`, `resolve.internal: false`) cannot be applied
+  const unresolvedReference = (0, _apidomDatamodel.isArrayElement)(dereferencedOverlay.actions) ? dereferencedOverlay.actions.content.find(_apidomNsOverlay.isReusableActionReferenceElement) : undefined;
+  if ((0, _apidomNsOverlay.isReusableActionReferenceElement)(unresolvedReference)) {
+    throw new _OverlayError.default(`Overlay contains unresolved Reusable Action Reference "${(0, _apidomCore.toValue)(unresolvedReference.$ref)}"`);
+  }
   const opts = withDefaults(options);
   let parseResult;
   let resultElement;
@@ -387,8 +422,8 @@ const applyOverlay = (overlayElement, targetElement, options = defaultApplyOptio
     ...internalOptions,
     immutable: false
   };
-  if ((0, _apidomDatamodel.isArrayElement)(overlay.actions)) {
-    for (const action of overlay.actions) {
+  if ((0, _apidomDatamodel.isArrayElement)(dereferencedOverlay.actions)) {
+    for (const action of dereferencedOverlay.actions) {
       target = applyAction(action, target, mutatingOptions);
     }
   }

package/src/apply/realms/apidom.mjs

@@ -1,10 +1,14 @@
 import { isObjectElement, isArrayElement, includesClasses, cloneDeep, cloneShallow, ParseResultElement } from '@speclynx/apidom-datamodel';
 import { deepmerge, toValue } from '@speclynx/apidom-core';
 import { evaluate, NormalizedPath } from '@speclynx/apidom-json-path';
-import { isOverlay1Element } from '@speclynx/apidom-ns-overlay-1';
+import { isOverlay1Element, isReusableActionReferenceElement } from '@speclynx/apidom-ns-overlay-1';
+import { dereferenceApiDOM } from '@speclynx/apidom-reference';
 import OverlayError from "../../errors/OverlayError.mjs";
 import { validateAction, validateTargetNodes } from "../../validate.mjs";
 import TraceBuilder from "../trace/TraceBuilder.mjs";
+/**
+ * @public
+ */
 /**
  * @public
  */
@@ -330,13 +334,43 @@ export const applyAction = (actionElement, targetElement, options = defaultApply
  * Under `immutable: false` the caller's parse result is updated in place
  * instead, with its result element replaced by the new tree.
  *
+ * The overlay is dereferenced first (`options.reference` configures
+ * `@speclynx/apidom-reference`), so Reusable Action References are applied as
+ * the Action Objects they resolve to. The overlay itself is never mutated.
+ *
  * @public
  */
-export const applyOverlay = (overlayElement, targetElement, options = defaultApplyOptions) => {
+export const applyOverlay = async (overlayElement, targetElement, options = defaultApplyOptions) => {
   const overlay = overlayElement instanceof ParseResultElement ? overlayElement.api : overlayElement;
   if (!isOverlay1Element(overlay)) {
     throw new OverlayError('First argument must be an Overlay 1.x document');
   }
+
+  /**
+   * References (Overlay 1.2.0) are resolved by dereferencing before the target is
+   * touched, so an unresolvable reference fails the overlay without applying any action.
+   */
+  let dereferencedOverlay;
+  try {
+    // always immutable: dereferencing must never modify the caller's overlay
+    dereferencedOverlay = await dereferenceApiDOM(overlay, {
+      ...options.reference,
+      dereference: {
+        ...options.reference?.dereference,
+        immutable: true
+      }
+    });
+  } catch (error) {
+    throw new OverlayError(error.message, {
+      cause: error
+    });
+  }
+
+  // references left in place (`continueOnError`, `resolve.internal: false`) cannot be applied
+  const unresolvedReference = isArrayElement(dereferencedOverlay.actions) ? dereferencedOverlay.actions.content.find(isReusableActionReferenceElement) : undefined;
+  if (isReusableActionReferenceElement(unresolvedReference)) {
+    throw new OverlayError(`Overlay contains unresolved Reusable Action Reference "${toValue(unresolvedReference.$ref)}"`);
+  }
   const opts = withDefaults(options);
   let parseResult;
   let resultElement;
@@ -374,8 +408,8 @@ export const applyOverlay = (overlayElement, targetElement, options = defaultApp
     ...internalOptions,
     immutable: false
   };
-  if (isArrayElement(overlay.actions)) {
-    for (const action of overlay.actions) {
+  if (isArrayElement(dereferencedOverlay.actions)) {
+    for (const action of dereferencedOverlay.actions) {
       target = applyAction(action, target, mutatingOptions);
     }
   }

package/src/apply/realms/pojo.cjs

@@ -30,7 +30,7 @@ const applyAction = (action, target, options) => (0, _apidomCore.toValue)((0, _a
  * @public
  */
 exports.applyAction = applyAction;
-const applyOverlay = (overlay, target, options) => (0, _apidomCore.toValue)((0, _apidom.applyOverlay)((0, _apidomNsOverlay.refractOverlay1)(overlay), (0, _apidomDatamodel.refract)(target), {
+const applyOverlay = async (overlay, target, options) => (0, _apidomCore.toValue)(await (0, _apidom.applyOverlay)((0, _apidomNsOverlay.refractOverlay1)(overlay), (0, _apidomDatamodel.refract)(target), {
   ...options,
   immutable: false
 }));

package/src/apply/realms/pojo.mjs

@@ -23,7 +23,7 @@ export const applyAction = (action, target, options) => toValue(applyActionApiDO
  *
  * @public
  */
-export const applyOverlay = (overlay, target, options) => toValue(applyOverlayApiDOM(refractOverlay1(overlay), refract(target), {
+export const applyOverlay = async (overlay, target, options) => toValue(await applyOverlayApiDOM(refractOverlay1(overlay), refract(target), {
   ...options,
   immutable: false
 }));

package/src/apply/realms/uri.cjs

@@ -10,10 +10,6 @@ var _apidomNsOverlay = require("@speclynx/apidom-ns-overlay-1");
 var _apidomReference = require("@speclynx/apidom-reference");
 var _apidom = require("./apidom.cjs");
 var _OverlayError = _interopRequireDefault(require("../../errors/OverlayError.cjs"));
-/**
- * @public
- */
-
 const defaultReferenceOptions = {
   parse: {
     parserOpts: {
@@ -84,7 +80,15 @@ const applyOverlay = async (overlayURI, targetURI, options = defaultOptions) =>
   // 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
+    immutable: options.immutable ?? defaultOptions.immutable,
+    reference: {
+      ...options.reference,
+      // same normalization `parse` applies, so reference errors report the parsed document's URI
+      resolve: {
+        ...options.reference?.resolve,
+        baseURI: _apidomReference.url.sanitize(_apidomReference.url.stripHash(overlayURI))
+      }
+    }
   });
 };
 var _default = exports.default = applyOverlay;

package/src/apply/realms/uri.mjs

@@ -1,11 +1,8 @@
 import { isParseResultElement } from '@speclynx/apidom-datamodel';
 import { isOverlay1Element } from '@speclynx/apidom-ns-overlay-1';
-import { parse, mergeOptions } from '@speclynx/apidom-reference';
+import { parse, mergeOptions, url } from '@speclynx/apidom-reference';
 import { applyOverlay as applyOverlayApiDOM } from "./apidom.mjs";
 import OverlayError from "../../errors/OverlayError.mjs";
-/**
- * @public
- */
 const defaultReferenceOptions = {
   parse: {
     parserOpts: {
@@ -76,7 +73,15 @@ const applyOverlay = async (overlayURI, targetURI, options = defaultOptions) =>
   // apply overlay actions to the target (mutable by default: targetParseResult with result replaced)
   return applyOverlayApiDOM(overlayParseResult, targetParseResult, {
     ...options,
-    immutable: options.immutable ?? defaultOptions.immutable
+    immutable: options.immutable ?? defaultOptions.immutable,
+    reference: {
+      ...options.reference,
+      // same normalization `parse` applies, so reference errors report the parsed document's URI
+      resolve: {
+        ...options.reference?.resolve,
+        baseURI: url.sanitize(url.stripHash(overlayURI))
+      }
+    }
   });
 };
 export default applyOverlay;

package/src/diff/realms/apidom.cjs

@@ -14,7 +14,7 @@ var _OverlayError = _interopRequireDefault(require("../../errors/OverlayError.cj
  */
 
 const defaultDiffOptions = {
-  overlay: '1.1.0',
+  overlay: '1.2.0',
   info: {
     title: 'API diff',
     version: '0.0.0'
@@ -143,7 +143,7 @@ const diffArrays = (left, right, segments, actions) => {
  * Produces an {@link Overlay1Element} that, when applied to `leftElement`, yields `rightElement`.
  *
  * Known limitations:
- * - Identical documents produce an overlay with an empty `actions` array. Overlay 1.1.0 §3
+ * - Identical documents produce an overlay with an empty `actions` array. Overlay 1.x §3
  *   requires `actions` to be non-empty; callers should guard against the no-diff case.
  * - Root-level structural type change (e.g. object root → array root) throws {@link OverlayError}
  *   because Overlay has no mechanism to replace the root node.

package/src/diff/realms/apidom.mjs

@@ -6,7 +6,7 @@ import OverlayError from "../../errors/OverlayError.mjs";
  * @public
  */
 const defaultDiffOptions = {
-  overlay: '1.1.0',
+  overlay: '1.2.0',
   info: {
     title: 'API diff',
     version: '0.0.0'
@@ -135,7 +135,7 @@ const diffArrays = (left, right, segments, actions) => {
  * Produces an {@link Overlay1Element} that, when applied to `leftElement`, yields `rightElement`.
  *
  * Known limitations:
- * - Identical documents produce an overlay with an empty `actions` array. Overlay 1.1.0 §3
+ * - Identical documents produce an overlay with an empty `actions` array. Overlay 1.x §3
  *   requires `actions` to be non-empty; callers should guard against the no-diff case.
  * - Root-level structural type change (e.g. object root → array root) throws {@link OverlayError}
  *   because Overlay has no mechanism to replace the root node.

package/types/apidom-overlay.d.ts

@@ -96,9 +96,13 @@ export declare const applyOverlay: (overlayURI: string, targetURI?: string, opti
  * Under `immutable: false` the caller's parse result is updated in place
  * instead, with its result element replaced by the new tree.
  *
+ * The overlay is dereferenced first (`options.reference` configures
+ * `@speclynx/apidom-reference`), so Reusable Action References are applied as
+ * the Action Objects they resolve to. The overlay itself is never mutated.
+ *
  * @public
  */
-export declare const applyOverlayApiDOM: <T extends Element_2 | ParseResultElement>(overlayElement: Overlay1Element | ParseResultElement, targetElement: T, options?: ApplyOptions) => T;
+export declare const applyOverlayApiDOM: <T extends Element_2 | ParseResultElement>(overlayElement: Overlay1Element | ParseResultElement, targetElement: T, options?: ApplyOverlayOptions) => Promise<T>;
 
 /**
  * @public
@@ -115,7 +119,7 @@ export declare interface ApplyOverlayOptions extends ApplyOptions {
  *
  * @public
  */
-export declare const applyOverlayPOJO: (overlay: Record<string, unknown>, target: Record<string, unknown>, options?: ApplyOptions) => unknown;
+export declare const applyOverlayPOJO: (overlay: Record<string, unknown>, target: Record<string, unknown>, options?: ApplyOverlayOptions) => Promise<unknown>;
 
 /**
  * @public
@@ -131,7 +135,7 @@ export declare const defaultDiffOverlayOptions: DiffOverlayOptions;
  * Produces an {@link Overlay1Element} that, when applied to `leftElement`, yields `rightElement`.
  *
  * Known limitations:
- * - Identical documents produce an overlay with an empty `actions` array. Overlay 1.1.0 §3
+ * - Identical documents produce an overlay with an empty `actions` array. Overlay 1.x §3
  *   requires `actions` to be non-empty; callers should guard against the no-diff case.
  * - Root-level structural type change (e.g. object root → array root) throws {@link OverlayError}
  *   because Overlay has no mechanism to replace the root node.