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

package/dist/index.mjs

@@ -0,0 +1,647 @@
+// src/serialize.ts
+function serializeCause(cause) {
+  if (cause instanceof Error) {
+    return { name: cause.name, message: cause.message, stack: cause.stack };
+  }
+  return cause;
+}
+function serializeEntry(entry) {
+  const serialized = {
+    code: entry.code,
+    message: entry.message,
+    timestamp: entry.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
+  };
+  if (entry.cause !== void 0) {
+    serialized.cause = serializeCause(entry.cause);
+  }
+  if (entry.source !== void 0) {
+    serialized.source = entry.source;
+  }
+  return serialized;
+}
+function describeError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/adapters/console-error-adapter.ts
+var ConsoleErrorAdapter = class {
+  constructor(options = {}) {
+    this.prefix = options.prefix ?? "[error-log-adapter]";
+  }
+  async log(entry) {
+    try {
+      console.error(this.prefix, entry);
+      return { ok: true };
+    } catch (error) {
+      return {
+        ok: false,
+        error: `ConsoleErrorAdapter failed: ${String(error)}`
+      };
+    }
+  }
+};
+
+// src/adapters/webhook-error-adapter.ts
+var WebhookErrorAdapter = class {
+  constructor(url, options = {}) {
+    this.url = url;
+    this.options = options;
+    this.prefix = options.prefix ?? "[error-log-adapter]";
+  }
+  async log(entry) {
+    try {
+      const response = await fetch(this.url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...this.options.headers
+        },
+        body: JSON.stringify(serializeEntry(entry))
+      });
+      if (!response.ok) {
+        return this.fail(
+          `webhook ${this.url} responded with HTTP ${response.status}`
+        );
+      }
+      return { ok: true };
+    } catch (error) {
+      console.error(`${this.prefix} WebhookErrorAdapter:`, error);
+      return this.fail(
+        `could not reach webhook ${this.url}: ${describeError(error)}`
+      );
+    }
+  }
+  fail(reason) {
+    return { ok: false, error: `WebhookErrorAdapter failed: ${reason}` };
+  }
+};
+
+// src/adapters/mongodb-error-adapter.ts
+var MongoDbErrorAdapter = class {
+  constructor(collection, options = {}) {
+    this.collection = collection;
+    this.prefix = options.prefix ?? "[error-log-adapter]";
+  }
+  async log(entry) {
+    try {
+      await this.collection.insertOne(serializeEntry(entry));
+      return { ok: true };
+    } catch (error) {
+      console.error(`${this.prefix} MongoDbErrorAdapter:`, error);
+      return {
+        ok: false,
+        error: `MongoDbErrorAdapter failed to insert entry: ${describeError(error)}`
+      };
+    }
+  }
+};
+
+// src/adapters/composite-error-adapter.ts
+var CompositeErrorAdapter = class {
+  constructor(adapters) {
+    this.adapters = adapters;
+  }
+  async log(entry) {
+    const results = await Promise.all(
+      this.adapters.map(
+        async (adapter) => {
+          try {
+            return await adapter.log(entry);
+          } catch (error) {
+            return {
+              ok: false,
+              error: `adapter threw instead of returning a result: ${String(error)}`
+            };
+          }
+        }
+      )
+    );
+    const failures = results.flatMap(
+      (result) => result.ok ? [] : [result.error ?? "unknown failure"]
+    );
+    if (failures.length === 0) {
+      return { ok: true };
+    }
+    return {
+      ok: false,
+      error: `${failures.length} of ${results.length} adapters failed: ${failures.join("; ")}`
+    };
+  }
+};
+
+// src/adapters/indexeddb-error-adapter.ts
+var DEFAULT_STORE_NAME = "error_log";
+function createErrorLogStore(database, storeName = DEFAULT_STORE_NAME) {
+  if (database.objectStoreNames.contains(storeName)) {
+    return;
+  }
+  database.createObjectStore(storeName, { keyPath: "id" }).createIndex("timestamp", "timestamp");
+}
+var IndexedDbErrorAdapter = class {
+  constructor(database, options = {}) {
+    this.database = database;
+    this.storeName = options.storeName ?? DEFAULT_STORE_NAME;
+    this.prefix = options.prefix ?? "[error-log-adapter]";
+  }
+  async log(entry) {
+    try {
+      const record = {
+        id: crypto.randomUUID(),
+        ...serializeEntry(entry)
+      };
+      await this.write(record);
+      return { ok: true };
+    } catch (error) {
+      console.error(`${this.prefix} IndexedDbErrorAdapter:`, error);
+      return {
+        ok: false,
+        error: `IndexedDbErrorAdapter failed to write to object store "${this.storeName}": ${describeError(error)}`
+      };
+    }
+  }
+  /** Resolves once the transaction commits; rejects if it errors or aborts. */
+  write(record) {
+    return new Promise(
+      (resolve, reject) => {
+        const transaction = this.database.transaction(
+          this.storeName,
+          "readwrite"
+        );
+        const fail = (action) => () => reject(
+          new Error(
+            `transaction ${action}: ${transaction.error?.message ?? "no details provided"}`
+          )
+        );
+        transaction.oncomplete = () => resolve();
+        transaction.onerror = fail("failed");
+        transaction.onabort = fail("aborted");
+        transaction.objectStore(this.storeName).add(record);
+      }
+    );
+  }
+};
+
+// src/adapters/sqlite-error-adapter.ts
+var DEFAULT_TABLE_NAME = "error_log";
+var IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function assertValidTableName(tableName) {
+  if (!IDENTIFIER_PATTERN.test(tableName)) {
+    throw new RangeError(
+      `SqliteErrorAdapter: invalid table name "${tableName}". Use only letters, digits and underscores, and do not start with a digit.`
+    );
+  }
+}
+function buildCreateErrorLogTableSql(tableName = DEFAULT_TABLE_NAME) {
+  assertValidTableName(tableName);
+  return [
+    `CREATE TABLE IF NOT EXISTS ${tableName} (id TEXT PRIMARY KEY NOT NULL, code TEXT NOT NULL, message TEXT NOT NULL, cause TEXT, source TEXT, occurred_at TEXT NOT NULL, created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')))`,
+    `CREATE INDEX IF NOT EXISTS ${tableName}_occurred_at_idx ON ${tableName} (occurred_at)`
+  ];
+}
+var SqliteErrorAdapter = class {
+  /** @throws {RangeError} if `options.tableName` is not a plain identifier. */
+  constructor(client, options = {}) {
+    this.client = client;
+    this.tableReady = null;
+    this.tableName = options.tableName ?? DEFAULT_TABLE_NAME;
+    assertValidTableName(this.tableName);
+    this.createTable = options.createTable ?? true;
+    this.prefix = options.prefix ?? "[error-log-adapter]";
+  }
+  async log(entry) {
+    try {
+      await this.ensureTable();
+      const serialized = serializeEntry(entry);
+      await this.client.run(
+        `INSERT INTO ${this.tableName} (id, code, message, cause, source, occurred_at) VALUES (?, ?, ?, ?, ?, ?)`,
+        [
+          crypto.randomUUID(),
+          serialized.code,
+          serialized.message,
+          serialized.cause === void 0 ? null : JSON.stringify(serialized.cause),
+          serialized.source ?? null,
+          serialized.timestamp
+        ]
+      );
+      return { ok: true };
+    } catch (error) {
+      console.error(`${this.prefix} SqliteErrorAdapter:`, error);
+      return {
+        ok: false,
+        error: `SqliteErrorAdapter failed to write to table "${this.tableName}": ${describeError(error)}`
+      };
+    }
+  }
+  /** Creates the table once. A failed attempt is retried on the next log call. */
+  ensureTable() {
+    if (!this.createTable) {
+      return Promise.resolve();
+    }
+    if (this.tableReady === null) {
+      this.tableReady = this.runCreateStatements().catch(
+        (error) => {
+          this.tableReady = null;
+          throw error;
+        }
+      );
+    }
+    return this.tableReady;
+  }
+  async runCreateStatements() {
+    for (const sql of buildCreateErrorLogTableSql(this.tableName)) {
+      await this.client.run(sql, []);
+    }
+  }
+};
+
+// src/adapters/web-storage-error-adapter.ts
+var DEFAULT_STORAGE_KEY = "error_log";
+var DEFAULT_MAX_ENTRIES = 100;
+function isQuotaError(error) {
+  if (typeof error !== "object" || error === null) {
+    return false;
+  }
+  const { name, code } = error;
+  return typeof name === "string" && name.toLowerCase().includes("quota") || code === 22 || code === 1014;
+}
+var WebStorageErrorAdapter = class {
+  /** @throws {RangeError} if `options.maxEntries` is not a positive integer. */
+  constructor(storage, options = {}) {
+    this.storage = storage;
+    this.key = options.key ?? DEFAULT_STORAGE_KEY;
+    this.maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    this.prefix = options.prefix ?? "[error-log-adapter]";
+    if (!Number.isInteger(this.maxEntries) || this.maxEntries < 1) {
+      throw new RangeError(
+        `WebStorageErrorAdapter: maxEntries must be a positive integer, received ${String(options.maxEntries)}.`
+      );
+    }
+  }
+  async log(entry) {
+    try {
+      const record = {
+        id: crypto.randomUUID(),
+        ...serializeEntry(entry)
+      };
+      this.append(record);
+      return { ok: true };
+    } catch (error) {
+      console.error(`${this.prefix} WebStorageErrorAdapter:`, error);
+      return {
+        ok: false,
+        error: `WebStorageErrorAdapter failed to write to storage key "${this.key}": ${describeError(error)}`
+      };
+    }
+  }
+  /** Reads, appends, trims, and writes back. Runs without awaiting, so calls never interleave. */
+  append(record) {
+    const records = [
+      ...this.readRecords(),
+      record
+    ].slice(-this.maxEntries);
+    for (; ; ) {
+      try {
+        this.storage.setItem(this.key, JSON.stringify(records));
+        return;
+      } catch (error) {
+        if (!isQuotaError(error) || records.length <= 1) {
+          throw error;
+        }
+        records.shift();
+      }
+    }
+  }
+  /** Returns the stored records, or none if the value is missing or unreadable. */
+  readRecords() {
+    const stored = this.storage.getItem(this.key);
+    if (stored === null) {
+      return [];
+    }
+    try {
+      const parsed = JSON.parse(stored);
+      if (Array.isArray(parsed)) {
+        return parsed;
+      }
+      console.error(
+        `${this.prefix} WebStorageErrorAdapter: storage key "${this.key}" did not hold an array, so it was replaced.`
+      );
+    } catch (error) {
+      console.error(
+        `${this.prefix} WebStorageErrorAdapter: storage key "${this.key}" held invalid JSON (${describeError(error)}), so it was replaced.`
+      );
+    }
+    return [];
+  }
+};
+
+// src/file-system.ts
+async function loadNodeFileSystem() {
+  const moduleName = "node:fs/promises";
+  return await import(moduleName);
+}
+function parentDirectory(filePath) {
+  const lastSeparator = Math.max(
+    filePath.lastIndexOf("/"),
+    filePath.lastIndexOf("\\")
+  );
+  if (lastSeparator < 0) {
+    return null;
+  }
+  return lastSeparator === 0 ? "/" : filePath.slice(0, lastSeparator);
+}
+function isMissingFileError(error) {
+  return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
+
+// src/adapters/flat-file-error-adapter.ts
+var DEFAULT_MAX_FILES = 3;
+function escapeLineBreaks(text) {
+  return text.replace(/\r?\n/g, "\\n");
+}
+function describeCause(cause) {
+  if (typeof cause === "string") {
+    return cause;
+  }
+  if (typeof cause === "object" && cause !== null) {
+    const { name, message } = cause;
+    if (typeof name === "string" && typeof message === "string") {
+      return `${name}: ${message}`;
+    }
+  }
+  try {
+    return JSON.stringify(cause) ?? String(cause);
+  } catch {
+    return String(cause);
+  }
+}
+function formatErrorLogLine(entry) {
+  const source = entry.source === void 0 ? "" : `${entry.source}: `;
+  const cause = entry.cause === void 0 ? "" : ` (cause: ${describeCause(entry.cause)})`;
+  return escapeLineBreaks(
+    `${entry.timestamp} [${entry.code}] ${source}${entry.message}${cause}`
+  );
+}
+function assertPositiveInteger(value, name) {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new RangeError(
+      `FlatFileErrorAdapter: ${name} must be a positive integer, received ${String(value)}.`
+    );
+  }
+}
+var FlatFileErrorAdapter = class {
+  /** @throws {RangeError} if `maxBytes` or `maxFiles` is not a positive integer. */
+  constructor(filePath, options = {}) {
+    this.filePath = filePath;
+    this.directoryReady = false;
+    this.queue = Promise.resolve();
+    this.fs = options.fs;
+    this.formatLine = options.formatLine ?? formatErrorLogLine;
+    this.maxBytes = options.maxBytes;
+    this.maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
+    this.createDirectory = options.createDirectory ?? true;
+    this.prefix = options.prefix ?? "[error-log-adapter]";
+    if (this.maxBytes !== void 0) {
+      assertPositiveInteger(this.maxBytes, "maxBytes");
+    }
+    assertPositiveInteger(this.maxFiles, "maxFiles");
+  }
+  log(entry) {
+    const result = this.queue.then(
+      () => this.write(entry)
+    );
+    this.queue = result.catch(() => void 0);
+    return result;
+  }
+  async write(entry) {
+    try {
+      const fs = await this.getFileSystem();
+      const formatted = this.formatLine(serializeEntry(entry));
+      const line = formatted.endsWith("\n") ? formatted : `${formatted}
+`;
+      await this.prepareDirectory(fs);
+      await this.rotateIfNeeded(fs, new TextEncoder().encode(line).length);
+      await fs.appendFile(this.filePath, line);
+      return { ok: true };
+    } catch (error) {
+      console.error(`${this.prefix} FlatFileErrorAdapter:`, error);
+      return {
+        ok: false,
+        error: `FlatFileErrorAdapter failed to append to "${this.filePath}": ${describeError(error)}`
+      };
+    }
+  }
+  /** Uses the injected file system, or loads `node:fs/promises` on first use. */
+  async getFileSystem() {
+    if (this.fs === void 0) {
+      this.fs = await loadNodeFileSystem();
+    }
+    return this.fs;
+  }
+  async prepareDirectory(fs) {
+    if (!this.createDirectory || this.directoryReady) {
+      return;
+    }
+    const directory = parentDirectory(this.filePath);
+    if (directory !== null) {
+      await fs.mkdir(directory, { recursive: true });
+    }
+    this.directoryReady = true;
+  }
+  /**
+   * 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.
+   */
+  async rotateIfNeeded(fs, lineBytes) {
+    if (this.maxBytes === void 0) {
+      return;
+    }
+    try {
+      let currentSize;
+      try {
+        currentSize = (await fs.stat(this.filePath)).size;
+      } catch (error) {
+        if (isMissingFileError(error)) {
+          return;
+        }
+        throw error;
+      }
+      if (currentSize === 0 || currentSize + lineBytes <= this.maxBytes) {
+        return;
+      }
+      await fs.rm(`${this.filePath}.${this.maxFiles}`, { force: true });
+      for (let index = this.maxFiles - 1; index >= 1; index -= 1) {
+        await this.renameIfPresent(
+          fs,
+          `${this.filePath}.${index}`,
+          `${this.filePath}.${index + 1}`
+        );
+      }
+      await fs.rename(this.filePath, `${this.filePath}.1`);
+    } catch (error) {
+      console.error(
+        `${this.prefix} FlatFileErrorAdapter: could not rotate "${this.filePath}", so it will keep growing: ${describeError(error)}`
+      );
+    }
+  }
+  async renameIfPresent(fs, from, to) {
+    try {
+      await fs.rename(from, to);
+    } catch (error) {
+      if (!isMissingFileError(error)) {
+        throw error;
+      }
+    }
+  }
+};
+
+// src/adapters/json-file-error-adapter.ts
+var DEFAULT_INDENT = 2;
+var JsonFileErrorAdapter = class {
+  /** @throws {RangeError} if `maxEntries` or `indent` is invalid, or `maxEntries` is used outside array mode. */
+  constructor(filePath, options = {}) {
+    this.filePath = filePath;
+    this.directoryReady = false;
+    this.queue = Promise.resolve();
+    this.mode = options.mode ?? "ndjson";
+    this.maxEntries = options.maxEntries;
+    this.indent = options.indent ?? DEFAULT_INDENT;
+    this.fs = options.fs;
+    this.createDirectory = options.createDirectory ?? true;
+    this.prefix = options.prefix ?? "[error-log-adapter]";
+    if (this.maxEntries !== void 0) {
+      if (this.mode !== "array") {
+        throw new RangeError(
+          `JsonFileErrorAdapter: maxEntries only applies to mode "array", but mode is "${this.mode}". Use mode "array" or remove maxEntries.`
+        );
+      }
+      if (!Number.isInteger(this.maxEntries) || this.maxEntries < 1) {
+        throw new RangeError(
+          `JsonFileErrorAdapter: maxEntries must be a positive integer, received ${String(this.maxEntries)}.`
+        );
+      }
+    }
+    if (!Number.isInteger(this.indent) || this.indent < 0) {
+      throw new RangeError(
+        `JsonFileErrorAdapter: indent must be a non-negative integer, received ${String(this.indent)}.`
+      );
+    }
+  }
+  log(entry) {
+    const result = this.queue.then(
+      () => this.write(entry)
+    );
+    this.queue = result.catch(() => void 0);
+    return result;
+  }
+  async write(entry) {
+    try {
+      const record = {
+        id: crypto.randomUUID(),
+        ...serializeEntry(entry)
+      };
+      const fs = await this.getFileSystem();
+      await this.prepareDirectory(fs);
+      if (this.mode === "ndjson") {
+        await fs.appendFile(this.filePath, `${JSON.stringify(record)}
+`);
+      } else {
+        await this.rewriteArray(fs, record);
+      }
+      return { ok: true };
+    } catch (error) {
+      console.error(`${this.prefix} JsonFileErrorAdapter:`, error);
+      return {
+        ok: false,
+        error: `JsonFileErrorAdapter failed to write "${this.filePath}" in ${this.mode} mode: ${describeError(error)}`
+      };
+    }
+  }
+  async getFileSystem() {
+    if (this.fs === void 0) {
+      this.fs = await loadNodeFileSystem();
+    }
+    return this.fs;
+  }
+  async prepareDirectory(fs) {
+    if (!this.createDirectory || this.directoryReady) {
+      return;
+    }
+    const directory = parentDirectory(this.filePath);
+    if (directory !== null) {
+      await fs.mkdir(directory, { recursive: true });
+    }
+    this.directoryReady = true;
+  }
+  /**
+   * 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.
+   */
+  async rewriteArray(fs, record) {
+    const records = [
+      ...await this.readRecords(fs),
+      record
+    ];
+    const kept = this.maxEntries === void 0 ? records : records.slice(-this.maxEntries);
+    const temporaryPath = `${this.filePath}.tmp`;
+    await fs.writeFile(
+      temporaryPath,
+      `${JSON.stringify(kept, null, this.indent)}
+`
+    );
+    await fs.rename(temporaryPath, this.filePath);
+  }
+  /**
+   * 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.
+   */
+  async readRecords(fs) {
+    let content;
+    try {
+      content = await fs.readFile(this.filePath, "utf8");
+    } catch (error) {
+      if (isMissingFileError(error)) {
+        return [];
+      }
+      throw error;
+    }
+    if (content.trim() === "") {
+      return [];
+    }
+    let problem;
+    try {
+      const parsed = JSON.parse(content);
+      if (Array.isArray(parsed)) {
+        return parsed;
+      }
+      problem = "did not hold a JSON array";
+    } catch (error) {
+      problem = `held invalid JSON (${describeError(error)})`;
+    }
+    const corruptPath = `${this.filePath}.corrupt`;
+    await fs.rename(this.filePath, corruptPath);
+    console.error(
+      `${this.prefix} JsonFileErrorAdapter: "${this.filePath}" ${problem}, so it was moved to "${corruptPath}" and a new file was started.`
+    );
+    return [];
+  }
+};
+export {
+  CompositeErrorAdapter,
+  ConsoleErrorAdapter,
+  FlatFileErrorAdapter,
+  IndexedDbErrorAdapter,
+  JsonFileErrorAdapter,
+  MongoDbErrorAdapter,
+  SqliteErrorAdapter,
+  WebStorageErrorAdapter,
+  WebhookErrorAdapter,
+  buildCreateErrorLogTableSql,
+  createErrorLogStore,
+  formatErrorLogLine,
+  serializeCause,
+  serializeEntry
+};
+//# sourceMappingURL=index.mjs.map