@oh-my-pi/pi-utils 18.4.1 → 18.4.2

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [18.4.2] - 2026-09-28
+
+### Added
+
+- Added cloneJsonTree to provide a high-performance deep copy utility for JSON-shaped object trees
+
 ## [18.4.1] - 2026-09-28
 
 ### Fixed

package/dist/types/index.d.ts

@@ -43,3 +43,15 @@ export * from "./version.js";
 export * from "./which.js";
 export * from "./yaml-config.js";
 export declare function structuredCloneJSON<T>(value: T): T;
+/**
+ * Deep-copies a JSON-shaped tree (arrays and plain or null-prototype objects)
+ * so later mutation of the source can never reach the copy. Strings and other
+ * primitives are immutable and shared, so the cost is O(containers) instead of
+ * `structuredClone`'s O(bytes) — the difference matters for hot paths that
+ * re-copy large string payloads (e.g. streamed tool-call arguments) per delta.
+ *
+ * Copies own enumerable string keys only. Any other object (class instance,
+ * Date, Map, inherited-prototype object) is copied with {@link structuredCloneJSON}.
+ * Not cycle-safe: callers MUST pass acyclic data, as any JSON-serializable value is.
+ */
+export declare function cloneJsonTree<T>(value: T): T;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-utils",
-	"version": "18.4.1",
+	"version": "18.4.2",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"cli",
@@ -57,7 +57,7 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.4.1"
+		"@oh-my-pi/pi-natives": "18.4.2"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/index.ts

@@ -63,3 +63,42 @@ export function structuredCloneJSON<T>(value: T): T {
 	}
 	return JSON.parse(JSON.stringify(value)) as T;
 }
+
+/**
+ * Deep-copies a JSON-shaped tree (arrays and plain or null-prototype objects)
+ * so later mutation of the source can never reach the copy. Strings and other
+ * primitives are immutable and shared, so the cost is O(containers) instead of
+ * `structuredClone`'s O(bytes) — the difference matters for hot paths that
+ * re-copy large string payloads (e.g. streamed tool-call arguments) per delta.
+ *
+ * Copies own enumerable string keys only. Any other object (class instance,
+ * Date, Map, inherited-prototype object) is copied with {@link structuredCloneJSON}.
+ * Not cycle-safe: callers MUST pass acyclic data, as any JSON-serializable value is.
+ */
+export function cloneJsonTree<T>(value: T): T {
+	return cloneJsonNode(value) as T;
+}
+
+function isJsonRecord(value: object): value is Record<string, unknown> {
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+
+function cloneJsonNode(value: unknown): unknown {
+	if (value === null || typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map(cloneJsonNode);
+	if (!isJsonRecord(value)) return structuredCloneJSON(value);
+	const out: Record<string, unknown> = {};
+	for (const key in value) {
+		if (!Object.hasOwn(value, key)) continue;
+		const child = cloneJsonNode(value[key]);
+		// Assigning `__proto__` would swap the copy's prototype instead of
+		// creating the own data property JSON.parse produces.
+		if (key === "__proto__") {
+			Object.defineProperty(out, key, { value: child, enumerable: true, writable: true, configurable: true });
+		} else {
+			out[key] = child;
+		}
+	}
+	return out;
+}