@speclynx/apidom-overlay 4.3.1

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@speclynx/apidom-overlay",
+  "version": "4.3.1",
+  "description": "Apply Overlay 1.x.y documents to API definitions.",
+  "keywords": [
+    "apidom",
+    "api",
+    "overlay",
+    "openapi-overlay",
+    "openapi",
+    "jsonpath",
+    "rfc9535",
+    "spec",
+    "specification",
+    "typescript",
+    "javascript"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "provenance": false
+  },
+  "type": "module",
+  "sideEffects": false,
+  "unpkg": "./dist/apidom-overlay.browser.min.js",
+  "main": "./src/index.cjs",
+  "exports": {
+    "types": "./types/apidom-overlay.d.ts",
+    "import": "./src/index.mjs",
+    "require": "./src/index.cjs"
+  },
+  "types": "./types/apidom-overlay.d.ts",
+  "scripts": {
+    "build": "npm run clean && run-p --max-parallel ${CPU_CORES:-2} typescript:declaration build:es build:cjs build:umd:browser",
+    "build:es": "cross-env BABEL_ENV=es babel src --out-dir src --extensions '.ts' --out-file-extension '.mjs' --root-mode 'upward'",
+    "build:cjs": "cross-env BABEL_ENV=cjs babel src --out-dir src --extensions '.ts' --out-file-extension '.cjs' --root-mode 'upward'",
+    "build:umd:browser": "cross-env BABEL_ENV=browser webpack --config config/webpack/browser.config.js --progress",
+    "lint": "eslint ./",
+    "lint:fix": "eslint ./ --fix",
+    "clean": "rimraf --glob 'src/**/*.mjs' 'src/**/*.cjs' 'test/**/*.mjs' ./dist ./types",
+    "test": "npm run build:es && cross-env BABEL_ENV=es babel test --out-dir test --extensions '.ts' --out-file-extension '.mjs' --root-mode 'upward' && cross-env NODE_ENV=test mocha",
+    "test:update-snapshots": "cross-env UPDATE_SNAPSHOT=1 BABEL_ENV=cjs mocha",
+    "typescript:check-types": "tsc --noEmit",
+    "typescript:declaration": "tsc -p tsconfig.declaration.json && api-extractor run -l -c ./config/api-extractor/api-extractor.json",
+    "prepack": "copyfiles -u 3 ../../LICENSES/* LICENSES && copyfiles -u 2 ../../NOTICE .",
+    "postpack": "rimraf NOTICE LICENSES"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/speclynx/apidom.git"
+  },
+  "author": "Vladimir Gorej",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@babel/runtime-corejs3": "^7.28.4",
+    "@speclynx/apidom-core": "4.3.1",
+    "@speclynx/apidom-datamodel": "4.3.1",
+    "@speclynx/apidom-error": "4.3.1",
+    "@speclynx/apidom-json-path": "4.3.1",
+    "@speclynx/apidom-ns-overlay-1": "4.3.1",
+    "@speclynx/apidom-reference": "4.3.1"
+  },
+  "files": [
+    "src/**/*.mjs",
+    "src/**/*.cjs",
+    "dist/",
+    "types/apidom-overlay.d.ts",
+    "LICENSES",
+    "NOTICE",
+    "README.md",
+    "CHANGELOG.md"
+  ]
+}

package/src/apply-uri.cjs

@@ -0,0 +1,80 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomNsOverlay = require("@speclynx/apidom-ns-overlay-1");
+var _apidomReference = require("@speclynx/apidom-reference");
+var _apply = require("./apply.cjs");
+var _OverlayError = _interopRequireDefault(require("./errors/OverlayError.cjs"));
+/**
+ * @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, _apidomReference.mergeOptions)(defaultOptions, options);
+
+  // parse the overlay document along with document attached to `extends` field (if present)
+  const overlayParseResult = await (0, _apidomReference.parse)(overlayURI, mergedOptions);
+  const overlayElement = overlayParseResult.api;
+  if (!(0, _apidomNsOverlay.isOverlay1Element)(overlayElement)) {
+    throw new _OverlayError.default(`Failed to parse overlay document "${overlayURI}"`);
+  }
+  let targetParseResult;
+  if (targetURI) {
+    const targetOptions = (0, _apidomReference.mergeOptions)(defaultOptions, options);
+    targetParseResult = await (0, _apidomReference.parse)(targetURI, targetOptions);
+  } else {
+    const extendsElement = overlayElement.get('extends');
+    targetParseResult = extendsElement?.meta?.get('parseResult');
+  }
+  if (!(0, _apidomDatamodel.isParseResultElement)(targetParseResult)) {
+    throw new _OverlayError.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.applyOverlayApiDOM)(overlayParseResult, targetParseResult, options);
+};
+var _default = exports.default = applyOverlay;

package/src/apply-uri.mjs

@@ -0,0 +1,74 @@
+import { isParseResultElement } from '@speclynx/apidom-datamodel';
+import { isOverlay1Element } from '@speclynx/apidom-ns-overlay-1';
+import { parse, mergeOptions } from '@speclynx/apidom-reference';
+import { applyOverlayApiDOM } from "./apply.mjs";
+import OverlayError from "./errors/OverlayError.mjs";
+/**
+ * @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 = mergeOptions(defaultOptions, options);
+
+  // parse the overlay document along with document attached to `extends` field (if present)
+  const overlayParseResult = await parse(overlayURI, mergedOptions);
+  const overlayElement = overlayParseResult.api;
+  if (!isOverlay1Element(overlayElement)) {
+    throw new OverlayError(`Failed to parse overlay document "${overlayURI}"`);
+  }
+  let targetParseResult;
+  if (targetURI) {
+    const targetOptions = mergeOptions(defaultOptions, options);
+    targetParseResult = await parse(targetURI, targetOptions);
+  } else {
+    const extendsElement = overlayElement.get('extends');
+    targetParseResult = extendsElement?.meta?.get('parseResult');
+  }
+  if (!isParseResultElement(targetParseResult)) {
+    throw new OverlayError('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 applyOverlayApiDOM(overlayParseResult, targetParseResult, options);
+};
+export default applyOverlay;

package/src/apply.cjs

@@ -0,0 +1,243 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.applyUpdateAction = exports.applyRemoveAction = exports.applyOverlayApiDOM = exports.applyCopyAction = exports.applyAction = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomJsonPath = require("@speclynx/apidom-json-path");
+var _apidomNsOverlay = require("@speclynx/apidom-ns-overlay-1");
+var _OverlayError = _interopRequireDefault(require("./errors/OverlayError.cjs"));
+var _validate = require("./validate.cjs");
+/**
+ * @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 = (0, _apidomDatamodel.isObjectElement)(target);
+    const sourceIsObject = (0, _apidomDatamodel.isObjectElement)(source);
+    const targetIsArray = (0, _apidomDatamodel.isArrayElement)(target);
+    const sourceIsArray = (0, _apidomDatamodel.isArrayElement)(source);
+    if (targetIsObject !== sourceIsObject || targetIsArray !== sourceIsArray) {
+      throw new _OverlayError.default(`Incompatible types in overlay merge: cannot merge ` + `${targetIsObject ? 'object' : targetIsArray ? 'array' : 'primitive'} with ` + `${sourceIsObject ? 'object' : sourceIsArray ? 'array' : 'primitive'}`);
+    }
+    return (0, _apidomCore.deepmerge)(target, source, options);
+  };
+};
+
+/**
+ * Merges a value into a target node following Overlay spec semantics.
+ */
+const mergeValue = (targetElement, sourceElement, options = defaultApplyOptions) => {
+  const targetIsObject = (0, _apidomDatamodel.isObjectElement)(targetElement);
+  const targetIsArray = (0, _apidomDatamodel.isArrayElement)(targetElement);
+  const sourceIsObject = (0, _apidomDatamodel.isObjectElement)(sourceElement);
+  const sourceIsArray = (0, _apidomDatamodel.isArrayElement)(sourceElement);
+  const clone = options.immutable;
+  if (targetIsObject && sourceIsObject || targetIsArray && sourceIsArray) {
+    const mergeOpts = {
+      clone,
+      customMerge: overlayCustomMerge,
+      ...options.deepmerge
+    };
+    return (0, _apidomCore.deepmerge)(targetElement, sourceElement, mergeOpts);
+  }
+  if (!targetIsObject && !targetIsArray && !sourceIsObject && !sourceIsArray) {
+    return clone ? (0, _apidomDatamodel.cloneDeep)(sourceElement) : sourceElement;
+  }
+  throw new _OverlayError.default(`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 = _apidomJsonPath.NormalizedPath.to(normalizedPath);
+  if (selectors.length === 0) return null; // root — no parent
+  const key = selectors[selectors.length - 1];
+  const parentPath = _apidomJsonPath.NormalizedPath.from(selectors.slice(0, -1));
+  const [parent] = (0, _apidomJsonPath.evaluate)(root, parentPath);
+  return {
+    parent,
+    key
+  };
+};
+
+/**
+ * Applies an update action to matched nodes.
+ * @public
+ */
+const applyUpdateAction = (normalizedPaths, updateValue, targetElement, options = defaultApplyOptions) => {
+  let result = options.immutable ? (0, _apidomDatamodel.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 ((0, _apidomDatamodel.isObjectElement)(parent)) {
+      const current = parent.get(key);
+      if (current !== undefined) {
+        parent.set(key, mergeValue(current, updateValue, options));
+      }
+    } else if ((0, _apidomDatamodel.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
+ */
+exports.applyUpdateAction = applyUpdateAction;
+const applyCopyAction = (normalizedPaths, copyExpression, targetElement, options = defaultApplyOptions) => {
+  const sourceMatches = (0, _apidomJsonPath.evaluate)(targetElement, copyExpression);
+  if (sourceMatches.length === 0) {
+    throw new _OverlayError.default(`Copy source JSONPath "${copyExpression}" selected zero nodes`);
+  }
+  if (sourceMatches.length > 1) {
+    throw new _OverlayError.default(`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
+ */
+exports.applyCopyAction = applyCopyAction;
+const applyRemoveAction = (normalizedPaths, targetElement, options = defaultApplyOptions) => {
+  const result = options.immutable ? (0, _apidomDatamodel.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.default('Cannot remove the root node');
+    }
+    const {
+      parent,
+      key
+    } = resolved;
+    if ((0, _apidomDatamodel.isObjectElement)(parent)) {
+      parent.remove(key);
+    } else if ((0, _apidomDatamodel.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
+ */
+exports.applyRemoveAction = applyRemoveAction;
+const applyAction = (actionElement, targetElement, options = defaultApplyOptions) => {
+  const actionValidation = (0, _validate.validateAction)(actionElement);
+  if (!actionValidation.valid) throw actionValidation.error;
+  const targetExpression = (0, _apidomCore.toValue)(actionElement.target);
+  const matches = [];
+  const normalizedPaths = [];
+  (0, _apidomJsonPath.evaluate)(targetElement, targetExpression, {
+    callback: (value, normalizedPath) => {
+      matches.push(value);
+      normalizedPaths.push(normalizedPath);
+    }
+  });
+  if (matches.length === 0) {
+    if (options.strict) {
+      throw new _OverlayError.default(`Action target "${targetExpression}" matched zero nodes (strict mode)`, {
+        action: actionElement
+      });
+    }
+    return targetElement;
+  }
+  try {
+    // remove action
+    const removeValue = actionElement.removeField;
+    if (removeValue !== undefined && (0, _apidomCore.toValue)(removeValue) === true) {
+      return applyRemoveAction(normalizedPaths, targetElement, options);
+    }
+
+    // update action
+    if (actionElement.update !== undefined) {
+      const nodesValidation = (0, _validate.validateTargetNodes)(matches);
+      if (!nodesValidation.valid) throw nodesValidation.error;
+      return applyUpdateAction(normalizedPaths, actionElement.update, targetElement, options);
+    }
+
+    // copy action
+    if (actionElement.copy !== undefined) {
+      const nodesValidation = (0, _validate.validateTargetNodes)(matches);
+      if (!nodesValidation.valid) throw nodesValidation.error;
+      const copyExpression = (0, _apidomCore.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.default && !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
+ */
+exports.applyAction = applyAction;
+const applyOverlayApiDOM = (overlayElement, targetElement, options = defaultApplyOptions) => {
+  const overlay = overlayElement instanceof _apidomDatamodel.ParseResultElement ? overlayElement.api : overlayElement;
+  if (!(0, _apidomNsOverlay.isOverlay1Element)(overlay)) {
+    throw new _OverlayError.default('First argument must be an Overlay 1.x document');
+  }
+  let target;
+  if (targetElement instanceof _apidomDatamodel.ParseResultElement) {
+    if (targetElement.api === undefined) {
+      throw new _OverlayError.default('Target ParseResultElement contains no API element');
+    }
+    target = targetElement.api;
+  } else {
+    target = targetElement;
+  }
+  if (!(0, _apidomDatamodel.isArrayElement)(overlay.actions)) {
+    return targetElement;
+  }
+  for (const action of overlay.actions) {
+    target = applyAction(action, target, options);
+  }
+  if (targetElement instanceof _apidomDatamodel.ParseResultElement) {
+    targetElement.replaceResult(target);
+    return targetElement;
+  }
+  return target;
+};
+exports.applyOverlayApiDOM = applyOverlayApiDOM;