@amkisko/json-logging 0.1.0 → 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,10 +11,10 @@ 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. Set the package description to the same summary as `package.json`.
+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).
 
 ## Install
 
@@ -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/console-bridge.d.ts

@@ -1,14 +1,19 @@
 import { type ConsoleMethodName, type ConsoleMethods } from "./console-state.js";
 import type { Logger } from "./logger.js";
 import type { LoggerOptions, LogMessage } from "./types.js";
+/** Options for {@link installConsoleBridge}. */
 export type ConsoleBridgeOptions = {
+    /** Which console methods to patch. Default: log, info, warn, error, debug. */
     methods?: readonly ConsoleMethodName[];
 };
+/** Result of {@link installStructuredLogging}: logger plus uninstall handle. */
 export type StructuredLoggingInstall = {
     logger: Logger;
     uninstall: () => void;
 };
+/** True when console methods are currently routed through a logger. */
 export declare function isConsoleBridgeInstalled(): boolean;
+/** Restore original console methods if a bridge was installed. */
 export declare function uninstallConsoleBridge(): void;
 /**
  * Routes console.log/info/warn/error/debug through `logger` as structured JSON.
@@ -21,6 +26,7 @@ export declare function installConsoleBridge(logger: Logger, options?: ConsoleBr
  * Prefer this when the goal is "app + console.* become structured JSON lines".
  */
 export declare function installStructuredLogging(options?: LoggerOptions & ConsoleBridgeOptions): StructuredLoggingInstall;
+/** Map `console.*` arguments into a {@link LogMessage} for structured emit. */
 export declare function messageFromConsoleArgs(args: unknown[]): LogMessage;
 export type { ConsoleMethods, ConsoleMethodName };
 //# sourceMappingURL=console-bridge.d.ts.map

package/dist/console-bridge.js

@@ -11,9 +11,11 @@ const LEVEL_BY_METHOD = {
     debug: "debug",
 };
 let installedMethods = null;
+/** True when console methods are currently routed through a logger. */
 export function isConsoleBridgeInstalled() {
     return getBridgeOriginals() !== null;
 }
+/** Restore original console methods if a bridge was installed. */
 export function uninstallConsoleBridge() {
     const originals = getBridgeOriginals();
     if (!originals || !installedMethods) {
@@ -73,6 +75,7 @@ export function installStructuredLogging(options = {}) {
     const uninstall = installConsoleBridge(logger, methods ? { methods } : {});
     return { logger, uninstall };
 }
+/** Map `console.*` arguments into a {@link LogMessage} for structured emit. */
 export function messageFromConsoleArgs(args) {
     if (args.length === 0) {
         return "";

package/dist/console-state.d.ts

@@ -1,11 +1,19 @@
+/** Console method names the bridge may patch. */
 export type ConsoleMethodName = "log" | "info" | "warn" | "error" | "debug";
+/** Bound console method bag used by sinks and the bridge. */
 export type ConsoleMethods = {
     [K in ConsoleMethodName]: (...args: unknown[]) => void;
 };
+/** Store or clear the pre-patch console methods while the bridge is installed. */
 export declare function setBridgeOriginals(methods: ConsoleMethods | null): void;
+/** Pre-patch console methods, or null when the bridge is not installed. */
 export declare function getBridgeOriginals(): ConsoleMethods | null;
+/** Enter a re-entrancy guard so bridge writes use original console methods. */
 export declare function enterBridge(): void;
+/** Leave the re-entrancy guard opened by {@link enterBridge}. */
 export declare function leaveBridge(): void;
+/** True while a bridged console write is in progress. */
 export declare function isInBridge(): boolean;
+/** Snapshot console methods from `target` (defaults to global `console`). */
 export declare function captureConsoleMethods(target?: Partial<ConsoleMethods> & object): ConsoleMethods;
 //# sourceMappingURL=console-state.d.ts.map

package/dist/console-state.js

@@ -1,22 +1,28 @@
 let bridgeOriginals = null;
 let bridgeDepth = 0;
+/** Store or clear the pre-patch console methods while the bridge is installed. */
 export function setBridgeOriginals(methods) {
     bridgeOriginals = methods;
 }
+/** Pre-patch console methods, or null when the bridge is not installed. */
 export function getBridgeOriginals() {
     return bridgeOriginals;
 }
+/** Enter a re-entrancy guard so bridge writes use original console methods. */
 export function enterBridge() {
     bridgeDepth += 1;
 }
+/** Leave the re-entrancy guard opened by {@link enterBridge}. */
 export function leaveBridge() {
     if (bridgeDepth > 0) {
         bridgeDepth -= 1;
     }
 }
+/** True while a bridged console write is in progress. */
 export function isInBridge() {
     return bridgeDepth > 0;
 }
+/** Snapshot console methods from `target` (defaults to global `console`). */
 export function captureConsoleMethods(target = console) {
     return {
         log: bindMethod(target, "log"),

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/http-ambient.d.ts

@@ -1,5 +1,7 @@
 import type { Logger } from "./logger.js";
+/** Set the process-wide ambient logger used by HTTP adapters. */
 export declare function bindHttpLogger(logger: Logger): void;
+/** Current ambient HTTP logger, if {@link bindHttpLogger} was called. */
 export declare function getAmbientHttpLogger(): Logger | undefined;
 /** Bind options.logger once when building an adapter factory. */
 export declare function bindLoggerFromOptions(options?: {

package/dist/http-ambient.js

@@ -1,7 +1,9 @@
 let ambientLogger;
+/** Set the process-wide ambient logger used by HTTP adapters. */
 export function bindHttpLogger(logger) {
     ambientLogger = logger;
 }
+/** Current ambient HTTP logger, if {@link bindHttpLogger} was called. */
 export function getAmbientHttpLogger() {
     return ambientLogger;
 }

package/dist/http-context.d.ts

@@ -1,8 +1,10 @@
 import type { Logger } from "./logger.js";
 import type { LoggerOptions } from "./types.js";
+/** Headers-like object with a `get` method (Fetch `Headers`, etc.). */
 export type HeaderBag = {
     get(name: string): string | null;
 };
+/** Request fields used to build ambient HTTP context. */
 export type HttpRequestInput = {
     method?: string;
     url?: string;
@@ -10,9 +12,13 @@ export type HttpRequestInput = {
     headers?: HeaderBag | Record<string, string | string[] | undefined>;
     requestId?: string;
 };
+/** Options for {@link withHttpContext} and framework adapters. */
 export type WithHttpContextOptions = {
+    /** Header name for inbound request id. Default `x-request-id`. */
     headerName?: string;
+    /** Explicit logger; otherwise ambient or a new logger from loggerOptions. */
     logger?: Logger;
+    /** Used when creating a logger if none is bound. */
     loggerOptions?: LoggerOptions;
     /** Optional allowlisted fields merged under http fields (http fields win). */
     extra?: Record<string, unknown>;
@@ -24,6 +30,7 @@ export type WithHttpContextOptions = {
     /** When true, adapters emit one completion line after the request. */
     logCompletion?: boolean;
 };
+/** Fields for {@link logRequestCompletion}. */
 export type RequestCompletionFields = {
     method?: string;
     path?: string;
@@ -33,17 +40,26 @@ export type RequestCompletionFields = {
 };
 /** Accept inbound request ids that are short and correlation-safe. */
 export declare const REQUEST_ID_PATTERN: RegExp;
+/** Monotonic fallback request id when crypto UUID is unavailable. */
 export declare function fallbackRequestId(now?: () => number): string;
+/** Prefer `crypto.randomUUID`, else {@link fallbackRequestId}. */
 export declare function defaultRandomId(randomUUID?: (() => string) | null): string;
+/** True when `value` matches {@link REQUEST_ID_PATTERN}. */
 export declare function isValidRequestId(value: string): boolean;
+/** Keep a valid inbound id, otherwise allocate a new one. */
 export declare function allocateRequestId(existing: string | null | undefined, randomId?: () => string): string;
+/** Pathname from an absolute or relative URL string. */
 export declare function requestPathFromUrl(url: string): string | undefined;
+/** Pick named keys from a bag; missing keys are omitted. */
 export declare function pickContextKeys(bag: Record<string, unknown> | undefined, keys: readonly string[] | undefined): Record<string, unknown>;
+/** Build requestId / method / path fields from {@link HttpRequestInput}. */
 export declare function httpFieldsFrom(input: HttpRequestInput, headerName?: string): Record<string, unknown>;
+/** Copy allowlisted header names into a sanitized string map. */
 export declare function pickAllowlistedHeaders(headers: HeaderBag | Record<string, string | string[] | undefined> | undefined, names: readonly string[] | undefined): Record<string, unknown>;
 /**
  * One structured access line. Level is error when status >= 500 or error is set.
  */
 export declare function logRequestCompletion(logger: Logger, fields: RequestCompletionFields): void;
+/** Run `fn` under ALS context built from the HTTP request input. */
 export declare function withHttpContext<T>(input: HttpRequestInput, fn: () => T | Promise<T>, options?: WithHttpContextOptions): T | Promise<T>;
 //# sourceMappingURL=http-context.d.ts.map

package/dist/http-context.js

@@ -3,10 +3,12 @@ import { sanitizeError, sanitizeString } from "./sanitize.js";
 /** Accept inbound request ids that are short and correlation-safe. */
 export const REQUEST_ID_PATTERN = /^[\w.\-:]{1,128}$/;
 let fallbackCounter = 0;
+/** Monotonic fallback request id when crypto UUID is unavailable. */
 export function fallbackRequestId(now = Date.now) {
     fallbackCounter += 1;
     return `req_${now().toString(36)}_${fallbackCounter.toString(36)}`;
 }
+/** Prefer `crypto.randomUUID`, else {@link fallbackRequestId}. */
 export function defaultRandomId(randomUUID) {
     const resolved = randomUUID === undefined ? globalThis.crypto?.randomUUID?.bind(globalThis.crypto) : randomUUID;
     if (typeof resolved === "function") {
@@ -14,9 +16,11 @@ export function defaultRandomId(randomUUID) {
     }
     return fallbackRequestId();
 }
+/** True when `value` matches {@link REQUEST_ID_PATTERN}. */
 export function isValidRequestId(value) {
     return REQUEST_ID_PATTERN.test(value);
 }
+/** Keep a valid inbound id, otherwise allocate a new one. */
 export function allocateRequestId(existing, randomId = defaultRandomId) {
     if (existing && isValidRequestId(existing)) {
         return existing;
@@ -28,6 +32,7 @@ export function allocateRequestId(existing, randomId = defaultRandomId) {
         return fallbackRequestId();
     }
 }
+/** Pathname from an absolute or relative URL string. */
 export function requestPathFromUrl(url) {
     if (url.length === 0) {
         return undefined;
@@ -66,6 +71,7 @@ function headerGet(headers, name) {
     }
     return typeof direct === "string" ? direct : null;
 }
+/** Pick named keys from a bag; missing keys are omitted. */
 export function pickContextKeys(bag, keys) {
     if (!bag || !keys || keys.length === 0) {
         return {};
@@ -78,6 +84,7 @@ export function pickContextKeys(bag, keys) {
     }
     return out;
 }
+/** Build requestId / method / path fields from {@link HttpRequestInput}. */
 export function httpFieldsFrom(input, headerName = "x-request-id") {
     const fromHeader = headerGet(input.headers, headerName);
     const requestId = allocateRequestId(input.requestId ?? fromHeader);
@@ -91,6 +98,7 @@ export function httpFieldsFrom(input, headerName = "x-request-id") {
     }
     return fields;
 }
+/** Copy allowlisted header names into a sanitized string map. */
 export function pickAllowlistedHeaders(headers, names) {
     if (!headers || !names || names.length === 0) {
         return {};
@@ -135,6 +143,7 @@ export function logRequestCompletion(logger, fields) {
         logger.info(payload);
     }
 }
+/** Run `fn` under ALS context built from the HTTP request input. */
 export function withHttpContext(input, fn, options = {}) {
     const headerName = options.headerName ?? "x-request-id";
     const fields = {

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/next.d.ts

@@ -31,6 +31,7 @@ export type WithRequestLoggingOptions = {
     logger?: Logger;
     loggerOptions?: LoggerOptions;
 };
+/** Re-export request-id helpers for Next entrypoint consumers. */
 export { allocateRequestId, defaultRandomId, fallbackRequestId };
 /**
  * Wrap a Next.js middleware or route handler with request-scoped context.

package/dist/next.js

@@ -15,6 +15,7 @@
  */
 import { bindLoggerFromOptions } from "./http-ambient.js";
 import { allocateRequestId, defaultRandomId, fallbackRequestId, withHttpContext, } from "./http-context.js";
+/** Re-export request-id helpers for Next entrypoint consumers. */
 export { allocateRequestId, defaultRandomId, fallbackRequestId };
 /**
  * Wrap a Next.js middleware or route handler with request-scoped context.

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/sanitize.d.ts

@@ -9,12 +9,17 @@ export declare const MAX_DEPTH = 10;
 export declare const MAX_BACKTRACE_LINES = 20;
 /** Case-insensitive sensitive key names (password, secret, token, authorization, api_key, ...). */
 export declare const SENSITIVE_KEY_PATTERN: RegExp;
+/** True when a key name matches {@link SENSITIVE_KEY_PATTERN}. */
 export declare function isSensitiveKey(key: string): boolean;
+/** Strip control characters and truncate to {@link MAX_STRING_LENGTH}. */
 export declare function sanitizeString(value: string): string;
+/** Coerce tags to non-empty sanitized strings, dropping nullish entries. */
 export declare function prepareTags(tags: readonly unknown[]): string[];
+/** Shape an Error under an `error` key for log payloads (name, message, stack, cause). */
 export declare function sanitizeError(error: Error): {
     [key: string]: JsonValue;
 };
 export declare function sanitizeValue(value: unknown, depth: number, seen: WeakSet<object>): JsonValue;
+/** Sanitize a plain object: filter sensitive keys, bound depth/size, mark cycles. */
 export declare function sanitizeHash(hash: Record<string, unknown>, depth?: number): Record<string, unknown>;
 //# sourceMappingURL=sanitize.d.ts.map

package/dist/sanitize.js

@@ -12,9 +12,11 @@ const CONTROL_CHARS = /[\x00-\x1F\x7F]/g;
 export const SENSITIVE_KEY_PATTERN = /(passw|pwd|secret|token|authorization|auth|api[_-]?key|_key$|crypt|salt|certificate|otp|ssn|cvv|cvc|credential)/i;
 const FILTERED = "[FILTERED]";
 const CIRCULAR = "[Circular]";
+/** True when a key name matches {@link SENSITIVE_KEY_PATTERN}. */
 export function isSensitiveKey(key) {
     return SENSITIVE_KEY_PATTERN.test(key);
 }
+/** Strip control characters and truncate to {@link MAX_STRING_LENGTH}. */
 export function sanitizeString(value) {
     try {
         let result = value.replace(CONTROL_CHARS, "");
@@ -27,6 +29,7 @@ export function sanitizeString(value) {
         return "<sanitization_error>";
     }
 }
+/** Coerce tags to non-empty sanitized strings, dropping nullish entries. */
 export function prepareTags(tags) {
     const prepared = [];
     for (const tag of tags) {
@@ -40,6 +43,7 @@ export function prepareTags(tags) {
     }
     return prepared;
 }
+/** Shape an Error under an `error` key for log payloads (name, message, stack, cause). */
 export function sanitizeError(error) {
     try {
         const body = {
@@ -134,6 +138,7 @@ function sanitizeObject(value, depth, seen) {
     }
     return result;
 }
+/** Sanitize a plain object: filter sensitive keys, bound depth/size, mark cycles. */
 export function sanitizeHash(hash, depth = 0) {
     try {
         if (depth > MAX_DEPTH) {

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";
@@ -6,6 +6,7 @@ export { currentTimestamp, defaultPerformance, formatTimestamp, } from "./timest
 export declare const SYSTEM_KEYS: ReadonlySet<string>;
 /** Normalize a log message into root fields (string, object, or Error). */
 export declare function parseMessage(message: LogMessage): Record<string, unknown>;
+/** Inputs for {@link buildRecord} on the log hot path. */
 export type BuildLineInput = {
     message: LogMessage;
     level: Level;
@@ -17,11 +18,15 @@ 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;
 };
+/** Assemble one log record: message, severity, tags, context, serializers, redact. */
 export declare function buildRecord(input: BuildLineInput): LogRecord;
+/** Serialize a record to one JSON line with a trailing newline. */
 export declare function toJsonLine(record: LogRecord): string;
+/** Never-raise fallback record when the primary emit path throws. */
 export declare function buildFallbackRecord(level: Level, message: unknown, error: unknown, clock?: () => Date): LogRecord;
 //# sourceMappingURL=serialize.d.ts.map

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)) {
@@ -82,6 +85,7 @@ function mergeProviderContext(payload, provider) {
         ...readObjectField(payload, "context"),
     };
 }
+/** Assemble one log record: message, severity, tags, context, serializers, redact. */
 export function buildRecord(input) {
     const payload = {};
     if (input.base && Object.keys(input.base).length > 0) {
@@ -145,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];
             }
@@ -176,11 +186,13 @@ function uniqueTags(tags) {
     }
     return result;
 }
+/** Serialize a record to one JSON line with a trailing newline. */
 export function toJsonLine(record) {
     const seen = new WeakSet();
     const safe = sanitizeValue(record, 0, seen);
     return `${JSON.stringify(safe)}\n`;
 }
+/** Never-raise fallback record when the primary emit path throws. */
 export function buildFallbackRecord(level, message, error, clock) {
     const err = error instanceof Error ? error : new Error(typeof error === "string" ? error : "unknown");
     return {

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.0",
+  "version": "0.2.0",
   "description": "Structured JSON logging with ActiveSupport-style tagged and withContext helpers",
   "type": "module",
   "license": "MIT",