@speclynx/apidom-overlay 4.9.0 → 4.10.0

package/package.json

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

package/src/diff/index.cjs

@@ -0,0 +1,12 @@
+"use strict";
+
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+exports.__esModule = true;
+exports.diffPOJO = exports.diffOverlay = exports.diffApiDOM = exports.defaultDiffOverlayOptions = void 0;
+var _apidom = require("./realms/apidom.cjs");
+exports.diffApiDOM = _apidom.diff;
+var _pojo = require("./realms/pojo.cjs");
+exports.diffPOJO = _pojo.diff;
+var _uri = _interopRequireWildcard(require("./realms/uri.cjs"));
+exports.diffOverlay = _uri.default;
+exports.defaultDiffOverlayOptions = _uri.defaultOptions;

package/src/diff/index.mjs

@@ -0,0 +1,3 @@
+export { diff as diffApiDOM } from "./realms/apidom.mjs";
+export { diff as diffPOJO } from "./realms/pojo.mjs";
+export { default as diffOverlay, defaultOptions as defaultDiffOverlayOptions } from "./realms/uri.mjs";

package/src/diff/realms/apidom.cjs

@@ -0,0 +1,177 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.diff = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomJsonPath = require("@speclynx/apidom-json-path");
+var _apidomNsOverlay = require("@speclynx/apidom-ns-overlay-1");
+var _OverlayError = _interopRequireDefault(require("../../errors/OverlayError.cjs"));
+/**
+ * @public
+ */
+
+const defaultDiffOptions = {
+  overlay: '1.1.0',
+  info: {
+    title: 'API diff',
+    version: '0.0.0'
+  }
+};
+const createUpdateAction = (segments, value) => {
+  const action = new _apidomNsOverlay.ActionElement();
+  action.target = new _apidomDatamodel.StringElement(_apidomJsonPath.NormalizedPath.from(segments));
+  action.update = value;
+  return action;
+};
+const createRemoveAction = segments => {
+  const action = new _apidomNsOverlay.ActionElement();
+  action.target = new _apidomDatamodel.StringElement(_apidomJsonPath.NormalizedPath.from(segments));
+  action.removeField = new _apidomDatamodel.BooleanElement(true);
+  return action;
+};
+const diffElements = (left, right, segments, actions) => {
+  if (left.equals(right)) return;
+  const leftKind = left.primitive();
+  const rightKind = right.primitive();
+  if (leftKind !== rightKind) {
+    if (segments.length === 0) {
+      throw new _OverlayError.default('Cannot diff documents with incompatible root types');
+    }
+    // structural type change: remove old, re-add new via parent update.
+    // only reachable from diffObjects — segments tail is always a string key
+    actions.push(createRemoveAction(segments));
+    const key = segments[segments.length - 1];
+    const wrapper = new _apidomDatamodel.ObjectElement();
+    wrapper.set(key, right);
+    actions.push(createUpdateAction(segments.slice(0, -1), wrapper));
+    return;
+  }
+  if ((0, _apidomDatamodel.isObjectElement)(left) && (0, _apidomDatamodel.isObjectElement)(right)) {
+    diffObjects(left, right, segments, actions);
+    return;
+  }
+  if ((0, _apidomDatamodel.isArrayElement)(left) && (0, _apidomDatamodel.isArrayElement)(right)) {
+    diffArrays(left, right, segments, actions);
+    return;
+  }
+
+  // primitive value changed
+  actions.push(createUpdateAction(segments, right));
+};
+const diffObjects = (left, right, segments, actions) => {
+  const leftKeys = new Set(left.keys());
+  const rightKeys = new Set(right.keys());
+
+  // removed keys
+  for (const key of leftKeys) {
+    if (!rightKeys.has(key)) {
+      actions.push(createRemoveAction([...segments, key]));
+    }
+  }
+
+  // added keys — batched into a single parent update to minimize action count
+  const added = [];
+  for (const key of rightKeys) {
+    if (!leftKeys.has(key)) added.push(key);
+  }
+  if (added.length > 0) {
+    const patch = new _apidomDatamodel.ObjectElement();
+    for (const key of added) {
+      patch.set(key, right.get(key));
+    }
+    actions.push(createUpdateAction(segments, patch));
+  }
+
+  // common keys — recurse into changed values
+  for (const key of leftKeys) {
+    if (!rightKeys.has(key)) continue;
+    diffElements(left.get(key), right.get(key), [...segments, key], actions);
+  }
+};
+const diffArrays = (left, right, segments, actions) => {
+  const leftLen = left.length;
+  const rightLen = right.length;
+  const minLen = Math.min(leftLen, rightLen);
+  for (let i = 0; i < minLen; i++) {
+    const leftItem = left.get(i);
+    const rightItem = right.get(i);
+    if (leftItem.equals(rightItem)) continue;
+    if (leftItem.primitive() !== rightItem.primitive()) {
+      // structural type change at index i — reconstruct tail:
+      // remove from end down to i (reverse order preserves index stability),
+      // then batch-append right[i..] as a single ArrayElement (Overlay concat semantics)
+      for (let j = leftLen - 1; j >= i; j--) {
+        actions.push(createRemoveAction([...segments, j]));
+      }
+      const tail = new _apidomDatamodel.ArrayElement();
+      for (let j = i; j < rightLen; j++) {
+        tail.push(right.get(j));
+      }
+      actions.push(createUpdateAction(segments, tail));
+      return;
+    }
+    diffElements(leftItem, rightItem, [...segments, i], actions);
+  }
+
+  // right is longer — batch all new items into a single ArrayElement update.
+  // wrapping is required: applyUpdateAction uses deepmerge(array, array) for array targets,
+  // so the update value must be an ArrayElement to trigger concat semantics.
+  if (leftLen < rightLen) {
+    const tail = new _apidomDatamodel.ArrayElement();
+    for (let i = leftLen; i < rightLen; i++) {
+      tail.push(right.get(i));
+    }
+    actions.push(createUpdateAction(segments, tail));
+  }
+
+  // left is longer — remove trailing items in reverse order for index stability
+  for (let i = leftLen - 1; i >= rightLen; i--) {
+    actions.push(createRemoveAction([...segments, i]));
+  }
+};
+
+/**
+ * Produces an {@link Overlay1Element} that, when applied to `leftElement`, yields `rightElement`.
+ *
+ * Known limitations:
+ * - Identical documents produce an overlay with an empty `actions` array. Overlay 1.1.0 §3
+ *   requires `actions` to be non-empty; callers should guard against the no-diff case.
+ * - Root-level structural type change (e.g. object root → array root) throws {@link OverlayError}
+ *   because Overlay has no mechanism to replace the root node.
+ * - Array insert-at-position is not supported by Overlay 1.x; positional diffing cascades
+ *   replaces and appends, which is always correct but may be verbose for large reorderings.
+ * - Array items with a structural type change are handled via tail-reconstruct
+ *   (remove tail + re-append from right), producing more actions than a minimal diff.
+ * - The overlay carries no "before" value, so it cannot be reversed without the original document.
+ * - Action `update` values reference elements from `rightElement` directly. Mutating `rightElement`
+ *   after calling `diff` will affect the returned overlay.
+ *
+ * @public
+ */
+const diff = (leftElement, rightElement, options = {}) => {
+  const overlayVersion = options.overlay ?? defaultDiffOptions.overlay;
+  const infoTitle = options.info?.title ?? defaultDiffOptions.info.title;
+  const infoVersion = options.info?.version ?? defaultDiffOptions.info.version;
+  const infoDescription = options.info?.description;
+  const actions = [];
+  diffElements(leftElement, rightElement, [], actions);
+  if (actions.length === 0 && options.onEmptyDiff === 'throw') {
+    throw new _OverlayError.default('Diff produced no actions: documents are identical');
+  }
+  const overlay = new _apidomNsOverlay.Overlay1Element();
+  overlay.overlay = new _apidomNsOverlay.OverlayElement(overlayVersion);
+  const info = new _apidomNsOverlay.InfoElement();
+  info.title = new _apidomDatamodel.StringElement(infoTitle);
+  info.version = new _apidomDatamodel.StringElement(infoVersion);
+  if (infoDescription !== undefined) {
+    info.description = new _apidomDatamodel.StringElement(infoDescription);
+  }
+  overlay.info = info;
+  if (options.extends !== undefined) {
+    overlay.extends = new _apidomDatamodel.StringElement(options.extends);
+  }
+  overlay.actions = new _apidomNsOverlay.ActionsElement(actions);
+  return overlay;
+};
+exports.diff = diff;

package/src/diff/realms/apidom.mjs

@@ -0,0 +1,170 @@
+import { ObjectElement, ArrayElement, StringElement, BooleanElement, isObjectElement, isArrayElement } from '@speclynx/apidom-datamodel';
+import { NormalizedPath } from '@speclynx/apidom-json-path';
+import { ActionElement, Overlay1Element, InfoElement, OverlayElement, ActionsElement } from '@speclynx/apidom-ns-overlay-1';
+import OverlayError from "../../errors/OverlayError.mjs";
+/**
+ * @public
+ */
+const defaultDiffOptions = {
+  overlay: '1.1.0',
+  info: {
+    title: 'API diff',
+    version: '0.0.0'
+  }
+};
+const createUpdateAction = (segments, value) => {
+  const action = new ActionElement();
+  action.target = new StringElement(NormalizedPath.from(segments));
+  action.update = value;
+  return action;
+};
+const createRemoveAction = segments => {
+  const action = new ActionElement();
+  action.target = new StringElement(NormalizedPath.from(segments));
+  action.removeField = new BooleanElement(true);
+  return action;
+};
+const diffElements = (left, right, segments, actions) => {
+  if (left.equals(right)) return;
+  const leftKind = left.primitive();
+  const rightKind = right.primitive();
+  if (leftKind !== rightKind) {
+    if (segments.length === 0) {
+      throw new OverlayError('Cannot diff documents with incompatible root types');
+    }
+    // structural type change: remove old, re-add new via parent update.
+    // only reachable from diffObjects — segments tail is always a string key
+    actions.push(createRemoveAction(segments));
+    const key = segments[segments.length - 1];
+    const wrapper = new ObjectElement();
+    wrapper.set(key, right);
+    actions.push(createUpdateAction(segments.slice(0, -1), wrapper));
+    return;
+  }
+  if (isObjectElement(left) && isObjectElement(right)) {
+    diffObjects(left, right, segments, actions);
+    return;
+  }
+  if (isArrayElement(left) && isArrayElement(right)) {
+    diffArrays(left, right, segments, actions);
+    return;
+  }
+
+  // primitive value changed
+  actions.push(createUpdateAction(segments, right));
+};
+const diffObjects = (left, right, segments, actions) => {
+  const leftKeys = new Set(left.keys());
+  const rightKeys = new Set(right.keys());
+
+  // removed keys
+  for (const key of leftKeys) {
+    if (!rightKeys.has(key)) {
+      actions.push(createRemoveAction([...segments, key]));
+    }
+  }
+
+  // added keys — batched into a single parent update to minimize action count
+  const added = [];
+  for (const key of rightKeys) {
+    if (!leftKeys.has(key)) added.push(key);
+  }
+  if (added.length > 0) {
+    const patch = new ObjectElement();
+    for (const key of added) {
+      patch.set(key, right.get(key));
+    }
+    actions.push(createUpdateAction(segments, patch));
+  }
+
+  // common keys — recurse into changed values
+  for (const key of leftKeys) {
+    if (!rightKeys.has(key)) continue;
+    diffElements(left.get(key), right.get(key), [...segments, key], actions);
+  }
+};
+const diffArrays = (left, right, segments, actions) => {
+  const leftLen = left.length;
+  const rightLen = right.length;
+  const minLen = Math.min(leftLen, rightLen);
+  for (let i = 0; i < minLen; i++) {
+    const leftItem = left.get(i);
+    const rightItem = right.get(i);
+    if (leftItem.equals(rightItem)) continue;
+    if (leftItem.primitive() !== rightItem.primitive()) {
+      // structural type change at index i — reconstruct tail:
+      // remove from end down to i (reverse order preserves index stability),
+      // then batch-append right[i..] as a single ArrayElement (Overlay concat semantics)
+      for (let j = leftLen - 1; j >= i; j--) {
+        actions.push(createRemoveAction([...segments, j]));
+      }
+      const tail = new ArrayElement();
+      for (let j = i; j < rightLen; j++) {
+        tail.push(right.get(j));
+      }
+      actions.push(createUpdateAction(segments, tail));
+      return;
+    }
+    diffElements(leftItem, rightItem, [...segments, i], actions);
+  }
+
+  // right is longer — batch all new items into a single ArrayElement update.
+  // wrapping is required: applyUpdateAction uses deepmerge(array, array) for array targets,
+  // so the update value must be an ArrayElement to trigger concat semantics.
+  if (leftLen < rightLen) {
+    const tail = new ArrayElement();
+    for (let i = leftLen; i < rightLen; i++) {
+      tail.push(right.get(i));
+    }
+    actions.push(createUpdateAction(segments, tail));
+  }
+
+  // left is longer — remove trailing items in reverse order for index stability
+  for (let i = leftLen - 1; i >= rightLen; i--) {
+    actions.push(createRemoveAction([...segments, i]));
+  }
+};
+
+/**
+ * Produces an {@link Overlay1Element} that, when applied to `leftElement`, yields `rightElement`.
+ *
+ * Known limitations:
+ * - Identical documents produce an overlay with an empty `actions` array. Overlay 1.1.0 §3
+ *   requires `actions` to be non-empty; callers should guard against the no-diff case.
+ * - Root-level structural type change (e.g. object root → array root) throws {@link OverlayError}
+ *   because Overlay has no mechanism to replace the root node.
+ * - Array insert-at-position is not supported by Overlay 1.x; positional diffing cascades
+ *   replaces and appends, which is always correct but may be verbose for large reorderings.
+ * - Array items with a structural type change are handled via tail-reconstruct
+ *   (remove tail + re-append from right), producing more actions than a minimal diff.
+ * - The overlay carries no "before" value, so it cannot be reversed without the original document.
+ * - Action `update` values reference elements from `rightElement` directly. Mutating `rightElement`
+ *   after calling `diff` will affect the returned overlay.
+ *
+ * @public
+ */
+export const diff = (leftElement, rightElement, options = {}) => {
+  const overlayVersion = options.overlay ?? defaultDiffOptions.overlay;
+  const infoTitle = options.info?.title ?? defaultDiffOptions.info.title;
+  const infoVersion = options.info?.version ?? defaultDiffOptions.info.version;
+  const infoDescription = options.info?.description;
+  const actions = [];
+  diffElements(leftElement, rightElement, [], actions);
+  if (actions.length === 0 && options.onEmptyDiff === 'throw') {
+    throw new OverlayError('Diff produced no actions: documents are identical');
+  }
+  const overlay = new Overlay1Element();
+  overlay.overlay = new OverlayElement(overlayVersion);
+  const info = new InfoElement();
+  info.title = new StringElement(infoTitle);
+  info.version = new StringElement(infoVersion);
+  if (infoDescription !== undefined) {
+    info.description = new StringElement(infoDescription);
+  }
+  overlay.info = info;
+  if (options.extends !== undefined) {
+    overlay.extends = new StringElement(options.extends);
+  }
+  overlay.actions = new ActionsElement(actions);
+  return overlay;
+};

package/src/diff/realms/pojo.cjs

@@ -0,0 +1,15 @@
+"use strict";
+
+exports.__esModule = true;
+exports.diff = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidom = require("./apidom.cjs");
+/**
+ * Computes the diff between two plain JavaScript objects and returns an Overlay document
+ * as a plain JavaScript object.
+ *
+ * @public
+ */
+const diff = (left, right, options) => (0, _apidomCore.toValue)((0, _apidom.diff)((0, _apidomDatamodel.refract)(left), (0, _apidomDatamodel.refract)(right), options));
+exports.diff = diff;

package/src/diff/realms/pojo.mjs

@@ -0,0 +1,10 @@
+import { refract } from '@speclynx/apidom-datamodel';
+import { toValue } from '@speclynx/apidom-core';
+import { diff as diffApiDOM } from "./apidom.mjs";
+/**
+ * Computes the diff between two plain JavaScript objects and returns an Overlay document
+ * as a plain JavaScript object.
+ *
+ * @public
+ */
+export const diff = (left, right, options) => toValue(diffApiDOM(refract(left), refract(right), options));

package/src/diff/realms/uri.cjs

@@ -0,0 +1,66 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.defaultOptions = exports.default = void 0;
+var _apidomReference = require("@speclynx/apidom-reference");
+var _apidom = require("./apidom.cjs");
+var _OverlayError = _interopRequireDefault(require("../../errors/OverlayError.cjs"));
+/**
+ * @public
+ */
+
+// intentionally omits overlay-json-1/overlay-yaml-1 parser opts present in apply/realms/uri.ts
+// because diff inputs are regular API documents, not overlay documents
+const defaultReferenceOptions = {
+  parse: {
+    parserOpts: {
+      strict: false
+    }
+  },
+  resolve: {
+    resolverOpts: {
+      fileAllowList: ['*']
+    }
+  }
+};
+
+/**
+ * @public
+ */
+const defaultOptions = exports.defaultOptions = {
+  reference: defaultReferenceOptions
+};
+
+/**
+ * Computes the diff between two API documents identified by URIs and returns
+ * an {@link Overlay1Element} that, when applied to the left document, yields the right.
+ *
+ * When `options.extends` is not provided, it is automatically set to `leftURI`
+ * so the generated overlay can be applied back to the original document.
+ *
+ * @param leftURI - URI to the base (source) document
+ * @param rightURI - URI to the target (changed) document
+ * @param options - diff options; reference options live under `options.reference`
+ * @returns Overlay1Element representing the diff
+ *
+ * @public
+ */
+const diff = async (leftURI, rightURI, options = defaultOptions) => {
+  const mergedRefOptions = (0, _apidomReference.mergeOptions)(defaultReferenceOptions, options.reference ?? {});
+  const [leftParseResult, rightParseResult] = await Promise.all([(0, _apidomReference.parse)(leftURI, mergedRefOptions), (0, _apidomReference.parse)(rightURI, mergedRefOptions)]);
+  const leftElement = leftParseResult.api;
+  const rightElement = rightParseResult.api;
+  if (leftElement == null) {
+    throw new _OverlayError.default(`Failed to parse document "${leftURI}"`);
+  }
+  if (rightElement == null) {
+    throw new _OverlayError.default(`Failed to parse document "${rightURI}"`);
+  }
+  const diffOptions = {
+    ...options,
+    extends: options.extends ?? leftURI
+  };
+  return (0, _apidom.diff)(leftElement, rightElement, diffOptions);
+};
+var _default = exports.default = diff;

package/src/diff/realms/uri.mjs

@@ -0,0 +1,60 @@
+import { parse, mergeOptions } from '@speclynx/apidom-reference';
+import { diff as diffApiDOM } from "./apidom.mjs";
+import OverlayError from "../../errors/OverlayError.mjs";
+/**
+ * @public
+ */
+// intentionally omits overlay-json-1/overlay-yaml-1 parser opts present in apply/realms/uri.ts
+// because diff inputs are regular API documents, not overlay documents
+const defaultReferenceOptions = {
+  parse: {
+    parserOpts: {
+      strict: false
+    }
+  },
+  resolve: {
+    resolverOpts: {
+      fileAllowList: ['*']
+    }
+  }
+};
+
+/**
+ * @public
+ */
+export const defaultOptions = {
+  reference: defaultReferenceOptions
+};
+
+/**
+ * Computes the diff between two API documents identified by URIs and returns
+ * an {@link Overlay1Element} that, when applied to the left document, yields the right.
+ *
+ * When `options.extends` is not provided, it is automatically set to `leftURI`
+ * so the generated overlay can be applied back to the original document.
+ *
+ * @param leftURI - URI to the base (source) document
+ * @param rightURI - URI to the target (changed) document
+ * @param options - diff options; reference options live under `options.reference`
+ * @returns Overlay1Element representing the diff
+ *
+ * @public
+ */
+const diff = async (leftURI, rightURI, options = defaultOptions) => {
+  const mergedRefOptions = mergeOptions(defaultReferenceOptions, options.reference ?? {});
+  const [leftParseResult, rightParseResult] = await Promise.all([parse(leftURI, mergedRefOptions), parse(rightURI, mergedRefOptions)]);
+  const leftElement = leftParseResult.api;
+  const rightElement = rightParseResult.api;
+  if (leftElement == null) {
+    throw new OverlayError(`Failed to parse document "${leftURI}"`);
+  }
+  if (rightElement == null) {
+    throw new OverlayError(`Failed to parse document "${rightURI}"`);
+  }
+  const diffOptions = {
+    ...options,
+    extends: options.extends ?? leftURI
+  };
+  return diffApiDOM(leftElement, rightElement, diffOptions);
+};
+export default diff;

package/src/index.cjs

@@ -3,7 +3,7 @@
 var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
 var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
 exports.__esModule = true;
-exports.validateAction = exports.defaultApplyOverlayOptions = exports.applyOverlayPOJO = exports.applyOverlayApiDOM = exports.applyOverlay = exports.applyActionPOJO = exports.applyActionApiDOM = exports.OverlayError = void 0;
+exports.validateAction = exports.diffPOJO = exports.diffOverlay = exports.diffApiDOM = exports.defaultDiffOverlayOptions = 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;
@@ -13,6 +13,11 @@ exports.defaultApplyOverlayOptions = _uri.defaultOptions;
 var _pojo = require("./apply/realms/pojo.cjs");
 exports.applyActionPOJO = _pojo.applyAction;
 exports.applyOverlayPOJO = _pojo.applyOverlay;
+var _index = require("./diff/index.cjs");
+exports.diffApiDOM = _index.diffApiDOM;
+exports.diffPOJO = _index.diffPOJO;
+exports.diffOverlay = _index.diffOverlay;
+exports.defaultDiffOverlayOptions = _index.defaultDiffOverlayOptions;
 var _validate = require("./validate.cjs");
 exports.validateAction = _validate.validateAction;
 var _OverlayError = _interopRequireDefault(require("./errors/OverlayError.cjs"));

package/src/index.mjs

@@ -1,5 +1,6 @@
 export { applyAction as applyActionApiDOM, applyOverlay as applyOverlayApiDOM } from "./apply/realms/apidom.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 { diffApiDOM, diffPOJO, diffOverlay, defaultDiffOverlayOptions } from "./diff/index.mjs";
 export { validateAction } from "./validate.mjs";
 export { default as OverlayError } from "./errors/OverlayError.mjs";

package/types/apidom-overlay.d.ts

@@ -95,6 +95,81 @@ export declare const applyOverlayPOJO: (overlay: Record<string, unknown>, target
  */
 export declare const defaultApplyOverlayOptions: ApplyOverlayOptions;
 
+/**
+ * @public
+ */
+export declare const defaultDiffOverlayOptions: DiffOverlayOptions;
+
+/**
+ * Produces an {@link Overlay1Element} that, when applied to `leftElement`, yields `rightElement`.
+ *
+ * Known limitations:
+ * - Identical documents produce an overlay with an empty `actions` array. Overlay 1.1.0 §3
+ *   requires `actions` to be non-empty; callers should guard against the no-diff case.
+ * - Root-level structural type change (e.g. object root → array root) throws {@link OverlayError}
+ *   because Overlay has no mechanism to replace the root node.
+ * - Array insert-at-position is not supported by Overlay 1.x; positional diffing cascades
+ *   replaces and appends, which is always correct but may be verbose for large reorderings.
+ * - Array items with a structural type change are handled via tail-reconstruct
+ *   (remove tail + re-append from right), producing more actions than a minimal diff.
+ * - The overlay carries no "before" value, so it cannot be reversed without the original document.
+ * - Action `update` values reference elements from `rightElement` directly. Mutating `rightElement`
+ *   after calling `diff` will affect the returned overlay.
+ *
+ * @public
+ */
+export declare const diffApiDOM: (leftElement: Element_2, rightElement: Element_2, options?: DiffOptions) => Overlay1Element;
+
+/**
+ * @public
+ */
+export declare interface DiffOptions {
+    readonly overlay?: string;
+    readonly info?: {
+        title?: string;
+        description?: string;
+        version?: string;
+    };
+    readonly extends?: string;
+    /**
+     * Controls behavior when the two documents are identical and the diff produces no actions.
+     * - `'allow'` (default) — returns an overlay with an empty `actions` array
+     * - `'throw'` — throws {@link OverlayError}
+     */
+    readonly onEmptyDiff?: 'allow' | 'throw';
+}
+
+/**
+ * Computes the diff between two API documents identified by URIs and returns
+ * an {@link Overlay1Element} that, when applied to the left document, yields the right.
+ *
+ * When `options.extends` is not provided, it is automatically set to `leftURI`
+ * so the generated overlay can be applied back to the original document.
+ *
+ * @param leftURI - URI to the base (source) document
+ * @param rightURI - URI to the target (changed) document
+ * @param options - diff options; reference options live under `options.reference`
+ * @returns Overlay1Element representing the diff
+ *
+ * @public
+ */
+export declare const diffOverlay: (leftURI: string, rightURI: string, options?: DiffOverlayOptions) => Promise<Overlay1Element>;
+
+/**
+ * @public
+ */
+export declare interface DiffOverlayOptions extends DiffOptions {
+    readonly reference?: PartialDeep<ApiDOMReferenceOptions>;
+}
+
+/**
+ * Computes the diff between two plain JavaScript objects and returns an Overlay document
+ * as a plain JavaScript object.
+ *
+ * @public
+ */
+export declare const diffPOJO: (left: Record<string, unknown>, right: Record<string, unknown>, options?: DiffOptions) => unknown;
+
 /**
  * @public
  */