@mintlify/common 1.0.1131 → 1.0.1133

package/dist/openapi/fetchYamlDocument.d.ts

@@ -0,0 +1,2 @@
+/** Fetches and parses a JSON or YAML document from a URL with exponential backoff. */
+export declare const fetchYamlDocument: (url: string) => Promise<unknown>;

package/dist/openapi/fetchYamlDocument.js

@@ -0,0 +1,23 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import yaml from 'js-yaml';
+import { exponentialBackoff } from '../exponentialBackoff.js';
+/** Fetches and parses a JSON or YAML document from a URL with exponential backoff. */
+export const fetchYamlDocument = (url) => __awaiter(void 0, void 0, void 0, function* () {
+    const response = yield exponentialBackoff(() => __awaiter(void 0, void 0, void 0, function* () {
+        const res = yield fetch(url);
+        if (!res.ok) {
+            throw new Error(`${res.status} ${res.statusText}`);
+        }
+        return res;
+    }));
+    const data = yield response.text();
+    return yaml.load(data);
+});

package/dist/openapi/getOpenApiDocumentFromUrl.d.ts

@@ -1,2 +1,10 @@
 import type { OpenAPI } from 'openapi-types';
-export declare const getOpenApiDocumentFromUrl: (url: string) => Promise<OpenAPI.Document>;
+import { type LoadedOverlay } from './overlay/applyOverlay.js';
+export declare const getOpenApiDocumentFromUrl: (url: string, options?: {
+    overlays?: readonly LoadedOverlay[];
+    /**
+     * Overrides fetching and parsing of the spec URL. Hosted environments substitute an
+     * SSRF-safe fetch that blocks private, loopback, and metadata targets across redirects.
+     */
+    fetchRemoteDocument?: (url: string) => Promise<unknown>;
+}) => Promise<OpenAPI.Document>;

package/dist/openapi/getOpenApiDocumentFromUrl.js

@@ -7,19 +7,19 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import yaml from 'js-yaml';
-import { exponentialBackoff } from '../exponentialBackoff.js';
+import { fetchYamlDocument } from './fetchYamlDocument.js';
+import { applyOverlays } from './overlay/applyOverlay.js';
 import { validate } from './validate.js';
-export const getOpenApiDocumentFromUrl = (url) => __awaiter(void 0, void 0, void 0, function* () {
-    const response = yield exponentialBackoff(() => __awaiter(void 0, void 0, void 0, function* () {
-        const res = yield fetch(url);
-        if (!res.ok) {
-            throw new Error(`${res.status} ${res.statusText}`);
-        }
-        return res;
-    }));
-    const data = yield response.text();
-    const openApiDocument = yaml.load(data);
+export const getOpenApiDocumentFromUrl = (url_1, ...args_1) => __awaiter(void 0, [url_1, ...args_1], void 0, function* (url, options = {}) {
+    const fetched = options.fetchRemoteDocument
+        ? yield options.fetchRemoteDocument(url)
+        : yield fetchYamlDocument(url);
+    if (fetched == undefined) {
+        throw Error('Could not parse OpenAPI document.');
+    }
+    const openApiDocument = options.overlays && options.overlays.length > 0
+        ? applyOverlays(fetched, options.overlays)
+        : fetched;
     if (openApiDocument == undefined) {
         throw Error('Could not parse OpenAPI document.');
     }

package/dist/openapi/index.d.ts

@@ -1,4 +1,8 @@
 export { getOpenApiOperationMethodAndEndpoint } from './getOpenApiOperationMethodAndEndpoint.js';
+export { applyOverlay, applyOverlays, type LoadedOverlay } from './overlay/applyOverlay.js';
+export { OverlayApplicationError } from './overlay/errors.js';
+export { createOverlayRegistry, normalizeOverlayKey, parseLoadedOverlayDocument, resolveExtends, resolveOverlaysForSpec, type CreateOverlayRegistryOptions, type DiscoveredOverlay, type OverlayRegistry, } from './overlay/overlayRegistry.js';
+export { fetchYamlDocument } from './fetchYamlDocument.js';
 export { truncateCircularReferences } from './truncateCircularReferences.js';
 export { parseOpenApiString, potentiallyParseOpenApiString, parseOpenApiSchemaString, } from './parseOpenApiString.js';
 export { getOpenApiTitleAndDescription } from './getOpenApiTitleAndDescription.js';

package/dist/openapi/index.js

@@ -1,4 +1,8 @@
 export { getOpenApiOperationMethodAndEndpoint } from './getOpenApiOperationMethodAndEndpoint.js';
+export { applyOverlay, applyOverlays } from './overlay/applyOverlay.js';
+export { OverlayApplicationError } from './overlay/errors.js';
+export { createOverlayRegistry, normalizeOverlayKey, parseLoadedOverlayDocument, resolveExtends, resolveOverlaysForSpec, } from './overlay/overlayRegistry.js';
+export { fetchYamlDocument } from './fetchYamlDocument.js';
 export { truncateCircularReferences } from './truncateCircularReferences.js';
 export { parseOpenApiString, potentiallyParseOpenApiString, parseOpenApiSchemaString, } from './parseOpenApiString.js';
 export { getOpenApiTitleAndDescription } from './getOpenApiTitleAndDescription.js';

package/dist/openapi/overlay/applyOverlay.d.ts

@@ -0,0 +1,27 @@
+import type { OverlayDocument } from '@mintlify/validation';
+import { type JsonValue } from './jsonValue.js';
+export type LoadedOverlay = {
+    document: OverlayDocument;
+    /** Path or URL of the overlay file, used in error messages. */
+    location?: string;
+};
+/**
+ * Guardrails against pathological overlay documents tying up shared workers: a cap on
+ * actions per overlay and a wall-clock budget per application run, checked before each
+ * action (a single JSONPath evaluation cannot be preempted, but repeated expensive
+ * actions are bounded).
+ */
+export declare const MAX_OVERLAY_ACTIONS = 1000;
+export declare const OVERLAY_TIME_BUDGET_MS = 30000;
+/**
+ * Applies one Overlay document to a parsed OpenAPI description, returning a
+ * transformed copy. Throws {@link OverlayApplicationError} on failure.
+ */
+export declare function applyOverlay(document: unknown, overlay: OverlayDocument, options?: {
+    source?: string;
+    timeBudgetMs?: number;
+}): JsonValue;
+/** Applies Overlay documents in order, returning a transformed copy. */
+export declare function applyOverlays(document: unknown, overlays: readonly LoadedOverlay[], options?: {
+    timeBudgetMs?: number;
+}): unknown;

package/dist/openapi/overlay/applyOverlay.js

@@ -0,0 +1,360 @@
+// json-p3 is pinned to exactly 2.2.2: the 2.3.0 release was published without its
+// TypeScript declaration files. Unpin once a typed release (2.3.1+) ships.
+import { check as isIRegexpPattern } from 'iregexp-check';
+import { FunctionExpressionType, JSONPathEnvironment } from 'json-p3';
+import { RE2JS } from 're2js';
+import { OverlayApplicationError } from './errors.js';
+import { deepCloneJson, isJsonArray, isJsonObject, isJsonPrimitive, isJsonValue, setOwnProperty, toJsonValue, } from './jsonValue.js';
+import { IncompatibleMergeError, mergeObjectInto } from './mergeValue.js';
+/** Caps on regex filter functions, enforced mid-query by the guarded environment. */
+const MAX_FILTER_REGEX_PATTERN_LENGTH = 512;
+const MAX_FILTER_REGEX_INPUT_LENGTH = 100000;
+class QueryBudgetError extends Error {
+}
+/**
+ * Deadline consulted by the guarded match()/search() implementations, so a single
+ * long-running filter evaluation is interrupted mid-query instead of only between
+ * actions. Module-level is safe: overlay application is fully synchronous.
+ */
+let activeQueryDeadline;
+function guardFilterRegexCall(input, pattern) {
+    if (activeQueryDeadline !== undefined && Date.now() >= activeQueryDeadline) {
+        throw new QueryBudgetError('JSONPath evaluation exceeded the overlay processing budget');
+    }
+    if (typeof pattern === 'string' && pattern.length > MAX_FILTER_REGEX_PATTERN_LENGTH) {
+        throw new QueryBudgetError(`JSONPath regex patterns are limited to ${MAX_FILTER_REGEX_PATTERN_LENGTH} characters`);
+    }
+    if (typeof input === 'string' && input.length > MAX_FILTER_REGEX_INPUT_LENGTH) {
+        throw new QueryBudgetError(`JSONPath regex input strings are limited to ${MAX_FILTER_REGEX_INPUT_LENGTH} characters`);
+    }
+}
+/**
+ * Maps an I-Regexp pattern for RE2 evaluation (RFC 9485 semantics): `.` outside
+ * character classes matches any character except CR/LF, and `^`/`$` outside character
+ * classes are literal characters, not anchors. RE2 handles surrogate pairs natively so
+ * no astral-pair alternation is needed.
+ */
+function mapIRegexpForRE2(pattern) {
+    let escaped = false;
+    let charClass = false;
+    const parts = [];
+    for (const ch of pattern) {
+        if (escaped) {
+            parts.push(ch);
+            escaped = false;
+            continue;
+        }
+        if (ch === '\\') {
+            escaped = true;
+            parts.push(ch);
+        }
+        else if (ch === '.' && !charClass) {
+            parts.push('[^\\r\\n]');
+        }
+        else if ((ch === '^' || ch === '$') && !charClass) {
+            parts.push(`\\${ch}`);
+        }
+        else {
+            if (ch === '[')
+                charClass = true;
+            else if (ch === ']')
+                charClass = false;
+            parts.push(ch);
+        }
+    }
+    return parts.join('');
+}
+const RE2_CACHE_LIMIT = 64;
+const re2Cache = new Map();
+/** Compiles an I-Regexp pattern to a linear-time RE2 matcher, or null when invalid. */
+function compileIRegexp(pattern) {
+    const cached = re2Cache.get(pattern);
+    if (cached !== undefined)
+        return cached;
+    let compiled = null;
+    if (isIRegexpPattern(pattern)) {
+        try {
+            compiled = RE2JS.compile(mapIRegexpForRE2(pattern));
+        }
+        catch (_a) {
+            compiled = null;
+        }
+    }
+    if (re2Cache.size >= RE2_CACHE_LIMIT)
+        re2Cache.clear();
+    re2Cache.set(pattern, compiled);
+    return compiled;
+}
+/**
+ * RFC 9535 match()/search() evaluated with RE2 (via re2js), which guarantees linear-time
+ * matching with no backtracking, so a customer-supplied pattern cannot produce
+ * catastrophic-backtracking CPU blowups (CWE-1333). Non-I-Regexp or invalid patterns
+ * evaluate to false, matching json-p3's standard behavior.
+ */
+class LinearTimeRegexFilter {
+    constructor(fullMatch) {
+        this.fullMatch = fullMatch;
+        this.argTypes = [FunctionExpressionType.ValueType, FunctionExpressionType.ValueType];
+        this.returnType = FunctionExpressionType.LogicalType;
+    }
+    call(...args) {
+        const [s, pattern] = args;
+        guardFilterRegexCall(s, pattern);
+        if (typeof s !== 'string' || typeof pattern !== 'string')
+            return false;
+        const re = compileIRegexp(pattern);
+        if (re == null)
+            return false;
+        const matcher = re.matcher(s);
+        // RFC 9535: match() full-matches, search() finds a substring match. I-Regexp has no
+        // anchor metacharacters; ^ and $ are escaped to literals in the RE2 mapping.
+        return this.fullMatch ? matcher.matches() : matcher.find();
+    }
+}
+// Recursive descent depth is capped by the environment default (50); match()/search()
+// run on a linear-time engine and check the deadline, so a single query's cost stays
+// bounded even mid-evaluation.
+const overlayQueryEnvironment = new JSONPathEnvironment();
+overlayQueryEnvironment.functionRegister.set('match', new LinearTimeRegexFilter(true));
+overlayQueryEnvironment.functionRegister.set('search', new LinearTimeRegexFilter(false));
+function queryNodes(document, expression, expressionLabel, fail) {
+    const nodes = [];
+    try {
+        for (const node of overlayQueryEnvironment.query(expression, document).nodes) {
+            if (node.value === undefined || !isJsonValue(node.value))
+                continue;
+            nodes.push({ value: node.value, path: [...node.location] });
+        }
+    }
+    catch (error) {
+        if (error instanceof QueryBudgetError) {
+            fail(error.message);
+        }
+        fail(`invalid JSONPath expression ${expressionLabel}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const seen = new Set();
+    return nodes.filter((node) => {
+        const key = JSON.stringify(node.path);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function resolvePath(document, path, fail) {
+    let current = document;
+    for (const segment of path) {
+        if (typeof segment === 'number') {
+            if (!isJsonArray(current)) {
+                fail(`expected an array while resolving the selected node's location`);
+            }
+            const next = current[segment];
+            if (next === undefined) {
+                fail(`the selected node's location no longer exists in the document`);
+            }
+            current = next;
+        }
+        else {
+            if (!isJsonObject(current)) {
+                fail(`expected an object while resolving the selected node's location`);
+            }
+            const next = current[segment];
+            if (next === undefined) {
+                fail(`the selected node's location no longer exists in the document`);
+            }
+            current = next;
+        }
+    }
+    return current;
+}
+// Deeper nodes first, then descending array indexes, so paths stay valid mid-removal.
+function removalOrder(a, b) {
+    if (a.path.length !== b.path.length)
+        return b.path.length - a.path.length;
+    for (let i = 0; i < a.path.length; i++) {
+        const segmentA = a.path[i];
+        const segmentB = b.path[i];
+        if (segmentA === segmentB || segmentA === undefined || segmentB === undefined)
+            continue;
+        if (typeof segmentA === 'number' && typeof segmentB === 'number') {
+            return segmentB - segmentA;
+        }
+        return String(segmentA) < String(segmentB) ? -1 : 1;
+    }
+    return 0;
+}
+function removeNodes(document, nodes, fail) {
+    const sorted = [...nodes].sort(removalOrder);
+    for (const node of sorted) {
+        if (node.path.length === 0) {
+            fail('the document root cannot be removed');
+        }
+        const parent = resolvePath(document, node.path.slice(0, -1), fail);
+        const key = node.path[node.path.length - 1];
+        if (isJsonArray(parent) && typeof key === 'number') {
+            parent.splice(key, 1);
+        }
+        else if (isJsonObject(parent) && typeof key === 'string') {
+            delete parent[key];
+        }
+        else {
+            fail('the selected node cannot be removed from its parent');
+        }
+    }
+}
+function nodeKind(value) {
+    if (isJsonObject(value))
+        return 'object';
+    if (isJsonArray(value))
+        return 'array';
+    return 'primitive';
+}
+function applyValueToNodes(document, nodes, value, fail) {
+    const kinds = new Set(nodes.map((node) => nodeKind(node.value)));
+    if (kinds.size > 1) {
+        fail('the target expression selects nodes of mixed types. Selected nodes must be all objects, all arrays, or all primitives');
+    }
+    for (const node of nodes) {
+        const target = node.value;
+        if (isJsonObject(target)) {
+            if (!isJsonObject(value)) {
+                fail('the value must be an object to merge with the selected object nodes');
+            }
+            try {
+                mergeObjectInto(target, value);
+            }
+            catch (error) {
+                if (error instanceof IncompatibleMergeError)
+                    fail(error.message);
+                throw error;
+            }
+        }
+        else if (isJsonArray(target)) {
+            if (isJsonArray(value)) {
+                for (const entry of value) {
+                    target.push(deepCloneJson(entry));
+                }
+            }
+            else {
+                target.push(deepCloneJson(value));
+            }
+        }
+        else {
+            if (!isJsonPrimitive(value)) {
+                fail('the value must be a primitive to replace the selected primitive nodes');
+            }
+            if (node.path.length === 0) {
+                fail('the document root cannot be replaced with a primitive value');
+            }
+            const parent = resolvePath(document, node.path.slice(0, -1), fail);
+            const key = node.path[node.path.length - 1];
+            if (isJsonArray(parent) && typeof key === 'number') {
+                parent[key] = value;
+            }
+            else if (isJsonObject(parent) && typeof key === 'string') {
+                setOwnProperty(parent, key, value);
+            }
+            else {
+                fail('the selected node cannot be replaced in its parent');
+            }
+        }
+    }
+}
+function applyAction(document, action, actionIndex, overlaySource) {
+    const fail = (message) => {
+        throw new OverlayApplicationError({
+            message,
+            overlaySource,
+            actionIndex,
+            target: action.target,
+        });
+    };
+    const targetNodes = queryNodes(document, action.target, `"${action.target}"`, fail);
+    if (action.remove === true) {
+        removeNodes(document, targetNodes, fail);
+        return;
+    }
+    // Spec: a zero-match target succeeds without changing the document.
+    if (targetNodes.length === 0)
+        return;
+    let value;
+    if (action.copy !== undefined) {
+        const copyNodes = queryNodes(document, action.copy, `"${action.copy}" (copy)`, fail);
+        const single = copyNodes[0];
+        if (copyNodes.length !== 1 || single === undefined) {
+            fail(`the "copy" expression "${action.copy}" must select exactly one node, but selected ${copyNodes.length}`);
+        }
+        value = deepCloneJson(single.value);
+    }
+    else if (action.update !== undefined) {
+        if (!isJsonValue(action.update)) {
+            fail('the "update" value is not JSON-representable');
+        }
+        value = action.update;
+    }
+    else {
+        return;
+    }
+    applyValueToNodes(document, targetNodes, value, fail);
+}
+/**
+ * Guardrails against pathological overlay documents tying up shared workers: a cap on
+ * actions per overlay and a wall-clock budget per application run, checked before each
+ * action (a single JSONPath evaluation cannot be preempted, but repeated expensive
+ * actions are bounded).
+ */
+export const MAX_OVERLAY_ACTIONS = 1000;
+export const OVERLAY_TIME_BUDGET_MS = 30000;
+function applyOverlayActions(document, overlay, source, deadline, budgetMs) {
+    var _a;
+    if (overlay.actions.length > MAX_OVERLAY_ACTIONS) {
+        const firstExcess = overlay.actions[MAX_OVERLAY_ACTIONS];
+        throw new OverlayApplicationError({
+            message: `the overlay declares ${overlay.actions.length} actions, above the supported maximum of ${MAX_OVERLAY_ACTIONS}`,
+            overlaySource: source,
+            actionIndex: MAX_OVERLAY_ACTIONS,
+            target: (_a = firstExcess === null || firstExcess === void 0 ? void 0 : firstExcess.target) !== null && _a !== void 0 ? _a : '',
+        });
+    }
+    activeQueryDeadline = deadline;
+    try {
+        overlay.actions.forEach((action, index) => {
+            if (Date.now() >= deadline) {
+                throw new OverlayApplicationError({
+                    message: `overlay application exceeded the ${budgetMs}ms processing budget`,
+                    overlaySource: source,
+                    actionIndex: index,
+                    target: action.target,
+                });
+            }
+            applyAction(document, action, index, source);
+        });
+    }
+    finally {
+        activeQueryDeadline = undefined;
+    }
+}
+/**
+ * Applies one Overlay document to a parsed OpenAPI description, returning a
+ * transformed copy. Throws {@link OverlayApplicationError} on failure.
+ */
+export function applyOverlay(document, overlay, options = {}) {
+    var _a;
+    const cloned = toJsonValue(document, 'OpenAPI document');
+    const budgetMs = (_a = options.timeBudgetMs) !== null && _a !== void 0 ? _a : OVERLAY_TIME_BUDGET_MS;
+    applyOverlayActions(cloned, overlay, options.source, Date.now() + budgetMs, budgetMs);
+    return cloned;
+}
+/** Applies Overlay documents in order, returning a transformed copy. */
+export function applyOverlays(document, overlays, options = {}) {
+    var _a;
+    if (overlays.length === 0)
+        return document;
+    const current = toJsonValue(document, 'OpenAPI document');
+    const budgetMs = (_a = options.timeBudgetMs) !== null && _a !== void 0 ? _a : OVERLAY_TIME_BUDGET_MS;
+    const deadline = Date.now() + budgetMs;
+    for (const { document: overlayDocument, location } of overlays) {
+        applyOverlayActions(current, overlayDocument, location, deadline, budgetMs);
+    }
+    return current;
+}

package/dist/openapi/overlay/errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Error thrown when an OpenAPI Overlay document cannot be applied to a target document.
+ * Carries enough context to point the customer at the exact failing action.
+ */
+export declare class OverlayApplicationError extends Error {
+    /** Path or URL of the overlay document, when known. */
+    overlaySource?: string;
+    /** Zero-based index of the failing action in the overlay's `actions` array. */
+    actionIndex: number;
+    /** The action's `target` JSONPath expression. */
+    target: string;
+    constructor({ message, overlaySource, actionIndex, target, }: {
+        message: string;
+        overlaySource?: string;
+        actionIndex: number;
+        target: string;
+    });
+}

package/dist/openapi/overlay/errors.js

@@ -0,0 +1,14 @@
+/**
+ * Error thrown when an OpenAPI Overlay document cannot be applied to a target document.
+ * Carries enough context to point the customer at the exact failing action.
+ */
+export class OverlayApplicationError extends Error {
+    constructor({ message, overlaySource, actionIndex, target, }) {
+        const sourceLabel = overlaySource ? ` in overlay ${overlaySource}` : '';
+        super(`Overlay action ${actionIndex + 1}${sourceLabel} (target: ${target}): ${message}`);
+        this.name = 'OverlayApplicationError';
+        this.overlaySource = overlaySource;
+        this.actionIndex = actionIndex;
+        this.target = target;
+    }
+}

package/dist/openapi/overlay/jsonValue.d.ts

@@ -0,0 +1,19 @@
+/** A JSON-representable value. Unlike json-p3's JSONValue, `undefined` is excluded. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export declare function isJsonPrimitive(value: JsonValue): value is string | number | boolean | null;
+export declare function isJsonObject(value: JsonValue): value is JsonObject;
+export declare function isJsonArray(value: JsonValue): value is JsonValue[];
+export declare function isJsonValue(value: unknown): value is JsonValue;
+/** Clones a parsed document into a JSON-representable value using JSON semantics. */
+export declare function toJsonValue(value: unknown, label: string): JsonValue;
+/**
+ * Writes an own data property without triggering prototype setters, so hostile keys
+ * like `__proto__` cannot pollute the prototype chain.
+ */
+export declare function setOwnProperty(target: JsonObject, key: string, value: JsonValue): void;
+export declare function deepCloneJson(value: JsonValue): JsonValue;

package/dist/openapi/overlay/jsonValue.js

@@ -0,0 +1,64 @@
+export function isJsonPrimitive(value) {
+    return value === null || typeof value !== 'object';
+}
+export function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function isJsonArray(value) {
+    return Array.isArray(value);
+}
+export function isJsonValue(value) {
+    if (value === null)
+        return true;
+    switch (typeof value) {
+        case 'string':
+        case 'boolean':
+            return true;
+        case 'number':
+            return Number.isFinite(value);
+        case 'object':
+            if (Array.isArray(value)) {
+                return value.every((entry) => isJsonValue(entry));
+            }
+            return Object.values(value).every((entry) => isJsonValue(entry));
+        default:
+            return false;
+    }
+}
+/** Clones a parsed document into a JSON-representable value using JSON semantics. */
+export function toJsonValue(value, label) {
+    let cloned;
+    try {
+        cloned = JSON.parse(JSON.stringify(value));
+    }
+    catch (error) {
+        throw new Error(`${label} is not JSON-serializable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (cloned === undefined || !isJsonValue(cloned)) {
+        throw new Error(`${label} is not a valid JSON document`);
+    }
+    return cloned;
+}
+/**
+ * Writes an own data property without triggering prototype setters, so hostile keys
+ * like `__proto__` cannot pollute the prototype chain.
+ */
+export function setOwnProperty(target, key, value) {
+    Object.defineProperty(target, key, {
+        value,
+        writable: true,
+        enumerable: true,
+        configurable: true,
+    });
+}
+export function deepCloneJson(value) {
+    if (isJsonPrimitive(value))
+        return value;
+    if (isJsonArray(value))
+        return value.map((entry) => deepCloneJson(entry));
+    const result = {};
+    for (const [key, entry] of Object.entries(value)) {
+        setOwnProperty(result, key, deepCloneJson(entry));
+    }
+    return result;
+}

package/dist/openapi/overlay/mergeValue.d.ts

@@ -0,0 +1,9 @@
+import { type JsonObject } from './jsonValue.js';
+export declare class IncompatibleMergeError extends Error {
+    constructor(propertyPath: string[]);
+}
+/**
+ * Recursively merges an overlay `update`/`copy` object into a target object per the
+ * Overlay Specification merge rules, mutating the target in place.
+ */
+export declare function mergeObjectInto(target: JsonObject, update: JsonObject, propertyPath?: string[]): void;

package/dist/openapi/overlay/mergeValue.js

@@ -0,0 +1,43 @@
+import { deepCloneJson, isJsonArray, isJsonObject, isJsonPrimitive, setOwnProperty, } from './jsonValue.js';
+export class IncompatibleMergeError extends Error {
+    constructor(propertyPath) {
+        super(`Cannot merge incompatible values at "${propertyPath.join('.')}". A primitive can only replace a primitive, an array can only be concatenated with an array, and an object can only be merged with an object.`);
+        this.name = 'IncompatibleMergeError';
+    }
+}
+/**
+ * Recursively merges an overlay `update`/`copy` object into a target object per the
+ * Overlay Specification merge rules, mutating the target in place.
+ */
+export function mergeObjectInto(target, update, propertyPath = []) {
+    for (const [key, updateValue] of Object.entries(update)) {
+        // Own-property checks and setOwnProperty writes block prototype pollution.
+        if (!Object.prototype.hasOwnProperty.call(target, key)) {
+            setOwnProperty(target, key, deepCloneJson(updateValue));
+            continue;
+        }
+        const targetValue = target[key];
+        if (targetValue === undefined) {
+            setOwnProperty(target, key, deepCloneJson(updateValue));
+            continue;
+        }
+        mergeValueInto(target, key, targetValue, updateValue, [...propertyPath, key]);
+    }
+}
+function mergeValueInto(parent, key, targetValue, updateValue, propertyPath) {
+    if (isJsonPrimitive(updateValue) && isJsonPrimitive(targetValue)) {
+        setOwnProperty(parent, key, updateValue);
+        return;
+    }
+    if (isJsonArray(updateValue) && isJsonArray(targetValue)) {
+        for (const entry of updateValue) {
+            targetValue.push(deepCloneJson(entry));
+        }
+        return;
+    }
+    if (isJsonObject(updateValue) && isJsonObject(targetValue)) {
+        mergeObjectInto(targetValue, updateValue, propertyPath);
+        return;
+    }
+    throw new IncompatibleMergeError(propertyPath);
+}