@richardmcquiston01/error-log-adapter 0.8.0 → 0.10.0

package/README.md

@@ -70,27 +70,28 @@ Constructor options are checked when the adapter is created and throw a descript
 
 Every adapter takes an optional `prefix` (default `[error-log-adapter]`) that is printed before its failure messages.
 
-| Adapter                                             | Sink                                                      | Runs in       | Main options                                                        |
-| --------------------------------------------------- | --------------------------------------------------------- | ------------- | ------------------------------------------------------------------- |
-| `ConsoleErrorAdapter`                               | `console.error`                                           | Anywhere      |                                                                     |
-| `WebhookErrorAdapter(url)`                          | HTTP `POST` of the entry as JSON                          | Anywhere      | `headers`, `timeoutMs`, `retries`, `signingSecret`, `allowInsecure` |
-| `MongoDbErrorAdapter(collection)`                   | Anything with `insertOne`, such as a MongoDB `Collection` | Node          | `timeoutMs`                                                         |
-| `PostgresErrorAdapter(client)`                      | A Postgres table, through `pg`                            | Node          | `tableName`, `createTable`, `timeoutMs`                             |
-| `MySqlErrorAdapter(client)`                         | A MySQL / MariaDB table, through `mysql2/promise`         | Node          | `tableName`, `createTable`, `timeoutMs`                             |
-| `SqliteErrorAdapter(client)`                        | A SQLite table, through any driver                        | Node, Bun     | `tableName`, `createTable`, `timeoutMs`                             |
-| `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`                                                         |
-| `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`                                      |
-| `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`                                      |
-| `WebSocketErrorAdapter(socket)`                     | One JSON message over a socket you own                    | Anywhere      | (none)                                                              |
-| `CloudWatchLogsErrorAdapter(client, group, stream)` | AWS CloudWatch Logs events                                | Node          | `batch`, `createMissing`, `timeoutMs`                               |
-| `CompositeErrorAdapter([...])`                      | Several adapters at once; succeeds only if all succeed    | Anywhere      | `timeoutMs`                                                         |
+| Adapter                                             | Sink                                                           | Runs in       | Main options                                                        |
+| --------------------------------------------------- | -------------------------------------------------------------- | ------------- | ------------------------------------------------------------------- |
+| `ConsoleErrorAdapter`                               | `console.error`                                                | Anywhere      |                                                                     |
+| `WebhookErrorAdapter(url)`                          | HTTP `POST` of the entry as JSON                               | Anywhere      | `headers`, `timeoutMs`, `retries`, `signingSecret`, `allowInsecure` |
+| `MongoDbErrorAdapter(collection)`                   | Anything with `insertOne`, such as a MongoDB `Collection`      | Node          | `timeoutMs`                                                         |
+| `PostgresErrorAdapter(client)`                      | A Postgres table, through `pg`                                 | Node          | `tableName`, `createTable`, `timeoutMs`                             |
+| `MySqlErrorAdapter(client)`                         | A MySQL / MariaDB table, through `mysql2/promise`              | Node          | `tableName`, `createTable`, `timeoutMs`                             |
+| `SqliteErrorAdapter(client)`                        | A SQLite table, through any driver                             | Node, Bun     | `tableName`, `createTable`, `timeoutMs`                             |
+| `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`, `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`                                      |
+| `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`                                      |
+| `WebSocketErrorAdapter(socket)`                     | One JSON message over a socket you own                         | Anywhere      | (none)                                                              |
+| `CloudWatchLogsErrorAdapter(client, group, stream)` | AWS CloudWatch Logs events                                     | Node          | `batch`, `createMissing`, `timeoutMs`                               |
+| `BatchingErrorAdapter(adapter)`                     | A queue in front of any adapter: batches, retries with backoff | Anywhere      | `batchSize`, `maxWaitMs`, `retries`, `maxBuffered`, `onDrop`        |
+| `CompositeErrorAdapter([...])`                      | Several adapters at once; succeeds only if all succeed         | Anywhere      | `timeoutMs`                                                         |
 
 Every stored record has the same shape: a UUID `id`, `code`, `message`, `timestamp` (ISO 8601), and optional `source` and `cause`. An `Error` cause is stored as `{ name, message, stack }`. `serializeEntry` and `serializeCause` are exported if you build your own sink.
 
@@ -102,9 +103,11 @@ 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.
+- **Batching wrapper**: `BatchingErrorAdapter` puts a queue in front of any other adapter. `log()` returns `ok: true` as soon as the entry is queued, so a slow or failing sink never holds up the app, and entries are delivered in order in batches (`batchSize`, default 20, or after `maxWaitMs`, default 5000). A failed delivery is retried with exponential backoff (`retries`, default 3) and then given up on: the entries go to `onDrop` and the console, and `flush()` returns `ok: false` once. Delivery stops at the first failure so a dead sink is not hammered. If the wrapped adapter has a `logBatch` method (the webhook does) the batch goes in one call, which for the webhook means one request carrying a JSON array, so the receiver must accept an array; pass `useBatchMethod: false` to keep one request per entry. `ok: true` means _queued_, not stored, and the queue lives in memory: call `flush()` before the process exits, and put a durable adapter beside it in a `CompositeErrorAdapter` if entries must survive a crash. Do not also enable the wrapped adapter's own retries (the webhook's `retries`); they multiply. The buffer holds `maxBuffered` entries (default 1000) and drops the oldest past that.
 - **Webhook**: the URL must be `https://` (or `http://localhost`, `127.0.0.1`, `[::1]`) unless you pass `allowInsecure: true`, because entries carry messages and stack traces. Redirects are not followed, since a redirect would turn the `POST` into a body-less `GET` or re-send the entry and your headers to another host; a redirect is reported as `ok: false`. Failure messages contain only the origin, never the path or query, because webhook URLs often hold a secret. Set `retries` to try again after a network error, a timeout, HTTP 408, 425, 429 or 5xx (exponential backoff with jitter from `retryDelayMs`, capped by `maxRetryDelayMs`, honoring `Retry-After`; other 4xx answers are never retried). With `retries` set, every attempt sends the same body including an `id`, so the receiver can drop a repeat. Set `signingSecret` to add `X-Signature-Timestamp` and `X-Signature-256` (`sha256=` + hex HMAC-SHA256 of `<timestamp>.<body>`); the receiver recomputes it and rejects old timestamps.
 
 ### When a sink is slow or down
@@ -275,6 +278,23 @@ const errorLog = new CloudWatchLogsErrorAdapter(
 process.on('beforeExit', () => void errorLog.flush());
 ```
 
+Batch and retry in front of a webhook, so a slow endpoint never holds up the app:
+
+```ts
+const errorLog = new BatchingErrorAdapter(
+  new WebhookErrorAdapter('https://example.com/errors', {
+    signingSecret: process.env.ERROR_WEBHOOK_SECRET,
+  }),
+  {
+    batchSize: 50,
+    maxWaitMs: 2000,
+    onDrop: (entries, reason) =>
+      console.warn(`lost ${entries.length}: ${reason}`),
+  }
+);
+process.on('beforeExit', () => void errorLog.flush());
+```
+
 Write your own adapter by implementing the interface. Catch failures and return them rather than throwing:
 
 ```ts
@@ -303,6 +323,8 @@ class SlackErrorAdapter implements ErrorLogAdapter {
 }
 ```
 
+The full guide, [docs/custom-adapters.md](./docs/custom-adapters.md), covers the contract, timeouts, entry ids, buffering adapters, testing, and a checklist.
+
 See [ROADMAP.md](./ROADMAP.md) for planned adapters and [CHANGELOG.md](./CHANGELOG.md) for what changed in each release.
 
 ### Development

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BatchingErrorAdapter: () => BatchingErrorAdapter,
   CloudWatchLogsErrorAdapter: () => CloudWatchLogsErrorAdapter,
   CompositeErrorAdapter: () => CompositeErrorAdapter,
   ConsoleErrorAdapter: () => ConsoleErrorAdapter,
@@ -192,6 +193,12 @@ var ConsoleErrorAdapter = class {
   }
 };
 
+// src/backoff.ts
+function backoffDelayMs(retryNumber, baseMs, maxMs) {
+  const ceiling = Math.min(maxMs, baseMs * 2 ** (retryNumber - 1));
+  return ceiling / 2 + Math.random() * ceiling / 2;
+}
+
 // src/uuid.ts
 function generateId() {
   const cryptoApi = globalThis.crypto;
@@ -403,6 +410,36 @@ var WebhookErrorAdapter = class {
         `could not prepare the entry: ${this.redact(describeError(error))}`
       );
     }
+    return this.deliver(body);
+  }
+  /**
+   * Sends several entries in one request, as a JSON array of the same records
+   * `log` sends one at a time (each with an `id`). `BatchingErrorAdapter` uses
+   * this when it wraps a webhook, so the receiver must accept an array. The
+   * whole request succeeds or fails together.
+   */
+  async logBatch(entries) {
+    if (entries.length === 0) {
+      return { ok: true };
+    }
+    let body;
+    try {
+      body = JSON.stringify(
+        entries.map((entry) => ({
+          id: resolveEntryId(entry),
+          ...serializeEntry(entry)
+        }))
+      );
+    } catch (error) {
+      console.error(`${this.prefix} WebhookErrorAdapter:`, error);
+      return this.fail(
+        `could not prepare the entries: ${this.redact(describeError(error))}`
+      );
+    }
+    return this.deliver(body);
+  }
+  /** Sends one prepared body, trying again as `retries` allows. */
+  async deliver(body) {
     let attempt = await this.send(body);
     let attempts = 1;
     while (!attempt.ok && attempt.retryable && attempts <= this.retries) {
@@ -422,11 +459,7 @@ var WebhookErrorAdapter = class {
     if (retryAfterMs !== void 0) {
       return Math.min(retryAfterMs, this.maxRetryDelayMs);
     }
-    const ceiling = Math.min(
-      this.maxRetryDelayMs,
-      this.retryDelayMs * 2 ** (retryNumber - 1)
-    );
-    return ceiling / 2 + Math.random() * ceiling / 2;
+    return backoffDelayMs(retryNumber, this.retryDelayMs, this.maxRetryDelayMs);
   }
   async send(body) {
     const controller = new AbortController();
@@ -1594,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,
@@ -1618,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;
@@ -1626,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
@@ -2146,8 +2209,259 @@ function describeRejection(output, eventCount) {
   }
   return reasons.length === 0 ? void 0 : `CloudWatch Logs accepted the request but rejected events: ${reasons.join("; ")}`;
 }
+
+// src/adapters/batching-error-adapter.ts
+var DEFAULT_BATCH_SIZE = 20;
+var DEFAULT_MAX_WAIT_MS = 5e3;
+var DEFAULT_RETRIES = 3;
+var DEFAULT_RETRY_DELAY_MS2 = 500;
+var DEFAULT_MAX_RETRY_DELAY_MS2 = 3e4;
+var DEFAULT_MAX_BUFFERED = 1e3;
+function hasLogBatch(adapter) {
+  return typeof adapter.logBatch === "function";
+}
+var BatchingErrorAdapter = class {
+  /** @throws {RangeError} if an option is out of range. */
+  constructor(inner, options = {}) {
+    this.inner = inner;
+    this.queue = [];
+    this.waitTimer = null;
+    this.backoffTimer = null;
+    this.draining = null;
+    this.flushers = 0;
+    this.droppedSinceFlush = 0;
+    this.lastDropReason = "";
+    this.batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
+    this.maxWaitMs = options.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
+    this.retries = options.retries ?? DEFAULT_RETRIES;
+    this.retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS2;
+    this.maxRetryDelayMs = options.maxRetryDelayMs ?? DEFAULT_MAX_RETRY_DELAY_MS2;
+    this.maxBuffered = options.maxBuffered ?? DEFAULT_MAX_BUFFERED;
+    this.useBatchMethod = options.useBatchMethod ?? true;
+    this.onDrop = options.onDrop;
+    this.logPrefix = options.prefix ?? DEFAULT_PREFIX;
+    if (!Number.isInteger(this.batchSize) || this.batchSize < 1) {
+      throw new RangeError(
+        `BatchingErrorAdapter: batchSize must be a positive integer, received ${String(options.batchSize)}.`
+      );
+    }
+    if (Number.isNaN(this.maxWaitMs) || this.maxWaitMs <= 0) {
+      throw new RangeError(
+        `BatchingErrorAdapter: maxWaitMs must be a positive number or Infinity, received ${String(options.maxWaitMs)}.`
+      );
+    }
+    if (!Number.isInteger(this.retries) || this.retries < 0) {
+      throw new RangeError(
+        `BatchingErrorAdapter: retries must be a whole number of 0 or more, received ${String(options.retries)}.`
+      );
+    }
+    if (!Number.isFinite(this.retryDelayMs) || this.retryDelayMs <= 0) {
+      throw new RangeError(
+        `BatchingErrorAdapter: retryDelayMs must be a positive number, received ${String(options.retryDelayMs)}.`
+      );
+    }
+    if (!Number.isFinite(this.maxRetryDelayMs) || this.maxRetryDelayMs < this.retryDelayMs) {
+      throw new RangeError(
+        `BatchingErrorAdapter: maxRetryDelayMs must be a number no smaller than retryDelayMs (${this.retryDelayMs}), received ${String(options.maxRetryDelayMs)}.`
+      );
+    }
+    if (!Number.isInteger(this.maxBuffered) || this.maxBuffered < this.batchSize) {
+      throw new RangeError(
+        `BatchingErrorAdapter: maxBuffered must be a whole number no smaller than batchSize (${this.batchSize}), received ${String(options.maxBuffered)}.`
+      );
+    }
+  }
+  /** Queues the entry. Resolves ok straight away; delivery happens in the background. */
+  log(entry) {
+    this.queue.push({ entry, failures: 0 });
+    if (this.queue.length > this.maxBuffered) {
+      const overflow = this.queue.splice(
+        0,
+        this.queue.length - this.maxBuffered
+      );
+      this.drop(
+        overflow,
+        `the buffer of ${this.maxBuffered} entries was full because the wrapped adapter keeps failing`
+      );
+    }
+    if (this.queue.length >= this.batchSize) {
+      this.startDraining();
+    } else {
+      this.scheduleDrain();
+    }
+    return Promise.resolve({ ok: true });
+  }
+  /**
+   * Delivers everything queued, retrying as configured, and resolves once the
+   * queue is empty. Resolves `ok: false` if any entries were given up on since
+   * the last flush. With retries on and the sink down this can take a while
+   * (the waits add up to well over a minute with the defaults).
+   */
+  async flush() {
+    this.flushers += 1;
+    this.backoffTimer?.ref?.();
+    try {
+      this.startDraining();
+      while (this.draining !== null) {
+        await this.draining;
+      }
+    } finally {
+      this.flushers -= 1;
+    }
+    if (this.droppedSinceFlush > 0) {
+      const count = this.droppedSinceFlush;
+      const reason = this.lastDropReason;
+      this.droppedSinceFlush = 0;
+      this.lastDropReason = "";
+      return {
+        ok: false,
+        error: `BatchingErrorAdapter gave up on ${count} entr${count === 1 ? "y" : "ies"}: ${reason}`
+      };
+    }
+    return { ok: true };
+  }
+  scheduleDrain() {
+    if (this.waitTimer !== null || this.maxWaitMs === Infinity) {
+      return;
+    }
+    const timer = setTimeout(() => {
+      this.waitTimer = null;
+      this.startDraining();
+    }, this.maxWaitMs);
+    timer.unref?.();
+    this.waitTimer = timer;
+  }
+  startDraining() {
+    if (this.waitTimer !== null) {
+      clearTimeout(this.waitTimer);
+      this.waitTimer = null;
+    }
+    if (this.draining !== null || this.queue.length === 0) {
+      return;
+    }
+    this.draining = this.drain().catch((error) => {
+      console.error(`${this.logPrefix} BatchingErrorAdapter:`, error);
+    }).finally(() => {
+      this.draining = null;
+      if (this.queue.length > 0) {
+        this.scheduleDrain();
+      }
+    });
+  }
+  /** Delivers batches until the queue is empty, waiting out a backoff after each failure. */
+  async drain() {
+    let failedRounds = 0;
+    while (this.queue.length > 0) {
+      const batch = this.queue.slice(0, this.batchSize);
+      const failure = await this.deliver(batch);
+      if (failure === void 0) {
+        failedRounds = 0;
+        continue;
+      }
+      failedRounds += 1;
+      const exhausted = this.queue.filter(
+        (item) => item.failures > this.retries
+      );
+      if (exhausted.length > 0) {
+        this.queue = this.queue.filter(
+          (item) => item.failures <= this.retries
+        );
+        this.drop(
+          exhausted,
+          `delivery failed ${this.retries + 1} time${this.retries === 0 ? "" : "s"}; last error: ${failure}`
+        );
+      }
+      if (this.queue.length > 0) {
+        await this.backoff(failedRounds);
+      }
+    }
+  }
+  /**
+   * Tries to deliver `batch` (the front of the queue). Delivered entries leave
+   * the queue; an entry that failed has its failure count raised and stays.
+   * Resolves to the failure message, or undefined when everything went through.
+   */
+  async deliver(batch) {
+    const remove = (delivered) => {
+      const gone = new Set(delivered);
+      this.queue = this.queue.filter(
+        (item) => !gone.has(item)
+      );
+    };
+    if (this.useBatchMethod && hasLogBatch(this.inner)) {
+      const result = await this.safely(
+        () => this.inner.logBatch(
+          batch.map(
+            (item) => item.entry
+          )
+        )
+      );
+      if (result.ok) {
+        remove(batch);
+        return void 0;
+      }
+      for (const item of batch) {
+        item.failures += 1;
+      }
+      return result.error ?? "the wrapped adapter reported a failure";
+    }
+    for (const item of batch) {
+      const result = await this.safely(
+        () => this.inner.log(item.entry)
+      );
+      if (result.ok) {
+        remove([item]);
+        continue;
+      }
+      item.failures += 1;
+      return result.error ?? "the wrapped adapter reported a failure";
+    }
+    return void 0;
+  }
+  /** The wrapped adapter should not throw, but a bug in one must not stop the queue. */
+  async safely(call) {
+    try {
+      return await call();
+    } catch (error) {
+      return { ok: false, error: describeError(error) };
+    }
+  }
+  backoff(failedRounds) {
+    return new Promise((resolve) => {
+      const timer = setTimeout(
+        () => {
+          this.backoffTimer = null;
+          resolve();
+        },
+        backoffDelayMs(failedRounds, this.retryDelayMs, this.maxRetryDelayMs)
+      );
+      if (this.flushers === 0) {
+        timer.unref?.();
+      }
+      this.backoffTimer = timer;
+    });
+  }
+  drop(items, reason) {
+    if (items.length === 0) {
+      return;
+    }
+    this.droppedSinceFlush += items.length;
+    this.lastDropReason = reason;
+    console.error(
+      `${this.logPrefix} BatchingErrorAdapter: gave up on ${items.length} entr${items.length === 1 ? "y" : "ies"}: ${reason}`
+    );
+    try {
+      this.onDrop?.(
+        items.map((item) => item.entry),
+        reason
+      );
+    } catch {
+    }
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BatchingErrorAdapter,
   CloudWatchLogsErrorAdapter,
   CompositeErrorAdapter,
   ConsoleErrorAdapter,