logquill 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -54,6 +54,21 @@ interface Plugin {
     /** 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`.
@@ -78,15 +93,44 @@ declare class RedactPlugin implements Plugin {
     beforeLog(record: LogRecord): LogRecord;
 }
 
-interface SamplingPluginOptions {
-    rng?: () => number;
+/**
+ * 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>>;
+interface PIIRedactPluginOptions {
+    patterns?: Readonly<Record<string, RegExp>>;
+    replacement?: string;
 }
-/** Keeps roughly `rate` of records (0.0-1.0), dropping the rest. */
-declare class SamplingPlugin implements Plugin {
-    readonly rate: number;
-    private readonly rng;
-    constructor(rate: number, options?: SamplingPluginOptions);
-    beforeLog(record: LogRecord): LogRecord | null;
+/**
+ * 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 {
+    readonly patterns: Readonly<Record<string, RegExp>>;
+    readonly replacement: string;
+    constructor(options?: PIIRedactPluginOptions);
+    beforeLog(record: LogRecord): LogRecord;
+    private redactValue;
+    private redactText;
 }
 
 /**
@@ -110,6 +154,252 @@ declare class CollectingTransport extends Transport {
     close(): void;
 }
 
+interface SamplingPluginOptions {
+    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 {
+    readonly rate: number;
+    readonly traceKey: string;
+    readonly elevateAt: Level;
+    readonly transports: Transport[] | undefined;
+    readonly maxBufferedRecords: number;
+    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;
+}
+
+declare const GENESIS_HASH: string;
+interface TamperEvidentPluginOptions {
+    genesisHash?: string;
+}
+/**
+ * Hash-chains every record so tampering with a written log can be
+ * detected after the fact.
+ *
+ * Each record gets `meta.hash` — a SHA-256 hex digest over the record's
+ * own content plus the previous record's hash (`meta.prevHash`) — the same
+ * hash-chain construction used by tamper-evident/append-only logs: editing
+ * or deleting any one line breaks every hash after it in the chain, even
+ * if the tamperer edits the file directly and not through this plugin.
+ * Opt-in — hashing every record has a real, measurable CPU cost, so it
+ * isn't part of the default pipeline.
+ *
+ * Verify a previously-written log with `TamperEvidentPlugin.verifyChain`,
+ * which re-derives each record's hash from its content and confirms it
+ * matches both the stored `meta.hash` and the chain built from the records
+ * before it, in order.
+ */
+declare class TamperEvidentPlugin implements Plugin {
+    private readonly genesisHash;
+    private lastHash;
+    constructor(options?: TamperEvidentPluginOptions);
+    beforeLog(record: LogRecord): LogRecord;
+    /**
+     * Returns `true` iff every record's hash matches its content plus the
+     * previous record's hash, in the given order. Returns `false` at the
+     * first break in the chain (an edited, removed, or reordered record).
+     */
+    static verifyChain(records: Iterable<Pick<LogRecord, "timestamp" | "level" | "logger" | "message" | "meta">>, options?: TamperEvidentPluginOptions): boolean;
+}
+
+interface AlertingPluginOptions {
+    /** A record at or above this level fires an alert. Default `Level.ERROR`. */
+    threshold?: LevelInput;
+    /** How long a dedupe window stays open before a collapsed follow-up alert (if any) fires. Default 300_000 (5 minutes). */
+    dedupeWindowMs?: number;
+    /** Groups records into the same dedupe window. Default: `level:logger:message`. */
+    dedupeKey?: (record: LogRecord) => string;
+    /** Distinct concurrent dedupe keys tracked at once; beyond this, new keys are dropped rather than tracked. Default 500. */
+    maxTrackedKeys?: number;
+}
+/**
+ * Base class for plugins that fire an external alert on ERROR/FATAL (or any
+ * configurable `threshold`).
+ *
+ * A concrete subclass implements only `sendAlert(record, occurrences)` —
+ * everything else (thresholding, deduplication, never blocking the caller,
+ * never letting a broken destination crash logging) lives here.
+ *
+ * The first record at or above `threshold` for a given dedupe key (by
+ * default: level + logger + message) fires `sendAlert` right away, without
+ * awaiting it — so the log call that triggered it is never blocked on a
+ * webhook, SMTP handshake, or any other I/O, even if the destination is
+ * slow or unreachable. This stands in for the shared async dispatch queue
+ * a later phase will introduce; once that queue exists, `AlertingPlugin`
+ * can route through it instead of firing its own unawaited call per alert.
+ *
+ * Any further record matching the same dedupe key within
+ * `dedupeWindowMs` of the first is *not* sent again — it just increments a
+ * counter. When the window closes, if more than one record matched,
+ * exactly one follow-up alert is sent with the total occurrence count,
+ * instead of spamming the destination once per record. Tracking is bounded
+ * to `maxTrackedKeys` distinct concurrent dedupe keys; beyond that, new
+ * keys are dropped rather than tracked (alerting degrades under extreme
+ * cardinality, logging itself never does).
+ *
+ * `sendAlert` is always called without being awaited, and any rejection is
+ * routed to this plugin's own `onError`, the same as any other plugin hook
+ * that throws.
+ */
+declare abstract class AlertingPlugin implements Plugin {
+    readonly threshold: Level;
+    readonly dedupeWindowMs: number;
+    readonly maxTrackedKeys: number;
+    private readonly dedupeKeyFn;
+    private readonly windows;
+    constructor(options?: AlertingPluginOptions);
+    afterLog(record: LogRecord): void;
+    private flush;
+    private safeSend;
+    /**
+     * Send one alert for `record`, representing `occurrences` collapsed
+     * duplicates (1 on first occurrence; the deduped total on a follow-up
+     * flush). Override in a concrete subclass — never call this directly,
+     * `AlertingPlugin` calls it without awaiting it.
+     */
+    protected abstract sendAlert(record: LogRecord, occurrences: number): void | Promise<void>;
+    onError?(error: unknown, record: LogRecord): void;
+    /** Cancel any pending dedupe-window timers. Call on logger shutdown. */
+    close(): void;
+}
+
+/** Posts one alert body to a Slack incoming webhook URL. Swap in a fake for tests. */
+type SlackSender = (webhookUrl: string, body: string) => Promise<void> | void;
+interface SlackAlertPluginOptions extends AlertingPluginOptions {
+    sender?: SlackSender;
+}
+/**
+ * Sends deduplicated `AlertingPlugin` alerts to a Slack incoming webhook.
+ *
+ * `webhookUrl` is the full "Incoming Webhook" URL from Slack's app config.
+ * Uses `fetch` — no extra dependency required. Pass `sender` to swap in a
+ * fake for tests or an alternate backend.
+ */
+declare class SlackAlertPlugin extends AlertingPlugin {
+    readonly webhookUrl: string;
+    private readonly sender;
+    constructor(webhookUrl: string, options?: SlackAlertPluginOptions);
+    protected sendAlert(record: LogRecord, occurrences: number): Promise<void>;
+}
+
+/** POSTs one PagerDuty Events API v2 payload. Swap in a fake for tests. */
+type PagerDutySender = (body: string) => Promise<void> | void;
+interface PagerDutyAlertPluginOptions extends AlertingPluginOptions {
+    sender?: PagerDutySender;
+}
+/**
+ * Sends deduplicated `AlertingPlugin` alerts to PagerDuty via the Events
+ * API v2 (`POST https://events.pagerduty.com/v2/enqueue`).
+ *
+ * `routingKey` is an Events API v2 integration key from a PagerDuty
+ * service. Uses `fetch` — no extra dependency required. Pass `sender` to
+ * swap in a fake for tests or an alternate backend.
+ */
+declare class PagerDutyAlertPlugin extends AlertingPlugin {
+    readonly routingKey: string;
+    private readonly sender;
+    constructor(routingKey: string, options?: PagerDutyAlertPluginOptions);
+    protected sendAlert(record: LogRecord, occurrences: number): Promise<void>;
+}
+
+interface EmailMessage {
+    from: string;
+    to: string[];
+    subject: string;
+    text: string;
+}
+/** Sends one email message. Swap in a fake for tests. */
+type EmailSender = (message: EmailMessage) => Promise<void> | void;
+/** The subset of a `nodemailer` transporter that `EmailAlertPlugin` needs. */
+interface NodemailerTransporterLike {
+    sendMail(message: {
+        from: string;
+        to: string;
+        subject: string;
+        text: string;
+    }): Promise<unknown>;
+}
+interface EmailAlertPluginOptions extends AlertingPluginOptions {
+    smtpHost: string;
+    smtpPort: number;
+    fromAddr: string;
+    toAddrs: string[];
+    username?: string;
+    password?: string;
+    /** `false` for an SMTP server that doesn't support STARTTLS (e.g. a local relay). Default `true`. */
+    useTls?: boolean;
+    /** Pre-built sender, e.g. for tests. Skips the `nodemailer` auto-import entirely. */
+    sender?: EmailSender;
+}
+/**
+ * Sends deduplicated `AlertingPlugin` alerts by email over SMTP.
+ *
+ * `nodemailer` is an optional peer dependency: install it yourself, or
+ * pass `sender` to swap in a fake for tests or an alternate backend —
+ * `username`/`password` are only used if both are set.
+ */
+declare class EmailAlertPlugin extends AlertingPlugin {
+    readonly smtpHost: string;
+    readonly smtpPort: number;
+    readonly fromAddr: string;
+    readonly toAddrs: string[];
+    private readonly username;
+    private readonly password;
+    private readonly useTls;
+    private readonly injectedSender;
+    private transporter;
+    constructor(options: EmailAlertPluginOptions);
+    protected sendAlert(record: LogRecord, occurrences: number): Promise<void>;
+    private importTransporter;
+}
+
 interface BatchingTransportOptions {
     formatter?: Formatter;
     /** Flush once the buffer holds this many items. Default 100. */
@@ -946,7 +1236,7 @@ declare class HTTPTransport extends Transport {
 interface LoggerOptions {
     level?: LevelInput;
     transports?: Transport[];
-    plugins?: Plugin[];
+    plugins?: (Plugin | MiddlewareFunc)[];
     meta?: Record<string, unknown>;
 }
 declare class Logger {
@@ -958,8 +1248,13 @@ declare class Logger {
     constructor(name: string, options?: LoggerOptions);
     get level(): Level;
     setLevel(level: LevelInput): void;
-    /** Register a plugin. Returns `this` so calls can be chained. */
-    use(plugin: Plugin): this;
+    /**
+     * 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;
     /** Close every attached transport. Call on shutdown to flush buffered writes. */
     close(): void;
     /** A logger scoped under this one, inheriting its level, transports, and plugins. */
@@ -974,6 +1269,6 @@ declare class Logger {
     fatal(message: string, meta?: Record<string, unknown>): LogRecord | null;
 }
 
-declare const VERSION = "0.2.0";
+declare const VERSION = "0.3.0";
 
-export { type AmqpChannelLike, type AppInsightsClientLike, type AppInsightsTrace, AppInsightsTransport, type AppInsightsTransportOptions, BaseQueueTransport, type BaseQueueTransportOptions, BaseSQLTransport, type BaseSQLTransportOptions, BatchingTransport, type BatchingTransportOptions, type CloudLoggingClientLike, type CloudLoggingEntry, CloudLoggingTransport, type CloudLoggingTransportOptions, type CloudWatchClientLike, type CloudWatchLogEvent, CloudWatchTransport, type CloudWatchTransportOptions, CollectingTransport, type ConsoleLike, ConsoleTransport, type ConsoleTransportOptions, ContextPlugin, DEFAULT_REDACTED_KEYS, type DatadogSender, DatadogTransport, type DatadogTransportOptions, type DynamoClientLike, DynamoDBTransport, type DynamoDBTransportOptions, type DynamoLogItem, type ElasticsearchSender, ElasticsearchTransport, type ElasticsearchTransportOptions, FileTransport, type FileTransportOptions, type Formatter, HTTPTransport, type HTTPTransportOptions, JSONFormatter, type KafkaProducerLike, KafkaTransport, type KafkaTransportOptions, Level, type LevelInput, type LogRecord, Logger, type LoggerOptions, type MongoClientLike, type MongoCollectionLike, MongoDBTransport, type MongoDBTransportOptions, type MySQLClientLike, MySQLTransport, type MySQLTransportOptions, type NewRelicRegion, type NewRelicSender, type NewRelicSenderResult, NewRelicTransport, type NewRelicTransportOptions, type PgClientLike, type Plugin, PostgresTransport, type PostgresTransportOptions, type PubSubTopicLike, PubSubTransport, type PubSubTransportOptions, RabbitMQTransport, type RabbitMQTransportOptions, RedactPlugin, type RedactPluginOptions, type RedisClientLike, RedisTransport, type RedisTransportOptions, type SQLLogRow, type SQLiteClientLike, type SQLiteStatementLike, SQLiteTransport, type SQLiteTransportOptions, type SQSClientLike, SQSTransport, type SQSTransportOptions, SamplingPlugin, type SamplingPluginOptions, type Sender, Transport, VERSION, createRecord, levelName, parseLevel, utcTimestamp };
+export { AlertingPlugin, type AlertingPluginOptions, type AmqpChannelLike, type AppInsightsClientLike, type AppInsightsTrace, AppInsightsTransport, type AppInsightsTransportOptions, BaseQueueTransport, type BaseQueueTransportOptions, BaseSQLTransport, type BaseSQLTransportOptions, BatchingTransport, type BatchingTransportOptions, type CloudLoggingClientLike, type CloudLoggingEntry, CloudLoggingTransport, type CloudLoggingTransportOptions, type CloudWatchClientLike, type CloudWatchLogEvent, CloudWatchTransport, type CloudWatchTransportOptions, CollectingTransport, type ConsoleLike, ConsoleTransport, type ConsoleTransportOptions, ContextPlugin, DEFAULT_PII_PATTERNS, DEFAULT_REDACTED_KEYS, type DatadogSender, DatadogTransport, type DatadogTransportOptions, type DynamoClientLike, DynamoDBTransport, type DynamoDBTransportOptions, type DynamoLogItem, type ElasticsearchSender, ElasticsearchTransport, type ElasticsearchTransportOptions, EmailAlertPlugin, type EmailAlertPluginOptions, type EmailMessage, type EmailSender, FileTransport, type FileTransportOptions, type Formatter, FunctionPlugin, GENESIS_HASH, HTTPTransport, type HTTPTransportOptions, JSONFormatter, type KafkaProducerLike, KafkaTransport, type KafkaTransportOptions, Level, type LevelInput, type LogRecord, Logger, type LoggerOptions, type MiddlewareFunc, type MongoClientLike, type MongoCollectionLike, MongoDBTransport, type MongoDBTransportOptions, type MySQLClientLike, MySQLTransport, type MySQLTransportOptions, type NewRelicRegion, type NewRelicSender, type NewRelicSenderResult, NewRelicTransport, type NewRelicTransportOptions, type NodemailerTransporterLike, PIIRedactPlugin, type PIIRedactPluginOptions, PagerDutyAlertPlugin, type PagerDutyAlertPluginOptions, type PagerDutySender, type PgClientLike, type Plugin, PostgresTransport, type PostgresTransportOptions, type PubSubTopicLike, PubSubTransport, type PubSubTransportOptions, RabbitMQTransport, type RabbitMQTransportOptions, RedactPlugin, type RedactPluginOptions, type RedisClientLike, RedisTransport, type RedisTransportOptions, type SQLLogRow, type SQLiteClientLike, type SQLiteStatementLike, SQLiteTransport, type SQLiteTransportOptions, type SQSClientLike, SQSTransport, type SQSTransportOptions, SamplingPlugin, type SamplingPluginOptions, type Sender, SlackAlertPlugin, type SlackAlertPluginOptions, type SlackSender, TamperEvidentPlugin, type TamperEvidentPluginOptions, Transport, VERSION, createRecord, levelName, parseLevel, utcTimestamp };