@richardmcquiston01/error-log-adapter 0.6.0 → 0.7.0

package/README.md

@@ -88,6 +88,7 @@ Every adapter takes an optional `prefix` (default `[error-log-adapter]`) that is
 | `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)                                                              |
 | `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.
@@ -101,6 +102,7 @@ What changes durability or size, by adapter:
 - **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.
 - **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.
 - **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
@@ -245,6 +247,16 @@ target.addEventListener('error-log', (event) =>
 const errorLog = new EventEmitterErrorAdapter(emitter);
 ```
 
+Send errors over a socket you manage, with a file as the fallback while it is down:
+
+```ts
+const socket = new WebSocket('wss://logs.example.com/errors');
+const errorLog = new CompositeErrorAdapter([
+  new WebSocketErrorAdapter(socket),
+  new FlatFileErrorAdapter('./errors.log'),
+]);
+```
+
 Write your own adapter by implementing the interface. Catch failures and return them rather than throwing:
 
 ```ts

package/dist/index.cjs

@@ -35,6 +35,7 @@ __export(index_exports, {
   S3ErrorAdapter: () => S3ErrorAdapter,
   SqliteErrorAdapter: () => SqliteErrorAdapter,
   SupabaseErrorAdapter: () => SupabaseErrorAdapter,
+  WebSocketErrorAdapter: () => WebSocketErrorAdapter,
   WebStorageErrorAdapter: () => WebStorageErrorAdapter,
   WebhookErrorAdapter: () => WebhookErrorAdapter,
   buildCreateErrorLogTableSql: () => buildCreateErrorLogTableSql,
@@ -1820,6 +1821,42 @@ var EventEmitterErrorAdapter = class {
     }
   }
 };
+
+// src/adapters/websocket-error-adapter.ts
+var OPEN = 1;
+var STATE_NAMES = {
+  0: "still connecting",
+  1: "open",
+  2: "closing",
+  3: "closed"
+};
+var WebSocketErrorAdapter = class {
+  constructor(socket, options = {}) {
+    this.socket = socket;
+    this.prefix = options.prefix ?? DEFAULT_PREFIX;
+  }
+  async log(entry) {
+    try {
+      const state = this.socket.readyState;
+      if (state !== OPEN) {
+        throw new Error(
+          `the socket is ${STATE_NAMES[state] ?? `in unknown state ${String(state)}`} (readyState ${String(state)}), so the entry was not sent; connect or reconnect it first`
+        );
+      }
+      this.socket.send(
+        JSON.stringify({ id: resolveEntryId(entry), ...serializeEntry(entry) })
+      );
+      return { ok: true };
+    } catch (error) {
+      return reportFailure({
+        adapterName: "WebSocketErrorAdapter",
+        prefix: this.prefix,
+        action: "to send over the socket",
+        error
+      });
+    }
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CompositeErrorAdapter,
@@ -1837,6 +1874,7 @@ var EventEmitterErrorAdapter = class {
   S3ErrorAdapter,
   SqliteErrorAdapter,
   SupabaseErrorAdapter,
+  WebSocketErrorAdapter,
   WebStorageErrorAdapter,
   WebhookErrorAdapter,
   buildCreateErrorLogTableSql,