@hackylabs/deep-redact 3.0.5 → 4.0.1

package/README.md

@@ -3,128 +3,251 @@
 [![npm version](https://badge.fury.io/js/@hackylabs%2Fdeep-redact.svg)](https://badge.fury.io/js/@hackylabs%2Fdeep-redact)
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/hackylabs/deep-redact/blob/main/LICENSE)
 
-Safer and more configurable than many other redaction solutions, Deep Redact is a zero-dependency tool that redacts
-sensitive information from strings and objects. It is designed to be used in a production environment where sensitive
-information needs to be redacted from logs, error messages, files, and other outputs. Supporting both strings and objects
-or a mix of both, Deep Redact can be used to redact sensitive information from more data structures than any other
-redaction library. Even partially redacting sensitive information from strings is supported, by way of custom regex
-patterns and replacers.
+@hackylabs/deep-redact is a rule-driven redaction library for Node.js and Deno. It lets you express what to redact — a key name, a path, a regex, or a substring — and the runtime locates and replaces it everywhere in the payload without requiring exhaustive path enumeration. Policies are compiled once at initialisation and reused across every request, making it suitable for high-throughput production use.
 
-Circular references and other unsupported values are handled gracefully, and the library is designed to be as fast as
-possible while still being easy to use and configure.
-
-Supporting both CommonJS and ESM, with named and default exports, Deep Redact is designed to be versatile and easy to
-use in any modern JavaScript or TypeScript project in Node or the browser.
+Libraries like `fast-redact` require an explicit path for every location where a sensitive field might appear (`a.b.password`, `a.c.password`, …). Deep Redact inverts this: a single `keys: ['password']` rule targets every `password` field at any depth. It also adds capabilities that path-enumeration libraries cannot offer, such as partial string redaction (targeting a sensitive pattern inside a larger value) and wildcard path selectors for repeated structures.
 
 [![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/hackylabs)
 
+## Features
+
+- **Depth-agnostic key rules** — redact any field by name at any nesting depth; no path enumeration required
+- **Exact and structured path targeting** — pin redaction to a specific location when precision is needed
+- **Regex property matching** — match field names by regular expression
+- **Substring targeting** — redact a sensitive string that appears inside a larger value, not just whole-value replacement
+- **Wildcard and exclusion path selectors** — handle repeated structures at virtually any depth (`['addresses.*', { ignore: 'country' }]`) without listing every index
+- **Structured and serialised output** — return a live object graph or a guaranteed-JSON-safe string (`serialise: true`)
+- **Built-in and custom transformers** — override how specific runtime types are represented in serialised output
+- **Built-in security** — prevent prototype pollution and DoS by memory exhaustion
+- **Console adapter** — optional `console.*` redaction via an explicit adapter
+
+## Contributor Baseline
+
+- Node `24.14.1`
+- `pnpm@10.33.0`
+- `tsdown`
+- `Vitest`
+- `ESLint`
+
 ## Installation
 
-```bash
+```sh
 npm install @hackylabs/deep-redact
+pnpm add @hackylabs/deep-redact
+yarn add @hackylabs/deep-redact
+bun add @hackylabs/deep-redact
 ```
 
-## Usage
+**Deno** — add the package to your import map (`deno.json`):
 
-<h4 style="color: red">In order to maintain a consistent usage throughout your project, it is not advised to call this
-library outside of your global logging/error-reporting libraries.</h4>
+```json
+{
+  "imports": {
+    "@hackylabs/deep-redact": "npm:@hackylabs/deep-redact@4.0.1"
+  }
+}
+```
 
-```typescript
-// ./src/example.ts
-import {DeepRedact} from '@hackylabs/deep-redact'; // If you're using CommonJS, import with require('@hackylabs/deep-redact') instead. Both CommonJS and ESM support named and default imports.
+## Quick Start
 
-const objRedaction = new DeepRedact({
-  blacklistedKeys: ['sensitive', 'password', /name/i],
-})
+```ts
+import { deepRedact } from '@hackylabs/deep-redact'
 
-const obj = {
-  keepThis: 'This is fine',
-  sensitive: 'This is not fine',
-  user: {
-    id: 1,
-    password: '<h1><strong>Password</strong></h1>',
-    firstName: 'John',
-  }
-}
+const redact = deepRedact({ keys: ['password', 'token'] })
 
-// Recursively redact sensitive information from an object
-objRedaction.redact(obj)
-// {
-//  keepThis: 'This is fine',
-//  sensitive: '[REDACTED]',
-//  user: {
-//    id: 1,
-//    password: '[REDACTED]',
-//    firstName: '[REDACTED]'
-//  }
-// }
-
-const strRedaction = new DeepRedact({
-  stringTests: [
-    {
-      pattern: /<(email|password)>([^<]+)<\/\1>/gi,
-      replacer: (value: string, pattern: RegExp) => value.replace(pattern, '<$1>[REDACTED]</$1>'),
-    },
-  ],
-})
-
-// Partially redact sensitive information from a string
-strRedaction.redact('<email>someone@somewhere.com</email><keepThis>This is fine</keepThis><password>secret</password>')
-// '<email>[REDACTED]</email><keepThis>This is fine</keepThis><password>[REDACTED]</password>'
+redact({ user: { password: 'secret', safe: 'keep this' }, token: 'abc123', id: 1 })
+// { user: { password: '[REDACTED]', safe: 'keep this' }, token: '[REDACTED]', id: 1 }
 ```
 
-// Override the `transformers` property to handle unsupported values in your own way
-// WARNING: You are responsible for ensuring all used transformers safely and reliably transform unsupported values
-
-```typescript
-const customRedaction = new DeepRedact({
-  blacklistedKeys: ['sensitive', 'password', /name/i],
-  transformers: [
-    (value: unknown) => {
-      if (typeof value !== 'bigint') return value
-      return value.toString(10)
-    },
-    ...
-  ]
-})
-
-customRedaction.redact({ a: BigInt(1) })
-```
+## Benchmarks
+
+Generated from committed artefacts in `test/artefacts/benchmarks/speed/`. Node.js 24 LTS, Apple M-series. Steady-state after 10,000 warmup iterations.
+
+### TLDR Headline
+
+> **If raw throughput is your primary constraint and you can accept exhaustive path enumeration, use [`fast-redact`](https://www.npmjs.com/package/fast-redact) instead.** It is purpose-built for maximum JSON-string output speed and will outperform any rule-driven library in that narrow scenario. Use Deep Redact when you need depth-agnostic targeting, wildcard paths, substring redaction, or built-in security guarantees.
+
+If you choose fast-redact instead, be aware of the trade-offs:
+
+- **No depth-agnostic key rules** — every sensitive path must be enumerated explicitly
+- **No double-wildcard (`**`) path selectors** — you cannot target `records.**.email` without listing every depth
+- **No substring targeting** — whole-value replacement only; partial string redaction is not supported
+- **No serialisation-safe transformer pipeline** — no built-in handling for `BigInt`, `Date`, `Map`, `Set`, `Error`, `RegExp`, or `URL` values
+- **No prototype pollution protection** — no guard against `__proto__` and `constructor.prototype` injection
+- **No configurable depth or node limits** — no protection against DoS via deeply nested or excessively large payloads
+
+### Structured output (`serialise: false`)
+
+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`)
+
+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
 
-### Main Options
-
-| key | description | type | options | default | required |
-| --- | --- | --- | --- | --- | --- |
-| blacklistedKeys | Deeply compare names of these keys against the keys in your object. | array | Array<string￨RegExp￨BlacklistKeyConfig> | [] | N |
-| stringTests | Array of regular expressions to perform against string values, whether that value is a flat string or nested within an object. Can redact whole or partial string values. If a replacer function is provided in the config for the associated test, it will be used to redact the value if the value matches the test. | array | Array<RegExp￨StringTestConfig> | [] | N |
-| fuzzyKeyMatch | Loosely compare key names by checking if the key name of your unredacted object is included anywhere within the name of your blacklisted key. For example, is "pass" (your key) included in "password" (from config). | boolean |  | false | N |
-| caseSensitiveKeyMatch | Loosely compare key names by normalising the strings. This involves removing non-word characters and transforms the string to lowercase. This means you never have to worry having to list duplicate keys in different formats such as snake_case, camelCase, PascalCase or any other case. | boolean |  | true | N |
-| remove | Determines whether or not to remove the key from the object when it is redacted. | boolean |  | false | N |
-| retainStructure | Determines whether or not keep all nested values of a key that is going to be redacted. Circular references are always removed. | boolean |  | false | N |
-| replacement | When a value is going to be redacted, what would you like to replace it with? | string ￨ function |  | [REDACTED] | N |
-| replaceStringByLength | When a string value is going to be replaced, optionally replace it by repeating the `replacement` to match the length of the value. For example, if `replaceStringByLength` were set to `true` and `replacement` was set to "x", then redacting "secret" would return "xxxxxx". This is sometimes useful for debugging purposes, although it may be less secure as it could give hints to the original value. | boolean |  | false | N |
-| types | JS types (values of `typeof` keyword). Only values with a typeof equal to `string`, `number`, `bigint`, `boolean`, `symbol`, `object`, or `function` will be redacted. Undefined values will never be redacted, although the type `undefined` is included in this list to keep TypeScript happy. | array | Array<'string'￨'number'￨'bigint'￨'boolean'￨'symbol'￨'undefined'￨'object'￨'function'> | ['string'] | N |
-| serialise | Determines whether or not to serialise the object after redacting. Typical use cases for this are when you want to send it over the network or save to a file, both of which are common use cases for redacting sensitive information. | boolean |  | true | N |
-| serialize | Alias of `serialise` for International-English users. | boolean |  | Value of `serialise` | N |
-| transformers | A list of transformers to apply when transforming unsupported values. Each transformer should conditionally transform the value, or return the value unchanged to be passed to the next transformer. Transformers will be run in the order they are provided over the entire object. | array | Array<Transformer> | All standard transformers (bigint, date, error, map, regex, set, and url) | N |
-
-### BlacklistKeyConfig
-
-| key | type | default | required |
-| --- | --- | --- | --- |
-| key | string￨RegExp |  | Y |
-| fuzzyKeyMatch | boolean | Main options `fuzzyKeyMatch` | N |
-| caseSensitiveKeyMatch | boolean | Main options `caseSensitiveKeyMatch` | N |
-| remove | boolean | Main options `remove` | N |
-| replacement | string￨function | Main options `replacement` | N |
-| replaceStringByLength | boolean | Main options `replaceStringByLength` | N |
-| retainStructure | boolean | Main options `retainStructure` | N |
-
-### StringTestConfig
-
-| key | description | type | required |
-| --- | --- | --- | --- |
-| pattern | A regular expression to perform against a string value, whether that value is a flat string or nested within an object. | RegExp | Y |
-| replacer | A function that will be called with the value of the string that matched the pattern and the pattern itself. This function should return the new (redacted) value to replace the original value. | function | Y |
+`deepRedact(options)` accepts a single options object. All options are optional.
+
+### Top-level options
+
+| Option | Type | Default | Required | Description |
+|--------|------|---------|----------|-------------|
+| `keys` | `KeySelector[]` | `[]` | No | Redact any field matching a listed key, at any depth |
+| `paths` | `PathEntry[]` | `[]` | No | Redact fields at specific paths; supports exact strings, structured paths, wildcards, and exclusion selectors |
+| `stringTests` | `StringTest[]` | `[]` | No | Redact matching patterns inside string values |
+| `censor` | `string \| function` | `'[REDACTED]'` | No | Replacement value, or a function `(value, context) => replacement` |
+| `serialise` | `boolean \| function` | `false` | No | `true` returns a JSON-safe string; a function receives the safe graph and may return any string |
+| `remove` | `boolean` | `false` | No | Remove matched keys from the output instead of replacing their values |
+| `retainStructure` | `boolean` | `false` | No | Keep descendant nodes traversable for lower-precedence rules when a parent is matched |
+| `replaceStringByLength` | `boolean` | `false` | No | Repeat the `censor` string to match the character length of the redacted value |
+| `types` | `ValueTypeName[]` | `['string']` | No | `typeof` categories eligible for redaction; a matched key whose value's type is not listed is left untouched |
+| `fuzzyKeyMatch` | `boolean` | `false` | No | Match when the configured key is a substring of the field name (e.g. `'pass'` matches `'password'`) |
+| `caseSensitiveKeyMatch` | `boolean` | `true` | No | When `false`, normalises key names (strips non-word characters, lowercases) before comparing |
+| `maxDepth` | `number` | unlimited | No | Stop traversal beyond this nesting depth; guards against deeply nested payload DoS |
+| `maxNodes` | `number` | unlimited | No | Stop traversal after this many nodes; guards against excessively large payload DoS |
+| `transformers` | `TransformersOption` | built-in defaults | No | Override how runtime types are represented in serialised output |
+| `diagnostics` | `DiagnosticsOptions` | — | No | Receive a structured event when a value is degraded to `[UNSUPPORTED]` during serialisation |
+
+`ValueTypeName` is one of: `'string'`, `'number'`, `'bigint'`, `'boolean'`, `'object'`, `'function'`, `'symbol'`, `'undefined'`.
+
+### `KeySelector`
+
+Each entry in `keys` may be a plain `string`, a `RegExp`, or a `KeyRule` object for per-key overrides.
+
+| Field | Type | Default | Required | Description |
+|-------|------|---------|----------|-------------|
+| `key` | `string \| RegExp` | — | Yes | The key to match |
+| `censor` | `string \| function` | top-level `censor` | No | Override the censor for this key only |
+| `remove` | `boolean` | top-level `remove` | No | Override remove for this key only |
+| `retainStructure` | `boolean` | top-level `retainStructure` | No | Override retainStructure for this key only |
+| `replaceStringByLength` | `boolean` | top-level `replaceStringByLength` | No | Override replaceStringByLength for this key only |
+| `fuzzyKeyMatch` | `boolean` | top-level `fuzzyKeyMatch` | No | Override fuzzyKeyMatch for this key only |
+| `caseSensitiveKeyMatch` | `boolean` | top-level `caseSensitiveKeyMatch` | No | Override caseSensitiveKeyMatch for this key only |
+
+### `PathEntry`
+
+Each entry in `paths` may be a plain dot-notation string (e.g. `'user.profile.ssn'`), a structured path array, or a `PathRule` object for per-path overrides.
+
+Structured path arrays may contain:
+
+| Segment type | Example | Matches |
+|---|---|---|
+| `string` or `number` | `'password'` | Exact key or index |
+| `RegExp` | `/^pass/i` | Keys matching the regex |
+| `{ any: true }` | — | Any single key (`*`) |
+| `{ anyDepth: true }` | — | Zero or more keys at any depth (`**`) |
+| `{ ignore: string \| number \| RegExp }` | `{ ignore: 'country' }` | Excludes a key from a surrounding wildcard |
+
+| Field | Type | Default | Required | Description |
+|-------|------|---------|----------|-------------|
+| `path` | `string \| PathSegments[]` | — | Yes | The path to match |
+| `censor` | `string \| function` | top-level `censor` | No | Override the censor for this path only |
+| `remove` | `boolean` | top-level `remove` | No | Override remove for this path only |
+| `retainStructure` | `boolean` | top-level `retainStructure` | No | Override retainStructure for this path only |
+| `replaceStringByLength` | `boolean` | top-level `replaceStringByLength` | No | Override replaceStringByLength for this path only |
+
+### `StringTest`
+
+Each entry in `stringTests` may be a bare `RegExp` (whole-value replacement with `censor`) or a `SubstringRule` for partial replacement.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `pattern` | `RegExp` | Yes | Regular expression tested against string values |
+| `replacer` | `(value: string, pattern: RegExp) => string` | Yes | Returns the redacted string; called only when `pattern` matches |
+
+### `TransformersOption`
+
+Transformers control how non-JSON-safe runtime types are represented when `serialise: true`. Each transformer is a function `(value: unknown) => unknown` that either returns a transformed value or returns the value unchanged to pass to the next transformer in the chain.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `byType.bigint` | `Transformer[]` | Applied to `BigInt` values (does not consult `byType.object`) |
+| `byType.object` | `Transformer[]` | Applied first for built-in constructor types and unknown object types |
+| `byConstructor.Date` | `Transformer[]` | Applied to `Date` instances |
+| `byConstructor.Error` | `Transformer[]` | Applied to `Error` instances |
+| `byConstructor.Map` | `Transformer[]` | Applied to `Map` instances |
+| `byConstructor.RegExp` | `Transformer[]` | Applied to `RegExp` instances |
+| `byConstructor.Set` | `Transformer[]` | Applied to `Set` instances |
+| `byConstructor.URL` | `Transformer[]` | Applied to `URL` instances |
+| `byConstructor.custom` | `CustomConstructorTransformerRegistration[]` | Custom types matched by `instanceof` in declaration order |
+| `fallback` | `Transformer[]` | Applied when no earlier transformer returns a changed value |
+
+The built-in transformers produce deterministic marker objects (e.g. `{ _transformer: 'date', datetime: '<ISO string>' }`). See [`docs/architecture/serialise-output.md`](docs/architecture/serialise-output.md) for the full dispatch order and marker shapes.
+
+### `DiagnosticsOptions`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sink` | `(event: DiagnosticEvent) => void` | Called with a structured event when a value is degraded to `'[UNSUPPORTED]'` during serialisation |
+
+## Public API
+
+```ts
+import { createRedactor, deepRedact } from '@hackylabs/deep-redact'
+
+// deepRedact and createRedactor are the same factory under different names
+const redact = deepRedact({ keys: ['secret'] })
+const same = createRedactor({ keys: ['secret'] })
+```
+
+## Documentation
+
+### Worked examples
+
+- [Key targeting](docs/examples/key-targeting.md)
+- [Fuzzy and case-insensitive key matching](docs/examples/fuzzy-key-matching.md)
+- [Path targeting](docs/examples/path-targeting.md)
+- [Wildcard path segments and ignore selectors](docs/examples/path-segment-ignore.md)
+- [Regex property matching](docs/examples/regex-property-matching.md)
+- [Per-key rule overrides](docs/examples/per-key-rule-overrides-string.md)
+- [Substring targeting](docs/examples/substring-targeting.md)
+- [Replacement and removal](docs/examples/replacement-and-removal.md)
+- [Structured vs serialised output](docs/examples/serialised-output.md)
+- [Custom transformers](docs/examples/custom-transformer.md)
+- [Value-type allowlist](docs/examples/value-type-allowlist-default.md)
+- [Singleton / service-root setup](docs/examples/singleton-setup.md)
+- [Console redaction adapter](docs/examples/console-redaction.md)
+
+### Migration guides
+
+- [Migrating from Deep Redact v3](docs/migration/from-v3.md)
+- [Migrating from fast-redact](docs/migration/from-fast-redact.md)
+
+### Architecture and design
+
+- [Rule precedence and evaluation order](docs/architecture/precedence.md)
+- [Serialised output: transformer dispatch and marker shapes](docs/architecture/serialise-output.md)
+- [One-way redaction contract](docs/architecture/one-way-redaction.md)
+
+### Platform and security teams
+
+- [Standardisation guide](docs/platform/standardisation-guide.md) — supported capabilities, targeting semantics, verification evidence, and adoption decision scope
+
+## Scripts
+
+- `pnpm run build`
+- `pnpm run lint`
+- `pnpm run test`
+- `pnpm run generate-exports`
+- `pnpm run generate-readme`
+- `pnpm run verify-generated-files`
+- `pnpm run bench`
+- `pnpm run bench:generate-charts`

package/dist/adapters/console/index.cjs

@@ -0,0 +1,74 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_node_console_sink = require("../../node-console-sink-BnRUkAAr.cjs");
+//#region src/core/diagnostics/console-diagnostic-event.ts
+const consoleRecursionBlockedMessage = "Nested console adapter call was blocked to prevent a recursive redaction loop.";
+const createConsoleRecursionBlockedDiagnosticEvent = (method) => {
+	return Object.freeze({
+		details: Object.freeze({ method }),
+		event: "console.recursion_blocked",
+		message: consoleRecursionBlockedMessage,
+		path: "",
+		valueType: "console"
+	});
+};
+const emitConsoleRecursionBlockedDiagnostic = (method, sink) => {
+	const resolvedSink = sink ?? require_node_console_sink.getNodeConsoleDiagnosticSink();
+	if (resolvedSink === void 0) return;
+	try {
+		resolvedSink(createConsoleRecursionBlockedDiagnosticEvent(method));
+	} catch {
+		return;
+	}
+};
+//#endregion
+//#region src/adapters/console/recursion-guard.ts
+const createConsoleRecursionGuard = (options = {}) => {
+	let active = false;
+	let emittedForActiveChain = false;
+	const sink = options.diagnostics?.sink;
+	return {
+		block(method) {
+			if (!emittedForActiveChain) {
+				emittedForActiveChain = true;
+				emitConsoleRecursionBlockedDiagnostic(method, sink);
+			}
+		},
+		isActive() {
+			return active;
+		},
+		run(operation) {
+			active = true;
+			emittedForActiveChain = false;
+			try {
+				return operation();
+			} finally {
+				active = false;
+				emittedForActiveChain = false;
+			}
+		}
+	};
+};
+//#endregion
+//#region src/adapters/console/create-redacted-console.ts
+const consoleMethodNames = Object.freeze([
+	"debug",
+	"error",
+	"info",
+	"log",
+	"trace",
+	"warn"
+]);
+const createRedactedConsole = (redactor, target, options = {}) => {
+	const guard = createConsoleRecursionGuard(options);
+	const adapted = {};
+	for (const method of consoleMethodNames) adapted[method] = (...args) => {
+		if (guard.isActive()) return guard.block(method);
+		return guard.run(() => {
+			const redactedArgs = args.map((argument) => redactor(argument));
+			return target[method](...redactedArgs);
+		});
+	};
+	return adapted;
+};
+//#endregion
+exports.createRedactedConsole = createRedactedConsole;

package/dist/adapters/console/index.d.cts

@@ -0,0 +1,22 @@
+import { _ as DiagnosticSink, t as Redactor } from "../../public-Da0aARA9.cjs";
+
+//#region src/adapters/console/create-redacted-console.d.ts
+type ConsoleMethodName = 'debug' | 'error' | 'info' | 'log' | 'trace' | 'warn';
+type ConsoleMethod = (...args: unknown[]) => unknown;
+interface ConsoleLike {
+  readonly debug: ConsoleMethod;
+  readonly error: ConsoleMethod;
+  readonly info: ConsoleMethod;
+  readonly log: ConsoleMethod;
+  readonly trace: ConsoleMethod;
+  readonly warn: ConsoleMethod;
+}
+interface ConsoleRedactionOptions {
+  readonly diagnostics?: {
+    readonly sink?: DiagnosticSink;
+  };
+}
+type RedactedConsole = ConsoleLike;
+declare const createRedactedConsole: (redactor: Redactor, target: ConsoleLike, options?: ConsoleRedactionOptions) => RedactedConsole;
+//#endregion
+export { type ConsoleLike, type ConsoleMethodName, type ConsoleRedactionOptions, type RedactedConsole, createRedactedConsole };

package/dist/adapters/console/index.d.ts

@@ -0,0 +1,22 @@
+import { _ as DiagnosticSink, t as Redactor } from "../../public-Dw4ycNzO.js";
+
+//#region src/adapters/console/create-redacted-console.d.ts
+type ConsoleMethodName = 'debug' | 'error' | 'info' | 'log' | 'trace' | 'warn';
+type ConsoleMethod = (...args: unknown[]) => unknown;
+interface ConsoleLike {
+  readonly debug: ConsoleMethod;
+  readonly error: ConsoleMethod;
+  readonly info: ConsoleMethod;
+  readonly log: ConsoleMethod;
+  readonly trace: ConsoleMethod;
+  readonly warn: ConsoleMethod;
+}
+interface ConsoleRedactionOptions {
+  readonly diagnostics?: {
+    readonly sink?: DiagnosticSink;
+  };
+}
+type RedactedConsole = ConsoleLike;
+declare const createRedactedConsole: (redactor: Redactor, target: ConsoleLike, options?: ConsoleRedactionOptions) => RedactedConsole;
+//#endregion
+export { type ConsoleLike, type ConsoleMethodName, type ConsoleRedactionOptions, type RedactedConsole, createRedactedConsole };

package/dist/adapters/console/index.js

@@ -0,0 +1,73 @@
+import { t as getNodeConsoleDiagnosticSink } from "../../node-console-sink-DaQleNZ8.js";
+//#region src/core/diagnostics/console-diagnostic-event.ts
+const consoleRecursionBlockedMessage = "Nested console adapter call was blocked to prevent a recursive redaction loop.";
+const createConsoleRecursionBlockedDiagnosticEvent = (method) => {
+	return Object.freeze({
+		details: Object.freeze({ method }),
+		event: "console.recursion_blocked",
+		message: consoleRecursionBlockedMessage,
+		path: "",
+		valueType: "console"
+	});
+};
+const emitConsoleRecursionBlockedDiagnostic = (method, sink) => {
+	const resolvedSink = sink ?? getNodeConsoleDiagnosticSink();
+	if (resolvedSink === void 0) return;
+	try {
+		resolvedSink(createConsoleRecursionBlockedDiagnosticEvent(method));
+	} catch {
+		return;
+	}
+};
+//#endregion
+//#region src/adapters/console/recursion-guard.ts
+const createConsoleRecursionGuard = (options = {}) => {
+	let active = false;
+	let emittedForActiveChain = false;
+	const sink = options.diagnostics?.sink;
+	return {
+		block(method) {
+			if (!emittedForActiveChain) {
+				emittedForActiveChain = true;
+				emitConsoleRecursionBlockedDiagnostic(method, sink);
+			}
+		},
+		isActive() {
+			return active;
+		},
+		run(operation) {
+			active = true;
+			emittedForActiveChain = false;
+			try {
+				return operation();
+			} finally {
+				active = false;
+				emittedForActiveChain = false;
+			}
+		}
+	};
+};
+//#endregion
+//#region src/adapters/console/create-redacted-console.ts
+const consoleMethodNames = Object.freeze([
+	"debug",
+	"error",
+	"info",
+	"log",
+	"trace",
+	"warn"
+]);
+const createRedactedConsole = (redactor, target, options = {}) => {
+	const guard = createConsoleRecursionGuard(options);
+	const adapted = {};
+	for (const method of consoleMethodNames) adapted[method] = (...args) => {
+		if (guard.isActive()) return guard.block(method);
+		return guard.run(() => {
+			const redactedArgs = args.map((argument) => redactor(argument));
+			return target[method](...redactedArgs);
+		});
+	};
+	return adapted;
+};
+//#endregion
+export { createRedactedConsole };