@speclynx/apidom-overlay 4.6.0 → 4.7.1

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [4.7.1](https://github.com/speclynx/apidom/compare/v4.7.0...v4.7.1) (2026-04-16)
+
+**Note:** Version bump only for package @speclynx/apidom-overlay
+
+# [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');
@@ -91940,6 +91948,7 @@ class Arazzo1DereferenceVisitor {
      * Transclude referencing element with merged referenced element.
      */
     path.replaceWith(mergedElement);
+    path.skip();
   }
   async JSONSchemaElement(path) {
     const referencingElement = path.node;
@@ -92100,6 +92109,7 @@ class Arazzo1DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['arazzo-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -92143,6 +92153,7 @@ class Arazzo1DereferenceVisitor {
         booleanJsonSchemaElement.meta.set('ref-origin', reference.uri);
         booleanJsonSchemaElement.meta.set('ref-type', referencingElement.element);
         path.replaceWith(booleanJsonSchemaElement);
+        path.skip();
         return;
       }
 
@@ -92595,6 +92606,7 @@ class AsyncAPI2DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['asyncapi-2']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -92639,6 +92651,7 @@ class AsyncAPI2DereferenceVisitor {
         booleanJsonSchemaElement.meta.set('ref-origin', reference.uri);
         booleanJsonSchemaElement.meta.set('ref-type', referencingElement.element);
         path.replaceWith(booleanJsonSchemaElement);
+        path.skip();
         return;
       }
 
@@ -92658,6 +92671,7 @@ class AsyncAPI2DereferenceVisitor {
        * Transclude referencing element with merged referenced element.
        */
       path.replaceWith(mergedElement);
+      path.skip();
     } catch (error) {
       const $ref = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_4__["default"])(referencingElement.$ref);
       this.handleError(`Error while dereferencing Reference Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
@@ -93233,6 +93247,7 @@ class OpenAPI2DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['openapi-2']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -93280,6 +93295,7 @@ class OpenAPI2DereferenceVisitor {
        * Transclude referencing element with merged referenced element.
        */
       path.replaceWith(mergedElement);
+      path.skip();
     } catch (error) {
       const $ref = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_4__["default"])(referencingElement.$ref);
       this.handleError(`Error while dereferencing Reference Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
@@ -93367,6 +93383,7 @@ class OpenAPI2DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['openapi-2']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -93521,6 +93538,7 @@ class OpenAPI2DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['openapi-2']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -93570,6 +93588,7 @@ class OpenAPI2DereferenceVisitor {
        * Transclude referencing element with merged referenced element.
        */
       path.replaceWith(mergedElement);
+      path.skip();
     } catch (error) {
       const $ref = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_4__["default"])(referencingElement.$ref);
       this.handleError(`Error while dereferencing JSON Reference Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
@@ -93998,6 +94017,7 @@ class OpenAPI3_0DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['openapi-3-0']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -94047,6 +94067,7 @@ class OpenAPI3_0DereferenceVisitor {
        * Transclude referencing element with merged referenced element.
        */
       path.replaceWith(mergedElement);
+      path.skip();
     } catch (error) {
       const $ref = (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_5__["default"])(referencingElement.$ref);
       this.handleError(`Error while dereferencing Reference Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
@@ -94134,6 +94155,7 @@ class OpenAPI3_0DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['openapi-3-0']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -94996,6 +95018,7 @@ class OpenAPI3_1DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['openapi-3-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -95148,6 +95171,7 @@ class OpenAPI3_1DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['openapi-3-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -95504,6 +95528,7 @@ class OpenAPI3_1DereferenceVisitor {
           const replacer = this.options.dereference.strategyOpts['openapi-3-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
           const replacement = replacer(refElement);
           path.replaceWith(replacement);
+          path.skip();
           return;
         }
       }
@@ -95545,6 +95570,7 @@ class OpenAPI3_1DereferenceVisitor {
         booleanJsonSchemaElement.meta.set('ref-origin', reference.uri);
         booleanJsonSchemaElement.meta.set('ref-type', referencingElement.element);
         path.replaceWith(booleanJsonSchemaElement);
+        path.skip();
         return;
       }
 
@@ -100253,11 +100279,6 @@ function* traverseGenerator(root, visitor, options) {
         if (currentPath.shouldStop) {
           break;
         }
-        if (currentPath.shouldSkip) {
-          if (!isLeaving) {
-            continue;
-          }
-        }
         if (currentPath.removed) {
           edits.push([key, null]);
           if (!isLeaving) {
@@ -100267,12 +100288,19 @@ function* traverseGenerator(root, visitor, options) {
           const replacement = currentPath._getReplacementNode();
           edits.push([key, replacement]);
           if (!isLeaving) {
+            if (currentPath.shouldSkip) {
+              continue;
+            }
             if (nodePredicate(replacement)) {
               node = replacement;
             } else {
               continue;
             }
           }
+        } else if (currentPath.shouldSkip) {
+          if (!isLeaving) {
+            continue;
+          }
         } else if (result !== undefined) {
           // Support return value replacement for backwards compatibility
           edits.push([key, result]);
@@ -101017,6 +101045,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);