@richardmcquiston01/error-log-adapter 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -355,4 +355,376 @@ declare class JsonFileErrorAdapter<TCode extends string = string> implements Err
     private readRecords;
 }
 
-export { type CollectionLike, CompositeErrorAdapter, ConsoleErrorAdapter, type ConsoleErrorOptions, type ErrorLogAdapter, type ErrorLogEntry, type ErrorLogResult, type FileSystemLike, FlatFileErrorAdapter, type FlatFileErrorOptions, type IdbDatabaseLike, type IdbObjectStoreLike, type IdbTransactionLike, type IdbUpgradeDatabaseLike, IndexedDbErrorAdapter, type IndexedDbErrorOptions, type IndexedDbErrorRecord, JsonFileErrorAdapter, type JsonFileErrorOptions, type JsonFileErrorRecord, MongoDbErrorAdapter, type MongoDbErrorOptions, type ReadWriteFileSystemLike, type SerializedErrorLogEntry, type SqliteClientLike, SqliteErrorAdapter, type SqliteErrorOptions, type StorageLike, WebStorageErrorAdapter, type WebStorageErrorOptions, type WebStorageErrorRecord, WebhookErrorAdapter, type WebhookErrorOptions, buildCreateErrorLogTableSql, createErrorLogStore, formatErrorLogLine, serializeCause, serializeEntry };
+type SqlDialect = 'postgres' | 'mysql';
+/**
+ * The only thing these adapters need from a database driver: run one
+ * parameterized statement. `pg` (`Pool` / `Client`) and `mysql2/promise`
+ * (`Pool` / `Connection`) both fit as they are.
+ */
+interface SqlClientLike {
+    query(sql: string, params: unknown[]): Promise<unknown>;
+}
+interface SqlErrorOptions {
+    /** Table to write to. Defaults to `error_log`. Letters, digits and `_` only, up to 47 characters. */
+    tableName?: string;
+    /** Create the table (and index) on first use. Defaults to `true`. */
+    createTable?: boolean;
+    /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
+    prefix?: string;
+}
+/**
+ * Returns the statements that create the error log table and its index for a
+ * dialect. Use this to run your own migration when `createTable` is disabled.
+ *
+ * Postgres gets a native `UUID` key, `JSONB` for the cause, and `TIMESTAMPTZ`
+ * columns. MySQL gets a `CHAR(36)` UUID key (it has no UUID type), a `JSON`
+ * cause, and `DATETIME(3)` columns holding UTC times.
+ */
+declare function buildErrorLogTableDdl(dialect: SqlDialect, 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;
+    private readonly dialect;
+    private readonly adapterName;
+    private readonly tableName;
+    private readonly createTable;
+    private readonly prefix;
+    private tableReady;
+    protected constructor(client: SqlClientLike, dialect: SqlDialect, adapterName: string, options: SqlErrorOptions);
+    log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
+    private insertSql;
+    /** Creates the table once. A failed attempt is retried on the next log call. */
+    private ensureTable;
+    private runCreateStatements;
+}
+/**
+ * Writes entries to Postgres. Pass a `pg` `Pool` or `Client`.
+ *
+ * ```ts
+ * const adapter = new PostgresErrorAdapter(new Pool({ connectionString }));
+ * ```
+ */
+declare class PostgresErrorAdapter<TCode extends string = string> extends SqlErrorAdapter<TCode> {
+    /** @throws {RangeError} if `options.tableName` is not a plain identifier of 47 characters or fewer. */
+    constructor(client: SqlClientLike, options?: SqlErrorOptions);
+}
+/**
+ * Writes entries to MySQL or MariaDB. Pass a `mysql2/promise` `Pool` or `Connection`.
+ *
+ * ```ts
+ * const adapter = new MySqlErrorAdapter(mysql.createPool(connectionUri));
+ * ```
+ */
+declare class MySqlErrorAdapter<TCode extends string = string> extends SqlErrorAdapter<TCode> {
+    /** @throws {RangeError} if `options.tableName` is not a plain identifier of 47 characters or fewer. */
+    constructor(client: SqlClientLike, options?: SqlErrorOptions);
+}
+
+/**
+ * The only thing this adapter needs from a Redis client: send one raw command
+ * as an array of strings. node-redis (`client.sendCommand`) already matches.
+ * ioredis needs a one-line wrapper:
+ *
+ * ```ts
+ * const client: RedisClientLike = {
+ *   sendCommand: (args) => redis.call(args[0] as string, ...args.slice(1)),
+ * };
+ * ```
+ */
+interface RedisClientLike {
+    sendCommand(args: string[]): Promise<unknown>;
+}
+interface RedisErrorOptions {
+    /**
+     * `list` (default) pushes each entry onto a Redis list as one JSON string.
+     * `stream` appends each entry to a Redis stream (`XADD`) as separate fields.
+     */
+    mode?: 'list' | 'stream';
+    /** Key to write to. Defaults to `error_log`. */
+    key?: string;
+    /**
+     * Most entries to keep. The oldest are dropped first. Unlimited by default.
+     * Lists are trimmed with `LTRIM` after the push; streams use an exact `MAXLEN`.
+     */
+    maxEntries?: number;
+    /**
+     * List mode only: which end to push onto. `right` (default, `RPUSH`) keeps
+     * the newest entry last; `left` (`LPUSH`) keeps the newest entry first.
+     */
+    side?: 'left' | 'right';
+    /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
+    prefix?: string;
+}
+/**
+ * Writes entries to Redis, either as a capped list of JSON strings or as a
+ * stream. Each record holds a UUID `id` plus the serialized entry. In stream
+ * mode `cause` and `source` fields are left out when the entry has none.
+ */
+declare class RedisErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
+    private readonly client;
+    private readonly mode;
+    private readonly key;
+    private readonly maxEntries;
+    private readonly side;
+    private readonly prefix;
+    /** @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>;
+    private buildStreamCommand;
+    /**
+     * Drops the oldest list entries beyond `maxEntries`. The entry is already
+     * stored by now, so a trim failure is reported but does not fail the call;
+     * the next successful write trims the list again.
+     */
+    private trimList;
+}
+
+/** The parameters this adapter passes to `putObject`. */
+interface S3PutObjectInput {
+    Bucket: string;
+    Key: string;
+    Body: string;
+    ContentType: string;
+}
+/**
+ * The only thing this adapter needs from an S3 client: `putObject`. The AWS
+ * SDK v3 aggregated client (`new S3({ ... })` from `@aws-sdk/client-s3`) fits as
+ * it is, and so does anything else that follows the S3 API, including
+ * DigitalOcean Spaces, Cloudflare R2 and MinIO when you point the client at
+ * their endpoint.
+ *
+ * Some S3-compatible providers reject the checksum headers that recent AWS SDK
+ * v3 versions add by default. If uploads fail with a checksum or header error,
+ * create the client with `requestChecksumCalculation: 'WHEN_REQUIRED'` and
+ * `responseChecksumValidation: 'WHEN_REQUIRED'`.
+ */
+interface S3ClientLike {
+    putObject(input: S3PutObjectInput): Promise<unknown>;
+}
+interface S3BatchOptions {
+    /** Upload once this many entries are buffered. */
+    batchSize: number;
+    /**
+     * Also upload when the oldest buffered entry has waited this long (ms). The
+     * timer does not keep the process alive, so call `flush()` before exiting.
+     */
+    maxWaitMs?: number;
+}
+interface S3ErrorOptions {
+    /**
+     * Key prefix, for example `logs/app/`. A trailing slash is added if missing.
+     * Defaults to `error_log/`. Use `''` for no prefix.
+     */
+    keyPrefix?: string;
+    /**
+     * Content type of the uploaded objects. Defaults to `application/json`, or
+     * `application/x-ndjson` when batching.
+     */
+    contentType?: string;
+    /**
+     * Buffer entries and upload them together as one newline-delimited JSON
+     * object. Off by default: one object per entry.
+     */
+    batch?: S3BatchOptions;
+    /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
+    prefix?: string;
+}
+/**
+ * Stores entries as objects in an S3-compatible bucket, keyed by date and UUID:
+ * `error_log/2026/01/02/20260102T030405678Z-<uuid>.json`.
+ *
+ * By default each entry becomes its own JSON object and `log` resolves once the
+ * upload succeeds. With `batch`, entries are buffered and uploaded together as
+ * one `.ndjson` object; `log` then resolves ok as soon as the entry is
+ * buffered (it is not stored yet), except for the call that fills the batch,
+ * which resolves with the upload result. Call `flush()` before shutting down.
+ */
+declare class S3ErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
+    private readonly client;
+    private readonly bucket;
+    private readonly keyPrefix;
+    private readonly contentType;
+    private readonly batch;
+    private readonly logPrefix;
+    private buffer;
+    private timer;
+    private 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>;
+    /**
+     * Uploads any buffered entries now. Resolves ok when nothing is buffered.
+     * Entries from a failed upload stay buffered and are retried by the next flush.
+     */
+    flush(): Promise<ErrorLogResult>;
+    private addToBatch;
+    private scheduleFlush;
+    private uploadBuffered;
+    private upload;
+    private fail;
+}
+
+/** The fields stored for each entry, in Firestore and in the Realtime Database. */
+interface FirebaseErrorRecord {
+    /** UUID. In Firestore it is also the document id. */
+    id: string;
+    code: string;
+    message: string;
+    /** ISO 8601 timestamp of the entry. */
+    timestamp: string;
+    source?: string;
+    /**
+     * The entry's cause as a JSON string. Plain text avoids Firestore's limits on
+     * custom objects and nested arrays, and the Realtime Database's limits on key
+     * characters, so an odd cause can never make the write fail.
+     */
+    cause?: string;
+}
+/**
+ * The only thing the Firestore adapter needs from a collection: `doc(id).set(data)`.
+ * A `firebase-admin` collection (`getFirestore().collection('error_log')`) fits
+ * as it is. With the web SDK, wrap it:
+ *
+ * ```ts
+ * const collectionLike: FirestoreCollectionLike = {
+ *   doc: (id) => ({ set: (data) => setDoc(doc(db, 'error_log', id), data) }),
+ * };
+ * ```
+ */
+interface FirestoreCollectionLike {
+    doc(documentId: string): {
+        set(data: FirebaseErrorRecord): Promise<unknown>;
+    };
+}
+/**
+ * The only thing the Realtime Database adapter needs from a reference:
+ * `push(value)`, which resolves once the write is saved. A `firebase-admin`
+ * reference (`getDatabase().ref('error_log')`) fits as it is. With the web SDK, wrap it:
+ *
+ * ```ts
+ * const refLike: RealtimeDatabaseRefLike = {
+ *   push: (value) => push(ref(db, 'error_log'), value),
+ * };
+ * ```
+ */
+interface RealtimeDatabaseRefLike {
+    push(value: FirebaseErrorRecord): PromiseLike<unknown>;
+}
+interface FirebaseErrorOptions {
+    /**
+     * How long `log` waits for the write to be saved before giving up, in
+     * milliseconds. Defaults to 10000. Pass `Infinity` to wait without limit.
+     *
+     * 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.
+     */
+    timeoutMs?: number;
+    /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
+    prefix?: string;
+}
+/**
+ * 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.
+ */
+declare class FirestoreErrorAdapter<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: FirestoreCollectionLike, options?: FirebaseErrorOptions);
+    log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
+}
+/**
+ * Writes each entry under a Realtime Database reference with `push`, which
+ * generates a chronologically ordered key.
+ */
+declare class RealtimeDatabaseErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
+    private readonly reference;
+    private readonly prefix;
+    private readonly timeoutMs;
+    /** @throws {RangeError} if `options.timeoutMs` is not a positive number or `Infinity`. */
+    constructor(reference: RealtimeDatabaseRefLike, options?: FirebaseErrorOptions);
+    log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
+}
+
+/** The row inserted for each entry. The columns match the Postgres adapter's table. */
+interface SupabaseErrorRow {
+    /** UUID primary key. */
+    id: string;
+    code: string;
+    message: string;
+    /** The cause as JSON, or `null` when the entry has none. */
+    cause: unknown;
+    source: string | null;
+    /** ISO 8601 timestamp of the entry. */
+    occurred_at: string;
+}
+/** The error object `supabase-js` returns (a `PostgrestError`) instead of throwing. */
+interface SupabaseErrorLike {
+    message: string;
+    code?: string;
+    details?: string | null;
+    hint?: string | null;
+}
+/** What `insert` resolves to. The status fields are used when the error has no message. */
+interface SupabaseInsertResult {
+    error: SupabaseErrorLike | null;
+    status?: number;
+    statusText?: string;
+}
+/**
+ * The only thing the Supabase adapter needs from a client: `from(table).insert(row)`.
+ * A `supabase-js` client (`createClient(url, key)`) fits as it is.
+ */
+interface SupabaseClientLike {
+    from(table: string): {
+        insert(row: SupabaseErrorRow): PromiseLike<SupabaseInsertResult>;
+    };
+}
+interface SupabaseErrorOptions {
+    /** Table to write to. Defaults to `error_log`. */
+    tableName?: string;
+    /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
+    prefix?: string;
+}
+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.
+     */
+    insertRoles?: string[];
+}
+/**
+ * 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.
+ *
+ * @throws {RangeError} if the table name or a role is not a plain identifier.
+ */
+declare function buildSupabaseSetupSql(tableName?: string, options?: SupabaseSetupOptions): string[];
+/**
+ * Writes entries to a Supabase table through `supabase-js`. Create the table
+ * first with `buildSupabaseSetupSql` (or `buildErrorLogTableDdl('postgres')`).
+ *
+ * ```ts
+ * const adapter = new SupabaseErrorAdapter(createClient(url, serviceRoleKey));
+ * ```
+ *
+ * `supabase-js` reports failures in a returned `error` field rather than
+ * throwing; the adapter turns both that and a thrown error into `{ ok: false }`.
+ */
+declare class SupabaseErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
+    private readonly client;
+    private readonly tableName;
+    private readonly prefix;
+    /** @throws {RangeError} if `options.tableName` is empty. */
+    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 };