@richardmcquiston01/error-log-adapter 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,358 @@
+/** A single error to be routed to a sink. */
+interface ErrorLogEntry<TCode extends string = string> {
+    /** Machine-readable error code, e.g. `ADAPTER_ERROR`. */
+    code: TCode;
+    /** Human-readable description of what went wrong. */
+    message: string;
+    /** The underlying error or value that caused this entry. */
+    cause?: unknown;
+    /** Name of the application or module that raised the error. */
+    source?: string;
+    /** ISO 8601 timestamp. Adapters fill this in when it is omitted. */
+    timestamp?: string;
+}
+/** Outcome of a `log` call. Callers should check `ok`. */
+interface ErrorLogResult {
+    ok: boolean;
+    /** Description of the failure when `ok` is false. */
+    error?: string;
+}
+/**
+ * A sink for runtime errors. Implementations must never throw or reject:
+ * any failure is reported through the returned `ErrorLogResult`.
+ */
+interface ErrorLogAdapter<TCode extends string = string> {
+    log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
+}
+
+/** A JSON-safe copy of an `ErrorLogEntry`. */
+interface SerializedErrorLogEntry {
+    code: string;
+    message: string;
+    cause?: unknown;
+    source?: string;
+    timestamp: string;
+}
+/**
+ * Converts `Error` instances into plain objects, since `JSON.stringify`
+ * renders them as `{}`. Other values are returned unchanged.
+ */
+declare function serializeCause(cause: unknown): unknown;
+/** Returns a JSON-safe copy of the entry, adding a timestamp if missing. */
+declare function serializeEntry(entry: ErrorLogEntry): SerializedErrorLogEntry;
+
+interface ConsoleErrorOptions {
+    /** Text printed before each entry. Defaults to `[error-log-adapter]`. */
+    prefix?: string;
+}
+declare class ConsoleErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
+    private readonly prefix;
+    constructor(options?: ConsoleErrorOptions);
+    log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
+}
+
+interface WebhookErrorOptions {
+    /** Extra headers merged into the request. */
+    headers?: Record<string, string>;
+    /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
+    prefix?: string;
+}
+declare class WebhookErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
+    private readonly url;
+    private readonly options;
+    private readonly prefix;
+    constructor(url: string, options?: WebhookErrorOptions);
+    log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
+    private fail;
+}
+
+/** The subset of a MongoDB `Collection` this adapter uses. */
+interface CollectionLike {
+    insertOne(doc: object): Promise<unknown>;
+}
+interface MongoDbErrorOptions {
+    /** Text printed before failure messages. Defaults to `[error-log-adapter]`. */
+    prefix?: string;
+}
+declare class MongoDbErrorAdapter<TCode extends string = string> implements ErrorLogAdapter<TCode> {
+    private readonly collection;
+    private readonly prefix;
+    constructor(collection: CollectionLike, options?: MongoDbErrorOptions);
+    log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
+}
+
+/** 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>>);
+    log(entry: ErrorLogEntry<TCode>): Promise<ErrorLogResult>;
+}
+
+/** 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;
+}
+
+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 };