@amkisko/json-logging 0.0.0-stage → 0.1.0

package/dist/sanitize.d.ts

@@ -0,0 +1,20 @@
+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;
+export declare function isSensitiveKey(key: string): boolean;
+export declare function sanitizeString(value: string): string;
+export declare function prepareTags(tags: readonly unknown[]): string[];
+export declare function sanitizeError(error: Error): {
+    [key: string]: JsonValue;
+};
+export declare function sanitizeValue(value: unknown, depth: number, seen: WeakSet<object>): JsonValue;
+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,148 @@
+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]";
+export function isSensitiveKey(key) {
+    return SENSITIVE_KEY_PATTERN.test(key);
+}
+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>";
+    }
+}
+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;
+}
+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;
+}
+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,27 @@
+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>;
+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;
+};
+export declare function buildRecord(input: BuildLineInput): LogRecord;
+export declare function toJsonLine(record: LogRecord): string;
+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,200 @@
+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"),
+    };
+}
+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;
+}
+export function toJsonLine(record) {
+    const seen = new WeakSet();
+    const safe = sanitizeValue(record, 0, seen);
+    return `${JSON.stringify(safe)}\n`;
+}
+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

package/dist/sinks.js

@@ -0,0 +1,66 @@
+import { captureConsoleMethods, getBridgeOriginals } from "./console-state.js";
+function pickMethod(methods, severity) {
+    const name = typeof severity === "string" ? severity.toUpperCase() : "INFO";
+    switch (name) {
+        case "ERROR":
+        case "FATAL":
+            return methods.error;
+        case "WARN":
+            return methods.warn;
+        case "DEBUG":
+            return methods.debug;
+        default:
+            return methods.info;
+    }
+}
+/** Writes JSON lines using the given console method table (usually pre-bridge originals). */
+export function consoleSinkFrom(methods) {
+    return {
+        write(line, record) {
+            const method = pickMethod(methods, record.severity);
+            const trimmed = line.endsWith("\n") ? line.slice(0, -1) : line;
+            method(trimmed);
+        },
+    };
+}
+/**
+ * Default console sink. When a console bridge is installed, writes through the
+ * captured originals so logger calls do not re-enter the bridge.
+ */
+export function consoleSink() {
+    return {
+        write(line, record) {
+            const methods = getBridgeOriginals() ?? captureConsoleMethods(console);
+            const method = pickMethod(methods, record.severity);
+            const trimmed = line.endsWith("\n") ? line.slice(0, -1) : line;
+            method(trimmed);
+        },
+    };
+}
+/** Sink that writes JSON lines to a Web Streams `WritableStream`. */
+export function streamSink(stream, options) {
+    const encoding = options?.encoding ?? "utf-8";
+    const encoder = new TextEncoder();
+    let chain = Promise.resolve();
+    return {
+        write(line, _record) {
+            const chunk = line.endsWith("\n") ? line : `${line}\n`;
+            const bytes = encoding === "utf-8" ? encoder.encode(chunk) : encoder.encode(chunk);
+            chain = chain
+                .then(async () => {
+                const writer = stream.getWriter();
+                try {
+                    await writer.write(bytes);
+                }
+                finally {
+                    writer.releaseLock();
+                }
+            })
+                .catch(() => {
+                // Never throw from the sink chain; swallow write failures.
+            });
+            return chain;
+        },
+    };
+}
+//# sourceMappingURL=sinks.js.map

package/dist/timestamp.d.ts

@@ -0,0 +1,15 @@
+/** Format a Date as an ISO-8601 UTC string ending in `Z`. */
+export declare function formatTimestamp(date: Date): string;
+/** Subset of the Performance API used for microsecond timestamps. */
+export type PerformanceLike = {
+    now: () => number;
+    timeOrigin: number;
+};
+/**
+ * Prefer microsecond precision via performance.timeOrigin when no test clock is set.
+ * Pass perf=null to force the Date millisecond fallback.
+ */
+export declare function currentTimestamp(clock?: () => Date, perf?: PerformanceLike | null): string;
+/** Resolve `globalThis.performance` when it looks like {@link PerformanceLike}. */
+export declare function defaultPerformance(globalPerf?: unknown | null): PerformanceLike | undefined;
+//# sourceMappingURL=timestamp.d.ts.map

package/dist/timestamp.js

@@ -0,0 +1,47 @@
+/** Format a Date as an ISO-8601 UTC string ending in `Z`. */
+export function formatTimestamp(date) {
+    return date.toISOString();
+}
+function isPerformanceLike(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    return (typeof Reflect.get(value, "now") === "function" &&
+        typeof Reflect.get(value, "timeOrigin") === "number");
+}
+/**
+ * Prefer microsecond precision via performance.timeOrigin when no test clock is set.
+ * Pass perf=null to force the Date millisecond fallback.
+ */
+export function currentTimestamp(clock, perf) {
+    if (clock) {
+        return formatTimestamp(clock());
+    }
+    const resolved = perf === undefined ? defaultPerformance() : (perf ?? undefined);
+    try {
+        if (resolved) {
+            const epochMs = resolved.timeOrigin + resolved.now();
+            const wholeSeconds = Math.floor(epochMs / 1000);
+            const micros = Math.round((epochMs % 1000) * 1000);
+            const isoSecond = new Date(wholeSeconds * 1000).toISOString().replace(/\.\d{3}Z$/, "");
+            return `${isoSecond}.${String(micros).padStart(6, "0")}Z`;
+        }
+    }
+    catch {
+        // fall through to Date
+    }
+    return formatTimestamp(new Date());
+}
+/** Resolve `globalThis.performance` when it looks like {@link PerformanceLike}. */
+export function defaultPerformance(globalPerf) {
+    const resolved = globalPerf === undefined
+        ? typeof performance !== "undefined"
+            ? performance
+            : undefined
+        : globalPerf;
+    if (isPerformanceLike(resolved)) {
+        return resolved;
+    }
+    return undefined;
+}
+//# sourceMappingURL=timestamp.js.map

package/dist/types.d.ts

@@ -0,0 +1,42 @@
+/** Minimum severity that will be emitted. */
+export type Level = "debug" | "info" | "warn" | "error" | "fatal";
+/** Uppercase severity string written on each log line. */
+export type SeverityName = "DEBUG" | "INFO" | "WARN" | "ERROR" | "FATAL";
+/** Value accepted by severity methods: plain text, structured fields, or an Error. */
+export type LogMessage = string | Record<string, unknown> | Error;
+/** Sanitized object passed to sinks and JSON serialization. */
+export type LogRecord = Record<string, unknown>;
+/** Destination for one JSON line plus its record. */
+export type Sink = {
+    write(line: string, record: LogRecord): void | Promise<void>;
+};
+/** Root-field transform applied after message parse and before path redact. */
+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;
+/** Construction options for {@link Logger}. */
+export type LoggerOptions = {
+    /** Minimum level to emit. Default `info`. */
+    level?: Level;
+    /** Output destination. Default console sink. */
+    sink?: Sink;
+    /** Fields merged into every line at the root. */
+    base?: Record<string, unknown>;
+    /** Clock for timestamps (tests). */
+    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[];
+    /** Root field name to serializer. */
+    serializers?: Readonly<Record<string, FieldSerializer>>;
+    /** Merged under `context` after ALS ambient context; call-site context wins. */
+    contextProvider?: ContextProvider;
+};
+/** JSON scalar used in sanitized payloads. */
+export type JsonPrimitive = string | number | boolean | null;
+/** JSON-compatible value after sanitization. */
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map