@amkisko/json-logging 0.0.0-stage → 0.1.1

package/dist/redact.d.ts

@@ -0,0 +1,9 @@
+/** Dot-path segments after {@link compileRedactPaths} (config-time). */
+export type CompiledRedactPath = readonly string[];
+/** 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. */
+export declare function applyCompiledRedactPaths(value: unknown, paths: readonly CompiledRedactPath[]): unknown;
+/** Apply string paths (compiles each call). Prefer compileRedactPaths on hot paths. */
+export declare function applyRedactPaths(value: unknown, paths: readonly string[]): unknown;
+//# sourceMappingURL=redact.d.ts.map

package/dist/redact.js

@@ -0,0 +1,77 @@
+import { plainObjectFrom } from "./objects.js";
+const FILTERED = "[FILTERED]";
+function splitPath(path) {
+    if (path.length === 0) {
+        return undefined;
+    }
+    const parts = path.split(".");
+    if (parts.some((part) => part.length === 0)) {
+        return undefined;
+    }
+    return parts;
+}
+/** Compile redact paths once at logger construction. Config-time only. */
+export function compileRedactPaths(paths) {
+    const compiled = [];
+    for (const path of paths) {
+        const parts = splitPath(path);
+        if (parts) {
+            compiled.push(parts);
+        }
+    }
+    return compiled;
+}
+function redactArray(value, parts, index, key) {
+    if (key === "*") {
+        return value.map((item) => redactAt(item, parts, index + 1));
+    }
+    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);
+    return copy;
+}
+function redactObject(value, parts, index, key) {
+    if (key === "*") {
+        const out = {};
+        for (const childKey of Object.keys(value)) {
+            out[childKey] = redactAt(value[childKey], parts, index + 1);
+        }
+        return out;
+    }
+    if (!(key in value)) {
+        return value;
+    }
+    return {
+        ...value,
+        [key]: redactAt(value[key], parts, index + 1),
+    };
+}
+function redactAt(value, parts, index) {
+    if (index >= parts.length) {
+        return FILTERED;
+    }
+    if (typeof value !== "object" || value === null) {
+        return value;
+    }
+    const key = String(parts[index]);
+    if (Array.isArray(value)) {
+        return redactArray(value, parts, index, key);
+    }
+    return redactObject(plainObjectFrom(value), parts, index, key);
+}
+/** Apply precompiled redact paths to a value tree. */
+export function applyCompiledRedactPaths(value, paths) {
+    let current = value;
+    for (const parts of paths) {
+        current = redactAt(current, parts, 0);
+    }
+    return current;
+}
+/** Apply string paths (compiles each call). Prefer compileRedactPaths on hot paths. */
+export function applyRedactPaths(value, paths) {
+    return applyCompiledRedactPaths(value, compileRedactPaths(paths));
+}
+//# sourceMappingURL=redact.js.map

package/dist/remix.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Remix helpers: run handleRequest / loader bodies with request-scoped log context.
+ *
+ * @example
+ * ```ts
+ * import { withRemixContext } from "@amkisko/json-logging/remix";
+ * import { httpLogger } from "@amkisko/json-logging/http";
+ *
+ * return withRemixContext({ request, context }, () => {
+ *   httpLogger().info("loading");
+ *   return handle(request);
+ * });
+ * ```
+ *
+ * @module
+ */
+import type { Logger } from "./logger.js";
+import type { LoggerOptions } from "./types.js";
+/** Minimal Remix request shape (no Remix runtime dependency). */
+export type RemixRequestLike = {
+    method?: string;
+    url?: string;
+    headers?: Headers;
+};
+/** Load / app context bag passed into Remix. */
+export type RemixContextBag = Record<string, unknown>;
+/** Options for {@link withRemixContext}. */
+export type WithRemixContextOptions = {
+    logger?: Logger;
+    loggerOptions?: LoggerOptions;
+    requestIdHeader?: string;
+    /** Allowlisted keys copied from load context into log context. Default: none. */
+    contextKeys?: readonly string[];
+};
+/**
+ * Run a Remix handleRequest / middleware / loader body with ALS context.
+ * Bind loggers via `@amkisko/json-logging/http` (`bindHttpLogger` / `httpLogger`).
+ */
+export declare function withRemixContext<T>(input: {
+    request?: RemixRequestLike;
+    context?: RemixContextBag;
+}, fn: () => T | Promise<T>, options?: WithRemixContextOptions): T | Promise<T>;
+//# sourceMappingURL=remix.d.ts.map

package/dist/remix.js

@@ -0,0 +1,38 @@
+/**
+ * Remix helpers: run handleRequest / loader bodies with request-scoped log context.
+ *
+ * @example
+ * ```ts
+ * import { withRemixContext } from "@amkisko/json-logging/remix";
+ * import { httpLogger } from "@amkisko/json-logging/http";
+ *
+ * return withRemixContext({ request, context }, () => {
+ *   httpLogger().info("loading");
+ *   return handle(request);
+ * });
+ * ```
+ *
+ * @module
+ */
+import { bindLoggerFromOptions } from "./http-ambient.js";
+import { pickContextKeys, withHttpContext } from "./http-context.js";
+/**
+ * Run a Remix handleRequest / middleware / loader body with ALS context.
+ * Bind loggers via `@amkisko/json-logging/http` (`bindHttpLogger` / `httpLogger`).
+ */
+export function withRemixContext(input, fn, options = {}) {
+    bindLoggerFromOptions(options);
+    const requestId = input.context?.requestId != null ? String(input.context.requestId) : undefined;
+    return withHttpContext({
+        headers: input.request?.headers,
+        method: input.request?.method,
+        url: input.request?.url,
+        requestId,
+    }, fn, {
+        headerName: options.requestIdHeader,
+        logger: options.logger,
+        loggerOptions: options.loggerOptions,
+        extra: pickContextKeys(input.context, options.contextKeys),
+    });
+}
+//# sourceMappingURL=remix.js.map

package/dist/sanitize.d.ts

@@ -0,0 +1,25 @@
+import type { JsonValue } from "./types.js";
+/** Maximum string length kept after sanitization (longer values are truncated). */
+export declare const MAX_STRING_LENGTH = 10000;
+/** Maximum number of keys kept in a sanitized object. */
+export declare const MAX_CONTEXT_SIZE = 50;
+/** Maximum nesting depth when sanitizing structured values. */
+export declare const MAX_DEPTH = 10;
+/** Maximum stack frames kept on sanitized Error backtraces. */
+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

@@ -0,0 +1,153 @@
+import { plainObjectFrom } from "./objects.js";
+/** Maximum string length kept after sanitization (longer values are truncated). */
+export const MAX_STRING_LENGTH = 10_000;
+/** Maximum number of keys kept in a sanitized object. */
+export const MAX_CONTEXT_SIZE = 50;
+/** Maximum nesting depth when sanitizing structured values. */
+export const MAX_DEPTH = 10;
+/** Maximum stack frames kept on sanitized Error backtraces. */
+export const MAX_BACKTRACE_LINES = 20;
+const CONTROL_CHARS = /[\x00-\x1F\x7F]/g;
+/** Case-insensitive sensitive key names (password, secret, token, authorization, api_key, ...). */
+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, "");
+        if (result.length > MAX_STRING_LENGTH) {
+            result = `${result.slice(0, MAX_STRING_LENGTH)}...[truncated]`;
+        }
+        return result;
+    }
+    catch {
+        return "<sanitization_error>";
+    }
+}
+/** Coerce tags to non-empty sanitized strings, dropping nullish entries. */
+export function prepareTags(tags) {
+    const prepared = [];
+    for (const tag of tags) {
+        if (tag === null || tag === undefined) {
+            continue;
+        }
+        const text = sanitizeString(String(tag));
+        if (text.length > 0) {
+            prepared.push(text);
+        }
+    }
+    return prepared;
+}
+/** Shape an Error under an `error` key for log payloads (name, message, stack, cause). */
+export function sanitizeError(error) {
+    try {
+        const body = {
+            name: sanitizeString(error.name || "Error"),
+            message: sanitizeString(String(error.message ?? "")),
+        };
+        if (typeof error.stack === "string" && error.stack.length > 0) {
+            body.stack = sanitizeBacktrace(error.stack);
+        }
+        const cause = Reflect.get(error, "cause");
+        if (cause !== undefined) {
+            body.cause = sanitizeValue(cause, 0, new WeakSet());
+        }
+        return { error: body };
+    }
+    catch {
+        return {
+            error: { name: "Error", message: "<sanitization_failed>" },
+        };
+    }
+}
+function sanitizeBacktrace(stack) {
+    const lines = stack.split("\n").slice(0, MAX_BACKTRACE_LINES);
+    return sanitizeString(lines.join("\n"));
+}
+export function sanitizeValue(value, depth, seen) {
+    try {
+        if (value === null) {
+            return null;
+        }
+        if (value === undefined) {
+            return null;
+        }
+        if (typeof value === "string") {
+            return sanitizeString(value);
+        }
+        if (typeof value === "number") {
+            return Number.isFinite(value) ? value : String(value);
+        }
+        if (typeof value === "boolean") {
+            return value;
+        }
+        if (typeof value === "bigint") {
+            return value.toString();
+        }
+        if (typeof value === "symbol") {
+            return sanitizeString(String(value));
+        }
+        if (typeof value === "function") {
+            return sanitizeString(`[Function ${value.name || "anonymous"}]`);
+        }
+        if (value instanceof Error) {
+            return sanitizeError(value);
+        }
+        if (depth > MAX_DEPTH) {
+            return { error: "max_depth_exceeded" };
+        }
+        // Remaining values are objects (null already returned above).
+        if (seen.has(value)) {
+            return CIRCULAR;
+        }
+        seen.add(value);
+        if (Array.isArray(value)) {
+            return sanitizeArray(value, depth, seen);
+        }
+        return sanitizeObject(plainObjectFrom(value), depth, seen);
+    }
+    catch {
+        return "<unprintable>";
+    }
+}
+function sanitizeArray(value, depth, seen) {
+    const limited = value.slice(0, MAX_CONTEXT_SIZE);
+    const result = limited.map((item) => sanitizeValue(item, depth + 1, seen));
+    if (value.length > MAX_CONTEXT_SIZE) {
+        result.push("[truncated]");
+    }
+    return result;
+}
+function sanitizeObject(value, depth, seen) {
+    const result = {};
+    const keys = Object.keys(value).slice(0, MAX_CONTEXT_SIZE);
+    for (const key of keys) {
+        if (isSensitiveKey(key)) {
+            result[key] = FILTERED;
+            continue;
+        }
+        result[key] = sanitizeValue(value[key], depth + 1, seen);
+    }
+    if (Object.keys(value).length > MAX_CONTEXT_SIZE) {
+        result.__truncated__ = true;
+    }
+    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) {
+            return { error: "max_depth_exceeded" };
+        }
+        return sanitizeObject(hash, depth, new WeakSet());
+    }
+    catch {
+        return { sanitization_error: true };
+    }
+}
+//# sourceMappingURL=sanitize.js.map

package/dist/serialize.d.ts

@@ -0,0 +1,31 @@
+import { 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";
+/** Reserved root keys; collisions from user fields move under `context`. */
+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;
+    stickyTags: readonly string[];
+    base?: Record<string, unknown>;
+    /** When true, base was sanitized at Logger construction. */
+    preparedBase?: boolean;
+    /** When true, stickyTags were prepared at Logger construction. */
+    preparedTags?: boolean;
+    clock?: () => Date;
+    redact?: readonly string[];
+    compiledRedact?: readonly CompiledRedactPath[];
+    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

@@ -0,0 +1,203 @@
+import { peekLogStore } from "./context.js";
+import { isPlainObject, readObjectField } from "./objects.js";
+import { applyCompiledRedactPaths, applyRedactPaths } from "./redact.js";
+import { prepareTags, sanitizeError, sanitizeHash, sanitizeString, sanitizeValue, } from "./sanitize.js";
+import { severityName } from "./severity.js";
+import { currentTimestamp } from "./timestamp.js";
+export { currentTimestamp, defaultPerformance, formatTimestamp, } from "./timestamp.js";
+/** Reserved root keys; collisions from user fields move under `context`. */
+export const SYSTEM_KEYS = new Set([
+    "tags",
+    "severity",
+    "timestamp",
+    "message",
+    "context",
+]);
+/** Normalize a log message into root fields (string, object, or Error). */
+export function parseMessage(message) {
+    if (message instanceof Error) {
+        return sanitizeError(message);
+    }
+    if (typeof message === "string") {
+        return { message: sanitizeString(message) };
+    }
+    return mergeUserFields({}, message);
+}
+function mergeUserFields(payload, fields, alreadySanitized = false) {
+    const source = alreadySanitized ? fields : sanitizeHash(fields);
+    const conflicts = {};
+    for (const [key, value] of Object.entries(source)) {
+        if (key === "context" && isPlainObject(value)) {
+            payload.context = {
+                ...readObjectField(payload, "context"),
+                ...value,
+            };
+            continue;
+        }
+        if (SYSTEM_KEYS.has(key) || key in payload) {
+            conflicts[key] = value;
+            continue;
+        }
+        payload[key] = value;
+    }
+    if (Object.keys(conflicts).length > 0) {
+        payload.context = {
+            ...readObjectField(payload, "context"),
+            ...conflicts,
+        };
+    }
+    return payload;
+}
+function applySerializers(payload, serializers) {
+    for (const key of Object.keys(serializers)) {
+        if (!Object.hasOwn(payload, key)) {
+            continue;
+        }
+        const serialize = serializers[key];
+        if (typeof serialize !== "function") {
+            continue;
+        }
+        payload[key] = serialize(payload[key]);
+    }
+}
+function mergeProviderContext(payload, provider) {
+    const provided = provider();
+    if (!provided) {
+        return;
+    }
+    const sanitized = sanitizeHash(provided);
+    const filtered = {};
+    for (const [key, value] of Object.entries(sanitized)) {
+        if (SYSTEM_KEYS.has(key)) {
+            continue;
+        }
+        filtered[key] = value;
+    }
+    if (Object.keys(filtered).length === 0) {
+        return;
+    }
+    // Call-site / message context wins over provider.
+    payload.context = {
+        ...filtered,
+        ...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) {
+        mergeUserFields(payload, input.base, input.preparedBase === true);
+    }
+    const parsed = parseMessage(input.message);
+    for (const [key, value] of Object.entries(parsed)) {
+        if (key === "context" && isPlainObject(value)) {
+            payload.context = {
+                ...readObjectField(payload, "context"),
+                ...value,
+            };
+            continue;
+        }
+        payload[key] = value;
+    }
+    payload.severity = severityName(input.level);
+    payload.timestamp = currentTimestamp(input.clock);
+    const store = peekLogStore();
+    if (input.stickyTags.length > 0 || store.tags.length > 0) {
+        const sticky = input.preparedTags ? [...input.stickyTags] : prepareTags(input.stickyTags);
+        const tags = uniqueTags([...sticky, ...prepareTags(store.tags)]);
+        if (tags.length > 0) {
+            payload.tags = tags;
+        }
+    }
+    const context = store.context;
+    if (context) {
+        let hasContext = false;
+        for (const _key in context) {
+            hasContext = true;
+            break;
+        }
+        if (hasContext) {
+            const sanitizedContext = sanitizeHash(context);
+            const filtered = {};
+            for (const [key, value] of Object.entries(sanitizedContext)) {
+                if (SYSTEM_KEYS.has(key)) {
+                    continue;
+                }
+                filtered[key] = value;
+            }
+            if (Object.keys(filtered).length > 0) {
+                payload.context = {
+                    ...filtered,
+                    ...readObjectField(payload, "context"),
+                };
+            }
+        }
+    }
+    if (input.contextProvider) {
+        mergeProviderContext(payload, input.contextProvider);
+    }
+    if (input.serializers) {
+        let hasSerializers = false;
+        for (const _key in input.serializers) {
+            hasSerializers = true;
+            break;
+        }
+        if (hasSerializers) {
+            applySerializers(payload, input.serializers);
+        }
+    }
+    if (input.compiledRedact && input.compiledRedact.length > 0) {
+        const redacted = applyCompiledRedactPaths(payload, input.compiledRedact);
+        if (isPlainObject(redacted)) {
+            for (const key of Object.keys(payload)) {
+                delete payload[key];
+            }
+            Object.assign(payload, redacted);
+        }
+    }
+    else if (input.redact && input.redact.length > 0) {
+        const redacted = applyRedactPaths(payload, input.redact);
+        if (isPlainObject(redacted)) {
+            for (const key of Object.keys(payload)) {
+                delete payload[key];
+            }
+            Object.assign(payload, redacted);
+        }
+    }
+    return payload;
+}
+function uniqueTags(tags) {
+    const seen = new Set();
+    const result = [];
+    for (const tag of tags) {
+        if (!seen.has(tag)) {
+            seen.add(tag);
+            result.push(tag);
+        }
+    }
+    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 {
+        timestamp: currentTimestamp(clock),
+        severity: severityName(level),
+        message: sanitizeString(typeof message === "string"
+            ? message
+            : message instanceof Error
+                ? message.message
+                : "<unprintable>"),
+        logger_error: {
+            name: sanitizeString(err.name),
+            message: sanitizeString(String(err.message ?? "")),
+        },
+    };
+}
+//# sourceMappingURL=serialize.js.map

package/dist/severity.d.ts

@@ -0,0 +1,10 @@
+import type { Level, SeverityName } from "./types.js";
+/** Numeric order used to compare levels (higher is more severe). */
+export declare const LEVEL_ORDER: Record<Level, number>;
+/** Map from {@link Level} to the severity string written on each line. */
+export declare const SEVERITY_NAMES: Record<Level, SeverityName>;
+/** Return the uppercase severity name for a level. */
+export declare function severityName(level: Level): SeverityName;
+/** True when `requested` is at or above the configured minimum level. */
+export declare function isEnabled(configured: Level, requested: Level): boolean;
+//# sourceMappingURL=severity.d.ts.map

package/dist/severity.js

@@ -0,0 +1,25 @@
+/** Numeric order used to compare levels (higher is more severe). */
+export const LEVEL_ORDER = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    fatal: 4,
+};
+/** Map from {@link Level} to the severity string written on each line. */
+export const SEVERITY_NAMES = {
+    debug: "DEBUG",
+    info: "INFO",
+    warn: "WARN",
+    error: "ERROR",
+    fatal: "FATAL",
+};
+/** Return the uppercase severity name for a level. */
+export function severityName(level) {
+    return SEVERITY_NAMES[level];
+}
+/** True when `requested` is at or above the configured minimum level. */
+export function isEnabled(configured, requested) {
+    return LEVEL_ORDER[requested] >= LEVEL_ORDER[configured];
+}
+//# sourceMappingURL=severity.js.map

package/dist/sinks.d.ts

@@ -0,0 +1,14 @@
+import { type ConsoleMethods } from "./console-state.js";
+import type { Sink } from "./types.js";
+/** Writes JSON lines using the given console method table (usually pre-bridge originals). */
+export declare function consoleSinkFrom(methods: ConsoleMethods): Sink;
+/**
+ * Default console sink. When a console bridge is installed, writes through the
+ * captured originals so logger calls do not re-enter the bridge.
+ */
+export declare function consoleSink(): Sink;
+/** Sink that writes JSON lines to a Web Streams `WritableStream`. */
+export declare function streamSink(stream: WritableStream<Uint8Array>, options?: {
+    encoding?: "utf-8";
+}): Sink;
+//# sourceMappingURL=sinks.d.ts.map