@richardmcquiston01/error-log-adapter 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -10,6 +10,17 @@ interface ErrorLogEntry<TCode extends string = string> {
     source?: string;
     /** ISO 8601 timestamp. Adapters fill this in when it is omitted. */
     timestamp?: string;
+    /**
+     * Optional UUID that identifies this entry. Adapters generate a new one for
+     * every `log` call when it is omitted, so logging the same entry twice stores
+     * it twice. Supply the same `id` (and, for S3, the same `timestamp`) to make
+     * a retry safe: sinks that can detect a repeat overwrite or skip the existing
+     * record instead of adding another. It must be a UUID, for example from
+     * `crypto.randomUUID()`; anything else makes `log` return `ok: false`.
+     * Redis, the flat file and NDJSON file adapters, and the console cannot
+     * detect a repeat.
+     */
+    id?: string;
 }
 /** Outcome of a `log` call. Callers should check `ok`. */
 interface ErrorLogResult {
@@ -34,8 +45,16 @@ interface SerializedErrorLogEntry {
     timestamp: string;
 }
 /**
- * Converts `Error` instances into plain objects, since `JSON.stringify`
- * renders them as `{}`. Other values are returned unchanged.
+ * Returns a copy of `cause` that `JSON.stringify` can always handle, so a
+ * strange cause can never stop an entry from being stored.
+ *
+ * - `Error` objects (including ones from another realm) become
+ *   `{ name, message, stack }`, plus `cause` and, for an `AggregateError`,
+ *   `errors`, which are converted the same way.
+ * - Circular references become `"[Circular]"`, and anything nested deeper than
+ *   `MAX_CAUSE_DEPTH` levels becomes `"[Truncated]"`.
+ * - `BigInt`, `Symbol` and function values, and non-finite numbers, become strings.
+ * - A property or `toJSON` that throws is replaced by a short description.
  */
 declare function serializeCause(cause: unknown): unknown;
 /** Returns a JSON-safe copy of the entry, adding a timestamp if missing. */
@@ -56,13 +75,67 @@ interface WebhookErrorOptions {
     headers?: Record<string, string>;
     /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
     prefix?: string;
+    /**
+     * Allow a plain `http://` URL. Entries contain error messages and stack
+     * traces, so they are only sent over `https://` unless this is `true`.
+     * `http://localhost`, `127.0.0.1` and `[::1]` are always allowed.
+     * Defaults to `false`.
+     */
+    allowInsecure?: boolean;
+    /**
+     * How long to wait for the webhook to answer, in milliseconds. Defaults to
+     * 10000. Pass `Infinity` to wait without limit. When it passes, the request is
+     * cancelled, so the connection is closed rather than left open; the server may
+     * still have received the entry.
+     */
+    timeoutMs?: number;
+    /**
+     * How many times to try again after a failure that may go away on its own: a
+     * network error, a timeout, HTTP 408, 425, 429 or any 5xx. Other 4xx answers and
+     * redirects are never retried. Defaults to 0 (send once). The wait doubles
+     * after each attempt, starting at `retryDelayMs`, with jitter, and a
+     * `Retry-After` header is honored. `timeoutMs` applies to each attempt, and
+     * `log()` resolves only after the last one. Every attempt sends the same body,
+     * and with `retries` above 0 the body always carries an `id`, so the receiver
+     * can drop a repeat if an earlier attempt did arrive.
+     */
+    retries?: number;
+    /** Wait before the first retry, in milliseconds. Defaults to 500. */
+    retryDelayMs?: number;
+    /** Longest wait between attempts, in milliseconds. Defaults to 30000. */
+    maxRetryDelayMs?: number;
+    /**
+     * Shared secret for signing each request, so the receiver can verify the
+     * entry came from you and was not altered. Adds `X-Signature-Timestamp`
+     * (Unix seconds) and `X-Signature-256` (`sha256=` and the hex HMAC-SHA256 of
+     * `<timestamp>.<body>`). The receiver should recompute it and reject old
+     * timestamps. Needs Web Crypto (Node 20+, browsers, Deno, Bun); without it
+     * `log()` fails rather than sending an unsigned entry.
+     */
+    signingSecret?: string;
 }
 declare class WebhookErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
     private readonly url;
     private readonly options;
     private readonly prefix;
+    private readonly timeoutMs;
+    private readonly retries;
+    private readonly retryDelayMs;
+    private readonly maxRetryDelayMs;
+    /** Scheme and host only. Webhook URLs often carry a secret in the path or query. */
+    private readonly target;
+    /** @throws {RangeError} if `url` is not a valid `https://` URL (see `allowInsecure`) or a timeout, retry or signing option is invalid. */
     constructor(url: string, options?: WebhookErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
+    /** Milliseconds to wait before retry number `retryNumber` (1 for the first). */
+    private retryWaitMs;
+    private send;
+    /** Timestamp and signature headers, or none when no `signingSecret` is set. */
+    private signatureHeaders;
+    private rejected;
+    private redirectMessage;
+    /** Replaces the full URL in a message with its origin, in case the runtime put it there. */
+    private redact;
     private fail;
 }
 
@@ -73,26 +146,63 @@ interface CollectionLike {
 interface MongoDbErrorOptions {
     /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
     prefix?: string;
+    /**
+     * How long `log` waits for the insert before giving up, in milliseconds. Defaults to
+     * 10000. Pass `Infinity` to wait without limit. The call cannot be cancelled,
+     * so it may still finish after `log` has returned a failure.
+     */
+    timeoutMs?: number;
 }
 declare class MongoDbErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
     private readonly collection;
     private readonly prefix;
+    private readonly timeoutMs;
+    /** @throws {RangeError} if `options.timeoutMs` is not a positive number or Infinity. */
     constructor(collection: CollectionLike, options?: MongoDbErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
 }
 
+interface CompositeErrorOptions {
+    /**
+     * How long to wait for each adapter before reporting it as failed, in
+     * milliseconds. Defaults to 30000, longer than the 10000 default of the built-in
+     * adapters so their own, more specific timeout messages come first. This only
+     * matters for a custom adapter that can hang: one stuck adapter then cannot
+     * hold back the result of the others. Pass `Infinity` to wait without limit.
+     */
+    timeoutMs?: number;
+}
 /** Sends every entry to several adapters. Succeeds only if all of them do. */
 declare class CompositeErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
     private readonly adapters;
-    constructor(adapters: ReadonlyArray<ErrorLogAdapter<TCode>>);
+    private readonly timeoutMs;
+    /** @throws {RangeError} if `options.timeoutMs` is not a positive number or Infinity. */
+    constructor(adapters: ReadonlyArray<ErrorLogAdapter<TCode>>, options?: CompositeErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
 }
 
 /** Event handler slot. Typed loosely so real DOM `IDBTransaction` objects fit. */
 type IdbHandler = ((event: never) => unknown) | null;
+/** The error object of a failed request or transaction (a `DOMException`). */
+interface IdbErrorLike {
+    name?: string;
+    message?: string;
+}
+/** The subset of an `IDBRequest` this adapter uses. */
+interface IdbRequestLike {
+    onerror: IdbHandler;
+    readonly error?: IdbErrorLike | null;
+}
 /** The subset of an `IDBObjectStore` this adapter uses. */
 interface IdbObjectStoreLike {
+    /** Returns an `IDBRequest`. Fakes that return nothing also work. */
     add(value: unknown): unknown;
+    /**
+     * Replaces the record with the same key. Used for entries that carry their own
+     * `id`, so logging one again does not fail on the existing key. A real
+     * `IDBObjectStore` has it; a fake without it falls back to `add`.
+     */
+    put?(value: unknown): unknown;
 }
 /** The subset of an `IDBTransaction` this adapter uses. */
 interface IdbTransactionLike {
@@ -100,9 +210,7 @@ interface IdbTransactionLike {
     oncomplete: IdbHandler;
     onerror: IdbHandler;
     onabort: IdbHandler;
-    readonly error?: {
-        message?: string;
-    } | null;
+    readonly error?: IdbErrorLike | null;
 }
 /** The subset of an `IDBDatabase` this adapter uses. */
 interface IdbDatabaseLike {
@@ -128,6 +236,13 @@ interface IndexedDbErrorOptions {
     storeName?: string;
     /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
     prefix?: string;
+    /**
+     * How long `log` waits for the transaction to finish, in milliseconds. Defaults
+     * to 10000. Pass `Infinity` to wait without limit. A transaction can stay
+     * pending when a version change in another tab blocks it, or when the browser
+     * has evicted the origin's storage. The write may still finish afterwards.
+     */
+    timeoutMs?: number;
 }
 /**
  * Creates the error log object store (UUID `id` key, `timestamp` index).
@@ -138,9 +253,18 @@ declare class IndexedDbErrorAdapter<TCode extends string = string> implements Er
     private readonly database;
     private readonly storeName;
     private readonly prefix;
+    private readonly timeoutMs;
+    /** @throws {RangeError} if `options.timeoutMs` is not a positive number or Infinity. */
     constructor(database: IdbDatabaseLike, options?: IndexedDbErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
-    /** Resolves once the transaction commits; rejects if it errors or aborts. */
+    /**
+     * Resolves once the transaction commits; rejects if the request fails, the
+     * transaction aborts, or it does not finish within `timeoutMs`.
+     *
+     * Error events are handled here (`preventDefault` and `stopPropagation`), so a
+     * failed log write does not reach the `onerror` handler an app may have set on
+     * its own database object.
+     */
     private write;
 }
 
@@ -166,6 +290,12 @@ interface SqliteErrorOptions {
     createTable?: boolean;
     /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
     prefix?: string;
+    /**
+     * How long `log` waits for the driver before giving up, in milliseconds. Defaults
+     * to 10000. Pass `Infinity` to wait without limit. The call cannot be
+     * cancelled, so it may still finish after `log` has returned a failure.
+     */
+    timeoutMs?: number;
 }
 /**
  * Returns the statements that create the error log table and its index.
@@ -177,13 +307,16 @@ declare class SqliteErrorAdapter<TCode extends string = string> implements Error
     private readonly tableName;
     private readonly createTable;
     private readonly prefix;
+    private readonly timeoutMs;
     private tableReady;
-    /** @throws {RangeError} if `options.tableName` is not a plain identifier. */
+    /** @throws {RangeError} if `options.tableName` is not a plain identifier or `options.timeoutMs` is invalid. */
     constructor(client: SqliteClientLike, options?: SqliteErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
     /** Creates the table once. A failed attempt is retried on the next log call. */
     private ensureTable;
     private runCreateStatements;
+    /** Runs one statement, giving up waiting after `timeoutMs`. */
+    private run;
 }
 
 /**
@@ -194,6 +327,14 @@ interface StorageLike {
     getItem(key: string): string | null;
     setItem(key: string, value: string): void;
 }
+/**
+ * The part of `navigator.locks` this adapter uses. `localStorage` is shared by
+ * every tab of an origin and has no atomic update, so a lock keeps two tabs from
+ * overwriting each other's entry.
+ */
+interface LockManagerLike {
+    request<T>(name: string, callback: () => T | Promise<T>): Promise<T>;
+}
 /** A stored record: the serialized entry plus its generated UUID. */
 interface WebStorageErrorRecord extends SerializedErrorLogEntry {
     id: string;
@@ -205,24 +346,51 @@ interface WebStorageErrorOptions {
     maxEntries?: number;
     /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
     prefix?: string;
+    /**
+     * Lock manager that makes tabs sharing a `localStorage` take turns. Defaults to
+     * `navigator.locks` when the browser has it. This reduces lost entries but does
+     * not remove them: a tab in another process can still read a stale copy
+     * (measured in Chromium). Pass `null` to turn locking off.
+     */
+    locks?: LockManagerLike | null;
 }
 /**
  * Keeps the newest entries in a Web Storage object (`sessionStorage` or
  * `localStorage`) as a JSON array under one key, capped at `maxEntries`.
  * When the store is full, the oldest entries are dropped until the new one fits.
+ *
+ * `sessionStorage` belongs to one tab, so it is safe. `localStorage` is shared by
+ * every tab of the origin and has no atomic update: two tabs logging at the same
+ * moment can overwrite each other's entry while both get `ok: true`. In Chromium,
+ * tabs in separate processes (the usual case) even read a stale copy, so a lock
+ * reduces the loss without removing it. Where tabs may log at the same time and
+ * every entry matters, use `IndexedDbErrorAdapter`, whose writes are transactional.
  */
 declare class WebStorageErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
     private readonly storage;
     private readonly key;
     private readonly maxEntries;
     private readonly prefix;
+    private readonly locks;
     /** @throws {RangeError} if `options.maxEntries` is not a positive integer. */
     constructor(storage: StorageLike, options?: WebStorageErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
-    /** Reads, appends, trims, and writes back. Runs without awaiting, so calls never interleave. */
+    /**
+     * Appends under a cross-tab lock when one is available. If the lock itself
+     * cannot be taken (for example a sandboxed frame), the entry is still written
+     * without it rather than lost.
+     */
+    private appendLocked;
+    /** Reads, appends, trims, and writes back. Runs without awaiting, so calls in one tab never interleave. */
     private append;
     /** Returns the stored records, or none if the value is missing or unreadable. */
     private readRecords;
+    /**
+     * Copies an unusable value to `<key>.corrupt` before it is replaced, so data
+     * the host app stored under the same key is not silently destroyed. Only the
+     * first one is kept; a later unusable value would not overwrite it.
+     */
+    private setAside;
 }
 
 /**
@@ -281,7 +449,7 @@ declare class FlatFileErrorAdapter<TCode extends string = string> implements Err
     private readonly prefix;
     private fs;
     private directoryReady;
-    private queue;
+    private readonly queue;
     /** @throws {RangeError} if `maxBytes` or `maxFiles` is not a positive integer. */
     constructor(filePath: string, options?: FlatFileErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
@@ -334,7 +502,7 @@ declare class JsonFileErrorAdapter<TCode extends string = string> implements Err
     private readonly prefix;
     private fs;
     private directoryReady;
-    private queue;
+    private readonly queue;
     /** @throws {RangeError} if `maxEntries` or `indent` is invalid, or `maxEntries` is used outside array mode. */
     constructor(filePath: string, options?: JsonFileErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
@@ -371,6 +539,12 @@ interface SqlErrorOptions {
     createTable?: boolean;
     /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
     prefix?: string;
+    /**
+     * How long `log` waits for each database statement before giving up, in milliseconds. Defaults
+     * to 10000. Pass `Infinity` to wait without limit. The call cannot be
+     * cancelled, so it may still finish after `log` has returned a failure.
+     */
+    timeoutMs?: number;
 }
 /**
  * Returns the statements that create the error log table and its index for a
@@ -381,6 +555,12 @@ interface SqlErrorOptions {
  * cause, and `DATETIME(3)` columns holding UTC times.
  */
 declare function buildErrorLogTableDdl(dialect: SqlDialect, tableName?: string): string[];
+/**
+ * Returns the statement that widens the `code` and `source` columns of a MySQL
+ * table created by `buildErrorLogTableDdl` in 0.4.0 or earlier, where they were
+ * `VARCHAR(255)` and a longer value made the insert fail. Run it once.
+ */
+declare function buildMySqlWidenColumnsSql(tableName?: string): string[];
 /** Shared by the Postgres and MySQL adapters: only the SQL text and time format differ. */
 declare abstract class SqlErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
     private readonly client;
@@ -389,6 +569,7 @@ declare abstract class SqlErrorAdapter<TCode extends string = string> implements
     private readonly tableName;
     private readonly createTable;
     private readonly prefix;
+    private readonly timeoutMs;
     private tableReady;
     protected constructor(client: SqlClientLike, dialect: SqlDialect, adapterName: string, options: SqlErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
@@ -396,6 +577,8 @@ declare abstract class SqlErrorAdapter<TCode extends string = string> implements
     /** Creates the table once. A failed attempt is retried on the next log call. */
     private ensureTable;
     private runCreateStatements;
+    /** Runs one statement, giving up waiting after `timeoutMs`. */
+    private query;
 }
 /**
  * Writes entries to Postgres. Pass a `pg` `Pool` or `Client`.
@@ -454,6 +637,12 @@ interface RedisErrorOptions {
     side?: 'left' | 'right';
     /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
     prefix?: string;
+    /**
+     * How long `log` waits for each Redis command before giving up, in milliseconds. Defaults
+     * to 10000. Pass `Infinity` to wait without limit. The call cannot be
+     * cancelled, so it may still finish after `log` has returned a failure.
+     */
+    timeoutMs?: number;
 }
 /**
  * Writes entries to Redis, either as a capped list of JSON strings or as a
@@ -467,6 +656,7 @@ declare class RedisErrorAdapter<TCode extends string = string> implements ErrorL
     private readonly maxEntries;
     private readonly side;
     private readonly prefix;
+    private readonly timeoutMs;
     /** @throws {RangeError} if `key` is empty, `maxEntries` is not a positive integer, or `mode` / `side` is unknown. */
     constructor(client: RedisClientLike, options?: RedisErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
@@ -476,6 +666,8 @@ declare class RedisErrorAdapter<TCode extends string = string> implements ErrorL
      * stored by now, so a trim failure is reported but does not fail the call;
      * the next successful write trims the list again.
      */
+    /** Sends one command, giving up waiting after `timeoutMs`. */
+    private send;
     private trimList;
 }
 
@@ -528,6 +720,13 @@ interface S3ErrorOptions {
     batch?: S3BatchOptions;
     /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
     prefix?: string;
+    /**
+     * How long an upload may take before `log` (or `flush`) gives up waiting, in
+     * milliseconds. Defaults to 10000. Pass `Infinity` to wait without limit. The
+     * upload cannot be cancelled, so it may still finish afterwards; in batch mode
+     * the entries stay buffered and are uploaded again by the next flush.
+     */
+    timeoutMs?: number;
 }
 /**
  * Stores entries as objects in an S3-compatible bucket, keyed by date and UUID:
@@ -546,9 +745,10 @@ declare class S3ErrorAdapter<TCode extends string = string> implements ErrorLogA
     private readonly contentType;
     private readonly batch;
     private readonly logPrefix;
+    private readonly timeoutMs;
     private buffer;
     private timer;
-    private flushQueue;
+    private readonly flushQueue;
     /** @throws {RangeError} if `bucket` is empty or the batch options are invalid. */
     constructor(client: S3ClientLike, bucket: string, options?: S3ErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
@@ -604,11 +804,19 @@ interface FirestoreCollectionLike {
  * ```ts
  * const refLike: RealtimeDatabaseRefLike = {
  *   push: (value) => push(ref(db, 'error_log'), value),
+ *   child: (key) => ({ set: (value) => set(ref(db, `error_log/${key}`), value) }),
  * };
  * ```
+ *
+ * `child(key).set(value)` is only needed for entries that carry their own `id`
+ * (see `ErrorLogEntry.id`): they are written under that key, so logging the same
+ * entry again overwrites the record instead of adding a second one.
  */
 interface RealtimeDatabaseRefLike {
     push(value: FirebaseErrorRecord): PromiseLike<unknown>;
+    child?(key: string): {
+        set(value: FirebaseErrorRecord): PromiseLike<unknown>;
+    };
 }
 interface FirebaseErrorOptions {
     /**
@@ -618,7 +826,9 @@ interface FirebaseErrorOptions {
      * The Firebase SDKs keep writes queued while the connection is down, and
      * their promises stay pending until it returns, so without a limit `log`
      * could hang for as long as an outage lasts. A write that timed out is still
-     * queued by the SDK and may be saved later.
+     * queued by the SDK and may be saved later. Retry a timeout only with the same
+     * `ErrorLogEntry.id`, so the retry overwrites the first write instead of
+     * adding a second one.
      */
     timeoutMs?: number;
     /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
@@ -626,7 +836,11 @@ interface FirebaseErrorOptions {
 }
 /**
  * Writes each entry as a document in a Firestore collection. The document id is
- * the entry's UUID, so retrying a write never creates a duplicate.
+ * the entry's UUID, so the SDK finishing one queued write twice cannot create two
+ * documents. Calling `log` again without an `id` on the entry is a new write
+ * with a new UUID: if a call reported a timeout, the first write may still be
+ * saved later, and logging the same entry again can store it twice. Give the
+ * entry an `id` and the retry overwrites the same document.
  */
 declare class FirestoreErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
     private readonly collection;
@@ -684,26 +898,46 @@ interface SupabaseClientLike {
     };
 }
 interface SupabaseErrorOptions {
-    /** Table to write to. Defaults to `error_log`. */
+    /** Table to write to. Defaults to `error_log`. Letters, digits and `_` only. */
     tableName?: string;
     /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
     prefix?: string;
+    /**
+     * How long `log` waits for Supabase to answer before giving up, in milliseconds. Defaults
+     * to 10000. Pass `Infinity` to wait without limit. The call cannot be
+     * cancelled, so it may still finish after `log` has returned a failure.
+     */
+    timeoutMs?: number;
 }
 interface SupabaseSetupOptions {
     /**
-     * Postgres roles allowed to insert, for example `['anon', 'authenticated']`
-     * when the browser logs with the public key. Leave empty when only a server
-     * using the service role key logs: that role bypasses row level security.
+     * Postgres roles allowed to insert through the API, for example
+     * `['authenticated']`. Leave empty when only a server using the service role
+     * key logs: that role bypasses row level security, so it needs no policy, and
+     * its key must never be shipped to a browser.
+     *
+     * The generated policy only checks the size of each field. It does not tie a
+     * row to a user, so any holder of an allowed role's key can still add entries
+     * of their own making: forged entries can hide real incidents, and a flood of
+     * them uses up your database quota. Prefer `authenticated` over `anon`.
      */
     insertRoles?: string[];
+    /**
+     * Required to allow `anon` (or `public`) to insert. The `anon` key is part of
+     * your frontend, so this lets anyone who loads the page write to the log.
+     * Defaults to `false`.
+     */
+    allowPublicInsert?: boolean;
 }
 /**
  * Returns the SQL to run once in the Supabase SQL editor: the error log table,
  * with row level security turned on (as Supabase recommends for every table in
  * an exposed schema) and, optionally, an insert-only policy for the given roles.
- * Nobody but the service role can read the log through the API.
+ * The policy limits the size of each field. Nobody but the service role can read
+ * the log through the API.
  *
- * @throws {RangeError} if the table name or a role is not a plain identifier.
+ * @throws {RangeError} if the table name or a role is not a plain identifier, or
+ * `anon` / `public` is listed without `allowPublicInsert: true`.
  */
 declare function buildSupabaseSetupSql(tableName?: string, options?: SupabaseSetupOptions): string[];
 /**
@@ -721,10 +955,71 @@ declare class SupabaseErrorAdapter<TCode extends string = string> implements Err
     private readonly client;
     private readonly tableName;
     private readonly prefix;
-    /** @throws {RangeError} if `options.tableName` is empty. */
+    private readonly timeoutMs;
+    /** @throws {RangeError} if `options.tableName` is not a plain identifier or `options.timeoutMs` is invalid. */
     constructor(client: SupabaseClientLike, options?: SupabaseErrorOptions);
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
     private fail;
 }
 
-export { type CollectionLike, CompositeErrorAdapter, ConsoleErrorAdapter, type ConsoleErrorOptions, type ErrorLogAdapter, type ErrorLogEntry, type ErrorLogResult, type FileSystemLike, type FirebaseErrorOptions, type FirebaseErrorRecord, type FirestoreCollectionLike, FirestoreErrorAdapter, FlatFileErrorAdapter, type FlatFileErrorOptions, type IdbDatabaseLike, type IdbObjectStoreLike, type IdbTransactionLike, type IdbUpgradeDatabaseLike, IndexedDbErrorAdapter, type IndexedDbErrorOptions, type IndexedDbErrorRecord, JsonFileErrorAdapter, type JsonFileErrorOptions, type JsonFileErrorRecord, MongoDbErrorAdapter, type MongoDbErrorOptions, MySqlErrorAdapter, PostgresErrorAdapter, type ReadWriteFileSystemLike, RealtimeDatabaseErrorAdapter, type RealtimeDatabaseRefLike, type RedisClientLike, RedisErrorAdapter, type RedisErrorOptions, type S3BatchOptions, type S3ClientLike, S3ErrorAdapter, type S3ErrorOptions, type S3PutObjectInput, type SerializedErrorLogEntry, type SqlClientLike, type SqlDialect, type SqlErrorOptions, type SqliteClientLike, SqliteErrorAdapter, type SqliteErrorOptions, type StorageLike, type SupabaseClientLike, SupabaseErrorAdapter, type SupabaseErrorLike, type SupabaseErrorOptions, type SupabaseErrorRow, type SupabaseInsertResult, type SupabaseSetupOptions, WebStorageErrorAdapter, type WebStorageErrorOptions, type WebStorageErrorRecord, WebhookErrorAdapter, type WebhookErrorOptions, buildCreateErrorLogTableSql, buildErrorLogTableDdl, buildSupabaseSetupSql, createErrorLogStore, formatErrorLogLine, serializeCause, serializeEntry };
+/** What listeners receive: the serialized entry plus its UUID. */
+interface EventEmitterErrorRecord extends SerializedErrorLogEntry {
+    id: string;
+}
+/**
+ * The only thing this adapter needs from an emitter: `emit(eventName, payload)`.
+ * Node's `EventEmitter` and mitt-style emitters fit as they are. A browser
+ * `EventTarget` needs a one-line wrapper:
+ *
+ * ```ts
+ * const target = new EventTarget();
+ * const emitter: EmitterLike = {
+ *   emit: (name, payload) =>
+ *     target.dispatchEvent(new CustomEvent(name, { detail: payload })),
+ * };
+ * ```
+ */
+interface EmitterLike {
+    emit(eventName: string, payload: EventEmitterErrorRecord): unknown;
+}
+interface EventEmitterErrorOptions {
+    /**
+     * Name of the event to emit. Defaults to `error-log`. Avoid `error` on a Node
+     * `EventEmitter`: it throws when no listener is attached, and `log` would then
+     * return `ok: false`.
+     */
+    eventName?: string;
+    /**
+     * Treat an emit that reached nobody as a failure. Node's `EventEmitter.emit`
+     * returns `false` when there are no listeners; with this set to `true`, `log`
+     * then returns `ok: false` instead of letting the entry vanish. Emitters whose
+     * `emit` returns anything else (mitt, an `EventTarget` wrapper) cannot tell,
+     * so they always count as delivered. Defaults to `false`.
+     */
+    requireListener?: boolean;
+    /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
+    prefix?: string;
+}
+/**
+ * Emits each entry as an event on an emitter you own, for in-process hooks such
+ * as a toast, a metrics counter, or a test assertion. Listeners run
+ * synchronously inside `emit`, so a listener that throws makes `log` return
+ * `ok: false` with the listener's message; the application is not affected.
+ *
+ * ```ts
+ * const bus = new EventEmitter();
+ * bus.on('error-log', (record) => showToast(record.message));
+ * const adapter = new EventEmitterErrorAdapter(bus);
+ * ```
+ */
+declare class EventEmitterErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
+    private readonly emitter;
+    private readonly eventName;
+    private readonly requireListener;
+    private readonly prefix;
+    /** @throws {RangeError} if `options.eventName` is empty. */
+    constructor(emitter: EmitterLike, options?: EventEmitterErrorOptions);
+    log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
+}
+
+export { type CollectionLike, CompositeErrorAdapter, type CompositeErrorOptions, ConsoleErrorAdapter, type ConsoleErrorOptions, type EmitterLike, type ErrorLogAdapter, type ErrorLogEntry, type ErrorLogResult, EventEmitterErrorAdapter, type EventEmitterErrorOptions, type EventEmitterErrorRecord, type FileSystemLike, type FirebaseErrorOptions, type FirebaseErrorRecord, type FirestoreCollectionLike, FirestoreErrorAdapter, FlatFileErrorAdapter, type FlatFileErrorOptions, type IdbDatabaseLike, type IdbObjectStoreLike, type IdbRequestLike, type IdbTransactionLike, type IdbUpgradeDatabaseLike, IndexedDbErrorAdapter, type IndexedDbErrorOptions, type IndexedDbErrorRecord, JsonFileErrorAdapter, type JsonFileErrorOptions, type JsonFileErrorRecord, type LockManagerLike, MongoDbErrorAdapter, type MongoDbErrorOptions, MySqlErrorAdapter, PostgresErrorAdapter, type ReadWriteFileSystemLike, RealtimeDatabaseErrorAdapter, type RealtimeDatabaseRefLike, type RedisClientLike, RedisErrorAdapter, type RedisErrorOptions, type S3BatchOptions, type S3ClientLike, S3ErrorAdapter, type S3ErrorOptions, type S3PutObjectInput, type SerializedErrorLogEntry, type SqlClientLike, type SqlDialect, type SqlErrorOptions, type SqliteClientLike, SqliteErrorAdapter, type SqliteErrorOptions, type StorageLike, type SupabaseClientLike, SupabaseErrorAdapter, type SupabaseErrorLike, type SupabaseErrorOptions, type SupabaseErrorRow, type SupabaseInsertResult, type SupabaseSetupOptions, WebStorageErrorAdapter, type WebStorageErrorOptions, type WebStorageErrorRecord, WebhookErrorAdapter, type WebhookErrorOptions, buildCreateErrorLogTableSql, buildErrorLogTableDdl, buildMySqlWidenColumnsSql, buildSupabaseSetupSql, createErrorLogStore, formatErrorLogLine, serializeCause, serializeEntry };