@hackylabs/deep-redact 4.0.0 → 4.0.1

package/README.md

@@ -43,7 +43,7 @@ bun add @hackylabs/deep-redact
 ```json
 {
   "imports": {
-    "@hackylabs/deep-redact": "npm:@hackylabs/deep-redact@4.0.0"
+    "@hackylabs/deep-redact": "npm:@hackylabs/deep-redact@4.0.1"
   }
 }
 ```
@@ -82,6 +82,8 @@ v4, v3, and fast-redact all return a plain JavaScript object.
 
 ![Speed comparison — structured output](docs/benchmarks/charts/speed-comparison-non-serialised.svg)
 
+_† fast-redact is a third-party library, not a deep-redact version. It is shown as a throughput reference; its feature set and guarantees differ from deep-redact's, so it is not a like-for-like comparison._
+
 v4 is **~17× faster** than v3 on path-based workloads and **~10× faster** on wildcard workloads.
 
 ### Serialised output (`serialise: true`)
@@ -90,8 +92,14 @@ All four solutions return a JSON string.
 
 ![Speed comparison — serialised output](docs/benchmarks/charts/speed-comparison-serialised.svg)
 
+_† fast-redact is a third-party library; json-stringify-regex is a naive native approach (`JSON.stringify(value).replace(pattern, replacement)`), not a library. Neither performs deep-redact's structured redaction or offers its guarantees, so both are shown as throughput references rather than like-for-like comparisons._
+
 v4 remains faster than v3 in serialised mode. fast-redact and json-stringify-regex have a throughput advantage because their output path is oriented entirely toward string production.
 
+Against deep-redact v2 the serialised picture is mixed: v4 is roughly at parity on path-based workloads but slower on breadth-heavy (wildcard) ones. That gap is the cost of safety v2 does not provide — under `serialise: true`, v4 runs the type transformers that make `BigInt`, `Date`, `Map`, `Set`, `Error`, `RegExp`, and `URL` values JSON-safe, and it detects and neutralises circular references instead of throwing on them. (Node and depth budgeting via `maxNodes`/`maxDepth` is opt-in and unlimited by default, so it adds nothing unless you enable it.)
+
+These safety passes are intrinsic to `serialise: true` and cannot be switched off individually. If you do not need those guarantees and want to match v2's throughput (or better), set `serialise: false` and run your own `JSON.stringify`: the structured-output path skips the transformer and circular-reference passes entirely. This restores v2's trade-offs too — your `JSON.stringify` will throw on `BigInt` and circular references, `Map`/`Set` serialise as `{}`, and `undefined` is dropped.
+
 Full speed and resource benchmark results: [`docs/benchmarks/speed-results.md`](docs/benchmarks/speed-results.md) and [`docs/benchmarks/resource-results.md`](docs/benchmarks/resource-results.md).
 
 ## Configuration

package/dist/index.cjs

@@ -2630,6 +2630,8 @@ const validateConfig = (options) => {
 //#endregion
 //#region src/core/replacement/serialise-output.ts
 const bareIdentifierPattern = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const MAX_SERIALISE_DEPTH = 3e3;
+const NO_INDEX = -1;
 const buildObjectChildPath = (parentPath, key) => {
 	if (!bareIdentifierPattern.test(key)) return `${parentPath ?? ""}["${key.replaceAll("\\", "\\\\").replaceAll("\"", String.raw`\"`)}"]`;
 	return parentPath === void 0 ? key : `${parentPath}.${key}`;
@@ -2642,26 +2644,49 @@ const isStrictDescendantPath = (ancestor, path) => {
 	if (ancestor === "") return true;
 	return path.startsWith(`${ancestor}.`) || path.startsWith(`${ancestor}[`);
 };
-const buildSafeGraph = (value, transformers, seen, identityPaths, currentPath, cycleRegistry) => {
+const materialiseFramePath = (frame) => {
+	const chain = [];
+	for (let node = frame; node !== void 0; node = node.parent) chain.push(node);
+	let path;
+	for (let i = chain.length - 1; i >= 0; i -= 1) {
+		const node = chain[i];
+		if (node.index >= 0) path = buildArrayChildPath(path, node.index);
+		else if (node.key !== void 0) path = buildObjectChildPath(path, node.key);
+	}
+	return path;
+};
+const materialiseStepPath = (parentFrame, key, index) => {
+	const parentPath = materialiseFramePath(parentFrame);
+	if (index >= 0) return buildArrayChildPath(parentPath, index);
+	if (key !== void 0) return buildObjectChildPath(parentPath, key);
+	return parentPath;
+};
+const materialiseAncestorPath = (frame, identity) => {
+	for (let node = frame; node !== void 0; node = node.parent) if (node.identity === identity) return materialiseFramePath(node);
+};
+const buildSafeGraph = (value, transformers, seen, parentFrame, stepKey, stepIndex, cycleRegistry, depth) => {
+	if (depth > MAX_SERIALISE_DEPTH) return "[UNSUPPORTED]";
 	if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === void 0) return value;
 	if (typeof value === "function" || typeof value === "symbol") return "[UNSUPPORTED]";
 	const supportedKind = resolveSupportedTransformableValueKind(value);
 	if (supportedKind !== void 0) {
 		const runtimeIdentity = supportedKind === "bigint" ? void 0 : value;
-		if (runtimeIdentity !== void 0) {
-			if (seen.has(runtimeIdentity)) return {
-				_transformer: "circular",
-				path: currentPath ?? "",
-				value: identityPaths.get(runtimeIdentity) ?? ""
-			};
-			const currentPathStr = currentPath ?? "";
-			identityPaths.set(runtimeIdentity, currentPathStr);
-			seen.add(runtimeIdentity);
-		}
+		if (runtimeIdentity !== void 0 && seen.has(runtimeIdentity)) return {
+			_transformer: "circular",
+			path: materialiseStepPath(parentFrame, stepKey, stepIndex) ?? "",
+			value: materialiseAncestorPath(parentFrame, runtimeIdentity) ?? ""
+		};
+		const frame = {
+			parent: parentFrame,
+			key: stepKey,
+			index: stepIndex,
+			identity: runtimeIdentity
+		};
+		if (runtimeIdentity !== void 0) seen.add(runtimeIdentity);
 		try {
 			const transformed = resolveTransformedValue(value, transformers);
 			if (transformed === void 0) return "[UNSUPPORTED]";
-			return buildSafeGraph(transformed, transformers, seen, identityPaths, currentPath, cycleRegistry);
+			return buildTransformedGraph(transformed, transformers, seen, frame, cycleRegistry, depth + 1);
 		} catch {
 			return "[UNSUPPORTED]";
 		} finally {
@@ -2671,19 +2696,24 @@ const buildSafeGraph = (value, transformers, seen, identityPaths, currentPath, c
 	const identity = value;
 	if (seen.has(identity)) return {
 		_transformer: "circular",
-		path: currentPath ?? "",
-		value: identityPaths.get(identity) ?? ""
+		path: materialiseStepPath(parentFrame, stepKey, stepIndex) ?? "",
+		value: materialiseAncestorPath(parentFrame, identity) ?? ""
 	};
 	if (cycleRegistry?.has(identity)) {
 		const registryPath = cycleRegistry.get(identity);
-		if (isStrictDescendantPath(registryPath, currentPath ?? "")) return {
+		const currentPath = materialiseStepPath(parentFrame, stepKey, stepIndex) ?? "";
+		if (isStrictDescendantPath(registryPath, currentPath)) return {
 			_transformer: "circular",
-			path: currentPath ?? "",
+			path: currentPath,
 			value: registryPath
 		};
 	}
-	const currentPathStr = currentPath ?? "";
-	identityPaths.set(identity, currentPathStr);
+	const frame = {
+		parent: parentFrame,
+		key: stepKey,
+		index: stepIndex,
+		identity
+	};
 	seen.add(identity);
 	try {
 		if (Array.isArray(value)) {
@@ -2691,18 +2721,18 @@ const buildSafeGraph = (value, transformers, seen, identityPaths, currentPath, c
 			result.length = value.length;
 			for (let index = 0; index < value.length; index += 1) {
 				if (!(index in value)) continue;
-				result[index] = buildSafeGraph(value[index], transformers, seen, identityPaths, buildArrayChildPath(currentPath, index), cycleRegistry);
+				result[index] = buildSafeGraph(value[index], transformers, seen, frame, void 0, index, cycleRegistry, depth + 1);
 			}
 			return result;
 		}
 		if (isPlainObject$1(value)) {
 			const result = {};
-			for (const key of Object.keys(value)) result[key] = buildSafeGraph(value[key], transformers, seen, identityPaths, buildObjectChildPath(currentPath, key), cycleRegistry);
+			for (const key of Object.keys(value)) result[key] = buildSafeGraph(value[key], transformers, seen, frame, key, NO_INDEX, cycleRegistry, depth + 1);
 			return result;
 		}
 		try {
 			const transformed = resolveTransformedValue(value, transformers);
-			if (transformed !== void 0) return buildSafeGraph(transformed, transformers, seen, identityPaths, currentPath, cycleRegistry);
+			if (transformed !== void 0) return buildTransformedGraph(transformed, transformers, seen, frame, cycleRegistry, depth + 1);
 		} catch {
 			return "[UNSUPPORTED]";
 		}
@@ -2711,9 +2741,18 @@ const buildSafeGraph = (value, transformers, seen, identityPaths, currentPath, c
 		seen.delete(identity);
 	}
 };
+const buildTransformedGraph = (transformed, transformers, seen, containerFrame, cycleRegistry, depth) => {
+	if (isPlainObject$1(transformed) && typeof transformed._transformer === "string" && "value" in transformed) {
+		const wrapper = transformed;
+		const result = {};
+		for (const key of Object.keys(wrapper)) result[key] = key === "value" ? buildSafeGraph(wrapper.value, transformers, seen, containerFrame, void 0, NO_INDEX, cycleRegistry, depth + 1) : buildSafeGraph(wrapper[key], transformers, seen, containerFrame, key, NO_INDEX, cycleRegistry, depth + 1);
+		return result;
+	}
+	return buildSafeGraph(transformed, transformers, seen, containerFrame, void 0, NO_INDEX, cycleRegistry, depth + 1);
+};
 const serialiseOutput = (value, transformers, serialise, cycleRegistry) => {
 	if (!serialise) return value;
-	const safeGraph = value === void 0 ? "[UNSUPPORTED]" : buildSafeGraph(value, transformers, /* @__PURE__ */ new WeakSet(), /* @__PURE__ */ new WeakMap(), void 0, cycleRegistry);
+	const safeGraph = value === void 0 ? "[UNSUPPORTED]" : buildSafeGraph(value, transformers, /* @__PURE__ */ new WeakSet(), void 0, void 0, NO_INDEX, cycleRegistry, 0);
 	if (serialise === true) return JSON.stringify(safeGraph);
 	return serialise(safeGraph);
 };

package/dist/index.js

@@ -2629,6 +2629,8 @@ const validateConfig = (options) => {
 //#endregion
 //#region src/core/replacement/serialise-output.ts
 const bareIdentifierPattern = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const MAX_SERIALISE_DEPTH = 3e3;
+const NO_INDEX = -1;
 const buildObjectChildPath = (parentPath, key) => {
 	if (!bareIdentifierPattern.test(key)) return `${parentPath ?? ""}["${key.replaceAll("\\", "\\\\").replaceAll("\"", String.raw`\"`)}"]`;
 	return parentPath === void 0 ? key : `${parentPath}.${key}`;
@@ -2641,26 +2643,49 @@ const isStrictDescendantPath = (ancestor, path) => {
 	if (ancestor === "") return true;
 	return path.startsWith(`${ancestor}.`) || path.startsWith(`${ancestor}[`);
 };
-const buildSafeGraph = (value, transformers, seen, identityPaths, currentPath, cycleRegistry) => {
+const materialiseFramePath = (frame) => {
+	const chain = [];
+	for (let node = frame; node !== void 0; node = node.parent) chain.push(node);
+	let path;
+	for (let i = chain.length - 1; i >= 0; i -= 1) {
+		const node = chain[i];
+		if (node.index >= 0) path = buildArrayChildPath(path, node.index);
+		else if (node.key !== void 0) path = buildObjectChildPath(path, node.key);
+	}
+	return path;
+};
+const materialiseStepPath = (parentFrame, key, index) => {
+	const parentPath = materialiseFramePath(parentFrame);
+	if (index >= 0) return buildArrayChildPath(parentPath, index);
+	if (key !== void 0) return buildObjectChildPath(parentPath, key);
+	return parentPath;
+};
+const materialiseAncestorPath = (frame, identity) => {
+	for (let node = frame; node !== void 0; node = node.parent) if (node.identity === identity) return materialiseFramePath(node);
+};
+const buildSafeGraph = (value, transformers, seen, parentFrame, stepKey, stepIndex, cycleRegistry, depth) => {
+	if (depth > MAX_SERIALISE_DEPTH) return "[UNSUPPORTED]";
 	if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === void 0) return value;
 	if (typeof value === "function" || typeof value === "symbol") return "[UNSUPPORTED]";
 	const supportedKind = resolveSupportedTransformableValueKind(value);
 	if (supportedKind !== void 0) {
 		const runtimeIdentity = supportedKind === "bigint" ? void 0 : value;
-		if (runtimeIdentity !== void 0) {
-			if (seen.has(runtimeIdentity)) return {
-				_transformer: "circular",
-				path: currentPath ?? "",
-				value: identityPaths.get(runtimeIdentity) ?? ""
-			};
-			const currentPathStr = currentPath ?? "";
-			identityPaths.set(runtimeIdentity, currentPathStr);
-			seen.add(runtimeIdentity);
-		}
+		if (runtimeIdentity !== void 0 && seen.has(runtimeIdentity)) return {
+			_transformer: "circular",
+			path: materialiseStepPath(parentFrame, stepKey, stepIndex) ?? "",
+			value: materialiseAncestorPath(parentFrame, runtimeIdentity) ?? ""
+		};
+		const frame = {
+			parent: parentFrame,
+			key: stepKey,
+			index: stepIndex,
+			identity: runtimeIdentity
+		};
+		if (runtimeIdentity !== void 0) seen.add(runtimeIdentity);
 		try {
 			const transformed = resolveTransformedValue(value, transformers);
 			if (transformed === void 0) return "[UNSUPPORTED]";
-			return buildSafeGraph(transformed, transformers, seen, identityPaths, currentPath, cycleRegistry);
+			return buildTransformedGraph(transformed, transformers, seen, frame, cycleRegistry, depth + 1);
 		} catch {
 			return "[UNSUPPORTED]";
 		} finally {
@@ -2670,19 +2695,24 @@ const buildSafeGraph = (value, transformers, seen, identityPaths, currentPath, c
 	const identity = value;
 	if (seen.has(identity)) return {
 		_transformer: "circular",
-		path: currentPath ?? "",
-		value: identityPaths.get(identity) ?? ""
+		path: materialiseStepPath(parentFrame, stepKey, stepIndex) ?? "",
+		value: materialiseAncestorPath(parentFrame, identity) ?? ""
 	};
 	if (cycleRegistry?.has(identity)) {
 		const registryPath = cycleRegistry.get(identity);
-		if (isStrictDescendantPath(registryPath, currentPath ?? "")) return {
+		const currentPath = materialiseStepPath(parentFrame, stepKey, stepIndex) ?? "";
+		if (isStrictDescendantPath(registryPath, currentPath)) return {
 			_transformer: "circular",
-			path: currentPath ?? "",
+			path: currentPath,
 			value: registryPath
 		};
 	}
-	const currentPathStr = currentPath ?? "";
-	identityPaths.set(identity, currentPathStr);
+	const frame = {
+		parent: parentFrame,
+		key: stepKey,
+		index: stepIndex,
+		identity
+	};
 	seen.add(identity);
 	try {
 		if (Array.isArray(value)) {
@@ -2690,18 +2720,18 @@ const buildSafeGraph = (value, transformers, seen, identityPaths, currentPath, c
 			result.length = value.length;
 			for (let index = 0; index < value.length; index += 1) {
 				if (!(index in value)) continue;
-				result[index] = buildSafeGraph(value[index], transformers, seen, identityPaths, buildArrayChildPath(currentPath, index), cycleRegistry);
+				result[index] = buildSafeGraph(value[index], transformers, seen, frame, void 0, index, cycleRegistry, depth + 1);
 			}
 			return result;
 		}
 		if (isPlainObject$1(value)) {
 			const result = {};
-			for (const key of Object.keys(value)) result[key] = buildSafeGraph(value[key], transformers, seen, identityPaths, buildObjectChildPath(currentPath, key), cycleRegistry);
+			for (const key of Object.keys(value)) result[key] = buildSafeGraph(value[key], transformers, seen, frame, key, NO_INDEX, cycleRegistry, depth + 1);
 			return result;
 		}
 		try {
 			const transformed = resolveTransformedValue(value, transformers);
-			if (transformed !== void 0) return buildSafeGraph(transformed, transformers, seen, identityPaths, currentPath, cycleRegistry);
+			if (transformed !== void 0) return buildTransformedGraph(transformed, transformers, seen, frame, cycleRegistry, depth + 1);
 		} catch {
 			return "[UNSUPPORTED]";
 		}
@@ -2710,9 +2740,18 @@ const buildSafeGraph = (value, transformers, seen, identityPaths, currentPath, c
 		seen.delete(identity);
 	}
 };
+const buildTransformedGraph = (transformed, transformers, seen, containerFrame, cycleRegistry, depth) => {
+	if (isPlainObject$1(transformed) && typeof transformed._transformer === "string" && "value" in transformed) {
+		const wrapper = transformed;
+		const result = {};
+		for (const key of Object.keys(wrapper)) result[key] = key === "value" ? buildSafeGraph(wrapper.value, transformers, seen, containerFrame, void 0, NO_INDEX, cycleRegistry, depth + 1) : buildSafeGraph(wrapper[key], transformers, seen, containerFrame, key, NO_INDEX, cycleRegistry, depth + 1);
+		return result;
+	}
+	return buildSafeGraph(transformed, transformers, seen, containerFrame, void 0, NO_INDEX, cycleRegistry, depth + 1);
+};
 const serialiseOutput = (value, transformers, serialise, cycleRegistry) => {
 	if (!serialise) return value;
-	const safeGraph = value === void 0 ? "[UNSUPPORTED]" : buildSafeGraph(value, transformers, /* @__PURE__ */ new WeakSet(), /* @__PURE__ */ new WeakMap(), void 0, cycleRegistry);
+	const safeGraph = value === void 0 ? "[UNSUPPORTED]" : buildSafeGraph(value, transformers, /* @__PURE__ */ new WeakSet(), void 0, void 0, NO_INDEX, cycleRegistry, 0);
 	if (serialise === true) return JSON.stringify(safeGraph);
 	return serialise(safeGraph);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hackylabs/deep-redact",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "description": "Deeply redact sensitive data from objects, arrays and arbitrary strings (e.g. XML or raw cookies data) with a composable, function-first API.",
   "private": false,
   "license": "MIT",
@@ -60,7 +60,7 @@
     "url": "git+https://github.com/hackylabs/deep-redact"
   },
   "//": [
-    "deep-redact-v3 and fast-redact are installed only as internal benchmark comparisons and are not used in the library",
+    "deep-redact-v2, deep-redact-v3, deep-redact-v4-baseline (released 4.0.0) and fast-redact are installed only as internal benchmark comparisons and are not used in the library",
     "all dependencies are for development purposes only"
   ],
   "devDependencies": {
@@ -68,7 +68,9 @@
     "@stylistic/eslint-plugin": "4.4.1",
     "@types/fast-redact": "3.0.4",
     "@types/node": "24.1.0",
+    "deep-redact-v2": "npm:@hackylabs/deep-redact@2.2.1",
     "deep-redact-v3": "npm:@hackylabs/deep-redact@^3.0.0",
+    "deep-redact-v4-baseline": "npm:@hackylabs/deep-redact@4.0.0",
     "eslint": "9.39.4",
     "eslint-plugin-unicorn": "59.0.1",
     "fast-redact": "3.5.0",