logixia 1.12.4 → 1.12.6

package/dist/safe-stringify-DJ66tW5I.mjs

@@ -0,0 +1,118 @@
+//#region src/utils/safe-stringify.ts
+/** Build a JSONPath like `$["a"][0]["b"]` for a decycle pointer. */
+function jsonPath(parts) {
+	let path = "$";
+	for (const p of parts) path += typeof p === "number" ? `[${p}]` : `[${JSON.stringify(p)}]`;
+	return path;
+}
+/**
+* Serialize any value to JSON without throwing on circular references or BigInt.
+* Circular refs become `"[Circular]"` (or `{ $ref }` pointers when `decycle`).
+*/
+function safeStringify(value, options = {}) {
+	const { indent, deterministic = false, decycle = false, bigint = "string" } = options;
+	if (decycle) return JSON.stringify(decycleValue(value, bigint), void 0, indent);
+	const seen = /* @__PURE__ */ new WeakSet();
+	const transform = (val) => {
+		if (typeof val === "bigint") return bigint === "number" ? Number(val) : val.toString();
+		if (typeof val === "function") return `[Function: ${val.name || "anonymous"}]`;
+		if (typeof val === "symbol") return val.toString();
+		if (val === null || typeof val !== "object") return val;
+		if (seen.has(val)) return "[Circular]";
+		seen.add(val);
+		let out;
+		const toJSON = val.toJSON;
+		if (Array.isArray(val)) out = val.map((item) => transform(item));
+		else if (typeof toJSON === "function") out = transform(toJSON.call(val));
+		else {
+			const rec = val;
+			const keys = deterministic ? Object.keys(rec).sort() : Object.keys(rec);
+			const obj = {};
+			for (const k of keys) {
+				if (k === "__proto__" || k === "constructor" || k === "prototype") continue;
+				obj[k] = transform(rec[k]);
+			}
+			out = obj;
+		}
+		seen.delete(val);
+		return out;
+	};
+	return JSON.stringify(transform(value), void 0, indent);
+}
+/**
+* Replace repeated object references with round-trippable `{ "$ref": "$..." }`
+* JSONPath pointers (the classic Crockford decycle). Pair with {@link retrocycle}
+* to reconstruct the original shared/circular graph.
+*/
+function decycleValue(value, bigint = "string") {
+	const paths = /* @__PURE__ */ new WeakMap();
+	const walk = (val, path) => {
+		if (typeof val === "bigint") return bigint === "number" ? Number(val) : val.toString();
+		if (val === null || typeof val !== "object") return val;
+		if (val instanceof Date) return val.toISOString();
+		const existing = paths.get(val);
+		if (existing !== void 0) return { $ref: existing };
+		paths.set(val, jsonPath(path));
+		if (Array.isArray(val)) return val.map((item, i) => walk(item, [...path, i]));
+		const rec = val;
+		const obj = {};
+		for (const k of Object.keys(rec)) {
+			if (k === "__proto__" || k === "constructor" || k === "prototype") continue;
+			obj[k] = walk(rec[k], [...path, k]);
+		}
+		return obj;
+	};
+	return walk(value, []);
+}
+/**
+* Inverse of {@link decycleValue}: resolve `{ "$ref": "$..." }` pointers back
+* into the live object graph (mutates and returns the parsed input).
+*/
+function retrocycle(root) {
+	const refRe = /^\$(?:\[(?:\d+|"(?:[^"\\]|\\.)*")\])*$/;
+	const resolve = (path) => {
+		const segs = [];
+		const partRe = /\[(\d+|"(?:[^"\\]|\\.)*")\]/g;
+		let m;
+		while ((m = partRe.exec(path)) !== null) {
+			const raw = m[1];
+			segs.push(raw.startsWith("\"") ? JSON.parse(raw) : Number(raw));
+		}
+		let node = root;
+		for (const s of segs) node = node[s];
+		return node;
+	};
+	const walk = (val) => {
+		if (val === null || typeof val !== "object") return;
+		const rec = val;
+		for (const k of Object.keys(rec)) {
+			const child = rec[k];
+			if (child !== null && typeof child === "object" && typeof child.$ref === "string" && refRe.test(child.$ref)) rec[k] = resolve(child.$ref);
+			else walk(child);
+		}
+	};
+	walk(root);
+	return root;
+}
+/**
+* `JSON.stringify` for log output. Takes the plain fast path first and only
+* falls back to {@link safeStringify} when that throws (a cycle, a BigInt, a
+* throwing `toJSON`), so a bad payload costs nothing until it shows up.
+* Never throws: if even the safe walk fails, the value is replaced by a marker.
+*/
+function stringifyForLog(value) {
+	try {
+		return JSON.stringify(value);
+	} catch {
+		try {
+			return safeStringify(value);
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			return JSON.stringify(`[Unserializable: ${reason}]`);
+		}
+	}
+}
+
+//#endregion
+export { stringifyForLog as i, retrocycle as n, safeStringify as r, decycleValue as t };
+//# sourceMappingURL=safe-stringify-DJ66tW5I.mjs.map

package/dist/safe-stringify-DJ66tW5I.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-stringify-DJ66tW5I.mjs","names":["out: unknown","obj: Record<string, unknown>","segs: Array<string | number>","m: RegExpExecArray | null","node: unknown"],"sources":["../src/utils/safe-stringify.ts"],"sourcesContent":["/**\n * logixia — robust JSON serialization for log payloads.\n *\n * Modern Winston/Pino already neutralize circular refs to `[Circular]` (via\n * safe-stable-stringify / fast-safe-stringify), so merely \"surviving cycles\" is\n * not a differentiator. This goes one notch further:\n *\n *  - **BigInt** → serialized (as a string by default; JSON.stringify throws on\n *    BigInt, which silently breaks logging of e.g. DB bigint ids).\n *  - **Deterministic key order** (optional) so identical objects hash/diff equal.\n *  - **True decycle** (optional) — replace repeated references with JSONPath\n *    `$ref` pointers that round-trip back to the original object graph, instead\n *    of the lossy `[Circular]` tag. Useful when you need to reconstruct shared\n *    structure downstream.\n *\n * @example\n * ```ts\n * safeStringify({ id: 10n, self: obj });          // → BigInt + cycle safe\n * safeStringify(graph, { decycle: true });         // → round-trippable $ref pointers\n * const back = retrocycle(JSON.parse(json));       // → reconstruct shared refs\n * ```\n */\n\nexport interface SafeStringifyOptions {\n  /** Indentation passed to JSON.stringify (number of spaces or a string). */\n  indent?: number | string;\n  /** Sort object keys for deterministic output. Default: false. */\n  deterministic?: boolean;\n  /**\n   * Use round-trippable `$ref` JSONPath pointers for repeated references instead\n   * of the lossy \"[Circular]\" tag. Default: false.\n   */\n  decycle?: boolean;\n  /** How to render BigInt: 'string' (default) or 'number' (may lose precision). */\n  bigint?: 'string' | 'number';\n}\n\n/** Build a JSONPath like `$[\"a\"][0][\"b\"]` for a decycle pointer. */\nfunction jsonPath(parts: Array<string | number>): string {\n  let path = '$';\n  for (const p of parts) {\n    path += typeof p === 'number' ? `[${p}]` : `[${JSON.stringify(p)}]`;\n  }\n  return path;\n}\n\n/**\n * Serialize any value to JSON without throwing on circular references or BigInt.\n * Circular refs become `\"[Circular]\"` (or `{ $ref }` pointers when `decycle`).\n */\nexport function safeStringify(value: unknown, options: SafeStringifyOptions = {}): string {\n  const { indent, deterministic = false, decycle = false, bigint = 'string' } = options;\n\n  if (decycle) {\n    return JSON.stringify(decycleValue(value, bigint), undefined, indent);\n  }\n\n  const seen = new WeakSet<object>();\n\n  const transform = (val: unknown): unknown => {\n    if (typeof val === 'bigint') return bigint === 'number' ? Number(val) : val.toString();\n    if (typeof val === 'function') return `[Function: ${val.name || 'anonymous'}]`;\n    if (typeof val === 'symbol') return val.toString();\n    if (val === null || typeof val !== 'object') return val;\n\n    if (seen.has(val)) return '[Circular]';\n    seen.add(val);\n\n    let out: unknown;\n    const toJSON = (val as { toJSON?: unknown }).toJSON;\n    if (Array.isArray(val)) {\n      out = val.map((item) => transform(item));\n    } else if (typeof toJSON === 'function') {\n      // Dates, URLs, Buffers and classes with their own toJSON print the way\n      // JSON.stringify would; a toJSON that returns `this` hits the cycle check.\n      out = transform(toJSON.call(val));\n    } else {\n      const rec = val as Record<string, unknown>;\n      const keys = deterministic ? Object.keys(rec).sort() : Object.keys(rec);\n      const obj: Record<string, unknown> = {};\n      for (const k of keys) {\n        if (k === '__proto__' || k === 'constructor' || k === 'prototype') continue;\n        obj[k] = transform(rec[k]);\n      }\n      out = obj;\n    }\n    // Allow the same object to appear in sibling branches (not a true cycle):\n    // remove from `seen` after we finish its subtree.\n    seen.delete(val);\n    return out;\n  };\n\n  return JSON.stringify(transform(value), undefined, indent);\n}\n\n/**\n * Replace repeated object references with round-trippable `{ \"$ref\": \"$...\" }`\n * JSONPath pointers (the classic Crockford decycle). Pair with {@link retrocycle}\n * to reconstruct the original shared/circular graph.\n */\nexport function decycleValue(value: unknown, bigint: 'string' | 'number' = 'string'): unknown {\n  const paths = new WeakMap<object, string>();\n\n  const walk = (val: unknown, path: Array<string | number>): unknown => {\n    if (typeof val === 'bigint') return bigint === 'number' ? Number(val) : val.toString();\n    if (val === null || typeof val !== 'object') return val;\n    if (val instanceof Date) return val.toISOString();\n\n    const existing = paths.get(val);\n    if (existing !== undefined) return { $ref: existing };\n    paths.set(val, jsonPath(path));\n\n    if (Array.isArray(val)) {\n      return val.map((item, i) => walk(item, [...path, i]));\n    }\n    const rec = val as Record<string, unknown>;\n    const obj: Record<string, unknown> = {};\n    for (const k of Object.keys(rec)) {\n      if (k === '__proto__' || k === 'constructor' || k === 'prototype') continue;\n      obj[k] = walk(rec[k], [...path, k]);\n    }\n    return obj;\n  };\n\n  return walk(value, []);\n}\n\n/**\n * Inverse of {@link decycleValue}: resolve `{ \"$ref\": \"$...\" }` pointers back\n * into the live object graph (mutates and returns the parsed input).\n */\nexport function retrocycle<T>(root: T): T {\n  const refRe = /^\\$(?:\\[(?:\\d+|\"(?:[^\"\\\\]|\\\\.)*\")\\])*$/;\n\n  const resolve = (path: string): unknown => {\n    // Parse the JSONPath segments back out.\n    const segs: Array<string | number> = [];\n    const partRe = /\\[(\\d+|\"(?:[^\"\\\\]|\\\\.)*\")\\]/g;\n    let m: RegExpExecArray | null;\n    while ((m = partRe.exec(path)) !== null) {\n      const raw = m[1]!;\n      segs.push(raw.startsWith('\"') ? (JSON.parse(raw) as string) : Number(raw));\n    }\n    let node: unknown = root;\n    for (const s of segs) {\n      node = (node as Record<string | number, unknown>)[s];\n    }\n    return node;\n  };\n\n  const walk = (val: unknown): void => {\n    if (val === null || typeof val !== 'object') return;\n    const rec = val as Record<string, unknown>;\n    for (const k of Object.keys(rec)) {\n      const child = rec[k];\n      if (\n        child !== null &&\n        typeof child === 'object' &&\n        typeof (child as { $ref?: unknown }).$ref === 'string' &&\n        refRe.test((child as { $ref: string }).$ref)\n      ) {\n        rec[k] = resolve((child as { $ref: string }).$ref);\n      } else {\n        walk(child);\n      }\n    }\n  };\n\n  walk(root);\n  return root;\n}\n\n/**\n * `JSON.stringify` for log output. Takes the plain fast path first and only\n * falls back to {@link safeStringify} when that throws (a cycle, a BigInt, a\n * throwing `toJSON`), so a bad payload costs nothing until it shows up.\n * Never throws: if even the safe walk fails, the value is replaced by a marker.\n */\nexport function stringifyForLog(value: unknown): string {\n  try {\n    return JSON.stringify(value);\n  } catch {\n    try {\n      return safeStringify(value);\n    } catch (error) {\n      const reason = error instanceof Error ? error.message : String(error);\n      return JSON.stringify(`[Unserializable: ${reason}]`);\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/safe-stringify-DWo3aZp_.js

@@ -0,0 +1,142 @@
+
+//#region src/utils/safe-stringify.ts
+/** Build a JSONPath like `$["a"][0]["b"]` for a decycle pointer. */
+function jsonPath(parts) {
+	let path = "$";
+	for (const p of parts) path += typeof p === "number" ? `[${p}]` : `[${JSON.stringify(p)}]`;
+	return path;
+}
+/**
+* Serialize any value to JSON without throwing on circular references or BigInt.
+* Circular refs become `"[Circular]"` (or `{ $ref }` pointers when `decycle`).
+*/
+function safeStringify(value, options = {}) {
+	const { indent, deterministic = false, decycle = false, bigint = "string" } = options;
+	if (decycle) return JSON.stringify(decycleValue(value, bigint), void 0, indent);
+	const seen = /* @__PURE__ */ new WeakSet();
+	const transform = (val) => {
+		if (typeof val === "bigint") return bigint === "number" ? Number(val) : val.toString();
+		if (typeof val === "function") return `[Function: ${val.name || "anonymous"}]`;
+		if (typeof val === "symbol") return val.toString();
+		if (val === null || typeof val !== "object") return val;
+		if (seen.has(val)) return "[Circular]";
+		seen.add(val);
+		let out;
+		const toJSON = val.toJSON;
+		if (Array.isArray(val)) out = val.map((item) => transform(item));
+		else if (typeof toJSON === "function") out = transform(toJSON.call(val));
+		else {
+			const rec = val;
+			const keys = deterministic ? Object.keys(rec).sort() : Object.keys(rec);
+			const obj = {};
+			for (const k of keys) {
+				if (k === "__proto__" || k === "constructor" || k === "prototype") continue;
+				obj[k] = transform(rec[k]);
+			}
+			out = obj;
+		}
+		seen.delete(val);
+		return out;
+	};
+	return JSON.stringify(transform(value), void 0, indent);
+}
+/**
+* Replace repeated object references with round-trippable `{ "$ref": "$..." }`
+* JSONPath pointers (the classic Crockford decycle). Pair with {@link retrocycle}
+* to reconstruct the original shared/circular graph.
+*/
+function decycleValue(value, bigint = "string") {
+	const paths = /* @__PURE__ */ new WeakMap();
+	const walk = (val, path) => {
+		if (typeof val === "bigint") return bigint === "number" ? Number(val) : val.toString();
+		if (val === null || typeof val !== "object") return val;
+		if (val instanceof Date) return val.toISOString();
+		const existing = paths.get(val);
+		if (existing !== void 0) return { $ref: existing };
+		paths.set(val, jsonPath(path));
+		if (Array.isArray(val)) return val.map((item, i) => walk(item, [...path, i]));
+		const rec = val;
+		const obj = {};
+		for (const k of Object.keys(rec)) {
+			if (k === "__proto__" || k === "constructor" || k === "prototype") continue;
+			obj[k] = walk(rec[k], [...path, k]);
+		}
+		return obj;
+	};
+	return walk(value, []);
+}
+/**
+* Inverse of {@link decycleValue}: resolve `{ "$ref": "$..." }` pointers back
+* into the live object graph (mutates and returns the parsed input).
+*/
+function retrocycle(root) {
+	const refRe = /^\$(?:\[(?:\d+|"(?:[^"\\]|\\.)*")\])*$/;
+	const resolve = (path) => {
+		const segs = [];
+		const partRe = /\[(\d+|"(?:[^"\\]|\\.)*")\]/g;
+		let m;
+		while ((m = partRe.exec(path)) !== null) {
+			const raw = m[1];
+			segs.push(raw.startsWith("\"") ? JSON.parse(raw) : Number(raw));
+		}
+		let node = root;
+		for (const s of segs) node = node[s];
+		return node;
+	};
+	const walk = (val) => {
+		if (val === null || typeof val !== "object") return;
+		const rec = val;
+		for (const k of Object.keys(rec)) {
+			const child = rec[k];
+			if (child !== null && typeof child === "object" && typeof child.$ref === "string" && refRe.test(child.$ref)) rec[k] = resolve(child.$ref);
+			else walk(child);
+		}
+	};
+	walk(root);
+	return root;
+}
+/**
+* `JSON.stringify` for log output. Takes the plain fast path first and only
+* falls back to {@link safeStringify} when that throws (a cycle, a BigInt, a
+* throwing `toJSON`), so a bad payload costs nothing until it shows up.
+* Never throws: if even the safe walk fails, the value is replaced by a marker.
+*/
+function stringifyForLog(value) {
+	try {
+		return JSON.stringify(value);
+	} catch {
+		try {
+			return safeStringify(value);
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			return JSON.stringify(`[Unserializable: ${reason}]`);
+		}
+	}
+}
+
+//#endregion
+Object.defineProperty(exports, 'decycleValue', {
+  enumerable: true,
+  get: function () {
+    return decycleValue;
+  }
+});
+Object.defineProperty(exports, 'retrocycle', {
+  enumerable: true,
+  get: function () {
+    return retrocycle;
+  }
+});
+Object.defineProperty(exports, 'safeStringify', {
+  enumerable: true,
+  get: function () {
+    return safeStringify;
+  }
+});
+Object.defineProperty(exports, 'stringifyForLog', {
+  enumerable: true,
+  get: function () {
+    return stringifyForLog;
+  }
+});
+//# sourceMappingURL=safe-stringify-DWo3aZp_.js.map

package/dist/safe-stringify-DWo3aZp_.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-stringify-DWo3aZp_.js","names":["out: unknown","obj: Record<string, unknown>","segs: Array<string | number>","m: RegExpExecArray | null","node: unknown"],"sources":["../src/utils/safe-stringify.ts"],"sourcesContent":["/**\n * logixia — robust JSON serialization for log payloads.\n *\n * Modern Winston/Pino already neutralize circular refs to `[Circular]` (via\n * safe-stable-stringify / fast-safe-stringify), so merely \"surviving cycles\" is\n * not a differentiator. This goes one notch further:\n *\n *  - **BigInt** → serialized (as a string by default; JSON.stringify throws on\n *    BigInt, which silently breaks logging of e.g. DB bigint ids).\n *  - **Deterministic key order** (optional) so identical objects hash/diff equal.\n *  - **True decycle** (optional) — replace repeated references with JSONPath\n *    `$ref` pointers that round-trip back to the original object graph, instead\n *    of the lossy `[Circular]` tag. Useful when you need to reconstruct shared\n *    structure downstream.\n *\n * @example\n * ```ts\n * safeStringify({ id: 10n, self: obj });          // → BigInt + cycle safe\n * safeStringify(graph, { decycle: true });         // → round-trippable $ref pointers\n * const back = retrocycle(JSON.parse(json));       // → reconstruct shared refs\n * ```\n */\n\nexport interface SafeStringifyOptions {\n  /** Indentation passed to JSON.stringify (number of spaces or a string). */\n  indent?: number | string;\n  /** Sort object keys for deterministic output. Default: false. */\n  deterministic?: boolean;\n  /**\n   * Use round-trippable `$ref` JSONPath pointers for repeated references instead\n   * of the lossy \"[Circular]\" tag. Default: false.\n   */\n  decycle?: boolean;\n  /** How to render BigInt: 'string' (default) or 'number' (may lose precision). */\n  bigint?: 'string' | 'number';\n}\n\n/** Build a JSONPath like `$[\"a\"][0][\"b\"]` for a decycle pointer. */\nfunction jsonPath(parts: Array<string | number>): string {\n  let path = '$';\n  for (const p of parts) {\n    path += typeof p === 'number' ? `[${p}]` : `[${JSON.stringify(p)}]`;\n  }\n  return path;\n}\n\n/**\n * Serialize any value to JSON without throwing on circular references or BigInt.\n * Circular refs become `\"[Circular]\"` (or `{ $ref }` pointers when `decycle`).\n */\nexport function safeStringify(value: unknown, options: SafeStringifyOptions = {}): string {\n  const { indent, deterministic = false, decycle = false, bigint = 'string' } = options;\n\n  if (decycle) {\n    return JSON.stringify(decycleValue(value, bigint), undefined, indent);\n  }\n\n  const seen = new WeakSet<object>();\n\n  const transform = (val: unknown): unknown => {\n    if (typeof val === 'bigint') return bigint === 'number' ? Number(val) : val.toString();\n    if (typeof val === 'function') return `[Function: ${val.name || 'anonymous'}]`;\n    if (typeof val === 'symbol') return val.toString();\n    if (val === null || typeof val !== 'object') return val;\n\n    if (seen.has(val)) return '[Circular]';\n    seen.add(val);\n\n    let out: unknown;\n    const toJSON = (val as { toJSON?: unknown }).toJSON;\n    if (Array.isArray(val)) {\n      out = val.map((item) => transform(item));\n    } else if (typeof toJSON === 'function') {\n      // Dates, URLs, Buffers and classes with their own toJSON print the way\n      // JSON.stringify would; a toJSON that returns `this` hits the cycle check.\n      out = transform(toJSON.call(val));\n    } else {\n      const rec = val as Record<string, unknown>;\n      const keys = deterministic ? Object.keys(rec).sort() : Object.keys(rec);\n      const obj: Record<string, unknown> = {};\n      for (const k of keys) {\n        if (k === '__proto__' || k === 'constructor' || k === 'prototype') continue;\n        obj[k] = transform(rec[k]);\n      }\n      out = obj;\n    }\n    // Allow the same object to appear in sibling branches (not a true cycle):\n    // remove from `seen` after we finish its subtree.\n    seen.delete(val);\n    return out;\n  };\n\n  return JSON.stringify(transform(value), undefined, indent);\n}\n\n/**\n * Replace repeated object references with round-trippable `{ \"$ref\": \"$...\" }`\n * JSONPath pointers (the classic Crockford decycle). Pair with {@link retrocycle}\n * to reconstruct the original shared/circular graph.\n */\nexport function decycleValue(value: unknown, bigint: 'string' | 'number' = 'string'): unknown {\n  const paths = new WeakMap<object, string>();\n\n  const walk = (val: unknown, path: Array<string | number>): unknown => {\n    if (typeof val === 'bigint') return bigint === 'number' ? Number(val) : val.toString();\n    if (val === null || typeof val !== 'object') return val;\n    if (val instanceof Date) return val.toISOString();\n\n    const existing = paths.get(val);\n    if (existing !== undefined) return { $ref: existing };\n    paths.set(val, jsonPath(path));\n\n    if (Array.isArray(val)) {\n      return val.map((item, i) => walk(item, [...path, i]));\n    }\n    const rec = val as Record<string, unknown>;\n    const obj: Record<string, unknown> = {};\n    for (const k of Object.keys(rec)) {\n      if (k === '__proto__' || k === 'constructor' || k === 'prototype') continue;\n      obj[k] = walk(rec[k], [...path, k]);\n    }\n    return obj;\n  };\n\n  return walk(value, []);\n}\n\n/**\n * Inverse of {@link decycleValue}: resolve `{ \"$ref\": \"$...\" }` pointers back\n * into the live object graph (mutates and returns the parsed input).\n */\nexport function retrocycle<T>(root: T): T {\n  const refRe = /^\\$(?:\\[(?:\\d+|\"(?:[^\"\\\\]|\\\\.)*\")\\])*$/;\n\n  const resolve = (path: string): unknown => {\n    // Parse the JSONPath segments back out.\n    const segs: Array<string | number> = [];\n    const partRe = /\\[(\\d+|\"(?:[^\"\\\\]|\\\\.)*\")\\]/g;\n    let m: RegExpExecArray | null;\n    while ((m = partRe.exec(path)) !== null) {\n      const raw = m[1]!;\n      segs.push(raw.startsWith('\"') ? (JSON.parse(raw) as string) : Number(raw));\n    }\n    let node: unknown = root;\n    for (const s of segs) {\n      node = (node as Record<string | number, unknown>)[s];\n    }\n    return node;\n  };\n\n  const walk = (val: unknown): void => {\n    if (val === null || typeof val !== 'object') return;\n    const rec = val as Record<string, unknown>;\n    for (const k of Object.keys(rec)) {\n      const child = rec[k];\n      if (\n        child !== null &&\n        typeof child === 'object' &&\n        typeof (child as { $ref?: unknown }).$ref === 'string' &&\n        refRe.test((child as { $ref: string }).$ref)\n      ) {\n        rec[k] = resolve((child as { $ref: string }).$ref);\n      } else {\n        walk(child);\n      }\n    }\n  };\n\n  walk(root);\n  return root;\n}\n\n/**\n * `JSON.stringify` for log output. Takes the plain fast path first and only\n * falls back to {@link safeStringify} when that throws (a cycle, a BigInt, a\n * throwing `toJSON`), so a bad payload costs nothing until it shows up.\n * Never throws: if even the safe walk fails, the value is replaced by a marker.\n */\nexport function stringifyForLog(value: unknown): string {\n  try {\n    return JSON.stringify(value);\n  } catch {\n    try {\n      return safeStringify(value);\n    } catch (error) {\n      const reason = error instanceof Error ? error.message : String(error);\n      return JSON.stringify(`[Unserializable: ${reason}]`);\n    }\n  }\n}\n"],"mappings":"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"}