@richardmcquiston01/error-log-adapter 0.9.0 → 0.10.0

package/README.md

@@ -81,7 +81,7 @@ Every adapter takes an optional `prefix` (default `[error-log-adapter]`) that is
 | `SupabaseErrorAdapter(client)`                      | A Supabase table, through `supabase-js`                        | Anywhere      | `tableName`, `timeoutMs`                                            |
 | `RedisErrorAdapter(client)`                         | A Redis list or stream                                         | Node          | `mode`, `key`, `maxEntries`, `side`, `timeoutMs`                    |
 | `S3ErrorAdapter(client, bucket)`                    | S3, DigitalOcean Spaces, R2, MinIO objects                     | Node          | `keyPrefix`, `batch`, `contentType`, `timeoutMs`                    |
-| `FirestoreErrorAdapter(collection)`                 | A Firestore collection                                         | Node, browser | `timeoutMs`                                                         |
+| `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`                                      |
@@ -103,6 +103,7 @@ What changes durability or size, by adapter:
 - **Files** (`maxBytes` / `maxFiles`, `maxEntries`): the flat file adapter rotates by size; the JSON file adapter's `array` mode keeps the newest `maxEntries`.
 - **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.
 - **Event emitter**: each entry is emitted as an `error-log` event whose payload is the stored record, for in-process hooks such as a toast, a metrics counter or a test assertion. Listeners run synchronously, so one that throws makes `log()` return `ok: false` with its message. Node's `EventEmitter` and mitt work as they are; a browser `EventTarget` needs a one-line wrapper (shown in the example below). Don't name the event `error` on a Node `EventEmitter`: it throws when nobody listens. Node's `emit` returns `false` when there are no listeners; pass `requireListener: true` to report that as a failure instead of letting the entry vanish.
 - **WebSocket**: each entry is sent as one JSON text message (the serialized entry plus its UUID `id`) over a socket you own; the adapter never connects, reconnects or buffers. If the socket's `readyState` is not open (connecting, closing or closed), `log()` returns `ok: false` and says which. `ok: true` means the socket accepted the message, not that the server got it, since a WebSocket has no acknowledgement. Browsers, Node's global `WebSocket`, Deno, Bun and `ws` all fit. Pair it with a durable adapter in a `CompositeErrorAdapter` if entries must survive the socket being down.
 - **CloudWatch Logs**: each entry is sent through `PutLogEvents` as a JSON event (the serialized entry plus its UUID `id`) stamped with the entry's time, so Logs Insights can query its fields. Pass an AWS SDK v3 `CloudWatchLogs` client. AWS no longer needs sequence tokens, so none are tracked. If the stream (or group) does not exist, the adapter creates it and tries again once (`createMissing`, on by default; it needs `logs:CreateLogStream` and `logs:CreateLogGroup`, and a group created this way never expires its logs, so set a retention policy). CloudWatch can answer ok and still refuse events older than 14 days or more than 2 hours ahead; that is reported as `ok: false`. An event over 256 KiB is refused before sending. With `batch: { batchSize, maxWaitMs }`, events are buffered and sent together (up to 10,000 events and 1 MiB per request, oldest first), `log()` returns `ok` as soon as the event is buffered, and you should call `flush()` before the process exits. In Lambda and ECS, stdout already reaches CloudWatch; this is for apps running elsewhere.

package/dist/index.cjs

@@ -1627,6 +1627,15 @@ var S3ErrorAdapter = class {
 };
 
 // src/adapters/firebase-error-adapter.ts
+var DEFAULT_EXPIRE_FIELD = "expire_at";
+var RESERVED_FIELDS = /* @__PURE__ */ new Set([
+  "id",
+  "code",
+  "message",
+  "timestamp",
+  "source",
+  "cause"
+]);
 function waitForWrite(start, timeoutMs) {
   return withTimeout(
     start,
@@ -1651,7 +1660,7 @@ function buildRecord(entry) {
   return record;
 }
 var FirestoreErrorAdapter = class {
-  /** @throws {RangeError} if `options.timeoutMs` is not a positive number or `Infinity`. */
+  /** @throws {RangeError} if `options.timeoutMs` is not a positive number or `Infinity`, or the expiry options are invalid. */
   constructor(collection, options = {}) {
     this.collection = collection;
     this.prefix = options.prefix ?? DEFAULT_PREFIX;
@@ -1659,10 +1668,31 @@ var FirestoreErrorAdapter = class {
       options.timeoutMs,
       "FirestoreErrorAdapter"
     );
+    this.expireAfterMs = options.expireAfterMs;
+    this.expireField = options.expireField ?? DEFAULT_EXPIRE_FIELD;
+    if (this.expireAfterMs !== void 0 && (!Number.isFinite(this.expireAfterMs) || this.expireAfterMs <= 0)) {
+      throw new RangeError(
+        `FirestoreErrorAdapter: expireAfterMs must be a positive number of milliseconds, received ${String(options.expireAfterMs)}.`
+      );
+    }
+    if (this.expireField === "" || /[./]/.test(this.expireField) || RESERVED_FIELDS.has(this.expireField)) {
+      throw new RangeError(
+        `FirestoreErrorAdapter: expireField must be a name other than ${[...RESERVED_FIELDS].join(", ")}, without "." or "/", received ${JSON.stringify(this.expireField)}.`
+      );
+    }
   }
   async log(entry) {
     try {
-      const record = buildRecord(entry);
+      const record = { ...buildRecord(entry) };
+      if (this.expireAfterMs !== void 0) {
+        const occurredAt = Date.parse(record.timestamp);
+        if (Number.isNaN(occurredAt)) {
+          throw new RangeError(
+            `timestamp "${record.timestamp}" is not a valid ISO 8601 date, so the expiry time cannot be worked out`
+          );
+        }
+        record[this.expireField] = new Date(occurredAt + this.expireAfterMs);
+      }
       await waitForWrite(
         () => this.collection.doc(record.id).set(record),
         this.timeoutMs