@speclynx/apidom-overlay 4.3.1

package/src/apply.mjs

@@ -0,0 +1,232 @@
+import { isObjectElement, isArrayElement, cloneDeep, ParseResultElement } from '@speclynx/apidom-datamodel';
+import { deepmerge, toValue } from '@speclynx/apidom-core';
+import { evaluate, NormalizedPath } from '@speclynx/apidom-json-path';
+import { isOverlay1Element } from '@speclynx/apidom-ns-overlay-1';
+import OverlayError from "./errors/OverlayError.mjs";
+import { validateAction, validateTargetNodes } from "./validate.mjs";
+/**
+ * @public
+ */
+const defaultApplyOptions = {
+  immutable: true,
+  strict: false
+};
+
+/**
+ * Default customMerge that enforces Overlay spec type compatibility.
+ * Throws OverlayError on incompatible type combinations.
+ */
+const overlayCustomMerge = (_keyElement, options) => {
+  return (target, source) => {
+    const targetIsObject = isObjectElement(target);
+    const sourceIsObject = isObjectElement(source);
+    const targetIsArray = isArrayElement(target);
+    const sourceIsArray = isArrayElement(source);
+    if (targetIsObject !== sourceIsObject || targetIsArray !== sourceIsArray) {
+      throw new OverlayError(`Incompatible types in overlay merge: cannot merge ` + `${targetIsObject ? 'object' : targetIsArray ? 'array' : 'primitive'} with ` + `${sourceIsObject ? 'object' : sourceIsArray ? 'array' : 'primitive'}`);
+    }
+    return deepmerge(target, source, options);
+  };
+};
+
+/**
+ * Merges a value into a target node following Overlay spec semantics.
+ */
+const mergeValue = (targetElement, sourceElement, options = defaultApplyOptions) => {
+  const targetIsObject = isObjectElement(targetElement);
+  const targetIsArray = isArrayElement(targetElement);
+  const sourceIsObject = isObjectElement(sourceElement);
+  const sourceIsArray = isArrayElement(sourceElement);
+  const clone = options.immutable;
+  if (targetIsObject && sourceIsObject || targetIsArray && sourceIsArray) {
+    const mergeOpts = {
+      clone,
+      customMerge: overlayCustomMerge,
+      ...options.deepmerge
+    };
+    return deepmerge(targetElement, sourceElement, mergeOpts);
+  }
+  if (!targetIsObject && !targetIsArray && !sourceIsObject && !sourceIsArray) {
+    return clone ? cloneDeep(sourceElement) : sourceElement;
+  }
+  throw new OverlayError(`Incompatible types in overlay merge: cannot merge ` + `${targetIsObject ? 'object' : targetIsArray ? 'array' : 'primitive'} with ` + `${sourceIsObject ? 'object' : sourceIsArray ? 'array' : 'primitive'}`);
+};
+
+/**
+ * Resolves a normalized path to its parent element and child key.
+ */
+const resolveParent = (normalizedPath, root) => {
+  const selectors = NormalizedPath.to(normalizedPath);
+  if (selectors.length === 0) return null; // root — no parent
+  const key = selectors[selectors.length - 1];
+  const parentPath = NormalizedPath.from(selectors.slice(0, -1));
+  const [parent] = evaluate(root, parentPath);
+  return {
+    parent,
+    key
+  };
+};
+
+/**
+ * Applies an update action to matched nodes.
+ * @public
+ */
+export const applyUpdateAction = (normalizedPaths, updateValue, targetElement, options = defaultApplyOptions) => {
+  let result = options.immutable ? cloneDeep(targetElement) : targetElement;
+  for (const normalizedPath of normalizedPaths) {
+    const resolved = resolveParent(normalizedPath, result);
+    if (resolved === null) {
+      // targeting root
+      result = mergeValue(result, updateValue, options);
+      continue;
+    }
+    const {
+      parent,
+      key
+    } = resolved;
+    if (isObjectElement(parent)) {
+      const current = parent.get(key);
+      if (current !== undefined) {
+        parent.set(key, mergeValue(current, updateValue, options));
+      }
+    } else if (isArrayElement(parent)) {
+      const current = parent.get(key);
+      if (current !== undefined) {
+        parent.content[key] = mergeValue(current, updateValue, options);
+      }
+    }
+  }
+  return result;
+};
+
+/**
+ * Applies a copy action to matched nodes.
+ * @public
+ */
+export const applyCopyAction = (normalizedPaths, copyExpression, targetElement, options = defaultApplyOptions) => {
+  const sourceMatches = evaluate(targetElement, copyExpression);
+  if (sourceMatches.length === 0) {
+    throw new OverlayError(`Copy source JSONPath "${copyExpression}" selected zero nodes`);
+  }
+  if (sourceMatches.length > 1) {
+    throw new OverlayError(`Copy source JSONPath "${copyExpression}" must select a single node, but selected ${sourceMatches.length}`);
+  }
+  const sourceValue = sourceMatches[0];
+  return applyUpdateAction(normalizedPaths, sourceValue, targetElement, options);
+};
+
+/**
+ * Applies a remove action to matched nodes.
+ * @public
+ */
+export const applyRemoveAction = (normalizedPaths, targetElement, options = defaultApplyOptions) => {
+  const result = options.immutable ? cloneDeep(targetElement) : targetElement;
+  // reverse document order so higher array indices are removed first (avoids index shifting)
+  const sorted = [...normalizedPaths].reverse();
+  for (const normalizedPath of sorted) {
+    const resolved = resolveParent(normalizedPath, result);
+    if (resolved === null) {
+      throw new OverlayError('Cannot remove the root node');
+    }
+    const {
+      parent,
+      key
+    } = resolved;
+    if (isObjectElement(parent)) {
+      parent.remove(key);
+    } else if (isArrayElement(parent)) {
+      parent.content.splice(key, 1);
+    }
+  }
+  return result;
+};
+
+/**
+ * Applies a single overlay action to a target element.
+ * Immutable — returns a new element with the action applied.
+ *
+ * @public
+ */
+export const applyAction = (actionElement, targetElement, options = defaultApplyOptions) => {
+  const actionValidation = validateAction(actionElement);
+  if (!actionValidation.valid) throw actionValidation.error;
+  const targetExpression = toValue(actionElement.target);
+  const matches = [];
+  const normalizedPaths = [];
+  evaluate(targetElement, targetExpression, {
+    callback: (value, normalizedPath) => {
+      matches.push(value);
+      normalizedPaths.push(normalizedPath);
+    }
+  });
+  if (matches.length === 0) {
+    if (options.strict) {
+      throw new OverlayError(`Action target "${targetExpression}" matched zero nodes (strict mode)`, {
+        action: actionElement
+      });
+    }
+    return targetElement;
+  }
+  try {
+    // remove action
+    const removeValue = actionElement.removeField;
+    if (removeValue !== undefined && toValue(removeValue) === true) {
+      return applyRemoveAction(normalizedPaths, targetElement, options);
+    }
+
+    // update action
+    if (actionElement.update !== undefined) {
+      const nodesValidation = validateTargetNodes(matches);
+      if (!nodesValidation.valid) throw nodesValidation.error;
+      return applyUpdateAction(normalizedPaths, actionElement.update, targetElement, options);
+    }
+
+    // copy action
+    if (actionElement.copy !== undefined) {
+      const nodesValidation = validateTargetNodes(matches);
+      if (!nodesValidation.valid) throw nodesValidation.error;
+      const copyExpression = toValue(actionElement.copy);
+      return applyCopyAction(normalizedPaths, copyExpression, targetElement, options);
+    }
+    return targetElement;
+  } catch (error) {
+    // enrich OverlayError with action context, preserving original stack
+    if (error instanceof OverlayError && !error.action) {
+      error.action = actionElement;
+    }
+    throw error;
+  }
+};
+
+/**
+ * Applies an entire overlay document to a target element.
+ * Immutable — returns a new element with all actions applied sequentially.
+ *
+ * @public
+ */
+export const applyOverlayApiDOM = (overlayElement, targetElement, options = defaultApplyOptions) => {
+  const overlay = overlayElement instanceof ParseResultElement ? overlayElement.api : overlayElement;
+  if (!isOverlay1Element(overlay)) {
+    throw new OverlayError('First argument must be an Overlay 1.x document');
+  }
+  let target;
+  if (targetElement instanceof ParseResultElement) {
+    if (targetElement.api === undefined) {
+      throw new OverlayError('Target ParseResultElement contains no API element');
+    }
+    target = targetElement.api;
+  } else {
+    target = targetElement;
+  }
+  if (!isArrayElement(overlay.actions)) {
+    return targetElement;
+  }
+  for (const action of overlay.actions) {
+    target = applyAction(action, target, options);
+  }
+  if (targetElement instanceof ParseResultElement) {
+    targetElement.replaceResult(target);
+    return targetElement;
+  }
+  return target;
+};

package/src/errors/OverlayError.cjs

@@ -0,0 +1,22 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomError = require("@speclynx/apidom-error");
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class OverlayError extends _apidomError.ApiDOMStructuredError {
+  action;
+  member;
+  constructor(message, options) {
+    super(message, options);
+    this.action = options?.action;
+    this.member = options?.member;
+  }
+}
+var _default = exports.default = OverlayError;

package/src/errors/OverlayError.mjs

@@ -0,0 +1,19 @@
+import { ApiDOMStructuredError } from '@speclynx/apidom-error';
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class OverlayError extends ApiDOMStructuredError {
+  action;
+  member;
+  constructor(message, options) {
+    super(message, options);
+    this.action = options?.action;
+    this.member = options?.member;
+  }
+}
+export default OverlayError;

package/src/index.cjs

@@ -0,0 +1,14 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.validateAction = exports.default = exports.applyOverlayApiDOM = exports.applyAction = exports.OverlayError = void 0;
+var _apply = require("./apply.cjs");
+exports.applyAction = _apply.applyAction;
+exports.applyOverlayApiDOM = _apply.applyOverlayApiDOM;
+var _validate = require("./validate.cjs");
+exports.validateAction = _validate.validateAction;
+var _OverlayError = _interopRequireDefault(require("./errors/OverlayError.cjs"));
+exports.OverlayError = _OverlayError.default;
+var _applyUri = _interopRequireDefault(require("./apply-uri.cjs"));
+exports.default = _applyUri.default;

package/src/index.mjs

@@ -0,0 +1,4 @@
+export { applyAction, applyOverlayApiDOM } from "./apply.mjs";
+export { validateAction } from "./validate.mjs";
+export { default as OverlayError } from "./errors/OverlayError.mjs";
+export { default } from "./apply-uri.mjs";

package/src/validate.cjs

@@ -0,0 +1,81 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.validateTargetNodes = exports.validateAction = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomNsOverlay = require("@speclynx/apidom-ns-overlay-1");
+var _OverlayError = _interopRequireDefault(require("./errors/OverlayError.cjs"));
+/**
+ * @public
+ */
+
+const valid = {
+  valid: true
+};
+const invalid = error => ({
+  valid: false,
+  error
+});
+
+/**
+ * Validates that an ActionElement has the correct shape per the Overlay spec.
+ *
+ * @public
+ */
+const validateAction = actionElement => {
+  if (!(0, _apidomNsOverlay.isActionElement)(actionElement)) {
+    return invalid(new _OverlayError.default('Action must be an ActionElement', {
+      action: actionElement
+    }));
+  }
+  if (!(0, _apidomDatamodel.isStringElement)(actionElement.target)) {
+    return invalid(new _OverlayError.default('Action "target" field is required and must be a string', {
+      action: actionElement,
+      member: actionElement.getMember('target')
+    }));
+  }
+  if (actionElement.update !== undefined && actionElement.copy !== undefined) {
+    return invalid(new _OverlayError.default('Action must not have both "update" and "copy" fields', {
+      action: actionElement
+    }));
+  }
+  if (actionElement.copy !== undefined && !(0, _apidomDatamodel.isStringElement)(actionElement.copy)) {
+    return invalid(new _OverlayError.default('Action "copy" field must be a string (JSONPath expression)', {
+      action: actionElement,
+      member: actionElement.getMember('copy')
+    }));
+  }
+  if (actionElement.removeField !== undefined && !(0, _apidomDatamodel.isBooleanElement)(actionElement.removeField)) {
+    return invalid(new _OverlayError.default('Action "remove" field must be a boolean', {
+      action: actionElement,
+      member: actionElement.getMember('remove')
+    }));
+  }
+  return valid;
+};
+exports.validateAction = validateAction;
+const categorizeNode = node => {
+  if ((0, _apidomDatamodel.isObjectElement)(node)) return 'object';
+  if ((0, _apidomDatamodel.isArrayElement)(node)) return 'array';
+  return 'primitive';
+};
+
+/**
+ * Validates that all matched target nodes are the same type
+ * when there are 2 or more matches (spec requirement for update/copy).
+ *
+ * @public
+ */
+const validateTargetNodes = nodes => {
+  if (nodes.length < 2) return valid;
+  const firstCategory = categorizeNode(nodes[0]);
+  for (let i = 1; i < nodes.length; i++) {
+    const category = categorizeNode(nodes[i]);
+    if (category !== firstCategory) {
+      return invalid(new _OverlayError.default(`All target nodes must be the same type when selecting multiple nodes. ` + `Expected "${firstCategory}" but found "${category}" at index ${i}`));
+    }
+  }
+  return valid;
+};
+exports.validateTargetNodes = validateTargetNodes;

package/src/validate.mjs

@@ -0,0 +1,73 @@
+import { isStringElement, isBooleanElement, isObjectElement, isArrayElement } from '@speclynx/apidom-datamodel';
+import { isActionElement } from '@speclynx/apidom-ns-overlay-1';
+import OverlayError from "./errors/OverlayError.mjs";
+/**
+ * @public
+ */
+const valid = {
+  valid: true
+};
+const invalid = error => ({
+  valid: false,
+  error
+});
+
+/**
+ * Validates that an ActionElement has the correct shape per the Overlay spec.
+ *
+ * @public
+ */
+export const validateAction = actionElement => {
+  if (!isActionElement(actionElement)) {
+    return invalid(new OverlayError('Action must be an ActionElement', {
+      action: actionElement
+    }));
+  }
+  if (!isStringElement(actionElement.target)) {
+    return invalid(new OverlayError('Action "target" field is required and must be a string', {
+      action: actionElement,
+      member: actionElement.getMember('target')
+    }));
+  }
+  if (actionElement.update !== undefined && actionElement.copy !== undefined) {
+    return invalid(new OverlayError('Action must not have both "update" and "copy" fields', {
+      action: actionElement
+    }));
+  }
+  if (actionElement.copy !== undefined && !isStringElement(actionElement.copy)) {
+    return invalid(new OverlayError('Action "copy" field must be a string (JSONPath expression)', {
+      action: actionElement,
+      member: actionElement.getMember('copy')
+    }));
+  }
+  if (actionElement.removeField !== undefined && !isBooleanElement(actionElement.removeField)) {
+    return invalid(new OverlayError('Action "remove" field must be a boolean', {
+      action: actionElement,
+      member: actionElement.getMember('remove')
+    }));
+  }
+  return valid;
+};
+const categorizeNode = node => {
+  if (isObjectElement(node)) return 'object';
+  if (isArrayElement(node)) return 'array';
+  return 'primitive';
+};
+
+/**
+ * Validates that all matched target nodes are the same type
+ * when there are 2 or more matches (spec requirement for update/copy).
+ *
+ * @public
+ */
+export const validateTargetNodes = nodes => {
+  if (nodes.length < 2) return valid;
+  const firstCategory = categorizeNode(nodes[0]);
+  for (let i = 1; i < nodes.length; i++) {
+    const category = categorizeNode(nodes[i]);
+    if (category !== firstCategory) {
+      return invalid(new OverlayError(`All target nodes must be the same type when selecting multiple nodes. ` + `Expected "${firstCategory}" but found "${category}" at index ${i}`));
+    }
+  }
+  return valid;
+};

package/types/apidom-overlay.d.ts

@@ -0,0 +1,92 @@
+import { ActionElement } from '@speclynx/apidom-ns-overlay-1';
+import { ApiDOMReferenceOptions } from '@speclynx/apidom-reference';
+import { ApiDOMStructuredError } from '@speclynx/apidom-error';
+import { DeepMergeUserOptions } from '@speclynx/apidom-core';
+import { Element as Element_2 } from '@speclynx/apidom-datamodel';
+import { MemberElement } from '@speclynx/apidom-datamodel';
+import { Overlay1Element } from '@speclynx/apidom-ns-overlay-1';
+import { ParseResultElement } from '@speclynx/apidom-datamodel';
+
+/**
+ * Applies a single overlay action to a target element.
+ * Immutable — returns a new element with the action applied.
+ *
+ * @public
+ */
+export declare const applyAction: (actionElement: ActionElement, targetElement: Element_2, options?: ApplyOptions) => Element_2;
+
+/**
+ * @public
+ */
+export declare interface ApplyOptions {
+    readonly deepmerge?: DeepMergeUserOptions;
+    readonly strict?: boolean;
+    readonly immutable?: boolean;
+}
+
+/**
+ * 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
+ */
+declare const applyOverlay: (overlayURI: string, targetURI?: string, options?: ApplyOverlayOptions) => Promise<ParseResultElement>;
+export default applyOverlay;
+
+/**
+ * Applies an entire overlay document to a target element.
+ * Immutable — returns a new element with all actions applied sequentially.
+ *
+ * @public
+ */
+export declare const applyOverlayApiDOM: <T extends Element_2 | ParseResultElement>(overlayElement: Overlay1Element | ParseResultElement, targetElement: T, options?: ApplyOptions) => T;
+
+/**
+ * @public
+ */
+export declare interface ApplyOverlayOptions extends Partial<ApiDOMReferenceOptions>, ApplyOptions {
+}
+
+/**
+ * @public
+ */
+export declare class OverlayError extends ApiDOMStructuredError {
+    action?: ActionElement;
+    member?: MemberElement;
+    constructor(message?: string, options?: OverlayErrorOptions);
+}
+
+/**
+ * @public
+ */
+export declare interface OverlayErrorOptions {
+    readonly cause?: Error;
+    readonly action?: ActionElement;
+    readonly member?: MemberElement;
+    readonly [key: string]: unknown;
+}
+
+/**
+ * Validates that an ActionElement has the correct shape per the Overlay spec.
+ *
+ * @public
+ */
+export declare const validateAction: (actionElement: ActionElement) => ValidationResult;
+
+/**
+ * @public
+ */
+export declare interface ValidationResult {
+    readonly valid: boolean;
+    readonly error?: OverlayError;
+}
+
+export { }