@amkisko/json-logging 0.1.0 → 0.1.1

package/README.md

@@ -14,7 +14,7 @@ Zero runtime dependencies. Ambient `withContext` / block `tagged` use AsyncLocal
 | Cloudflare Workers | Compatible | Full ALS with `nodejs_compat`. Without it: import and basic logging still work; `withContext` does not retain fields. |
 | 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
 

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/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/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/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

@@ -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;
@@ -21,7 +22,10 @@ export type BuildLineInput = {
     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

@@ -82,6 +82,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) {
@@ -176,11 +177,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/package.json

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