@speclynx/apidom-overlay 4.6.0 → 4.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-overlay",
-  "version": "4.6.0",
+  "version": "4.7.0",
   "description": "Apply Overlay 1.x.y documents to API definitions.",
   "keywords": [
     "apidom",
@@ -53,12 +53,13 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.28.4",
-    "@speclynx/apidom-core": "4.6.0",
-    "@speclynx/apidom-datamodel": "4.6.0",
-    "@speclynx/apidom-error": "4.6.0",
-    "@speclynx/apidom-json-path": "4.6.0",
-    "@speclynx/apidom-ns-overlay-1": "4.6.0",
-    "@speclynx/apidom-reference": "4.6.0"
+    "@speclynx/apidom-core": "4.7.0",
+    "@speclynx/apidom-datamodel": "4.7.0",
+    "@speclynx/apidom-error": "4.7.0",
+    "@speclynx/apidom-json-path": "4.7.0",
+    "@speclynx/apidom-ns-overlay-1": "4.7.0",
+    "@speclynx/apidom-reference": "4.7.0",
+    "type-fest": "^5.5.0"
   },
   "files": [
     "src/**/*.mjs",
@@ -70,5 +71,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "c3cec30492f0e186ffdc7b1a761a016dab98b9d4"
+  "gitHead": "5afe50e432d90185f514e91bb35319aa4e23ba7b"
 }

package/src/apply/realms/apidom.cjs

@@ -278,10 +278,10 @@ const applyOverlay = (overlayElement, targetElement, options = defaultApplyOptio
   }
   let target;
   if (targetElement instanceof _apidomDatamodel.ParseResultElement) {
-    if (targetElement.api === undefined) {
-      throw new _OverlayError.default('Target ParseResultElement contains no API element');
+    if (targetElement.result === undefined) {
+      throw new _OverlayError.default('Target ParseResultElement contains no result element');
     }
-    target = targetElement.api;
+    target = targetElement.result;
   } else {
     target = targetElement;
   }
@@ -297,7 +297,9 @@ const applyOverlay = (overlayElement, targetElement, options = defaultApplyOptio
     target = applyAction(action, target, internalOptions);
   }
   if (targetElement instanceof _apidomDatamodel.ParseResultElement) {
-    targetElement.replaceResult(target);
+    if (target !== targetElement.result) {
+      targetElement.replaceResult(target);
+    }
     return targetElement;
   }
   return target;

package/src/apply/realms/apidom.mjs

@@ -267,10 +267,10 @@ export const applyOverlay = (overlayElement, targetElement, options = defaultApp
   }
   let target;
   if (targetElement instanceof ParseResultElement) {
-    if (targetElement.api === undefined) {
-      throw new OverlayError('Target ParseResultElement contains no API element');
+    if (targetElement.result === undefined) {
+      throw new OverlayError('Target ParseResultElement contains no result element');
     }
-    target = targetElement.api;
+    target = targetElement.result;
   } else {
     target = targetElement;
   }
@@ -286,7 +286,9 @@ export const applyOverlay = (overlayElement, targetElement, options = defaultApp
     target = applyAction(action, target, internalOptions);
   }
   if (targetElement instanceof ParseResultElement) {
-    targetElement.replaceResult(target);
+    if (target !== targetElement.result) {
+      targetElement.replaceResult(target);
+    }
     return targetElement;
   }
   return target;

package/src/apply/realms/uri.cjs

@@ -2,7 +2,7 @@
 
 var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
 exports.__esModule = true;
-exports.default = void 0;
+exports.defaultOptions = exports.default = void 0;
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
 var _apidomNsOverlay = require("@speclynx/apidom-ns-overlay-1");
 var _apidomReference = require("@speclynx/apidom-reference");
@@ -12,7 +12,7 @@ var _OverlayError = _interopRequireDefault(require("../../errors/OverlayError.cj
  * @public
  */
 
-const defaultOptions = {
+const defaultReferenceOptions = {
   parse: {
     parserOpts: {
       strict: false,
@@ -36,6 +36,15 @@ const defaultOptions = {
   }
 };
 
+/**
+ * @public
+ */
+const defaultOptions = exports.defaultOptions = {
+  immutable: false,
+  strict: false,
+  reference: defaultReferenceOptions
+};
+
 /**
  * Applies an overlay document from a file/URL to its target document.
  *
@@ -45,27 +54,23 @@ const defaultOptions = {
  *
  * @param overlayURI - URI to the overlay document (file path or URL)
  * @param targetURI - URI to the target document; if omitted, uses the overlay's `extends` field
- * @param options - apidom-reference options + overlay merge options
+ * @param options - overlay apply options; reference options live under `options.reference`
  * @returns ParseResultElement with the modified target document
  *
  * @public
  */
-const applyOverlay = async (overlayURI, targetURI, options = {
-  immutable: false,
-  strict: false
-}) => {
-  const mergedOptions = (0, _apidomReference.mergeOptions)(defaultOptions, options);
+const applyOverlay = async (overlayURI, targetURI, options = defaultOptions) => {
+  const mergedRefOptions = (0, _apidomReference.mergeOptions)(defaultReferenceOptions, options.reference ?? {});
 
   // parse the overlay document along with document attached to `extends` field (if present)
-  const overlayParseResult = await (0, _apidomReference.parse)(overlayURI, mergedOptions);
+  const overlayParseResult = await (0, _apidomReference.parse)(overlayURI, mergedRefOptions);
   const overlayElement = overlayParseResult.api;
   if (!(0, _apidomNsOverlay.isOverlay1Element)(overlayElement)) {
     throw new _OverlayError.default(`Failed to parse overlay document "${overlayURI}"`);
   }
   let targetParseResult;
   if (targetURI) {
-    const targetOptions = (0, _apidomReference.mergeOptions)(defaultOptions, options);
-    targetParseResult = await (0, _apidomReference.parse)(targetURI, targetOptions);
+    targetParseResult = await (0, _apidomReference.parse)(targetURI, mergedRefOptions);
   } else {
     const extendsElement = overlayElement.get('extends');
     targetParseResult = extendsElement?.meta?.get('parseResult');

package/src/apply/realms/uri.mjs

@@ -6,7 +6,7 @@ import OverlayError from "../../errors/OverlayError.mjs";
 /**
  * @public
  */
-const defaultOptions = {
+const defaultReferenceOptions = {
   parse: {
     parserOpts: {
       strict: false,
@@ -30,6 +30,15 @@ const defaultOptions = {
   }
 };
 
+/**
+ * @public
+ */
+export const defaultOptions = {
+  immutable: false,
+  strict: false,
+  reference: defaultReferenceOptions
+};
+
 /**
  * Applies an overlay document from a file/URL to its target document.
  *
@@ -39,27 +48,23 @@ const defaultOptions = {
  *
  * @param overlayURI - URI to the overlay document (file path or URL)
  * @param targetURI - URI to the target document; if omitted, uses the overlay's `extends` field
- * @param options - apidom-reference options + overlay merge options
+ * @param options - overlay apply options; reference options live under `options.reference`
  * @returns ParseResultElement with the modified target document
  *
  * @public
  */
-const applyOverlay = async (overlayURI, targetURI, options = {
-  immutable: false,
-  strict: false
-}) => {
-  const mergedOptions = mergeOptions(defaultOptions, options);
+const applyOverlay = async (overlayURI, targetURI, options = defaultOptions) => {
+  const mergedRefOptions = mergeOptions(defaultReferenceOptions, options.reference ?? {});
 
   // parse the overlay document along with document attached to `extends` field (if present)
-  const overlayParseResult = await parse(overlayURI, mergedOptions);
+  const overlayParseResult = await parse(overlayURI, mergedRefOptions);
   const overlayElement = overlayParseResult.api;
   if (!isOverlay1Element(overlayElement)) {
     throw new OverlayError(`Failed to parse overlay document "${overlayURI}"`);
   }
   let targetParseResult;
   if (targetURI) {
-    const targetOptions = mergeOptions(defaultOptions, options);
-    targetParseResult = await parse(targetURI, targetOptions);
+    targetParseResult = await parse(targetURI, mergedRefOptions);
   } else {
     const extendsElement = overlayElement.get('extends');
     targetParseResult = extendsElement?.meta?.get('parseResult');

package/src/index.cjs

@@ -1,13 +1,15 @@
 "use strict";
 
 var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
 exports.__esModule = true;
-exports.validateAction = exports.applyOverlayPOJO = exports.applyOverlayApiDOM = exports.applyOverlay = exports.applyActionPOJO = exports.applyActionApiDOM = exports.OverlayError = void 0;
+exports.validateAction = exports.defaultApplyOverlayOptions = exports.applyOverlayPOJO = exports.applyOverlayApiDOM = exports.applyOverlay = exports.applyActionPOJO = exports.applyActionApiDOM = exports.OverlayError = void 0;
 var _apidom = require("./apply/realms/apidom.cjs");
 exports.applyActionApiDOM = _apidom.applyAction;
 exports.applyOverlayApiDOM = _apidom.applyOverlay;
-var _uri = _interopRequireDefault(require("./apply/realms/uri.cjs"));
+var _uri = _interopRequireWildcard(require("./apply/realms/uri.cjs"));
 exports.applyOverlay = _uri.default;
+exports.defaultApplyOverlayOptions = _uri.defaultOptions;
 var _pojo = require("./apply/realms/pojo.cjs");
 exports.applyActionPOJO = _pojo.applyAction;
 exports.applyOverlayPOJO = _pojo.applyOverlay;

package/src/index.mjs

@@ -1,5 +1,5 @@
 export { applyAction as applyActionApiDOM, applyOverlay as applyOverlayApiDOM } from "./apply/realms/apidom.mjs";
-export { default as applyOverlay } from "./apply/realms/uri.mjs";
+export { default as applyOverlay, defaultOptions as defaultApplyOverlayOptions } from "./apply/realms/uri.mjs";
 export { applyAction as applyActionPOJO, applyOverlay as applyOverlayPOJO } from "./apply/realms/pojo.mjs";
 export { validateAction } from "./validate.mjs";
 export { default as OverlayError } from "./errors/OverlayError.mjs";

package/types/apidom-overlay.d.ts

@@ -6,6 +6,7 @@ import { Element as Element_2 } from '@speclynx/apidom-datamodel';
 import { MemberElement } from '@speclynx/apidom-datamodel';
 import { Overlay1Element } from '@speclynx/apidom-ns-overlay-1';
 import { ParseResultElement } from '@speclynx/apidom-datamodel';
+import type { PartialDeep } from 'type-fest';
 
 /**
  * Trace entry for a single overlay action application.
@@ -60,7 +61,7 @@ export declare interface ApplyOptions {
  *
  * @param overlayURI - URI to the overlay document (file path or URL)
  * @param targetURI - URI to the target document; if omitted, uses the overlay's `extends` field
- * @param options - apidom-reference options + overlay merge options
+ * @param options - overlay apply options; reference options live under `options.reference`
  * @returns ParseResultElement with the modified target document
  *
  * @public
@@ -78,7 +79,8 @@ export declare const applyOverlayApiDOM: <T extends Element_2 | ParseResultEleme
 /**
  * @public
  */
-export declare interface ApplyOverlayOptions extends Partial<ApiDOMReferenceOptions>, ApplyOptions {
+export declare interface ApplyOverlayOptions extends ApplyOptions {
+    readonly reference?: PartialDeep<ApiDOMReferenceOptions>;
 }
 
 /**
@@ -88,6 +90,11 @@ export declare interface ApplyOverlayOptions extends Partial<ApiDOMReferenceOpti
  */
 export declare const applyOverlayPOJO: (overlay: Record<string, unknown>, target: Record<string, unknown>, options?: ApplyOptions) => unknown;
 
+/**
+ * @public
+ */
+export declare const defaultApplyOverlayOptions: ApplyOverlayOptions;
+
 /**
  * @public
  */