@unhingged/logit 0.0.0-stage → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,877 @@
+/**
+ * Capturing — turning the arguments of a logging call into the values stored
+ * on the event. This is Serilog's destructuring step, with JS defaults:
+ *
+ *   scalars          kept as they are (Date stays a Date; bigint, symbol and
+ *                    functions become strings)
+ *   plain objects,   captured structurally — they are data
+ *   arrays, Map, Set
+ *   class instances  rendered with their own `toString()` / `toJSON()`, or
+ *                    the class name — they are behaviour — unless `@` is used
+ *   `@`              destructures anything, class instances included (`$type`
+ *                    carries the class name)
+ *   `$`              stringifies anything
+ *   Error            always captured as a structure (name, message, stack,
+ *                    own properties, `cause` chain)
+ *
+ * Depth, string and collection limits, redaction by key and transforming
+ * policies all apply here, once, at capture time — so every sink sees the
+ * same, already-safe value.
+ */
+interface CapturedError {
+    $type: 'Error';
+    name: string;
+    message: string;
+    stack?: string;
+    cause?: unknown;
+    errors?: unknown[];
+    [key: string]: unknown;
+}
+/**
+ * A policy sees every non-scalar value before the default rules and may
+ * replace it. Return `undefined` to decline; return `{ value }` to substitute
+ * (the substitute is captured again, so return something simpler than you
+ * were given or the policy recurses — Serilog's rule).
+ */
+type DestructuringPolicy = (value: object) => {
+    value: unknown;
+} | undefined;
+interface DestructuringOptions {
+    /** Nesting depth beyond which values are replaced by `'[Object]'` / `'[Array]'`. */
+    maxDepth: number;
+    /** Strings longer than this are cut and end with `…`. `Infinity` = no limit. */
+    maxStringLength: number;
+    /** Arrays, Sets and Maps are cut to this many elements. `Infinity` = no limit. */
+    maxCollectionCount: number;
+    /**
+     * Keys whose values are replaced by `redactedValue`, at any depth.
+     * A bare name (`'password'`) matches that key anywhere, case-insensitively.
+     * A dotted path (`'headers.authorization'`, `'*.token'`, `'user.*.ssn'`) is
+     * matched from the root of the captured value; `*` is one segment.
+     */
+    redact: readonly string[];
+    redactedValue: unknown;
+    /** Policies run in order; the first that answers wins. */
+    policies: readonly DestructuringPolicy[];
+    /** Add `$type` (the class name) when a class instance is destructured with `@`. */
+    typeTag: boolean;
+}
+declare const DEFAULT_DESTRUCTURING: DestructuringOptions;
+/** Serilog's `Destructure.ByTransforming<T>()`: when a value is an instance of `type`, log `transform(value)` instead. */
+declare function byTransforming<T extends object>(type: abstract new (...args: never[]) => T, transform: (value: T) => unknown): DestructuringPolicy;
+type CaptureOperator = '@' | '$' | undefined;
+/**
+ * Captures one value. `operator` is the hole's `@` / `$`; `path` is the key
+ * path from the root (for redaction) and `seen` guards against cycles.
+ */
+declare function captureValue(value: unknown, operator: CaptureOperator, options: DestructuringOptions, path?: string[], seen?: Set<object>, depth?: number): unknown;
+/**
+ * Captures a value that is about to become the property `name` — the root
+ * of its redaction path, so `redact: ['password']` also covers
+ * `log.info('Login {Password}', pw)` and `forContext('password', …)`.
+ */
+declare function captureProperty(name: string, value: unknown, operator: CaptureOperator, options: DestructuringOptions): unknown;
+/**
+ * Errors are always structured: name, message, stack, every own enumerable
+ * property (the `code` on a Node error, the `status` on an HTTP one), the
+ * `cause` chain and an `AggregateError`'s `errors`.
+ */
+declare function captureError(error: Error, options?: DestructuringOptions, path?: string[], seen?: Set<object>, depth?: number): CapturedError;
+
+/**
+ * Serilog's six levels. The names are the JS-idiomatic short forms
+ * (`info`, `warn`), with Serilog's own (`information`, `warning`) and
+ * pino's (`trace`) accepted wherever a level is parsed from text.
+ */
+type LogLevel = 'verbose' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+declare const LEVELS: readonly LogLevel[];
+declare const LEVEL_ORDER: Readonly<Record<LogLevel, number>>;
+/** Serilog's level names — what CLEF (`@l`) and `{Level}` in an output template print. */
+declare const SERILOG_LEVEL_NAMES: Readonly<Record<LogLevel, string>>;
+/** Serilog's three-letter codes (`{Level:u3}`). */
+declare const LEVEL_CODES: Readonly<Record<LogLevel, string>>;
+/** pino / bunyan numeric levels, for the JSON formatter's `levelFormat: 'number'`. */
+declare const LEVEL_NUMBERS: Readonly<Record<LogLevel, number>>;
+/**
+ * Parses a level from any of its spellings (`'Information'`, `'warning'`,
+ * `'trace'`, `'ERR'`, pino's `30`). Throws on anything it cannot read, so a
+ * typo in configuration fails at startup rather than silencing a logger.
+ */
+declare function parseLevel(input: LogLevel | string | number): LogLevel;
+declare function isLevel(input: unknown): input is LogLevel;
+/** `true` when `level` is at or above `minimum`. */
+declare function levelAtLeast(level: LogLevel, minimum: LogLevel): boolean;
+/**
+ * A level that can be changed while the application runs — Serilog's
+ * `LoggingLevelSwitch`. Hand the same instance to a logger's `minimumLevel`,
+ * an override, or a sink's `restrictedToMinimumLevel`, and flip it from an
+ * admin endpoint or a signal handler without recreating anything.
+ */
+declare class LevelSwitch {
+    #private;
+    constructor(initial?: LogLevel | string);
+    get level(): LogLevel;
+    set level(next: LogLevel | string);
+    /** Called with the new level on every change; returns an unsubscribe function. */
+    onChange(listener: (level: LogLevel) => void): () => void;
+}
+type LevelOrSwitch = LogLevel | string | LevelSwitch;
+/** Resolves a configured level — static or a switch — to its current value. */
+declare function resolveLevel(value: LevelOrSwitch): LogLevel;
+
+/**
+ * Message templates (https://messagetemplates.org): `"User {UserId} bought {@Order}"`.
+ *
+ * A template is parsed once (cached by its text) into text and hole tokens.
+ * Holes carry the `@` / `$` capturing operator, an optional `,alignment` and
+ * `:format`. Malformed holes are kept as literal text, as Serilog does, so a
+ * stray brace never throws from a logging call.
+ */
+interface TextToken {
+    readonly kind: 'text';
+    readonly text: string;
+}
+interface HoleToken {
+    readonly kind: 'hole';
+    /** The hole exactly as written, braces included — used when no value binds to it. */
+    readonly raw: string;
+    /** Property name, or the digits of a positional hole. */
+    readonly name: string;
+    /** Set for positional holes (`{0}`). */
+    readonly index?: number;
+    /** `@` destructures, `$` stringifies, undefined leaves it to the capture rules. */
+    readonly operator?: '@' | '$';
+    /** Positive pads on the left, negative on the right (`{Name,-10}`). */
+    readonly alignment?: number;
+    /** `{Elapsed:0.00}` — passed through to the renderer. */
+    readonly format?: string;
+}
+type TemplateToken = TextToken | HoleToken;
+interface MessageTemplate {
+    readonly raw: string;
+    readonly tokens: readonly TemplateToken[];
+    /** The holes in order of appearance — what positional arguments bind to. */
+    readonly holes: readonly HoleToken[];
+    /** All holes are numeric (`{0} {1}`), so arguments bind by index. */
+    readonly positional: boolean;
+}
+/** Parses a template, memoised by text. The cache is bounded; a flood of unique templates just costs a reparse. */
+declare function parseTemplate(raw: string): MessageTemplate;
+/**
+ * Serilog's event-type id: Jenkins one-at-a-time over the template's UTF-16
+ * code units, as eight hex digits — the same value Seq shows as `@i`, so
+ * "all events of this kind" queries match across both ecosystems.
+ */
+declare function templateHash(raw: string): string;
+
+/**
+ * Rendering captured values and templates to text — shared by
+ * `renderMessage()`, the text / pretty formatters and CLEF's `@r`.
+ *
+ * Rules follow Serilog's: strings are quoted unless the hole says `:l`,
+ * structures print as `Type { Key: value }` (or JSON with `:j`), sequences
+ * as `[a, b]`, dates as ISO 8601. Numbers accept `.NET`-style `0.00` / `F2`
+ * / `N0` patterns, dates the `yyyy-MM-dd HH:mm:ss.fff zzz` family.
+ */
+
+/** Hooks for colouring (the pretty formatter); each receives text and returns styled text. */
+interface ValueStyles {
+    string?: (text: string) => string;
+    number?: (text: string) => string;
+    boolean?: (text: string) => string;
+    null?: (text: string) => string;
+    name?: (text: string) => string;
+    punctuation?: (text: string) => string;
+    /** Raw hole text when nothing bound to it. */
+    missing?: (text: string) => string;
+}
+interface RenderOptions {
+    /** Strings print bare instead of quoted (`:l`). */
+    literal?: boolean;
+    /** Structures and sequences print as JSON (`:j`). */
+    json?: boolean;
+    /** Dates in text output print in UTC (default: local time). */
+    utc?: boolean;
+    styles?: ValueStyles;
+}
+/** Fills in identity functions so the renderer never has to branch on a missing style. */
+declare function resolveStyles(styles: ValueStyles | undefined): Required<ValueStyles>;
+declare function renderValue(value: unknown, format?: string, options?: RenderOptions): string;
+/**
+ * JSON that never throws. Captured values are already JSON-safe (capture
+ * turns bigint, NaN and Infinity into numbers or strings; Dates have
+ * `toJSON`), so the fast path is a plain `JSON.stringify` — a replacer
+ * function would cost a call per key on every event. The replacer only
+ * runs if something un-captured (a raw bigint) slipped through.
+ */
+declare function toJson(value: unknown): string;
+declare function jsonReplacer(this: unknown, _key: string, value: unknown): unknown;
+/** `0.00`, `0.####`, `F2`, `N0`, `P1`, `D3`, `X` — the common .NET numeric formats; anything else prints the number as is. */
+declare function formatNumber(value: number, format?: string): string;
+declare function isoTimestamp(date: Date): string;
+/**
+ * .NET-style date patterns: `yyyy MM dd HH hh mm ss fff tt zzz K`, quoted
+ * literals, plus `o` / `O` for ISO 8601. Local time unless `utc`.
+ */
+declare function formatDate(date: Date, pattern: string, utc?: boolean): string;
+/**
+ * Renders a template against captured properties. Holes with no bound value
+ * print as written (`{Missing}`), Serilog's behaviour, so a typo is visible.
+ * `renderings`, when given, collects the text of every formatted hole — the
+ * CLEF `@r` array.
+ */
+declare function renderTemplate(template: MessageTemplate, properties: Record<string, unknown>, options?: RenderOptions, renderings?: string[]): string;
+
+interface LogEventInit {
+    timestamp?: Date;
+    level: LogLevel;
+    template: MessageTemplate;
+    properties?: Record<string, unknown>;
+    error?: Error;
+    traceId?: string;
+    spanId?: string;
+}
+/**
+ * One logged event: when, how severe, the template it was written with, the
+ * captured properties, and — separately from the properties, as in Serilog —
+ * the error and the trace/span ids.
+ *
+ * Sinks receive the same instance; enrichers mutate it through the
+ * `add*` methods so that every value goes through the logger's capture rules.
+ */
+declare class LogEvent {
+    #private;
+    readonly timestamp: Date;
+    readonly level: LogLevel;
+    readonly template: MessageTemplate;
+    readonly properties: Record<string, unknown>;
+    error: Error | undefined;
+    traceId: string | undefined;
+    spanId: string | undefined;
+    constructor(init: LogEventInit, destructuring: DestructuringOptions);
+    /** The template text, e.g. `"User {UserId} logged in"`. */
+    get messageTemplate(): string;
+    /** Serilog's `SourceContext` — set by `logger.forSource()`. */
+    get sourceContext(): string | undefined;
+    /** Eight hex digits identifying the template (Seq's `@i`). */
+    get eventId(): string;
+    /** The error as a structure (name, message, stack, own properties, cause chain), captured once. */
+    get errorProperties(): CapturedError | undefined;
+    /** Captures and adds `value` under `name` unless the event already has it — the rule enrichers follow. */
+    addPropertyIfAbsent(name: string, value: unknown, destructure?: boolean): void;
+    /** Captures and adds `value` under `name`, replacing any existing value. */
+    addOrUpdateProperty(name: string, value: unknown, destructure?: boolean): void;
+    removeProperty(name: string): void;
+    hasProperty(name: string): boolean;
+    /** The template rendered with this event's properties. */
+    renderMessage(options?: RenderOptions): string;
+    /** Properties that are not holes in the template — the "extra" context, in Serilog's `{Properties}` sense. */
+    extraProperties(): Record<string, unknown>;
+}
+
+/**
+ * An enricher adds properties to every event that passes through a logger
+ * (Serilog's `ILogEventEnricher`). Use `addPropertyIfAbsent` so that a
+ * value written in the message, or bound closer to the call, wins.
+ */
+type Enricher = (event: LogEvent) => void;
+/** A fixed property on every event: `withProperty('Application', 'shop')`. */
+declare function withProperty(name: string, value: unknown, destructure?: boolean): Enricher;
+/** Several fixed properties at once. */
+declare function withProperties(properties: Record<string, unknown>, destructure?: boolean): Enricher;
+/** A property computed per event — `withComputed('Memory', () => process.memoryUsage().rss)`. */
+declare function withComputed(name: string, compute: (event: LogEvent) => unknown, destructure?: boolean): Enricher;
+/**
+ * Copies the ambient `LogContext` onto the event — Serilog's
+ * `Enrich.FromLogContext()`. `createLogger` includes it unless told not to.
+ * `traceId` / `spanId` in the context become the event's trace fields.
+ */
+declare function fromLogContext(): Enricher;
+/** `Environment` from `NODE_ENV` (or the value given). No-op where there is no `process.env`. */
+declare function withEnvironment(name?: string): Enricher;
+interface TraceContext {
+    traceId?: string;
+    spanId?: string;
+}
+/**
+ * Sets the event's trace and span ids from a getter — wire it to
+ * `trace.getActiveSpan()?.spanContext()` from `@opentelemetry/api`, or to
+ * whatever carries your correlation ids.
+ */
+declare function withTraceContext(get: () => TraceContext | undefined | null): Enricher;
+
+/** `true` keeps the event. Filters run after enrichment, before the sinks. */
+type Filter = (event: LogEvent) => boolean;
+/** Serilog's `Filter.ByExcluding`: drop events the predicate matches. */
+declare function byExcluding(predicate: (event: LogEvent) => boolean): Filter;
+/** Serilog's `Filter.ByIncludingOnly`: keep only events the predicate matches. */
+declare function byIncludingOnly(predicate: (event: LogEvent) => boolean): Filter;
+/** Serilog's `Matching` helpers — predicates for the two filters above and for `conditional()` sinks. */
+declare const Matching: {
+    /** Events whose `SourceContext` is `source` or starts with `source.`. */
+    fromSource(source: string): (event: LogEvent) => boolean;
+    /** Events that carry `name` — optionally with a value the predicate accepts. */
+    withProperty<T = unknown>(name: string, predicate?: (value: T) => boolean): (event: LogEvent) => boolean;
+    /** Events written with exactly this template text. */
+    withTemplate(template: string): (event: LogEvent) => boolean;
+    /** Events whose rendered message matches the pattern. */
+    messageMatches(pattern: RegExp): (event: LogEvent) => boolean;
+};
+/** Keeps a fraction of matching events — `sampled(0.1, Matching.fromSource('http'))` keeps one in ten request logs. */
+declare function sampled(rate: number, predicate?: (event: LogEvent) => boolean, random?: () => number): Filter;
+/**
+ * Lets at most `max` matching events through per `windowMs`; the rest are
+ * dropped. For the error that fires ten thousand times a second.
+ */
+declare function rateLimited(max: number, windowMs: number, predicate?: (event: LogEvent) => boolean, now?: () => number): Filter;
+
+/** Turns an event into one line (or block) of text. Sinks add the newline. */
+type Formatter = (event: LogEvent) => string;
+
+/**
+ * Serilog's output templates: `"{Timestamp:HH:mm:ss} [{Level:u3}] {SourceContext} {Message:lj}{NewLine}{Exception}"`.
+ *
+ * The template is parsed with the message-template parser — it IS one —
+ * and the well-known holes are filled from the event's own fields; any other
+ * name reads a property. `{Properties}` prints every property not already
+ * used by the message or the output template.
+ */
+
+declare const DEFAULT_OUTPUT_TEMPLATE = "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj}{NewLine}{Exception}";
+interface TextFormatterOptions {
+    outputTemplate?: string;
+    /** Timestamps in UTC instead of local time. */
+    utc?: boolean;
+    /** Colour hooks for the message's values (used by the pretty formatter). */
+    styles?: ValueStyles;
+    /** Hooks for the structural holes. */
+    tokenStyles?: Partial<Record<'Timestamp' | 'Level' | 'SourceContext' | 'Exception' | 'Properties' | 'Message', (text: string, event: LogEvent) => string>>;
+}
+declare function formatLevel(level: LogEvent['level'], format?: string): string;
+/** The error as text: stack (or name + message), then each cause indented — Node's own "caused by" shape. */
+declare function formatError(error: Error | undefined, indent?: string): string;
+declare function textFormatter(options?: TextFormatterOptions): Formatter;
+
+declare const ansi: {
+    bold: (text: string) => string;
+    dim: (text: string) => string;
+    italic: (text: string) => string;
+    underline: (text: string) => string;
+    red: (text: string) => string;
+    green: (text: string) => string;
+    yellow: (text: string) => string;
+    blue: (text: string) => string;
+    magenta: (text: string) => string;
+    cyan: (text: string) => string;
+    white: (text: string) => string;
+    gray: (text: string) => string;
+    bgRed: (text: string) => string;
+};
+interface PrettyFormatterOptions {
+    colors?: boolean;
+    /** Timestamp pattern; default `HH:mm:ss.fff`. `false` hides it. */
+    timestamp?: string | false;
+    utc?: boolean;
+    /** Show properties that are not part of the message, as `key=value`. Default true. */
+    extras?: boolean;
+    /** Show the source context. Default true. */
+    source?: boolean;
+}
+/** Detects colour support the way most CLIs do. Exported so sinks can share the decision. */
+declare function detectColors(stream?: {
+    isTTY?: boolean;
+}): boolean;
+declare function prettyFormatter(options?: PrettyFormatterOptions): Formatter;
+
+interface JsonFormatterOptions {
+    /** Rename the reified keys, e.g. `{ timestamp: 'time', message: 'msg' }` for pino-shaped output. */
+    keys?: Partial<Record<'timestamp' | 'level' | 'message' | 'template' | 'source' | 'error' | 'traceId' | 'spanId' | 'eventId', string>>;
+    /** `'name'` → `"info"`, `'serilog'` → `"Information"`, `'upper'` → `"INFO"`, `'number'` → pino's 30. */
+    levelFormat?: 'name' | 'serilog' | 'upper' | 'number';
+    /** Include the rendered message (default true) and / or the template (default true). */
+    message?: boolean;
+    template?: boolean;
+    /** Include the template hash as `eventId` (default false). */
+    eventId?: boolean;
+    /** Timestamp as ISO 8601 (default) or epoch milliseconds. */
+    timestampFormat?: 'iso' | 'epoch';
+}
+/**
+ * The line is assembled from fragments rather than built as an object and
+ * stringified whole: the reified keys are constant strings, the level's
+ * fragment is precomputed, the template's JSON is cached per template, and
+ * only the message and the properties are escaped per event.
+ */
+declare function jsonFormatter(options?: JsonFormatterOptions): Formatter;
+
+declare const CLEF_MEDIA_TYPE = "application/vnd.serilog.clef";
+interface ClefFormatterOptions {
+    /** Also write the rendered message as `@m` (Serilog's "rendered compact" variant). Default false. */
+    renderMessage?: boolean;
+}
+declare function clefFormatter(options?: ClefFormatterOptions): Formatter;
+
+type FormatName = 'pretty' | 'json' | 'clef' | 'text';
+/** `'json'` / `'clef'` / `'text'` / `'pretty'` by name, or a formatter function as given. */
+declare function resolveFormatter(format: FormatName | Formatter | undefined, defaults?: {
+    outputTemplate?: string;
+    colors?: boolean;
+    utc?: boolean;
+}, fallback?: FormatName): Formatter;
+
+/**
+ * Where events go. `emit` is synchronous and must not throw for ordinary
+ * failures (write to `selfLog` instead); a sink that buffers implements
+ * `flush` and `close` so `logger.close()` can drain it before the process
+ * ends. A `Logger` is itself a sink — that is how sub-loggers work.
+ */
+interface Sink {
+    emit(event: LogEvent): void;
+    flush?(): Promise<void> | void;
+    close?(): Promise<void> | void;
+    /** Events below this level are not handed to the sink (Serilog's `restrictedToMinimumLevel`). */
+    restrictedToMinimumLevel?: LevelOrSwitch;
+    /** An audit sink's failure propagates to the caller instead of going to selfLog (Serilog's `AuditTo`). */
+    audit?: boolean;
+    /** For selfLog messages. */
+    name?: string;
+}
+interface SinkOptions {
+    restrictedToMinimumLevel?: LevelOrSwitch;
+    audit?: boolean;
+}
+
+interface ConsoleSinkOptions extends SinkOptions {
+    /**
+     * `'pretty'` for people, `'json'` for machines, `'clef'` for Seq, `'text'` for
+     * a Serilog output template — or a formatter function. Default: `'pretty'` on
+     * a terminal and in browsers, `'json'` otherwise (a pipe, a container, Vercel).
+     */
+    format?: FormatName | Formatter;
+    outputTemplate?: string;
+    colors?: boolean;
+    utc?: boolean;
+    /** Events at or above this level go to stderr (Serilog's `standardErrorFromLevel`). Default: everything to stdout. */
+    stderrFrom?: LogLevel | string;
+}
+/**
+ * stdout / stderr in Node, Bun and Deno. Elsewhere the console: in a real
+ * browser the pretty format hands it objects so they stay expandable; on an
+ * edge runtime or in a worker (no `document`) the default is JSON lines,
+ * which is what the platform's log collector expects to parse.
+ */
+declare function consoleSink(options?: ConsoleSinkOptions): Sink;
+
+/**
+ * The batching core behind every network sink: events queue up, go out in
+ * batches on a timer or when the batch fills, retry with backoff on failure,
+ * and are dropped — with a selfLog note — rather than grow without bound.
+ * `flush()` sends what is queued and waits; `close()` flushes and stops.
+ */
+
+interface BatchingOptions extends SinkOptions {
+    /** Send when this many events are queued. Default 100. */
+    batchSize?: number;
+    /** Send at least this often (ms) while events are queued. Default 2000. */
+    flushInterval?: number;
+    /** Events kept while the network is down; beyond it the oldest are dropped. Default 10 000. */
+    maxQueue?: number;
+    /** Attempts per batch (first try included). Default 3. */
+    retries?: number;
+    /** Base delay between attempts (ms), doubled each time. Default 500. */
+    retryDelay?: number;
+    /** Called when a batch is given up on. */
+    onError?: (error: unknown, events: LogEvent[]) => void;
+    name?: string;
+}
+interface BatchingSink extends Sink {
+    /** Events waiting to be sent. */
+    readonly queued: number;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+declare function batchingSink(send: (events: LogEvent[]) => Promise<void>, options?: BatchingOptions): BatchingSink;
+
+type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal?: AbortSignal;
+    keepalive?: boolean;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+interface HttpSinkOptions extends BatchingOptions {
+    url: string;
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /**
+     * How a batch becomes a body: `'ndjson'` (one JSON event per line — Loki,
+     * Splunk HEC, Datadog, most collectors), `'array'` (a JSON array), `'clef'`
+     * (newline-delimited CLEF, Seq), or your own function.
+     */
+    body?: 'ndjson' | 'array' | 'clef' | ((events: LogEvent[]) => string);
+    /** Formatter for each event in `ndjson` / `array` mode. Default: the JSON formatter. */
+    formatter?: Formatter;
+    contentType?: string;
+    /** Request timeout in ms. Default 10 000. */
+    timeout?: number;
+    /** Supplied for tests and exotic runtimes; defaults to `globalThis.fetch`. */
+    fetch?: FetchLike;
+}
+/**
+ * POSTs batches of events to any HTTP endpoint. In a browser the request is
+ * sent with `keepalive`, and the queue is flushed on `pagehide`, so the last
+ * events of a session still leave.
+ */
+declare function httpSink(options: HttpSinkOptions): BatchingSink;
+interface SeqSinkOptions extends Omit<HttpSinkOptions, 'url' | 'body' | 'formatter' | 'contentType'> {
+    /** e.g. `http://localhost:5341` */
+    serverUrl: string;
+    apiKey?: string;
+}
+/** Seq (https://datalust.co/seq): CLEF over HTTP to `/ingest/clef`, with the API key header. */
+declare function seqSink(options: SeqSinkOptions): BatchingSink;
+
+/** The simplest sink: a function per event. */
+declare function callbackSink(fn: (event: LogEvent) => void, options?: SinkOptions): Sink;
+interface MemorySink extends Sink {
+    readonly events: LogEvent[];
+    clear(): void;
+    /** The rendered messages, for assertions. */
+    messages(): string[];
+}
+/** Keeps events in an array — for tests, and for the "last N events" page every ops team ends up wanting. */
+declare function memorySink(options?: SinkOptions & {
+    capacity?: number;
+}): MemorySink;
+interface StreamLike {
+    write(chunk: string): boolean | void;
+    isTTY?: boolean;
+    once?(event: 'drain', listener: () => void): unknown;
+}
+interface StreamSinkOptions extends SinkOptions {
+    format?: FormatName | Formatter;
+    outputTemplate?: string;
+    colors?: boolean;
+    utc?: boolean;
+}
+/** Writes formatted lines to anything with `write(string)` — a Node stream, a socket, a custom transport. */
+declare function streamSink(stream: StreamLike, options?: StreamSinkOptions): Sink;
+
+interface LoggerOptions {
+    /** Default `'info'`, or `LOGIT_LEVEL` from the environment when set. A `LevelSwitch` makes it changeable at runtime. */
+    minimumLevel?: LevelOrSwitch;
+    /**
+     * Per-source levels — Serilog's `MinimumLevel.Override`. Keys are
+     * `SourceContext` prefixes on dot boundaries (`'app.db'` covers
+     * `app.db.query`); the longest match wins.
+     */
+    overrides?: Record<string, LevelOrSwitch>;
+    /** Where events go (`writeTo`). A `Logger` is a valid sink. */
+    sinks?: Sink[];
+    /** Serilog's `AuditTo`: sinks whose failures propagate to the caller. */
+    auditSinks?: Sink[];
+    enrichers?: Enricher[];
+    filters?: Filter[];
+    destructuring?: Partial<DestructuringOptions>;
+    /** Fixed properties on every event — shorthand for `withProperties()`. */
+    properties?: Record<string, unknown>;
+    /** Read the ambient `LogContext` onto every event. Default true. */
+    logContext?: boolean;
+    /** Where a non-audit sink's failure is reported. Default: `selfLog`. */
+    onSinkError?: (error: unknown, sink: Sink, event: LogEvent) => void;
+}
+interface Override {
+    prefix: string;
+    level: LevelOrSwitch;
+}
+interface Pipeline {
+    minimumLevel: LevelOrSwitch;
+    overrides: Override[];
+    sinks: Sink[];
+    enrichers: Enricher[];
+    filters: Filter[];
+    destructuring: DestructuringOptions;
+    onSinkError?: LoggerOptions['onSinkError'];
+}
+/** Loggers read their pipeline through a ref, so `configure()` can swap the global one under every child. */
+interface PipelineRef {
+    current: Pipeline;
+}
+type LogArgs = unknown[];
+interface LogMethod {
+    (template: string, ...args: unknown[]): void;
+    (error: Error, template?: string, ...args: unknown[]): void;
+    (properties: Record<string, unknown>, template?: string, ...args: unknown[]): void;
+}
+interface OperationOptions {
+    /** Level of the completion event. Default `'info'`. */
+    completeLevel?: LogLevel;
+    /** Level of the abandonment event. Default `'warn'`. */
+    abandonLevel?: LogLevel;
+    /** Completions slower than this (ms) log at `warn` instead. */
+    warnAfter?: number;
+}
+/**
+ * A timed operation (SerilogTimings): begin it, do the work, `complete()`
+ * or `abandon()` — one event with `Outcome` and `Elapsed`. Disposing an
+ * unfinished operation abandons it.
+ */
+declare class Operation {
+    #private;
+    constructor(logger: Logger, template: string, args: unknown[], options?: OperationOptions);
+    /** Milliseconds since the operation began. */
+    get elapsed(): number;
+    /** Adds a property to the completion event. */
+    enrich(name: string, value: unknown, destructure?: boolean): this;
+    complete(): void;
+    complete(name: string, value: unknown): void;
+    abandon(error?: Error): void;
+    /** Ends the operation without logging anything. */
+    cancel(): void;
+    [Symbol.dispose](): void;
+}
+/**
+ * The logger. Immutable: `forContext` / `forSource` return a new logger
+ * bound to extra properties, sharing the pipeline. Also a `Sink`, so a
+ * logger can be written to by another (sub-loggers).
+ */
+declare class Logger implements Sink {
+    #private;
+    /** @internal */
+    constructor(ref: PipelineRef, context?: Record<string, unknown> | null, source?: string);
+    readonly name = "logger";
+    /** The `SourceContext` this logger is bound to, if any. */
+    get source(): string | undefined;
+    /** The current minimum level for this logger's source. */
+    get minimumLevel(): LogLevel;
+    /** Cheap check before building anything expensive to log. */
+    isEnabled(level: LogLevel): boolean;
+    verbose: LogMethod;
+    debug: LogMethod;
+    info: LogMethod;
+    warn: LogMethod;
+    error: LogMethod;
+    fatal: LogMethod;
+    /**
+     * Writes an event at `level`. Argument shapes:
+     *   `(template, ...args)`
+     *   `(error, template?, ...args)`
+     *   `(properties, template?, ...args)` — one-off properties on this event
+     */
+    write(level: LogLevel, ...args: LogArgs): void;
+    /** Sink entry point: an event from another logger, re-dispatched through this one's level, context, enrichers, filters and sinks. */
+    emit(event: LogEvent): void;
+    /** A logger bound to `name = value` (Serilog's `ForContext`), or to several properties at once. */
+    forContext(name: string, value: unknown, destructure?: boolean): Logger;
+    forContext(properties: Record<string, unknown>, destructure?: boolean): Logger;
+    /** A logger whose events carry `SourceContext` — the name level overrides match on. Dotted names nest: `'app.db'`. */
+    forSource(source: string): Logger;
+    /** pino / bunyan spelling of `forContext`. */
+    child(properties: Record<string, unknown>, destructure?: boolean): Logger;
+    /** Starts a timed operation; `complete()` / `abandon()` log one event with `Outcome` and `Elapsed`. */
+    beginOperation(template: string, ...args: unknown[]): Operation;
+    /** `beginOperation` with options (levels, `warnAfter`). */
+    operation(options: OperationOptions, template: string, ...args: unknown[]): Operation;
+    /**
+     * Runs `fn` as a timed operation: completes when it returns (or its
+     * promise resolves), abandons with the error when it throws (or rejects),
+     * then rethrows.
+     */
+    timed<R>(template: string, fn: (operation: Operation) => R, ...args: unknown[]): R;
+    /** Waits for every sink that buffers to send what it holds. */
+    flush(): Promise<void>;
+    /** Flushes, then closes the sinks — call once, before the process exits (Serilog's `CloseAndFlush`). */
+    close(): Promise<void>;
+    /** The sinks this logger writes to. */
+    get sinks(): readonly Sink[];
+    /** @internal — swaps the pipeline for every logger sharing this ref. */
+    _replace(options: LoggerOptions): void;
+}
+/** Creates an independent logger. With no options: `info` and above, to the console (pretty on a terminal, JSON elsewhere). */
+declare function createLogger(options?: LoggerOptions): Logger;
+/**
+ * Serilog's fluent `LoggerConfiguration`, for muscle memory:
+ *
+ *     const log = new LoggerConfiguration()
+ *       .minimumLevel.debug()
+ *       .minimumLevel.override('next', 'warn')
+ *       .enrich.withProperty('Application', 'shop')
+ *       .writeTo.console()
+ *       .createLogger();
+ */
+declare class LoggerConfiguration {
+    #private;
+    readonly minimumLevel: {
+        verbose: () => LoggerConfiguration;
+        debug: () => LoggerConfiguration;
+        info: () => LoggerConfiguration;
+        information: () => LoggerConfiguration;
+        warn: () => LoggerConfiguration;
+        warning: () => LoggerConfiguration;
+        error: () => LoggerConfiguration;
+        fatal: () => LoggerConfiguration;
+        is: (level: LevelOrSwitch) => LoggerConfiguration;
+        controlledBy: (levelSwitch: LevelSwitch) => LoggerConfiguration;
+        override: (source: string, level: LevelOrSwitch) => LoggerConfiguration;
+    };
+    readonly writeTo: {
+        sink: (...sinks: Sink[]) => LoggerConfiguration;
+        console: (options?: ConsoleSinkOptions) => LoggerConfiguration;
+        stream: (stream: StreamLike, options?: StreamSinkOptions) => LoggerConfiguration;
+        http: (options: HttpSinkOptions) => LoggerConfiguration;
+        seq: (options: SeqSinkOptions) => LoggerConfiguration;
+        /** A sub-logger with its own filters, enrichers and sinks (Serilog's `WriteTo.Logger`). */
+        logger: (configure: (configuration: LoggerConfiguration) => void, restrictedToMinimumLevel?: LevelOrSwitch) => LoggerConfiguration;
+    };
+    readonly auditTo: {
+        sink: (...sinks: Sink[]) => LoggerConfiguration;
+    };
+    readonly enrich: {
+        with: (...enrichers: Enricher[]) => LoggerConfiguration;
+        fromLogContext: () => LoggerConfiguration;
+        withProperty: (name: string, value: unknown, destructure?: boolean) => LoggerConfiguration;
+        withProperties: (properties: Record<string, unknown>, destructure?: boolean) => LoggerConfiguration;
+    };
+    readonly filter: {
+        with: (...filters: Filter[]) => LoggerConfiguration;
+        byExcluding: (predicate: (event: LogEvent) => boolean) => LoggerConfiguration;
+        byIncludingOnly: (predicate: (event: LogEvent) => boolean) => LoggerConfiguration;
+    };
+    readonly destructure: {
+        toMaximumDepth: (depth: number) => LoggerConfiguration;
+        toMaximumStringLength: (length: number) => LoggerConfiguration;
+        toMaximumCollectionCount: (count: number) => LoggerConfiguration;
+        with: (...policies: DestructuringPolicy[]) => LoggerConfiguration;
+        byTransforming: <T extends object>(type: abstract new (...args: never[]) => T, transform: (value: T) => unknown) => LoggerConfiguration;
+        /** Keys (or dotted paths) whose values are replaced by `[Redacted]`. */
+        redact: (...keys: string[]) => LoggerConfiguration;
+    };
+    readonly readFrom: {
+        /** `LOGIT_LEVEL` and `LOGIT_OVERRIDES` from the environment (they are read by default; this makes it explicit). */
+        env: () => LoggerConfiguration;
+    };
+    /** Disables the automatic `LogContext` enricher. */
+    withoutLogContext(): LoggerConfiguration;
+    /** The options as a plain object, for `createLogger()` or `configure()`. */
+    toOptions(): LoggerOptions;
+    createLogger(): Logger;
+}
+/**
+ * The default logger: `import { log } from '@unhingged/logit'` and go.
+ * Until `configure()` is called it writes `info` and above to the console —
+ * pretty on a terminal, JSON in a container or on Vercel. Every logger made
+ * from it (`log.forSource(...)`) follows a later `configure()`.
+ */
+declare const log: Logger;
+/** Reconfigures the global `log` (and every logger derived from it) in place. Returns it. */
+declare function configure(options?: LoggerOptions | LoggerConfiguration): Logger;
+/** Flushes and closes the global logger's sinks — Serilog's `Log.CloseAndFlush()`. */
+declare function closeAndFlush(): Promise<void>;
+
+/**
+ * Ambient properties — Serilog's `LogContext`. Everything logged inside
+ * `LogContext.run({ requestId }, fn)` carries `requestId`, however deep the
+ * call stack and across `await`s, because the frames live in an
+ * `AsyncLocalStorage` when one is available (Node, Bun, Deno, Next.js
+ * middleware and the edge runtime). Where there is none (a browser) the
+ * frames fall back to a plain stack, which is right for synchronous code.
+ *
+ * `push()` is the no-callback form, for `using`:
+ *
+ *     using _ = LogContext.push({ userId });
+ */
+interface ContextFrame {
+    readonly properties: Readonly<Record<string, unknown>>;
+    readonly parent: ContextFrame | null;
+    /** Serilog's `IDiagnosticContext`: values collected during a request for its completion event. */
+    readonly diagnostics?: Map<string, unknown>;
+}
+/** The subset of `AsyncLocalStorage` we need — structural, so any implementation (or a test double) fits. */
+interface ContextStore {
+    getStore(): ContextFrame | undefined;
+    run<R>(frame: ContextFrame | undefined, fn: () => R): R;
+    enterWith?(frame: ContextFrame | undefined): void;
+}
+interface ContextHandle {
+    /** Restores the previous frame. Calling it twice is harmless. */
+    dispose(): void;
+    [Symbol.dispose](): void;
+}
+declare const LogContext: {
+    /**
+     * Runs `fn` with `properties` added to the ambient context. Async
+     * functions are followed through every `await` when an
+     * AsyncLocalStorage-backed store is active.
+     */
+    run<R>(properties: Record<string, unknown>, fn: () => R): R;
+    /**
+     * Pushes properties onto the ambient context until the handle is disposed.
+     * Prefer `run()` for async code; `push()` relies on `enterWith`, which
+     * binds the rest of the *current* async scope.
+     */
+    push(properties: Record<string, unknown>): ContextHandle;
+    /** The merged ambient properties, innermost frame winning. */
+    current(): Record<string, unknown>;
+    /** The innermost frame, for enrichers that want to walk it themselves. */
+    frame(): ContextFrame | undefined;
+    /**
+     * Starts a request scope: ambient `properties` plus a fresh diagnostic
+     * bag that `diagnosticContext.set()` writes to and the request-completion
+     * event reads. Used by the Next.js and Express integrations.
+     */
+    runScope<R>(properties: Record<string, unknown>, fn: (diagnostics: Map<string, unknown>) => R): R;
+    /** Replaces the backing store — `new AsyncLocalStorage()` on runtimes we cannot detect. */
+    use(next: ContextStore): void;
+    /** `true` when frames follow async execution (an AsyncLocalStorage-like store is active). */
+    readonly isAsync: boolean;
+};
+/**
+ * Serilog's `IDiagnosticContext`: set a property from anywhere inside a
+ * request scope and it lands on that request's single completion event —
+ * one place for "which user, which tenant, how many rows" instead of a log
+ * line per fact.
+ */
+declare const diagnosticContext: {
+    set(name: string, value: unknown): void;
+    /** `true` inside a request scope (so a library can skip the work of computing a value nobody will collect). */
+    readonly active: boolean;
+};
+
+/**
+ * The logger's own diagnostics — Serilog's `SelfLog`. Off by default: a
+ * sink that fails must never take the application down, so failures go here
+ * and nowhere else. Enable it while setting up a sink, or point it at
+ * `console.error` in development.
+ */
+type SelfLogOutput = (message: string) => void;
+declare const selfLog: {
+    /** `'stderr'` writes to `console.error`; a function receives each line. */
+    enable(target: SelfLogOutput | "stderr"): void;
+    disable(): void;
+    readonly enabled: boolean;
+    /** Writes one line (prefixed with the time) if enabled; swallows its own errors. */
+    write(message: string, error?: unknown): void;
+};
+
+/** A sink that only sees events at or above `level` (Serilog's `restrictedToMinimumLevel`, for sinks that do not take the option themselves). */
+declare function restricted(sink: Sink, level: LevelOrSwitch): Sink;
+/** Serilog's `WriteTo.Conditional`: events the predicate accepts go to the sink, the rest are skipped. */
+declare function conditional(predicate: (event: LogEvent) => boolean, sink: Sink): Sink;
+/** Serilog's `AuditTo`: a failure in this sink propagates to the logging call instead of being swallowed. */
+declare function audit(sink: Sink): Sink;
+interface MapSinkOptions {
+    /** Sinks kept open at once; the least recently used is closed beyond this. Default 100. */
+    maxSinks?: number;
+    restrictedToMinimumLevel?: LevelOrSwitch;
+}
+/**
+ * Serilog.Sinks.Map: one sink per value of a key — a file per tenant, a
+ * stream per job. `keyOf` reads the key from the event (return `undefined`
+ * to skip); `create` builds the sink the first time a key is seen.
+ */
+declare function mapSink<K extends string | number>(keyOf: (event: LogEvent) => K | undefined, create: (key: K) => Sink, options?: MapSinkOptions): Sink;
+
+export { type BatchingOptions, type BatchingSink, CLEF_MEDIA_TYPE, type CapturedError, type ClefFormatterOptions, type ConsoleSinkOptions, type ContextFrame, type ContextHandle, type ContextStore, DEFAULT_DESTRUCTURING, DEFAULT_OUTPUT_TEMPLATE, type DestructuringOptions, type DestructuringPolicy, type Enricher, type FetchLike, type Filter, type FormatName, type Formatter, type HoleToken, type HttpSinkOptions, type JsonFormatterOptions, LEVELS, LEVEL_CODES, LEVEL_NUMBERS, LEVEL_ORDER, type LevelOrSwitch, LevelSwitch, LogContext, LogEvent, type LogEventInit, type LogLevel, type LogMethod, Logger, LoggerConfiguration, type LoggerOptions, type MapSinkOptions, Matching, type MemorySink, type MessageTemplate, Operation, type OperationOptions, type PrettyFormatterOptions, type RenderOptions, SERILOG_LEVEL_NAMES, type SeqSinkOptions, type Sink, type SinkOptions, type StreamLike, type StreamSinkOptions, type TemplateToken, type TextFormatterOptions, type TextToken, type TraceContext, type ValueStyles, ansi, audit, batchingSink, byExcluding, byIncludingOnly, byTransforming, callbackSink, captureError, captureProperty, captureValue, clefFormatter, closeAndFlush, conditional, configure, consoleSink, createLogger, detectColors, diagnosticContext, formatDate, formatError, formatLevel, formatNumber, fromLogContext, httpSink, isLevel, isoTimestamp, jsonFormatter, jsonReplacer, levelAtLeast, log, mapSink, memorySink, parseLevel, parseTemplate, prettyFormatter, rateLimited, renderTemplate, renderValue, resolveFormatter, resolveLevel, resolveStyles, restricted, sampled, selfLog, seqSink, streamSink, templateHash, textFormatter, toJson, withComputed, withEnvironment, withProperties, withProperty, withTraceContext };