@richardmcquiston01/error-log-adapter 0.10.0 → 0.11.0

package/README.md

@@ -84,7 +84,7 @@ Every adapter takes an optional `prefix` (default `[error-log-adapter]`) that is
 | `FirestoreErrorAdapter(collection)`                 | A Firestore collection                                         | Node, browser | `timeoutMs`, `expireAfterMs`                                        |
 | `RealtimeDatabaseErrorAdapter(ref)`                 | A Realtime Database reference                                  | Node, browser | `timeoutMs`                                                         |
 | `FlatFileErrorAdapter(path)`                        | One text line per entry                                        | Node, Bun     | `formatLine`, `maxBytes`, `maxFiles`                                |
-| `JsonFileErrorAdapter(path)`                        | NDJSON lines or one JSON array                                 | Node, Bun     | `mode`, `maxEntries`, `indent`                                      |
+| `JsonFileErrorAdapter(path)`                        | NDJSON lines or one JSON array                                 | Node, Bun     | `mode`, `maxBytes`, `maxFiles`, `maxEntries`, `indent`              |
 | `IndexedDbErrorAdapter(database)`                   | An IndexedDB object store                                      | Browser       | `storeName`, `timeoutMs`                                            |
 | `WebStorageErrorAdapter(storage)`                   | `sessionStorage` or `localStorage`, as one capped array        | Browser       | `key`, `maxEntries`, `locks`                                        |
 | `EventEmitterErrorAdapter(emitter)`                 | An event on an emitter you own (in-process hooks)              | Anywhere      | `eventName`, `requireListener`                                      |
@@ -100,7 +100,7 @@ What changes durability or size, by adapter:
 - **SQL adapters** (`createTable`): the table is created on first use by default. Set `createTable: false` and run the statements from `buildErrorLogTableDdl('postgres' | 'mysql')` (or `buildCreateErrorLogTableSql()` for SQLite) yourself if the application's database user should not change the schema. Table names are checked to be plain identifiers. A MySQL table made by 0.4.0 or earlier has `VARCHAR(255)` columns for `code` and `source`; run the statement from `buildMySqlWidenColumnsSql()` once to widen them.
 - **Supabase**: create the table once with `buildSupabaseSetupSql()`, which also turns on row level security. Log from a server with the service role key, which bypasses RLS and must never reach a browser. A browser-held key needs an insert policy: pass `insertRoles: ['authenticated']` to the same function. The policy limits the size of each field but cannot tie a row to a user, so a holder of that key can still add entries of their own. Listing `anon` or `public` throws unless you also pass `allowPublicInsert: true`, because the anon key is public.
 - **S3** (`batch`): with `batch: { batchSize, maxWaitMs }`, entries are buffered and uploaded together as one NDJSON object. `log()` then returns `ok` as soon as the entry is buffered, so call `flush()` before the process exits.
-- **Files** (`maxBytes` / `maxFiles`, `maxEntries`): the flat file adapter rotates by size; the JSON file adapter's `array` mode keeps the newest `maxEntries`.
+- **Files** (`maxBytes` / `maxFiles`, `maxEntries`): the flat file adapter and the JSON file adapter's `ndjson` mode rotate by size: before a write that would push the file past `maxBytes`, `errors.log` becomes `errors.log.1` (older files shift up, and the one past `maxFiles`, default 3, is deleted). Every file holds whole lines, an entry is never split across files, and a failed rotation is reported to the console but the entry is still written. Rotation assumes one process writes the file. The JSON file adapter's `array` mode instead keeps the newest `maxEntries`, and rejects `maxBytes` / `maxFiles`.
 - **Redis and Web Storage** (`maxEntries`): the oldest entries are dropped past the cap.
 - **Browser storage**: `sessionStorage` belongs to one tab. `localStorage` is shared by every tab and has no atomic update, so two tabs logging at the same instant can overwrite each other's entry. `WebStorageErrorAdapter` takes a `navigator.locks` lock around each write, which reduces the loss but cannot remove it, since tabs in separate processes can still read a stale copy. Use `IndexedDbErrorAdapter` when every entry matters. Create its object store from your `onupgradeneeded` handler with `createErrorLogStore`. A stored value the adapter cannot read is copied to `<key>.corrupt` before it is replaced.
 - **Firestore expiry**: pass `expireAfterMs` (for example `30 * 24 * 60 * 60 * 1000`) and every document gets a Firestore timestamp field, `expire_at` (change the name with `expireField`), set to the entry's `timestamp` plus that time. This only writes the field: Firestore deletes nothing until you enable a TTL policy on it, in the console or with `gcloud firestore fields ttls update expire_at --collection-group=error_log --enable-ttl`. Documents are then removed some time after they expire (typically within a day), and the deletes are billed like any other. The Realtime Database has no TTL feature, so the option is Firestore only.

package/dist/index.cjs

@@ -973,8 +973,55 @@ function isMissingFileError(error) {
   return typeof error === "object" && error !== null && error.code === "ENOENT";
 }
 
-// src/adapters/flat-file-error-adapter.ts
+// src/file-rotation.ts
 var DEFAULT_MAX_FILES = 3;
+function assertPositiveInteger(adapterName, value, name) {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new RangeError(
+      `${adapterName}: ${name} must be a positive integer, received ${String(value)}.`
+    );
+  }
+}
+async function renameIfPresent(fs, from, to) {
+  try {
+    await fs.rename(from, to);
+  } catch (error) {
+    if (!isMissingFileError(error)) {
+      throw error;
+    }
+  }
+}
+async function rotateIfNeeded(fs, filePath, writeBytes, settings, report) {
+  try {
+    let currentSize;
+    try {
+      currentSize = (await fs.stat(filePath)).size;
+    } catch (error) {
+      if (isMissingFileError(error)) {
+        return;
+      }
+      throw error;
+    }
+    if (currentSize === 0 || currentSize + writeBytes <= settings.maxBytes) {
+      return;
+    }
+    await fs.rm(`${filePath}.${settings.maxFiles}`, { force: true });
+    for (let index = settings.maxFiles - 1; index >= 1; index -= 1) {
+      await renameIfPresent(
+        fs,
+        `${filePath}.${index}`,
+        `${filePath}.${index + 1}`
+      );
+    }
+    await fs.rename(filePath, `${filePath}.1`);
+  } catch (error) {
+    console.error(
+      `${report.prefix} ${report.adapterName}: could not rotate "${filePath}", so it will keep growing: ${describeError(error)}`
+    );
+  }
+}
+
+// src/adapters/flat-file-error-adapter.ts
 function escapeLineBreaks(text) {
   return text.replace(/\r?\n/g, "\\n");
 }
@@ -1001,13 +1048,6 @@ function formatErrorLogLine(entry) {
     `${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 = {}) {
@@ -1021,9 +1061,9 @@ var FlatFileErrorAdapter = class {
     this.createDirectory = options.createDirectory ?? true;
     this.prefix = options.prefix ?? DEFAULT_PREFIX;
     if (this.maxBytes !== void 0) {
-      assertPositiveInteger(this.maxBytes, "maxBytes");
+      assertPositiveInteger("FlatFileErrorAdapter", this.maxBytes, "maxBytes");
     }
-    assertPositiveInteger(this.maxFiles, "maxFiles");
+    assertPositiveInteger("FlatFileErrorAdapter", this.maxFiles, "maxFiles");
   }
   log(entry) {
     return this.queue.run(() => this.write(entry));
@@ -1035,7 +1075,15 @@ var FlatFileErrorAdapter = class {
       const line = formatted.endsWith("\n") ? formatted : `${formatted}
 `;
       await this.prepareDirectory(fs);
-      await this.rotateIfNeeded(fs, new TextEncoder().encode(line).length);
+      if (this.maxBytes !== void 0) {
+        await rotateIfNeeded(
+          fs,
+          this.filePath,
+          new TextEncoder().encode(line).length,
+          { maxBytes: this.maxBytes, maxFiles: this.maxFiles },
+          { adapterName: "FlatFileErrorAdapter", prefix: this.prefix }
+        );
+      }
       await fs.appendFile(this.filePath, line);
       return { ok: true };
     } catch (error) {
@@ -1064,64 +1112,20 @@ var FlatFileErrorAdapter = class {
     }
     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. */
+  /** @throws {RangeError} if `maxEntries`, `maxBytes`, `maxFiles` or `indent` is invalid, or an option is used in the wrong mode. */
   constructor(filePath, options = {}) {
     this.filePath = filePath;
     this.directoryReady = false;
     this.queue = new SerialQueue();
     this.mode = options.mode ?? "ndjson";
     this.maxEntries = options.maxEntries;
+    this.maxBytes = options.maxBytes;
+    this.maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
     this.indent = options.indent ?? DEFAULT_INDENT;
     this.fs = options.fs;
     this.createDirectory = options.createDirectory ?? true;
@@ -1138,6 +1142,20 @@ var JsonFileErrorAdapter = class {
         );
       }
     }
+    if (this.maxBytes !== void 0 || options.maxFiles !== void 0) {
+      if (this.mode !== "ndjson") {
+        throw new RangeError(
+          `JsonFileErrorAdapter: maxBytes and maxFiles only apply to mode "ndjson", but mode is "${this.mode}". Use mode "ndjson", or use maxEntries to limit array mode.`
+        );
+      }
+      if (this.maxBytes === void 0) {
+        throw new RangeError(
+          "JsonFileErrorAdapter: maxFiles needs maxBytes; set maxBytes to turn rotation on."
+        );
+      }
+      assertPositiveInteger("JsonFileErrorAdapter", this.maxBytes, "maxBytes");
+      assertPositiveInteger("JsonFileErrorAdapter", this.maxFiles, "maxFiles");
+    }
     if (!Number.isInteger(this.indent) || this.indent < 0) {
       throw new RangeError(
         `JsonFileErrorAdapter: indent must be a non-negative integer, received ${String(this.indent)}.`
@@ -1156,8 +1174,18 @@ var JsonFileErrorAdapter = class {
       const fs = await this.getFileSystem();
       await this.prepareDirectory(fs);
       if (this.mode === "ndjson") {
-        await fs.appendFile(this.filePath, `${JSON.stringify(record)}
-`);
+        const line = `${JSON.stringify(record)}
+`;
+        if (this.maxBytes !== void 0) {
+          await rotateIfNeeded(
+            fs,
+            this.filePath,
+            new TextEncoder().encode(line).length,
+            { maxBytes: this.maxBytes, maxFiles: this.maxFiles },
+            { adapterName: "JsonFileErrorAdapter", prefix: this.prefix }
+          );
+        }
+        await fs.appendFile(this.filePath, line);
       } else {
         await this.rewriteArray(fs, record);
       }