@amkisko/json-logging 0.1.1 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 Structured JSON logging for Bun, Node, Deno, Next.js, and Remix. The portable API follows the Ruby `activesupport-json_logging` gem style: create a logger, call severity methods, use `tagged` and `withContext`, and emit one JSON object per line.
 
-Zero runtime dependencies. Ambient `withContext` / block `tagged` use AsyncLocalStorage when the runtime exposes it through `process.getBuiltinModule("async_hooks")` (Node, Bun, Deno with Node builtins, Cloudflare Workers with `nodejs_compat`). The package never statically imports `node:async_hooks`, so browsers and Workers without Node builtins can still import and emit basic JSON lines; ambient context is a no-op there. Call `isAsyncLocalStorageAvailable()` to detect ALS. Helpers under `@amkisko/json-logging/next` and `@amkisko/json-logging/remix` use Web APIs and do not add framework packages as runtime dependencies.
+Zero runtime dependencies. Ambient `withContext` / block `tagged` use AsyncLocalStorage when the runtime exposes it through `process.getBuiltinModule("async_hooks")` (Node, Bun, Deno with Node builtins, Cloudflare Workers with `nodejs_compat`). The package never statically imports `node:async_hooks`, so browsers and Workers without Node builtins can still import and emit basic JSON lines; ambient context is a no-op there. On Workers that import `AsyncLocalStorage` from `node:async_hooks` themselves, call `configureContextStorage(new AsyncLocalStorage())` once at boot. Call `isAsyncLocalStorageAvailable()` to detect ALS. Helpers under `@amkisko/json-logging/next` and `@amkisko/json-logging/remix` use Web APIs and do not add framework packages as runtime dependencies.
 
 ## Runtime compatibility
 
@@ -11,7 +11,7 @@ Zero runtime dependencies. Ambient `withContext` / block `tagged` use AsyncLocal
 | Node.js | Compatible | Primary target; ALS context works. |
 | Bun | Compatible | Tested in CI; `@amkisko/json-logging/bun` for `Bun.serve`. |
 | Deno | Compatible | ALS via Deno Node builtins (`getBuiltinModule`). |
-| Cloudflare Workers | Compatible | Full ALS with `nodejs_compat`. Without it: import and basic logging still work; `withContext` does not retain fields. |
+| Cloudflare Workers | Compatible | Full ALS with `nodejs_compat` (soft-load or `configureContextStorage`). Without it: import and basic logging still work; `withContext` does not retain fields unless you inject ALS. |
 | Browsers | Compatible | Basic logging and sinks work. Ambient context requires a host that provides ALS (unusual in browsers). |
 
 On the JSR package settings page, mark Node.js, Bun, Deno, Cloudflare Workers, and Browsers as compatible. Keep the package description aligned with `package.json` (`JSR_TOKEN=... ./usr/bin/sync-jsr-settings`, or set it in the Settings tab).
@@ -64,12 +64,17 @@ Each line looks like:
 
 Object fields merge at the root. Tags appear as `tags`. Request fields appear under `context`. System keys (`tags`, `severity`, `timestamp`, `message`, `context`) are reserved.
 
-Optional hot-path helpers (RFC-0002):
+Optional hot-path helpers (RFC-0002, RFC-0005):
 
 ```ts
 const logger = createLogger({
   level: "info",
-  redact: ["user.password", "headers.authorization"],
+  redact: {
+    paths: ["user.password", "headers.authorization"],
+    keys: ["ssn", "apiKey"],
+    caseInsensitive: true,
+    censor: "hash", // or "filtered" | "remove" | (value) => unknown
+  },
   serializers: {
     err: (value) => value, // root-field transform
   },
@@ -80,6 +85,8 @@ if (logger.isLevelEnabled("debug")) {
 }
 ```
 
+Path-only form `redact: ["user.password"]` still applies `[FILTERED]`.
+
 ## Sinks
 
 Console is the default. Pass a custom sink or a `WritableStream`:

package/dist/context.d.ts

@@ -1,9 +1,11 @@
 /** Key/value fields stored in the ambient request context. */
 export type ContextFields = Record<string, unknown>;
-type Store = {
+/** ALS store shape for {@link configureContextStorage} and ambient helpers. */
+export type ContextStore = {
     context: ContextFields;
     tags: string[];
 };
+type Store = ContextStore;
 /** Minimal ALS surface used for request/block context (run + getStore only). */
 export type AlsInstance<T> = {
     run<R>(store: T, callback: () => R): R;
@@ -11,8 +13,14 @@ export type AlsInstance<T> = {
 };
 /** Constructor for {@link AlsInstance}, matching `node:async_hooks`.AsyncLocalStorage. */
 export type AlsConstructor = new <T>() => AlsInstance<T>;
-/** True when this runtime can construct AsyncLocalStorage for ambient context. */
+/** True when ambient context can use AsyncLocalStorage (injected or soft-loaded). */
 export declare function isAsyncLocalStorageAvailable(): boolean;
+/**
+ * Inject an AsyncLocalStorage instance for ambient `withContext` / block `tagged`
+ * when soft-load via `process.getBuiltinModule` is unavailable (for example Workers
+ * that import `node:async_hooks` directly). Pass `null` to clear and restore soft-load.
+ */
+export declare function configureContextStorage(storage: AlsInstance<ContextStore> | null): void;
 /** Test helper: force ALS constructor resolution (`null` = unavailable). */
 export declare function setAlsConstructorForTests(value: AlsConstructor | null | undefined): void;
 /** Test helper: pass null to simulate a runtime without AsyncLocalStorage. */

package/dist/context.js

@@ -50,10 +50,24 @@ function loadAlsConstructor() {
     cachedConstructor = undefined;
     return undefined;
 }
-/** True when this runtime can construct AsyncLocalStorage for ambient context. */
+/** True when ambient context can use AsyncLocalStorage (injected or soft-loaded). */
 export function isAsyncLocalStorageAvailable() {
+    if (alsOverride !== undefined && alsOverride !== null) {
+        return true;
+    }
+    if (alsOverride === null) {
+        return false;
+    }
     return loadAlsConstructor() !== undefined;
 }
+/**
+ * Inject an AsyncLocalStorage instance for ambient `withContext` / block `tagged`
+ * when soft-load via `process.getBuiltinModule` is unavailable (for example Workers
+ * that import `node:async_hooks` directly). Pass `null` to clear and restore soft-load.
+ */
+export function configureContextStorage(storage) {
+    alsOverride = storage === null ? undefined : storage;
+}
 /** Test helper: force ALS constructor resolution (`null` = unavailable). */
 export function setAlsConstructorForTests(value) {
     alsConstructorOverride = value;

package/dist/index.d.ts

@@ -15,17 +15,17 @@
  */
 export type { ConsoleMethodName, ConsoleMethods } from "./console-state.js";
 export { captureConsoleMethods, getBridgeOriginals, isInBridge, } from "./console-state.js";
-export type { AlsConstructor, AlsInstance, ContextFields } from "./context.js";
-export { getBlockTags, getContext, isAsyncLocalStorageAvailable, peekLogStore, withContext, } from "./context.js";
+export type { AlsConstructor, AlsInstance, ContextFields, ContextStore } from "./context.js";
+export { configureContextStorage, getBlockTags, getContext, isAsyncLocalStorageAvailable, peekLogStore, withContext, } from "./context.js";
 export { createLogger, JsonLogging } from "./json-logging.js";
 export { Logger } from "./logger.js";
-export type { CompiledRedactPath } from "./redact.js";
-export { applyCompiledRedactPaths, applyRedactPaths, compileRedactPaths, } from "./redact.js";
+export type { CompiledRedact, CompiledRedactPath } from "./redact.js";
+export { applyCompiledRedact, applyCompiledRedactPaths, applyRedactPaths, compileRedact, compileRedactPaths, hasRedactWork, } from "./redact.js";
 export { isSensitiveKey, MAX_CONTEXT_SIZE, MAX_DEPTH, MAX_STRING_LENGTH, prepareTags, sanitizeError, sanitizeHash, sanitizeString, } from "./sanitize.js";
 export { buildFallbackRecord, buildRecord, currentTimestamp, formatTimestamp, parseMessage, SYSTEM_KEYS, toJsonLine, } from "./serialize.js";
 export { isEnabled, LEVEL_ORDER, SEVERITY_NAMES, severityName } from "./severity.js";
 export { consoleSink, consoleSinkFrom, streamSink } from "./sinks.js";
 export type { PerformanceLike } from "./timestamp.js";
 export { defaultPerformance } from "./timestamp.js";
-export type { ContextProvider, FieldSerializer, JsonPrimitive, JsonValue, Level, LoggerOptions, LogMessage, LogRecord, SeverityName, Sink, } from "./types.js";
+export type { ContextProvider, FieldSerializer, JsonPrimitive, JsonValue, Level, LoggerOptions, LogMessage, LogRecord, RedactCensor, RedactOptions, SeverityName, Sink, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -14,10 +14,10 @@
  * @module
  */
 export { captureConsoleMethods, getBridgeOriginals, isInBridge, } from "./console-state.js";
-export { getBlockTags, getContext, isAsyncLocalStorageAvailable, peekLogStore, withContext, } from "./context.js";
+export { configureContextStorage, getBlockTags, getContext, isAsyncLocalStorageAvailable, peekLogStore, withContext, } from "./context.js";
 export { createLogger, JsonLogging } from "./json-logging.js";
 export { Logger } from "./logger.js";
-export { applyCompiledRedactPaths, applyRedactPaths, compileRedactPaths, } from "./redact.js";
+export { applyCompiledRedact, applyCompiledRedactPaths, applyRedactPaths, compileRedact, compileRedactPaths, hasRedactWork, } from "./redact.js";
 export { isSensitiveKey, MAX_CONTEXT_SIZE, MAX_DEPTH, MAX_STRING_LENGTH, prepareTags, sanitizeError, sanitizeHash, sanitizeString, } from "./sanitize.js";
 export { buildFallbackRecord, buildRecord, currentTimestamp, formatTimestamp, parseMessage, SYSTEM_KEYS, toJsonLine, } from "./serialize.js";
 export { isEnabled, LEVEL_ORDER, SEVERITY_NAMES, severityName } from "./severity.js";

package/dist/logger.d.ts

@@ -11,12 +11,13 @@ export declare class Logger {
     readonly clock?: () => Date;
     /** Sticky tags from construction or {@link Logger.tagged}. */
     readonly tags: readonly string[];
-    /** Configured redact paths (dot notation). */
+    /** Configured redact paths (dot notation); empty when only keys are set. */
     readonly redact: readonly string[];
     /** Root-field serializers. */
     readonly serializers: Readonly<Record<string, FieldSerializer>>;
     /** Optional ambient context provider. */
     readonly contextProvider?: ContextProvider;
+    private readonly redactSource;
     private readonly compiledRedact;
     constructor(options?: LoggerOptions);
     /** True when a message at `level` would be emitted. */

package/dist/logger.js

@@ -1,5 +1,5 @@
 import { withBlockTags } from "./context.js";
-import { compileRedactPaths } from "./redact.js";
+import { compileRedact, hasRedactWork } from "./redact.js";
 import { prepareTags, sanitizeHash } from "./sanitize.js";
 import { buildFallbackRecord, buildRecord, toJsonLine } from "./serialize.js";
 import { isEnabled } from "./severity.js";
@@ -7,6 +7,18 @@ import { consoleSink } from "./sinks.js";
 function isCallback(value) {
     return typeof value === "function";
 }
+function isRedactOptions(value) {
+    return !Array.isArray(value);
+}
+function redactPathsFrom(input) {
+    if (input === undefined) {
+        return [];
+    }
+    if (isRedactOptions(input)) {
+        return input.paths ? [...input.paths] : [];
+    }
+    return [...input];
+}
 /** Structured logger: severity methods, sticky tags, child loggers, never-raise emit path. */
 export class Logger {
     /** Minimum level that will be written. */
@@ -19,12 +31,13 @@ export class Logger {
     clock;
     /** Sticky tags from construction or {@link Logger.tagged}. */
     tags;
-    /** Configured redact paths (dot notation). */
+    /** Configured redact paths (dot notation); empty when only keys are set. */
     redact;
     /** Root-field serializers. */
     serializers;
     /** Optional ambient context provider. */
     contextProvider;
+    redactSource;
     compiledRedact;
     constructor(options = {}) {
         this.level = options.level ?? "info";
@@ -32,10 +45,11 @@ export class Logger {
         this.base = options.base ? sanitizeHash(options.base) : {};
         this.clock = options.clock;
         this.tags = options.tags ? prepareTags(options.tags) : [];
-        this.redact = options.redact ? [...options.redact] : [];
+        this.redactSource = options.redact;
+        this.redact = redactPathsFrom(options.redact);
         this.serializers = options.serializers ? { ...options.serializers } : {};
         this.contextProvider = options.contextProvider;
-        this.compiledRedact = compileRedactPaths(this.redact);
+        this.compiledRedact = compileRedact(options.redact);
     }
     /** True when a message at `level` would be emitted. */
     isLevelEnabled(level) {
@@ -68,7 +82,7 @@ export class Logger {
             sink: this.sink,
             clock: this.clock,
             tags: this.tags,
-            redact: this.redact,
+            redact: this.redactSource,
             serializers: this.serializers,
             contextProvider: this.contextProvider,
             base: { ...this.base, ...sanitizeHash(bindings) },
@@ -89,7 +103,7 @@ export class Logger {
             sink: this.sink,
             clock: this.clock,
             base: this.base,
-            redact: this.redact,
+            redact: this.redactSource,
             serializers: this.serializers,
             contextProvider: this.contextProvider,
             tags: [...this.tags, ...tags],
@@ -108,7 +122,7 @@ export class Logger {
                 preparedBase: true,
                 preparedTags: true,
                 clock: this.clock,
-                compiledRedact: this.compiledRedact,
+                compiledRedact: hasRedactWork(this.compiledRedact) ? this.compiledRedact : undefined,
                 serializers: this.serializers,
                 contextProvider: this.contextProvider,
             });

package/dist/redact.d.ts

@@ -1,9 +1,23 @@
+import type { RedactOptions } from "./types.js";
 /** Dot-path segments after {@link compileRedactPaths} (config-time). */
 export type CompiledRedactPath = readonly string[];
+/** Resolved redact plan used on the log hot path. */
+export type CompiledRedact = {
+    paths: readonly CompiledRedactPath[];
+    keys: ReadonlySet<string>;
+    caseInsensitive: boolean;
+    replace: (value: unknown) => unknown;
+};
 /** Compile redact paths once at logger construction. Config-time only. */
 export declare function compileRedactPaths(paths: readonly string[]): CompiledRedactPath[];
-/** Apply precompiled redact paths to a value tree. */
+/** Compile path and key redact options once at logger construction. */
+export declare function compileRedact(input: readonly string[] | RedactOptions | undefined): CompiledRedact;
+/** Apply a compiled redact plan (paths then keys). */
+export declare function applyCompiledRedact(value: unknown, compiled: CompiledRedact): unknown;
+/** Apply precompiled path list with default `[FILTERED]` censor. */
 export declare function applyCompiledRedactPaths(value: unknown, paths: readonly CompiledRedactPath[]): unknown;
-/** Apply string paths (compiles each call). Prefer compileRedactPaths on hot paths. */
+/** Apply string paths (compiles each call). Prefer compileRedact on hot paths. */
 export declare function applyRedactPaths(value: unknown, paths: readonly string[]): unknown;
+/** True when the compiled plan has any paths or keys. */
+export declare function hasRedactWork(compiled: CompiledRedact): boolean;
 //# sourceMappingURL=redact.d.ts.map

package/dist/redact.js

@@ -1,5 +1,6 @@
 import { plainObjectFrom } from "./objects.js";
 const FILTERED = "[FILTERED]";
+const REMOVED = Symbol("json-logging-removed");
 function splitPath(path) {
     if (path.length === 0) {
         return undefined;
@@ -21,57 +22,167 @@ export function compileRedactPaths(paths) {
     }
     return compiled;
 }
-function redactArray(value, parts, index, key) {
+function fnv1a32Hex(text) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i += 1) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function valueFingerprint(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function resolveReplace(censor, hashLabel) {
+    if (censor === "remove") {
+        return () => REMOVED;
+    }
+    if (censor === "hash") {
+        const label = hashLabel.length > 0 ? hashLabel : "hash";
+        return (value) => `[${label}:${fnv1a32Hex(valueFingerprint(value))}]`;
+    }
+    if (typeof censor === "function") {
+        return censor;
+    }
+    return () => FILTERED;
+}
+function isRedactOptions(value) {
+    return !Array.isArray(value);
+}
+function normalizeOptions(input) {
+    if (input === undefined) {
+        return {};
+    }
+    if (isRedactOptions(input)) {
+        return input;
+    }
+    return { paths: input };
+}
+/** Compile path and key redact options once at logger construction. */
+export function compileRedact(input) {
+    const options = normalizeOptions(input);
+    const caseInsensitive = options.caseInsensitive === true;
+    const keys = new Set();
+    for (const key of options.keys ?? []) {
+        if (key.length === 0) {
+            continue;
+        }
+        keys.add(caseInsensitive ? key.toLowerCase() : key);
+    }
+    return {
+        paths: compileRedactPaths(options.paths ?? []),
+        keys,
+        caseInsensitive,
+        replace: resolveReplace(options.censor, options.hashLabel ?? "hash"),
+    };
+}
+function keyMatches(name, compiled) {
+    return compiled.keys.has(compiled.caseInsensitive ? name.toLowerCase() : name);
+}
+function redactArray(value, parts, index, key, compiled) {
     if (key === "*") {
-        return value.map((item) => redactAt(item, parts, index + 1));
+        return value.map((item) => redactAt(item, parts, index + 1, compiled));
     }
     const idx = Number(key);
     if (!Number.isInteger(idx) || idx < 0 || idx >= value.length) {
         return value;
     }
     const copy = value.slice();
-    copy[idx] = redactAt(copy[idx], parts, index + 1);
+    const next = redactAt(copy[idx], parts, index + 1, compiled);
+    copy[idx] = next === REMOVED ? null : next;
     return copy;
 }
-function redactObject(value, parts, index, key) {
+function redactObject(value, parts, index, key, compiled) {
     if (key === "*") {
         const out = {};
         for (const childKey of Object.keys(value)) {
-            out[childKey] = redactAt(value[childKey], parts, index + 1);
+            const next = redactAt(value[childKey], parts, index + 1, compiled);
+            if (next !== REMOVED) {
+                out[childKey] = next;
+            }
         }
         return out;
     }
     if (!(key in value)) {
         return value;
     }
-    return {
-        ...value,
-        [key]: redactAt(value[key], parts, index + 1),
-    };
+    const next = redactAt(value[key], parts, index + 1, compiled);
+    if (next === REMOVED) {
+        const out = { ...value };
+        delete out[key];
+        return out;
+    }
+    return { ...value, [key]: next };
 }
-function redactAt(value, parts, index) {
+function redactAt(value, parts, index, compiled) {
     if (index >= parts.length) {
-        return FILTERED;
+        return compiled.replace(value);
     }
     if (typeof value !== "object" || value === null) {
         return value;
     }
     const key = String(parts[index]);
     if (Array.isArray(value)) {
-        return redactArray(value, parts, index, key);
+        return redactArray(value, parts, index, key, compiled);
     }
-    return redactObject(plainObjectFrom(value), parts, index, key);
+    return redactObject(plainObjectFrom(value), parts, index, key, compiled);
 }
-/** Apply precompiled redact paths to a value tree. */
-export function applyCompiledRedactPaths(value, paths) {
+function applyKeys(value, compiled) {
+    if (compiled.keys.size === 0) {
+        return value;
+    }
+    if (typeof value !== "object" || value === null) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        const items = value;
+        return items.map((item) => applyKeys(item, compiled));
+    }
+    const source = plainObjectFrom(value);
+    const out = {};
+    for (const key of Object.keys(source)) {
+        if (keyMatches(key, compiled)) {
+            const replaced = compiled.replace(source[key]);
+            if (replaced !== REMOVED) {
+                out[key] = replaced;
+            }
+            continue;
+        }
+        out[key] = applyKeys(source[key], compiled);
+    }
+    return out;
+}
+/** Apply a compiled redact plan (paths then keys). */
+export function applyCompiledRedact(value, compiled) {
     let current = value;
-    for (const parts of paths) {
-        current = redactAt(current, parts, 0);
+    for (const parts of compiled.paths) {
+        current = redactAt(current, parts, 0, compiled);
     }
-    return current;
+    return applyKeys(current, compiled);
+}
+/** Apply precompiled path list with default `[FILTERED]` censor. */
+export function applyCompiledRedactPaths(value, paths) {
+    return applyCompiledRedact(value, {
+        paths,
+        keys: new Set(),
+        caseInsensitive: false,
+        replace: () => FILTERED,
+    });
 }
-/** Apply string paths (compiles each call). Prefer compileRedactPaths on hot paths. */
+/** Apply string paths (compiles each call). Prefer compileRedact on hot paths. */
 export function applyRedactPaths(value, paths) {
-    return applyCompiledRedactPaths(value, compileRedactPaths(paths));
+    return applyCompiledRedact(value, compileRedact(paths));
+}
+/** True when the compiled plan has any paths or keys. */
+export function hasRedactWork(compiled) {
+    return compiled.paths.length > 0 || compiled.keys.size > 0;
 }
 //# sourceMappingURL=redact.js.map

package/dist/serialize.d.ts

@@ -1,4 +1,4 @@
-import { type CompiledRedactPath } from "./redact.js";
+import { type CompiledRedact, type CompiledRedactPath } from "./redact.js";
 import type { ContextProvider, FieldSerializer, Level, LogMessage, LogRecord } from "./types.js";
 export type { PerformanceLike } from "./timestamp.js";
 export { currentTimestamp, defaultPerformance, formatTimestamp, } from "./timestamp.js";
@@ -18,7 +18,8 @@ export type BuildLineInput = {
     preparedTags?: boolean;
     clock?: () => Date;
     redact?: readonly string[];
-    compiledRedact?: readonly CompiledRedactPath[];
+    /** Precompiled path list (RFC-0002) or full plan (RFC-0005). */
+    compiledRedact?: readonly CompiledRedactPath[] | CompiledRedact;
     serializers?: Readonly<Record<string, FieldSerializer>>;
     contextProvider?: ContextProvider;
 };

package/dist/serialize.js

@@ -1,6 +1,6 @@
 import { peekLogStore } from "./context.js";
 import { isPlainObject, readObjectField } from "./objects.js";
-import { applyCompiledRedactPaths, applyRedactPaths } from "./redact.js";
+import { applyCompiledRedact, applyCompiledRedactPaths, applyRedactPaths, hasRedactWork, } from "./redact.js";
 import { prepareTags, sanitizeError, sanitizeHash, sanitizeString, sanitizeValue, } from "./sanitize.js";
 import { severityName } from "./severity.js";
 import { currentTimestamp } from "./timestamp.js";
@@ -48,6 +48,9 @@ function mergeUserFields(payload, fields, alreadySanitized = false) {
     }
     return payload;
 }
+function isCompiledRedactPlan(value) {
+    return !Array.isArray(value) && typeof value === "object" && value !== null && "replace" in value;
+}
 function applySerializers(payload, serializers) {
     for (const key of Object.keys(serializers)) {
         if (!Object.hasOwn(payload, key)) {
@@ -146,9 +149,15 @@ export function buildRecord(input) {
             applySerializers(payload, input.serializers);
         }
     }
-    if (input.compiledRedact && input.compiledRedact.length > 0) {
-        const redacted = applyCompiledRedactPaths(payload, input.compiledRedact);
-        if (isPlainObject(redacted)) {
+    if (input.compiledRedact) {
+        const redacted = isCompiledRedactPlan(input.compiledRedact)
+            ? hasRedactWork(input.compiledRedact)
+                ? applyCompiledRedact(payload, input.compiledRedact)
+                : payload
+            : input.compiledRedact.length > 0
+                ? applyCompiledRedactPaths(payload, input.compiledRedact)
+                : payload;
+        if (redacted !== payload && isPlainObject(redacted)) {
             for (const key of Object.keys(payload)) {
                 delete payload[key];
             }

package/dist/types.d.ts

@@ -14,6 +14,25 @@ export type Sink = {
 export type FieldSerializer = (value: unknown) => unknown;
 /** Optional ambient enrichment at log time (e.g. trace ids). Must not throw; throws take never-raise fallback. */
 export type ContextProvider = () => Record<string, unknown> | undefined;
+/**
+ * How matched redact leaves are replaced.
+ * `filtered` writes `[FILTERED]`; `remove` drops object keys (array slots become `null`);
+ * `hash` writes a non-cryptographic `[label:hex8]` correlation token.
+ */
+export type RedactCensor = "filtered" | "remove" | "hash" | ((value: unknown) => unknown);
+/** Path and key redaction options (RFC-0005). Array form remains path-only with `filtered`. */
+export type RedactOptions = {
+    /** Dot paths; segment `*` matches one key or index. */
+    paths?: readonly string[];
+    /** Object key names matched anywhere in the record tree. */
+    keys?: readonly string[];
+    /** When true, `keys` matching ignores case. Default false. */
+    caseInsensitive?: boolean;
+    /** Replacement mode. Default `filtered`. */
+    censor?: RedactCensor;
+    /** Label inside hash tokens. Default `hash`. */
+    hashLabel?: string;
+};
 /** Construction options for {@link Logger}. */
 export type LoggerOptions = {
     /** Minimum level to emit. Default `info`. */
@@ -26,8 +45,11 @@ export type LoggerOptions = {
     clock?: () => Date;
     /** Sticky tags applied to every line from this logger. */
     tags?: readonly string[];
-    /** Dot paths to filter (config-time only). Segment `*` matches one key or index. */
-    redact?: readonly string[];
+    /**
+     * Dot paths (RFC-0002) or {@link RedactOptions} with keys and censor modes (RFC-0005).
+     * Config-time only. Segment `*` matches one key or index.
+     */
+    redact?: readonly string[] | RedactOptions;
     /** Root field name to serializer. */
     serializers?: Readonly<Record<string, FieldSerializer>>;
     /** Merged under `context` after ALS ambient context; call-site context wins. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amkisko/json-logging",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Structured JSON logging with ActiveSupport-style tagged and withContext helpers",
   "type": "module",
   "license": "MIT",