@speclynx/apidom-overlay 4.3.1 → 4.5.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [4.5.0](https://github.com/speclynx/apidom/compare/v4.4.0...v4.5.0) (2026-04-12)
+
+### Features
+
+- **overlay:** add support for POJO ([#233](https://github.com/speclynx/apidom/issues/233)) ([810b8e4](https://github.com/speclynx/apidom/commit/810b8e4b10787f9982e449915fbc0c4d58c65e1d))
+
+# [4.4.0](https://github.com/speclynx/apidom/compare/v4.3.1...v4.4.0) (2026-04-12)
+
+### Features
+
+- **overlay:** add apidom-overlay package ([#231](https://github.com/speclynx/apidom/issues/231)) ([bcd63b9](https://github.com/speclynx/apidom/commit/bcd63b9ce08afceb03bf78d540992fa7ce50d91a))

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -19,11 +19,11 @@ This package provides three levels of API for applying overlays:
 
 ### Applying from file/URL
 
-The default export parses an overlay document, resolves the target (from `targetURI` or the overlay's `extends` field),
+`applyOverlay` parses an overlay document, resolves the target (from `targetURI` or the overlay's `extends` field),
 and applies all actions. The target is parsed with style preservation for round-trip fidelity.
 
 ```js
-import applyOverlay from '@speclynx/apidom-overlay';
+import { applyOverlay } from '@speclynx/apidom-overlay';
 import { toYAML } from '@speclynx/apidom-core';
 
 // target from extends field
@@ -62,14 +62,12 @@ const target = refract({
 const result = applyOverlayApiDOM(overlay, target);
 ```
 
-### Applying a single action
-
-`applyAction` applies a single overlay action. Useful for programmatic, step-by-step application.
+`applyActionApiDOM` applies a single overlay action. Useful for programmatic, step-by-step application.
 
 ```js
 import { refract } from '@speclynx/apidom-datamodel';
 import { refractAction } from '@speclynx/apidom-ns-overlay-1';
-import { applyAction } from '@speclynx/apidom-overlay';
+import { applyActionApiDOM } from '@speclynx/apidom-overlay';
 
 const action = refractAction({
   target: '$.info.title',
@@ -77,7 +75,38 @@ const action = refractAction({
 });
 const target = refract({ info: { title: 'Old Title', version: '1.0.0' } });
 
-const result = applyAction(action, target);
+const result = applyActionApiDOM(action, target);
+```
+
+### Applying to plain JavaScript objects (POJO)
+
+`applyOverlayPOJO` and `applyActionPOJO` accept and return plain JavaScript objects —
+no need to manually refract or serialize.
+
+```js
+import { applyOverlayPOJO, applyActionPOJO } from '@speclynx/apidom-overlay';
+
+// full overlay
+const result = applyOverlayPOJO(
+  {
+    overlay: '1.1.0',
+    info: { title: 'My overlay', version: '1.0.0' },
+    actions: [
+      { target: '$.info.title', update: 'Renamed API' },
+    ],
+  },
+  {
+    openapi: '3.1.0',
+    info: { title: 'Original', version: '1.0.0' },
+  },
+);
+// result is a plain object: { openapi: '3.1.0', info: { title: 'Renamed API', version: '1.0.0' } }
+
+// single action
+const updated = applyActionPOJO(
+  { target: '$.info.title', update: 'New Title' },
+  { info: { title: 'Old Title' } },
+);
 ```
 
 ## Overlay spec semantics
@@ -99,7 +128,7 @@ The implementation follows [Overlay 1.1.0](https://spec.openapis.org/overlay/v1.
 
 ### ApplyOptions
 
-Passed to `applyAction`, `applyOverlayApiDOM`, and `applyOverlay`:
+Passed to `applyActionApiDOM`, `applyOverlayApiDOM`, and `applyOverlay`:
 
 | Option | Type | Default | Description |
 |---|---|---|---|
@@ -136,10 +165,10 @@ All errors thrown by this package are instances of `OverlayError`, which extends
 Errors carry structured context for diagnostics:
 
 ```js
-import { applyAction, OverlayError } from '@speclynx/apidom-overlay';
+import { applyActionApiDOM, OverlayError } from '@speclynx/apidom-overlay';
 
 try {
-  applyAction(action, target);
+  applyActionApiDOM(action, target);
 } catch (error) {
   if (error instanceof OverlayError) {
     console.error(error.message);

package/dist/apidom-overlay.browser.js

@@ -11,99 +11,7 @@
 return /******/ (() => { // webpackBootstrap
 /******/ 	var __webpack_modules__ = ({
 
-/***/ 17621
-(__unused_webpack_module, __webpack_exports__, __webpack_require__) {
-
-"use strict";
-__webpack_require__.r(__webpack_exports__);
-/* harmony export */ __webpack_require__.d(__webpack_exports__, {
-/* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__)
-/* 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);
-/* harmony import */ var _speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(29807);
-/* harmony import */ var _apply_ts__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(3138);
-/* harmony import */ var _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(18436);
-
-
-
-
-
-
-/**
- * @public
- */
-
-const defaultOptions = {
-  parse: {
-    parserOpts: {
-      strict: false,
-      style: true,
-      'overlay-json-1': {
-        sourceMap: true,
-        style: false,
-        extends: true
-      },
-      'overlay-yaml-1': {
-        sourceMap: true,
-        style: false,
-        extends: true
-      }
-    }
-  },
-  resolve: {
-    resolverOpts: {
-      fileAllowList: ['*']
-    }
-  }
-};
-
-/**
- * Applies an overlay document from a file/URL to its target document.
- *
- * Parses the overlay, resolves the target from `targetURI` or the overlay's
- * `extends` field, parses the target with style preservation for round-trip fidelity,
- * and applies all overlay actions.
- *
- * @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
- * @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);
-
-  // 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 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);
-  } else {
-    const extendsElement = overlayElement.get('extends');
-    targetParseResult = extendsElement?.meta?.get('parseResult');
-  }
-  if (!(0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isParseResultElement)(targetParseResult)) {
-    throw new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_4__["default"]('No target specified: provide targetURI or set the "extends" field in the overlay document');
-  }
-
-  // apply overlay actions to the target (returns targetParseResult with result replaced)
-  return (0,_apply_ts__WEBPACK_IMPORTED_MODULE_3__.applyOverlayApiDOM)(overlayParseResult, targetParseResult, options);
-};
-/* harmony default export */ const __WEBPACK_DEFAULT_EXPORT__ = (applyOverlay);
-
-/***/ },
-
-/***/ 3138
+/***/ 4433
 (__unused_webpack_module, __webpack_exports__, __webpack_require__) {
 
 "use strict";
@@ -111,7 +19,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   applyAction: () => (/* binding */ applyAction),
 /* harmony export */   applyCopyAction: () => (/* binding */ applyCopyAction),
-/* harmony export */   applyOverlayApiDOM: () => (/* binding */ applyOverlayApiDOM),
+/* harmony export */   applyOverlay: () => (/* binding */ applyOverlay),
 /* harmony export */   applyRemoveAction: () => (/* binding */ applyRemoveAction),
 /* harmony export */   applyUpdateAction: () => (/* binding */ applyUpdateAction)
 /* harmony export */ });
@@ -333,7 +241,7 @@ const applyAction = (actionElement, targetElement, options = defaultApplyOptions
  *
  * @public
  */
-const applyOverlayApiDOM = (overlayElement, targetElement, options = defaultApplyOptions) => {
+const applyOverlay = (overlayElement, targetElement, options = defaultApplyOptions) => {
   const overlay = overlayElement instanceof _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_2__["default"] ? overlayElement.api : overlayElement;
   if (!(0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_7__.isOverlay1Element)(overlay)) {
     throw new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_8__["default"]('First argument must be an Overlay 1.x document');
@@ -362,6 +270,132 @@ const applyOverlayApiDOM = (overlayElement, targetElement, options = defaultAppl
 
 /***/ },
 
+/***/ 56019
+(__unused_webpack_module, __webpack_exports__, __webpack_require__) {
+
+"use strict";
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   applyAction: () => (/* binding */ applyAction),
+/* harmony export */   applyOverlay: () => (/* binding */ applyOverlay)
+/* harmony export */ });
+/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(10404);
+/* harmony import */ var _speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(44673);
+/* harmony import */ var _speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(35957);
+/* harmony import */ var _apidom_ts__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(4433);
+
+
+
+
+
+/**
+ * Applies a single overlay action (POJO) to a target (POJO).
+ *
+ * @public
+ */
+const applyAction = (action, target) => (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_1__["default"])((0,_apidom_ts__WEBPACK_IMPORTED_MODULE_3__.applyAction)((0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_2__.refractAction)(action), (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.refract)(target)));
+
+/**
+ * Applies an entire overlay document (POJO) to a target (POJO).
+ *
+ * @public
+ */
+const applyOverlay = (overlay, target) => (0,_speclynx_apidom_core__WEBPACK_IMPORTED_MODULE_1__["default"])((0,_apidom_ts__WEBPACK_IMPORTED_MODULE_3__.applyOverlay)((0,_speclynx_apidom_ns_overlay_1__WEBPACK_IMPORTED_MODULE_2__.refractOverlay1)(overlay), (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.refract)(target)));
+
+/***/ },
+
+/***/ 54687
+(__unused_webpack_module, __webpack_exports__, __webpack_require__) {
+
+"use strict";
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__)
+/* 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);
+/* harmony import */ var _speclynx_apidom_reference__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(29807);
+/* harmony import */ var _apidom_ts__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(4433);
+/* harmony import */ var _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(18436);
+
+
+
+
+
+
+/**
+ * @public
+ */
+
+const defaultOptions = {
+  parse: {
+    parserOpts: {
+      strict: false,
+      style: true,
+      'overlay-json-1': {
+        sourceMap: true,
+        style: false,
+        extends: true
+      },
+      'overlay-yaml-1': {
+        sourceMap: true,
+        style: false,
+        extends: true
+      }
+    }
+  },
+  resolve: {
+    resolverOpts: {
+      fileAllowList: ['*']
+    }
+  }
+};
+
+/**
+ * Applies an overlay document from a file/URL to its target document.
+ *
+ * Parses the overlay, resolves the target from `targetURI` or the overlay's
+ * `extends` field, parses the target with style preservation for round-trip fidelity,
+ * and applies all overlay actions.
+ *
+ * @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
+ * @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);
+
+  // 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 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);
+  } else {
+    const extendsElement = overlayElement.get('extends');
+    targetParseResult = extendsElement?.meta?.get('parseResult');
+  }
+  if (!(0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isParseResultElement)(targetParseResult)) {
+    throw new _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_4__["default"]('No target specified: provide targetURI or set the "extends" field in the overlay document');
+  }
+
+  // apply overlay actions to the target (returns targetParseResult with result replaced)
+  return (0,_apidom_ts__WEBPACK_IMPORTED_MODULE_3__.applyOverlay)(overlayParseResult, targetParseResult, options);
+};
+/* harmony default export */ const __WEBPACK_DEFAULT_EXPORT__ = (applyOverlay);
+
+/***/ },
+
 /***/ 18436
 (__unused_webpack_module, __webpack_exports__, __webpack_require__) {
 
@@ -27809,7 +27843,7 @@ async function Module2(moduleArg = {}) {
   var ENVIRONMENT_IS_NODE = typeof process == "object" && process.versions?.node && process.type != "renderer";
   if (ENVIRONMENT_IS_NODE) {
     const { createRequire } = await Promise.resolve(/* import() */).then(__webpack_require__.t.bind(__webpack_require__, 19451, 19));
-    var require = createRequire("file:///home/char0n/Documents/GitHub/speclynx/apidom/node_modules/web-tree-sitter/web-tree-sitter.js");
+    var require = createRequire("file:///home/runner/work/apidom/apidom/node_modules/web-tree-sitter/web-tree-sitter.js");
   }
   Module.currentQueryProgressCallback = null;
   Module.currentProgressCallback = null;
@@ -27820,7 +27854,7 @@ async function Module2(moduleArg = {}) {
   var quit_ = /* @__PURE__ */ __name((status, toThrow) => {
     throw toThrow;
   }, "quit_");
-  var _scriptName = "file:///home/char0n/Documents/GitHub/speclynx/apidom/node_modules/web-tree-sitter/web-tree-sitter.js";
+  var _scriptName = "file:///home/runner/work/apidom/apidom/node_modules/web-tree-sitter/web-tree-sitter.js";
   var scriptDirectory = "";
   function locateFile(path) {
     if (Module["locateFile"]) {
@@ -100862,16 +100896,20 @@ var __webpack_exports__ = {};
 "use strict";
 __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
-/* harmony export */   OverlayError: () => (/* reexport safe */ _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_2__["default"]),
-/* harmony export */   applyAction: () => (/* reexport safe */ _apply_ts__WEBPACK_IMPORTED_MODULE_0__.applyAction),
-/* harmony export */   applyOverlayApiDOM: () => (/* reexport safe */ _apply_ts__WEBPACK_IMPORTED_MODULE_0__.applyOverlayApiDOM),
-/* harmony export */   "default": () => (/* reexport safe */ _apply_uri_ts__WEBPACK_IMPORTED_MODULE_3__["default"]),
-/* harmony export */   validateAction: () => (/* reexport safe */ _validate_ts__WEBPACK_IMPORTED_MODULE_1__.validateAction)
+/* harmony export */   OverlayError: () => (/* reexport safe */ _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_4__["default"]),
+/* harmony export */   applyActionApiDOM: () => (/* reexport safe */ _apply_apidom_ts__WEBPACK_IMPORTED_MODULE_0__.applyAction),
+/* harmony export */   applyActionPOJO: () => (/* reexport safe */ _apply_pojo_ts__WEBPACK_IMPORTED_MODULE_2__.applyAction),
+/* harmony export */   applyOverlay: () => (/* reexport safe */ _apply_uri_ts__WEBPACK_IMPORTED_MODULE_1__["default"]),
+/* harmony export */   applyOverlayApiDOM: () => (/* reexport safe */ _apply_apidom_ts__WEBPACK_IMPORTED_MODULE_0__.applyOverlay),
+/* harmony export */   applyOverlayPOJO: () => (/* reexport safe */ _apply_pojo_ts__WEBPACK_IMPORTED_MODULE_2__.applyOverlay),
+/* harmony export */   validateAction: () => (/* reexport safe */ _validate_ts__WEBPACK_IMPORTED_MODULE_3__.validateAction)
 /* harmony export */ });
-/* harmony import */ var _apply_ts__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(3138);
-/* harmony import */ var _validate_ts__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(24338);
-/* harmony import */ var _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(18436);
-/* harmony import */ var _apply_uri_ts__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(17621);
+/* harmony import */ var _apply_apidom_ts__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(4433);
+/* harmony import */ var _apply_uri_ts__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(54687);
+/* harmony import */ var _apply_pojo_ts__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(56019);
+/* harmony import */ var _validate_ts__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(24338);
+/* harmony import */ var _errors_OverlayError_ts__WEBPACK_IMPORTED_MODULE_4__ = __webpack_require__(18436);
+