@speclynx/apidom-overlay 4.4.0 → 4.5.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.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

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__) {
 
@@ -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);
+