@richardmcquiston01/error-log-adapter 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -88,4 +88,475 @@ declare class CompositeErrorAdapter<TCode extends string = string> implements Er
     log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
 }
 
-export { type CollectionLike, CompositeErrorAdapter, ConsoleErrorAdapter, type ConsoleErrorOptions, type ErrorLogAdapter, type ErrorLogEntry, type ErrorLogResult, MongoDbErrorAdapter, type MongoDbErrorOptions, type SerializedErrorLogEntry, WebhookErrorAdapter, type WebhookErrorOptions, serializeCause, serializeEntry };
+/** Event handler slot. Typed loosely so real DOM `IDBTransaction` objects fit. */
+type IdbHandler = ((event: never) => unknown) | null;
+/** The subset of an `IDBObjectStore` this adapter uses. */
+interface IdbObjectStoreLike {
+    add(value: unknown): unknown;
+}
+/** The subset of an `IDBTransaction` this adapter uses. */
+interface IdbTransactionLike {
+    objectStore(name: string): IdbObjectStoreLike;
+    oncomplete: IdbHandler;
+    onerror: IdbHandler;
+    onabort: IdbHandler;
+    readonly error?: {
+        message?: string;
+    } | null;
+}
+/** The subset of an `IDBDatabase` this adapter uses. */
+interface IdbDatabaseLike {
+    transaction(storeNames: string, mode: 'readwrite'): IdbTransactionLike;
+}
+/** The subset of an `IDBDatabase` available inside `onupgradeneeded`. */
+interface IdbUpgradeDatabaseLike {
+    readonly objectStoreNames: {
+        contains(name: string): boolean;
+    };
+    createObjectStore(name: string, options: {
+        keyPath: string;
+    }): {
+        createIndex(name: string, keyPath: string): unknown;
+    };
+}
+/** A stored record: the serialized entry plus its generated UUID key. */
+interface IndexedDbErrorRecord extends SerializedErrorLogEntry {
+    id: string;
+}
+interface IndexedDbErrorOptions {
+    /** Object store to write to. Defaults to `error_log`. */
+    storeName?: string;
+    /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
+    prefix?: string;
+}
+/**
+ * Creates the error log object store (UUID `id` key, `timestamp` index).
+ * Call it from your `onupgradeneeded` handler. Does nothing if it already exists.
+ */
+declare function createErrorLogStore(database: IdbUpgradeDatabaseLike, storeName?: string): void;
+declare class IndexedDbErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
+    private readonly database;
+    private readonly storeName;
+    private readonly prefix;
+    constructor(database: IdbDatabaseLike, options?: IndexedDbErrorOptions);
+    log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
+    /** Resolves once the transaction commits; rejects if it errors or aborts. */
+    private write;
+}
+
+/**
+ * The only thing this adapter needs from a SQLite driver: run one statement
+ * with positional (`?`) parameters. `bun:sqlite` already matches this shape.
+ * Other drivers need a one-line wrapper, for example:
+ *
+ * ```ts
+ * // better-sqlite3 or node:sqlite
+ * const client: SqliteClientLike = {
+ *   run: (sql, params) => db.prepare(sql).run(...params),
+ * };
+ * ```
+ */
+interface SqliteClientLike {
+    run(sql: string, params: unknown[]): unknown;
+}
+interface SqliteErrorOptions {
+    /** Table to write to. Defaults to `error_log`. Letters, digits and `_` only. */
+    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.
+ * Use this to run your own migration when `createTable` is disabled.
+ */
+declare function buildCreateErrorLogTableSql(tableName?: string): string[];
+declare class SqliteErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
+    private readonly client;
+    private readonly tableName;
+    private readonly createTable;
+    private readonly prefix;
+    private tableReady;
+    /** @throws {RangeError} if `options.tableName` is not a plain identifier. */
+    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;
+}
+
+/**
+ * The subset of the Web Storage API this adapter uses. Both `sessionStorage`
+ * and `localStorage` fit.
+ */
+interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+/** A stored record: the serialized entry plus its generated UUID. */
+interface WebStorageErrorRecord extends SerializedErrorLogEntry {
+    id: string;
+}
+interface WebStorageErrorOptions {
+    /** Key the entries are stored under, as one JSON array. Defaults to `error_log`. */
+    key?: string;
+    /** Most entries to keep. The oldest are dropped first. Defaults to `100`. */
+    maxEntries?: number;
+    /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
+    prefix?: string;
+}
+/**
+ * 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.
+ */
+declare class WebStorageErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
+    private readonly storage;
+    private readonly key;
+    private readonly maxEntries;
+    private readonly prefix;
+    /** @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. */
+    private append;
+    /** Returns the stored records, or none if the value is missing or unreadable. */
+    private readRecords;
+}
+
+/**
+ * The subset of `node:fs/promises` the file adapters use. Pass `fs.promises`
+ * (or `node:fs/promises`) yourself, or leave `fs` unset in Node and Bun.
+ */
+interface FileSystemLike {
+    appendFile(path: string, data: string): Promise<unknown>;
+    mkdir(path: string, options: {
+        recursive: true;
+    }): Promise<unknown>;
+    stat(path: string): Promise<{
+        size: number;
+    }>;
+    rename(from: string, to: string): Promise<unknown>;
+    rm(path: string, options: {
+        force: true;
+    }): Promise<unknown>;
+}
+/** `FileSystemLike` plus the reading and replacing that whole-file writes need. */
+interface ReadWriteFileSystemLike extends FileSystemLike {
+    readFile(path: string, encoding: 'utf8'): Promise<string>;
+    writeFile(path: string, data: string): Promise<unknown>;
+}
+
+interface FlatFileErrorOptions {
+    /** File system to write to. Defaults to `node:fs/promises`, loaded on first use. */
+    fs?: FileSystemLike;
+    /** Turns an entry into one line of text. Defaults to `formatErrorLogLine`. */
+    formatLine?: (entry: SerializedErrorLogEntry) => string;
+    /** Rotate the file before it would grow past this many bytes. Off by default. */
+    maxBytes?: number;
+    /** Rotated files to keep (`app.log.1` is newest). Defaults to `3`. Needs `maxBytes`. */
+    maxFiles?: number;
+    /** Create missing parent directories on first use. Defaults to `true`. */
+    createDirectory?: boolean;
+    /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
+    prefix?: string;
+}
+/**
+ * The default line format:
+ * `2026-01-02T03:04:05.000Z [CODE] source: message (cause: Error: details)`.
+ * `source` and `cause` are left out when the entry has none.
+ */
+declare function formatErrorLogLine(entry: SerializedErrorLogEntry): string;
+/**
+ * Appends one text line per entry to a file, optionally rotating it by size.
+ * Writes are queued, so concurrent `log` calls never interleave or race a rotation.
+ */
+declare class FlatFileErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
+    private readonly filePath;
+    private readonly formatLine;
+    private readonly maxBytes;
+    private readonly maxFiles;
+    private readonly createDirectory;
+    private readonly prefix;
+    private fs;
+    private directoryReady;
+    private queue;
+    /** @throws {RangeError} if `maxBytes` or `maxFiles` is not a positive integer. */
+    constructor(filePath: string, options?: FlatFileErrorOptions);
+    log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
+    private write;
+    /** Uses the injected file system, or loads `node:fs/promises` on first use. */
+    private getFileSystem;
+    private prepareDirectory;
+    /**
+     * Moves `app.log` to `app.log.1` (shifting older files up, dropping the
+     * oldest) when the next line would push it past `maxBytes`. A failed rotation
+     * is reported, but the entry is still written so it is not lost.
+     */
+    private rotateIfNeeded;
+    private renameIfPresent;
+}
+
+/** A stored record: the serialized entry plus its generated UUID. */
+interface JsonFileErrorRecord extends SerializedErrorLogEntry {
+    id: string;
+}
+interface JsonFileErrorOptions {
+    /**
+     * `ndjson` (default) appends one compact JSON object per line, which is cheap
+     * and safe to tail. `array` keeps the whole file as one JSON array that is
+     * rewritten on every entry.
+     */
+    mode?: 'ndjson' | 'array';
+    /** Array mode only: most entries to keep. The oldest are dropped first. */
+    maxEntries?: number;
+    /** Array mode only: spaces of indentation. Defaults to `2`; `0` is compact. */
+    indent?: number;
+    /** File system to write to. Defaults to `node:fs/promises`, loaded on first use. */
+    fs?: ReadWriteFileSystemLike;
+    /** Create missing parent directories on first use. Defaults to `true`. */
+    createDirectory?: boolean;
+    /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
+    prefix?: string;
+}
+/**
+ * Stores entries as JSON in a file (Node and Bun), either as newline-delimited
+ * JSON or as one array. Writes are queued, so concurrent `log` calls stay in
+ * order. Only one process should write to a given file.
+ */
+declare class JsonFileErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
+    private readonly filePath;
+    private readonly mode;
+    private readonly maxEntries;
+    private readonly indent;
+    private readonly createDirectory;
+    private readonly prefix;
+    private fs;
+    private directoryReady;
+    private 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>;
+    private write;
+    private getFileSystem;
+    private prepareDirectory;
+    /**
+     * Adds the record to the array and replaces the file. The new content is
+     * written to a temporary file first and renamed into place, so a crash
+     * mid-write cannot leave a half-written file.
+     */
+    private rewriteArray;
+    /**
+     * Returns the records already in the file. A missing or empty file has none.
+     * A file that is not a JSON array is moved to `<path>.corrupt` (so nothing is
+     * lost) and logging continues with a fresh file.
+     */
+    private readRecords;
+}
+
+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.
+ */
+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;
+}
+
+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, MySqlErrorAdapter, PostgresErrorAdapter, type ReadWriteFileSystemLike, 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, WebStorageErrorAdapter, type WebStorageErrorOptions, type WebStorageErrorRecord, WebhookErrorAdapter, type WebhookErrorOptions, buildCreateErrorLogTableSql, buildErrorLogTableDdl, createErrorLogStore, formatErrorLogLine, serializeCause, serializeEntry };