logquill 0.3.0 → 1.0.0

package/dist/browser.d.ts

@@ -0,0 +1,468 @@
+/** Log levels, shared by name and numeric weight with the logquill-python contract. */
+declare enum Level {
+    /** Finest-grained diagnostic detail. */
+    TRACE = 5,
+    /** Diagnostic detail useful in development. */
+    DEBUG = 10,
+    /** Notable events during normal operation. */
+    INFO = 20,
+    /** Something unexpected, but not (yet) an error. */
+    WARN = 30,
+    /** An error that didn't necessarily stop the operation. */
+    ERROR = 40,
+    /** An error that precedes an unrecoverable failure. */
+    FATAL = 50
+}
+/** A level given as a `Level`, a level name (any case), or its numeric weight. */
+type LevelInput = Level | number | string;
+/** The level's name, e.g. `levelName(Level.INFO) === "INFO"`. */
+declare function levelName(level: Level): string;
+/** Normalize a level given as a `Level`, level name, or numeric weight. Throws if unknown. */
+declare function parseLevel(level: LevelInput): Level;
+
+/** The cross-language record shape shared with logquill-python. */
+interface LogRecord {
+    /** ISO8601 UTC timestamp with millisecond precision. */
+    timestamp: string;
+    /** Level name, e.g. `"INFO"`. */
+    level: string;
+    /** Name of the `Logger` that created this record. */
+    logger: string;
+    /** The log message. */
+    message: string;
+    /** Structured payload — always present, even if empty. */
+    meta: Record<string, unknown>;
+}
+/** ISO8601 UTC timestamp with millisecond precision, matching Python's `utc_timestamp()`. */
+declare function utcTimestamp(): string;
+/** Builds a `LogRecord` with the current UTC timestamp. Used internally by `Logger`; exported for transports/plugins that need to construct a record directly. */
+declare function createRecord(params: {
+    level: Level;
+    logger: string;
+    message: string;
+    meta: Record<string, unknown>;
+}): LogRecord;
+
+/** `format(record) -> string`, per the transport contract shared with logquill-python. */
+interface Formatter {
+    /** Turns a `LogRecord` into the string a `Transport` writes. */
+    format(record: LogRecord): string;
+}
+/** Serializes a record to the canonical JSON line shape. */
+declare class JSONFormatter implements Formatter {
+    /** Returns `JSON.stringify(record)`. */
+    format(record: LogRecord): string;
+}
+
+/**
+ * The plugin pipeline hooks, matching the Python hook names: `beforeLog`,
+ * `afterLog`, `onError`. All hooks are optional — implement only what you need.
+ * A hook that throws cannot crash logging: the pipeline catches it, routes it
+ * to `onError`, and moves on.
+ */
+interface Plugin {
+    /** Return a (possibly modified) record, or `null` to drop it. */
+    beforeLog?(record: LogRecord): LogRecord | null;
+    /** Called after the record has been dispatched to every transport. */
+    afterLog?(record: LogRecord): void;
+    /** Called when one of this plugin's own hooks throws. */
+    onError?(error: unknown, record: LogRecord): void;
+}
+/** A plain `beforeLog`-style function, as accepted by `Logger.use()` in place of a `Plugin`. */
+type MiddlewareFunc = (record: LogRecord) => LogRecord | null;
+/**
+ * Wraps a plain `beforeLog`-style function as a `Plugin`. `Logger.use()`
+ * builds one of these automatically when given a function instead of a
+ * `Plugin` — Express/Koa-style middleware ergonomics, without needing to
+ * read the `Plugin` interface first. There's no `next()` chaining: the
+ * pipeline already calls hooks in sequence, so this is sugar for a
+ * single-method `Plugin`, not a new execution model.
+ */
+declare class FunctionPlugin implements Plugin {
+    private readonly func;
+    constructor(func: MiddlewareFunc);
+    beforeLog(record: LogRecord): LogRecord | null;
+}
+
+/**
+ * Injects fixed key/value pairs into every record's `meta`.
+ * A value already present in a record's own `meta` wins over the fixed context.
+ */
+declare class ContextPlugin implements Plugin {
+    /** Fixed key/value pairs merged into every record's `meta`. */
+    readonly context: Record<string, unknown>;
+    constructor(context: Record<string, unknown>);
+    beforeLog(record: LogRecord): LogRecord;
+}
+
+/** `meta` keys (case-insensitive) `RedactPlugin` replaces by default. */
+declare const DEFAULT_REDACTED_KEYS: readonly string[];
+/** Options for {@link RedactPlugin}. */
+interface RedactPluginOptions {
+    /** Keys (case-insensitive) to redact. Default `DEFAULT_REDACTED_KEYS`. */
+    keys?: readonly string[];
+    /** Placeholder a matched value is replaced with. Default `"***"`. */
+    replacement?: string;
+}
+/** Replaces sensitive `meta` values, matched by key (case-insensitive), with a placeholder. */
+declare class RedactPlugin implements Plugin {
+    private readonly keys;
+    /** Placeholder a matched value is replaced with. */
+    readonly replacement: string;
+    constructor(options?: RedactPluginOptions);
+    beforeLog(record: LogRecord): LogRecord;
+}
+
+/**
+ * Syntactic (not semantic) patterns — matched on shape, so both false
+ * positives (a random 9-digit number) and false negatives (anything that
+ * doesn't look like these shapes) are expected. Override via `patterns`
+ * for anything stricter.
+ */
+declare const DEFAULT_PII_PATTERNS: Readonly<Record<string, RegExp>>;
+/** Options for {@link PIIRedactPlugin}. */
+interface PIIRedactPluginOptions {
+    /** Named patterns to scan for. Default `DEFAULT_PII_PATTERNS`. */
+    patterns?: Readonly<Record<string, RegExp>>;
+    /** Placeholder a matched substring is replaced with. Default `"***"`. */
+    replacement?: string;
+}
+/**
+ * Regex-based PII redaction over `meta` **values**, not just keys.
+ *
+ * Complements `RedactPlugin`, which redacts by exact key match —
+ * `PIIRedactPlugin` scans string values (recursively through nested
+ * objects/arrays) for emails, SSNs, credit-card numbers, and phone
+ * numbers, and redacts matches wherever they appear, regardless of which
+ * key holds them (a `notes` field containing a stray SSN is still caught).
+ *
+ * Detection is pattern-based: fast and dependency-free, but it matches on
+ * syntactic shape, not meaning — a random 9-digit number can false-positive
+ * as an SSN, and anything that doesn't fit these shapes (a name, a street
+ * address) is a false negative. Pass your own `patterns` to extend or
+ * replace the defaults.
+ *
+ * Recursion into nested `meta` structures is depth- and cycle-bounded, so a
+ * circular reference or a pathologically deep structure can't hang or
+ * crash the caller — it's left unredacted past the bound rather than
+ * throwing.
+ */
+declare class PIIRedactPlugin implements Plugin {
+    /** Named patterns scanned for in every string `meta` value. */
+    readonly patterns: Readonly<Record<string, RegExp>>;
+    /** Placeholder a matched substring is replaced with. */
+    readonly replacement: string;
+    constructor(options?: PIIRedactPluginOptions);
+    beforeLog(record: LogRecord): LogRecord;
+    private redactValue;
+    private redactText;
+}
+
+/**
+ * Sink for log records, per the cross-language transport contract:
+ * `format(record) -> string`, `write(formatted, record)`, `close()` on shutdown.
+ */
+declare abstract class Transport {
+    /** Turns a `LogRecord` into the string this transport actually writes. Defaults to `JSONFormatter`. */
+    formatter: Formatter;
+    constructor(formatter?: Formatter);
+    /** Formats `record` via `this.formatter`. Called once per record before `write()`. */
+    format(record: LogRecord): string;
+    /** Sends the already-formatted record to this transport's sink. */
+    abstract write(formatted: string, record: LogRecord): void;
+    /** Flush/release resources on shutdown. No-op unless a transport overrides it. */
+    close(): void;
+}
+/** Duck-typed: a transport (typically a `BatchingTransport`) whose `flush()` sends its current buffer now, without closing. */
+interface FlushableTransport {
+    /** Sends the current buffer now, even if it hasn't reached its own flush threshold. */
+    flush(): void | Promise<void>;
+}
+/** Type guard for {@link FlushableTransport} — true for any transport (e.g. every `BatchingTransport`) that exposes a `flush()` method. */
+declare function hasFlush(transport: Transport): transport is Transport & FlushableTransport;
+/** In-memory transport for tests: collects every (formatted, record) pair written to it. */
+declare class CollectingTransport extends Transport {
+    /** Every formatted string passed to `write()`, in call order. */
+    readonly formatted: string[];
+    /** Every raw `LogRecord` passed to `write()`, in call order. */
+    readonly records: LogRecord[];
+    /** Set once `close()` has been called. */
+    closed: boolean;
+    write(formatted: string, record: LogRecord): void;
+    close(): void;
+}
+
+/** Options for {@link SamplingPlugin}. */
+interface SamplingPluginOptions {
+    /** Source of randomness for the rate check. Defaults to `Math.random`; override with a seeded/fake generator for deterministic tests. */
+    rng?: () => number;
+    /** `meta` key holding the trace/run id used to group buffered records. Default `"traceId"`. */
+    traceKey?: string;
+    /** A record at or above this level elevates its whole trace. Default `Level.ERROR`. */
+    elevateAt?: LevelInput;
+    /** Enables tail-based elevation, writing straight to these transports on elevation. Omit to disable and get plain rate-based sampling. */
+    transports?: Transport[];
+    /** Total buffered records allowed across every trace before the oldest trace is evicted. Default 1000. */
+    maxBufferedRecords?: number;
+    /** Distinct trace ids held at once before the oldest is evicted. Default 200. */
+    maxTraces?: number;
+}
+/**
+ * Keeps roughly `rate` of records (0.0-1.0), dropping the rest.
+ *
+ * With `transports` set, sampling becomes tail-based per trace: a record
+ * that would otherwise be dropped is buffered under its `meta[traceKey]`
+ * value instead of discarded outright. If any later record sharing that
+ * trace id reaches `elevateAt` or above, the whole trace is "elevated" —
+ * every buffered record for that trace id is flushed straight to
+ * `transports`, and every subsequent record for that trace id ships
+ * unconditionally. This is what lets a sampled-out request still produce a
+ * complete trace once it turns out to matter (it errored).
+ *
+ * Flushing writes buffered records directly to `transports` — pass the
+ * same array given to the `Logger`. This bypasses `beforeLog`/`afterLog`/
+ * `onError` for any plugin *after* `SamplingPlugin` in the pipeline (the
+ * plugins before it already ran, since that's how the buffered record was
+ * built); put `SamplingPlugin` last if that matters for your pipeline.
+ *
+ * Without `transports`, tail-based elevation is inactive and this behaves
+ * exactly like plain rate-based sampling (the original behavior) — a
+ * record without `meta[traceKey]` is also just rate-sampled, since there's
+ * no trace to buffer it under.
+ *
+ * Buffering is bounded: at most `maxBufferedRecords` records total and
+ * `maxTraces` distinct trace ids are held at once. Once either limit is
+ * hit, the oldest buffered trace is evicted (and its records are lost, not
+ * flushed) — a deliberate bounded-memory trade-off, not a bug: an
+ * unbounded per-trace buffer would let a single pathologically long-lived
+ * or high-cardinality trace grow memory without limit.
+ */
+declare class SamplingPlugin implements Plugin {
+    /** Fraction of non-elevated records kept, in `[0, 1]`. */
+    readonly rate: number;
+    /** `meta` key holding the trace/run id used to group buffered records. */
+    readonly traceKey: string;
+    /** A record at or above this level elevates its whole trace. */
+    readonly elevateAt: Level;
+    /** Transports buffered records are flushed straight to on elevation; `undefined` disables tail-based elevation. */
+    readonly transports: Transport[] | undefined;
+    /** Total buffered records allowed across every trace before the oldest trace is evicted. */
+    readonly maxBufferedRecords: number;
+    /** Distinct trace ids held at once before the oldest is evicted. */
+    readonly maxTraces: number;
+    private readonly rng;
+    private readonly buffer;
+    private bufferedCount;
+    private readonly elevated;
+    constructor(rate: number, options?: SamplingPluginOptions);
+    beforeLog(record: LogRecord): LogRecord | null;
+    private elevate;
+    private bufferRecord;
+    private evictOldestTrace;
+}
+
+/** The subset of `console` this transport needs — swap in a fake for tests. */
+interface ConsoleLike {
+    /** Writes one already-formatted line, e.g. for a TRACE–WARN record. */
+    log(message: string): void;
+    /** Writes one already-formatted line, e.g. for an ERROR/FATAL record. */
+    error(message: string): void;
+}
+/** Options for {@link ConsoleTransport}. */
+interface ConsoleTransportOptions {
+    /** Turns a `LogRecord` into the string this transport writes. Defaults to `JSONFormatter`. */
+    formatter?: Formatter;
+    /** Wrap each line in an ANSI color escape for its level. Defaults to `true` unless the `NO_COLOR` env var is set. */
+    colorize?: boolean;
+    /** Sink to write through instead of the global `console` — swap in a fake for tests. */
+    console?: ConsoleLike;
+}
+/**
+ * Writes to `console.log`, routing ERROR/FATAL to `console.error`, colorized by
+ * level. Uses the global `console` rather than Node's `process.stdout`/`stderr`
+ * so this transport works unmodified in a browser bundle.
+ */
+declare class ConsoleTransport extends Transport {
+    /** Whether each line is wrapped in an ANSI color escape for its level. */
+    colorize: boolean;
+    private readonly out;
+    constructor(options?: ConsoleTransportOptions);
+    /** Writes `formatted` via `console.log`, or `console.error` for ERROR/FATAL records. */
+    write(formatted: string, record: LogRecord): void;
+    private applyColor;
+}
+
+/** Sends one batch of formatted lines to `url`. Swap in a fake for tests. */
+type BeaconSender = (url: string, batch: readonly string[]) => void;
+/** Options for {@link BeaconTransport}. */
+interface BeaconTransportOptions {
+    /** Turns a `LogRecord` into the string this transport writes. Defaults to `JSONFormatter`. */
+    formatter?: Formatter;
+    /** Flush once the buffer holds this many lines. Default 20 — kept low since `sendBeacon` payloads are capped. */
+    batchSize?: number;
+    /** Delivers one batch. Defaults to `sendBeacon` with a `fetch(..., { keepalive: true })` fallback; override for a fake or a different backend. */
+    sender?: BeaconSender;
+}
+/**
+ * Batches formatted records and sends them via `navigator.sendBeacon`,
+ * falling back to a `keepalive` `fetch` where `sendBeacon` isn't available.
+ * Meant for the browser: unlike `HTTPTransport`, a beacon send can complete
+ * even after the page that queued it starts unloading. Keep `batchSize`
+ * small — `sendBeacon` payloads are capped (64KB in most browsers).
+ */
+declare class BeaconTransport extends Transport {
+    /** Endpoint each batch is sent to. */
+    readonly url: string;
+    /** Buffer is flushed once it holds this many lines. */
+    readonly batchSize: number;
+    private readonly sender;
+    private batch;
+    constructor(url: string, options?: BeaconTransportOptions);
+    /** Buffers the formatted line, flushing the batch once `batchSize` is reached. */
+    write(formatted: string): void;
+    /** Send the current batch now, even if it hasn't reached `batchSize`. */
+    flush(): void;
+    close(): void;
+}
+
+/** How a full queue behaves when another task arrives. */
+type BackpressurePolicy = "dropOldest" | "dropNewest" | "block";
+/** Options for the {@link DispatchQueue} constructor. */
+interface DispatchQueueOptions {
+    /** Maximum number of pending tasks the queue holds at once. Default 10_000. */
+    maxSize?: number;
+    /**
+     * What happens when `enqueue()` is called while the queue is already at
+     * `maxSize`:
+     * - `"dropOldest"` (default) — evict the longest-waiting task (it never
+     *   runs) and enqueue the new one. Favors recent records.
+     * - `"dropNewest"` — discard the incoming task; everything already queued
+     *   is left alone. Favors records already in flight.
+     * - `"block"` — run the task synchronously, right now, on the caller's
+     *   stack instead of queueing it. Nothing is ever dropped, at the cost of
+     *   the caller (e.g. `logger.info()`) taking as long as the write itself —
+     *   real backpressure rather than a silent drop.
+     */
+    policy?: BackpressurePolicy;
+    /**
+     * Called at most once per `warnIntervalMs` (default 5000) when the queue
+     * drops tasks, with the number dropped since the last call — a
+     * rate-limited way to surface sustained overload without flooding the
+     * caller's own logs with one warning per drop. Defaults to `console.warn`.
+     */
+    onDrop?: (droppedSinceLastWarning: number, policy: BackpressurePolicy) => void;
+    /** Minimum gap between `onDrop` calls. Default 5000ms. */
+    warnIntervalMs?: number;
+}
+
+/** Options for `Logger.span()`. Any extra keys become the span's own `meta`. */
+interface SpanOptions extends Record<string, unknown> {
+    /** Adopt an id handed in from elsewhere (e.g. a framework's own run id) instead of generating one. */
+    spanId?: string;
+    /** Adopt a parent id explicitly, overriding auto-nesting from an enclosing `span()` block. */
+    parentSpanId?: string;
+}
+/** Options for the {@link Logger} constructor. */
+interface LoggerOptions {
+    /** Minimum level that reaches a transport; records below it are dropped before any plugin runs. Default `INFO`. */
+    level?: LevelInput;
+    /** Sinks every record that passes the level filter and plugin pipeline is written to. */
+    transports?: Transport[];
+    /** Registered via `.use()` in order — a plain function is wrapped as an anonymous `Plugin`. */
+    plugins?: (Plugin | MiddlewareFunc)[];
+    /** Merged into every record's `meta`, before a call-site `meta` value (which always wins on collision). */
+    meta?: Record<string, unknown>;
+    /** Bounds and backpressure policy for the internal async dispatch queue. See `DispatchQueueOptions`. */
+    queue?: DispatchQueueOptions;
+}
+/**
+ * The core logger: leveled, structured logging over a pluggable transport
+ * and plugin pipeline. Every log call returns the finished `LogRecord` (or
+ * `null` if it was filtered by level or dropped by a plugin) synchronously —
+ * the actual transport writes are dispatched onto an internal queue so the
+ * call returns before any I/O runs; see `flush()`/`close()`.
+ */
+declare class Logger {
+    /** This logger's name, as passed to the constructor (or derived via `.child()`). Appears on every record as `logger`. */
+    readonly name: string;
+    /** Every transport a written record is sent to. */
+    readonly transports: Transport[];
+    /** Every plugin registered via `.use()`, in registration order. */
+    readonly plugins: Plugin[];
+    private currentLevel;
+    private readonly baseMeta;
+    private dispatchQueue;
+    constructor(name: string, options?: LoggerOptions);
+    /** This logger's current minimum level — records below it are filtered before any plugin runs. */
+    get level(): Level;
+    /** Changes the minimum level records must meet to reach a transport. Accepts a `Level`, its numeric weight, or its name. */
+    setLevel(level: LevelInput): void;
+    /**
+     * Register a plugin, or a plain `beforeLog`-style function. A function is
+     * wrapped internally as an anonymous `Plugin` (`FunctionPlugin`) — the
+     * same middleware ergonomics as Express/Koa, without needing to read the
+     * `Plugin` interface first. Returns `this` so calls can be chained.
+     */
+    use(plugin: Plugin | MiddlewareFunc): this;
+    /** Number of dispatched records not yet written to their transports. Bounded by the `queue` option. */
+    get queueSize(): number;
+    /**
+     * Waits for every record dispatched so far to reach its transports'
+     * `write()` (and any plugin `afterLog` hooks). Note this does *not* force
+     * a batching transport (SQL, a queue, `HTTPTransport`, ...) to send a
+     * batch still under its own `maxRecords`/`maxBytes` threshold early — it
+     * only guarantees the record has been handed to that transport, the same
+     * contract `write()` always had. Before a process may pause or exit
+     * (a serverless freeze, a shutdown signal), prefer `withLambda`/
+     * `installShutdownHandlers`, which additionally force every batching
+     * transport to send its current buffer regardless of threshold.
+     */
+    flush(): Promise<void>;
+    /** Flush every pending record, then close every attached transport. Call once, on shutdown. */
+    close(): Promise<void>;
+    /** A logger scoped under this one, inheriting its level, transports, plugins, and dispatch queue. */
+    child(name: string, meta?: Record<string, unknown>): Logger;
+    private notifyError;
+    private dispatch;
+    private writeAndNotify;
+    /** Logs at `TRACE` — the lowest level, for fine-grained diagnostic detail. Returns the record, or `null` if filtered/dropped. */
+    trace(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** Logs at `DEBUG`. Returns the record, or `null` if filtered/dropped. */
+    debug(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** Logs at `INFO`. Returns the record, or `null` if filtered/dropped. */
+    info(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** Logs at `WARN`. Returns the record, or `null` if filtered/dropped. */
+    warn(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** Logs at `ERROR`. Returns the record, or `null` if filtered/dropped. */
+    error(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** Logs at `FATAL` — the highest level, for errors that precede an unrecoverable failure. Returns the record, or `null` if filtered/dropped. */
+    fatal(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** `.info()` tagged `meta.kind = "thought"` — an agent's internal reasoning step, for harness/agentic tracing. */
+    thought(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** `.info()` tagged `meta.kind = "action"` — an agent taking an action (a tool call, an LLM request), for harness/agentic tracing. */
+    action(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** `.info()` tagged `meta.kind = "observation"` — the result an agent observed from an action, for harness/agentic tracing. */
+    observation(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** `.info()` tagged `meta.kind = "decision"` — an agent's concluding decision for a step or run, for harness/agentic tracing. */
+    decision(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /**
+     * `await logger.span("callLlm", async () => {...})` — runs `fn`, and on
+     * settling (success or throw) emits one record for the span itself
+     * carrying `meta.spanId` and `meta.durationMs`. Every record logged
+     * inside `fn` — through any method, and through any further `await` —
+     * is automatically stamped with `meta.parentSpanId` pointing at this
+     * span, so nested/sub-agent calls reconstruct their exact nesting when
+     * sorted by `spanId`/`parentSpanId`.
+     *
+     * Still emits its record — at `ERROR`, with `meta.error` set — if `fn`
+     * throws; the error itself propagates unchanged to the caller.
+     *
+     * `spanId`/`parentSpanId` normally auto-generate/auto-nest; pass them in
+     * `options` to adopt an id handed in from elsewhere (e.g. a framework
+     * adapter translating an id it already received).
+     */
+    span<T>(name: string, fn: () => T | Promise<T>, options?: SpanOptions): Promise<T>;
+    private finishSpan;
+}
+
+export { type BeaconSender, BeaconTransport, type BeaconTransportOptions, CollectingTransport, type ConsoleLike, ConsoleTransport, type ConsoleTransportOptions, ContextPlugin, DEFAULT_PII_PATTERNS, DEFAULT_REDACTED_KEYS, type FlushableTransport, type Formatter, FunctionPlugin, JSONFormatter, Level, type LevelInput, type LogRecord, Logger, type LoggerOptions, type MiddlewareFunc, PIIRedactPlugin, type PIIRedactPluginOptions, type Plugin, RedactPlugin, type RedactPluginOptions, SamplingPlugin, type SamplingPluginOptions, type SpanOptions, Transport, createRecord, hasFlush, levelName, parseLevel, utcTimestamp };