@speclynx/apidom-overlay 4.6.0 → 4.7.0

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [4.7.0](https://github.com/speclynx/apidom/compare/v4.6.0...v4.7.0) (2026-04-12)
+
+### Features
+
+- **overlay:** generic targets, export defaults, scoped opts ([#236](https://github.com/speclynx/apidom/issues/236)) ([7df6dc7](https://github.com/speclynx/apidom/commit/7df6dc79d18e4c71ceb17037a45f9ba069fdcaf1))
+
 # [4.6.0](https://github.com/speclynx/apidom/compare/v4.5.0...v4.6.0) (2026-04-12)
 
 ### Features

package/dist/apidom-overlay.browser.js

@@ -306,10 +306,10 @@ const applyOverlay = (overlayElement, targetElement, options = defaultApplyOptio
   }
   let target;
   if (targetElement instanceof _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"]) {
-    if (targetElement.api === undefined) {
-      throw new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_8__["default"]('Target ParseResultElement contains no API element');
+    if (targetElement.result === undefined) {
+      throw new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_8__["default"]('Target ParseResultElement contains no result element');
     }
-    target = targetElement.api;
+    target = targetElement.result;
   } else {
     target = targetElement;
   }
@@ -325,7 +325,9 @@ const applyOverlay = (overlayElement, targetElement, options = defaultApplyOptio
     target = applyAction(action, target, internalOptions);
   }
   if (targetElement instanceof _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"]) {
-    targetElement.replaceResult(target);
+    if (target !== targetElement.result) {
+      targetElement.replaceResult(target);
+    }
     return targetElement;
   }
   return target;
@@ -373,7 +375,8 @@ const applyOverlay = (overlay, target, options) => (0,_speclynx_apidom_core__WEB
 "use strict";
 __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
-/* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__)
+/* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__),
+/* harmony export */   defaultOptions: () => (/* binding */ defaultOptions)
 /* harmony export */ });
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(96911);
 /* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(26432);
@@ -390,7 +393,7 @@ __webpack_require__.r(__webpack_exports__);
  * @public
  */
 
-const defaultOptions = {
+const defaultReferenceOptions = {
   parse: {
     parserOpts: {
       strict: false,
@@ -414,6 +417,15 @@ const defaultOptions = {
   }
 };
 
+/**
+ * @public
+ */
+const defaultOptions = {
+  immutable: false,
+  strict: false,
+  reference: defaultReferenceOptions
+};
+
 /**
  * Applies an overlay document from a file/URL to its target document.
  *
@@ -423,27 +435,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,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.mergeOptions)(defaultOptions, options);
+const applyOverlay = async (overlayURI, targetURI, options = defaultOptions) => {
+  const mergedRefOptions = (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.mergeOptions)(defaultReferenceOptions, options.reference ?? {});
 
   // parse the overlay document along with document attached to `extends` field (if present)
-  const overlayParseResult = await (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.parse)(overlayURI, mergedOptions);
+  const overlayParseResult = await (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.parse)(overlayURI, mergedRefOptions);
   const overlayElement = overlayParseResult.api;
   if (!(0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_1__.isOverlay1Element)(overlayElement)) {
     throw new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_4__["default"](`Failed to parse overlay document "${overlayURI}"`);
   }
   let targetParseResult;
   if (targetURI) {
-    const targetOptions = (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.mergeOptions)(defaultOptions, options);
-    targetParseResult = await (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.parse)(targetURI, targetOptions);
+    targetParseResult = await (0,_speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__.parse)(targetURI, mergedRefOptions);
   } else {
     const extendsElement = overlayElement.get('extends');
     targetParseResult = extendsElement?.meta?.get('parseResult');
@@ -101017,6 +101025,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   applyOverlay: () => (/* reexport safe */ _apply_realms_uri_ts__WEBPACK_IMPORTED_MODULE_1__["default"]),
 /* harmony export */   applyOverlayApiDOM: () => (/* reexport safe */ _apply_realms_apidom_ts__WEBPACK_IMPORTED_MODULE_0__.applyOverlay),
 /* harmony export */   applyOverlayPOJO: () => (/* reexport safe */ _apply_realms_pojo_ts__WEBPACK_IMPORTED_MODULE_2__.applyOverlay),
+/* harmony export */   defaultApplyOverlayOptions: () => (/* reexport safe */ _apply_realms_uri_ts__WEBPACK_IMPORTED_MODULE_1__.defaultOptions),
 /* harmony export */   validateAction: () => (/* reexport safe */ _validate_ts__WEBPACK_IMPORTED_MODULE_3__.validateAction)
 /* harmony export */ });
 /* harmony import */ var _apply_realms_apidom_ts__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(28216);