eventsourcingdb 1.8.10 → 1.9.1

package/README.md

@@ -260,6 +260,29 @@ for await (const row of client.runEventQlQuery(`
 controller.abort();
 ```
 
+#### Detecting a Stalled Connection
+
+While a query is running, EventSourcingDB sends a heartbeat every second whenever there is no row to send. If neither a row nor a heartbeat arrives for 30 seconds, for example because a proxy keeps the connection open but no longer passes anything through, the client SDK closes the connection and the iterator throws a `HeartbeatTimeoutError`:
+
+```typescript
+import { HeartbeatTimeoutError } from 'eventsourcingdb';
+
+try {
+  for await (const row of client.runEventQlQuery(`
+    FROM e IN events
+    PROJECT INTO e
+  `)) {
+    // ...
+  }
+} catch (error) {
+  if (error instanceof HeartbeatTimeoutError) {
+    // ...
+  }
+}
+```
+
+*Note that the time you spend handling a row does not count towards the 30 seconds, and that aborting the query does not cause a `HeartbeatTimeoutError`.*
+
 ### Observing Events
 
 To observe all events of a subject, call the `observeEvents` function with the subject as the first argument and an options object as the second argument. Set the `recursive` option to `false`. This ensures that only events of the given subject are returned, not events of nested subjects.
@@ -344,6 +367,28 @@ for await (const event of client.observeEvents('/books/42', {
 controller.abort();
 ```
 
+#### Detecting a Stalled Connection
+
+While observing, EventSourcingDB sends a heartbeat every second whenever there is no event to send. If neither an event nor a heartbeat arrives for 30 seconds, for example because a proxy keeps the connection open but no longer passes anything through, the client SDK closes the connection and the iterator throws a `HeartbeatTimeoutError`:
+
+```typescript
+import { HeartbeatTimeoutError } from 'eventsourcingdb';
+
+try {
+  for await (const event of client.observeEvents('/books/42', {
+    recursive: false
+  })) {
+    // ...
+  }
+} catch (error) {
+  if (error instanceof HeartbeatTimeoutError) {
+    // ...
+  }
+}
+```
+
+*Note that the time you spend handling an event does not count towards the 30 seconds, and that aborting observing does not cause a `HeartbeatTimeoutError`.*
+
 ### Registering an Event Schema
 
 To register an event schema, call the `registerEventSchema` function and hand over an event type and the desired schema:

package/dist/Client.js

@@ -1,4 +1,5 @@
 import { convertCloudEventToEvent } from './convertCloudEventToEvent.js';
+import { heartbeatTimeout } from './heartbeatTimeout.js';
 import { isCloudEvent } from './isCloudEvent.js';
 import { isValidServerHeader } from './isValidServerHeader.js';
 import { readNdJsonStream } from './ndjson/readNdJsonStream.js';
@@ -203,7 +204,7 @@ class Client {
                 if (!response.body) {
                     throw new Error('Failed to run EventQL query.');
                 }
-                for await (const line of readNdJsonStream(response.body, combinedSignal)) {
+                for await (const line of readNdJsonStream(response.body, combinedSignal, heartbeatTimeout.milliseconds)) {
                     if (isStreamHeartbeat(line)) {
                         continue;
                     }
@@ -273,7 +274,7 @@ class Client {
                 if (!response.body) {
                     throw new Error('Failed to observe events.');
                 }
-                for await (const line of readNdJsonStream(response.body, combinedSignal)) {
+                for await (const line of readNdJsonStream(response.body, combinedSignal, heartbeatTimeout.milliseconds)) {
                     if (isStreamHeartbeat(line)) {
                         continue;
                     }

package/dist/HeartbeatTimeoutError.d.ts

@@ -0,0 +1,4 @@
+declare class HeartbeatTimeoutError extends Error {
+    constructor();
+}
+export { HeartbeatTimeoutError };

package/dist/HeartbeatTimeoutError.js

@@ -0,0 +1,7 @@
+class HeartbeatTimeoutError extends Error {
+    constructor() {
+        super('No event and no heartbeat arrived for 30 seconds.');
+        this.name = 'HeartbeatTimeoutError';
+    }
+}
+export { HeartbeatTimeoutError };

package/dist/heartbeatTimeout.d.ts

@@ -0,0 +1,4 @@
+declare const heartbeatTimeout: {
+    milliseconds: number;
+};
+export { heartbeatTimeout };

package/dist/heartbeatTimeout.js

@@ -0,0 +1,6 @@
+// A stream that carries heartbeats ends with a HeartbeatTimeoutError if no line
+// arrives for this long. The package does not export this, only tests shorten it.
+const heartbeatTimeout = {
+    milliseconds: 30_000,
+};
+export { heartbeatTimeout };

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { Container } from './Container.js';
 import type { Event } from './Event.js';
 import type { EventCandidate } from './EventCandidate.js';
 import type { EventType } from './EventType.js';
+import { HeartbeatTimeoutError } from './HeartbeatTimeoutError.js';
 import { isEventQlQueryTrue } from './isEventQlQueryTrue.js';
 import { isSubjectOnEventId } from './isSubjectOnEventId.js';
 import { isSubjectPopulated } from './isSubjectPopulated.js';
@@ -11,4 +12,4 @@ import type { ObserveEventsOptions } from './ObserveEventsOptions.js';
 import type { Precondition } from './Precondition.js';
 import type { ReadEventsOptions } from './ReadEventsOptions.js';
 export type { Event, EventCandidate, EventType, ObserveEventsOptions, Precondition, ReadEventsOptions, };
-export { Client, Container, isEventQlQueryTrue, isSubjectOnEventId, isSubjectPopulated, isSubjectPristine, };
+export { Client, Container, HeartbeatTimeoutError, isEventQlQueryTrue, isSubjectOnEventId, isSubjectPopulated, isSubjectPristine, };

package/dist/index.js

@@ -1,7 +1,8 @@
 import { Client } from './Client.js';
 import { Container } from './Container.js';
+import { HeartbeatTimeoutError } from './HeartbeatTimeoutError.js';
 import { isEventQlQueryTrue } from './isEventQlQueryTrue.js';
 import { isSubjectOnEventId } from './isSubjectOnEventId.js';
 import { isSubjectPopulated } from './isSubjectPopulated.js';
 import { isSubjectPristine } from './isSubjectPristine.js';
-export { Client, Container, isEventQlQueryTrue, isSubjectOnEventId, isSubjectPopulated, isSubjectPristine, };
+export { Client, Container, HeartbeatTimeoutError, isEventQlQueryTrue, isSubjectOnEventId, isSubjectPopulated, isSubjectPristine, };

package/dist/ndjson/readNdJsonStream.d.ts

@@ -1,2 +1,2 @@
-declare const readNdJsonStream: (stream: ReadableStream<Uint8Array>, signal: AbortSignal) => AsyncGenerator<Record<string, unknown>, void, void>;
+declare const readNdJsonStream: (stream: ReadableStream<Uint8Array>, signal: AbortSignal, heartbeatTimeoutInMilliseconds?: number) => AsyncGenerator<Record<string, unknown>, void, void>;
 export { readNdJsonStream };

package/dist/ndjson/readNdJsonStream.js

@@ -1,7 +1,27 @@
-const readNdJsonStream = async function* (stream, signal) {
+import { HeartbeatTimeoutError } from '../HeartbeatTimeoutError.js';
+const readNdJsonStream = async function* (stream, signal, heartbeatTimeoutInMilliseconds) {
     const reader = stream.getReader();
     const decoder = new TextDecoder('utf-8');
     let buffer = '';
+    let heartbeatTimer;
+    let hasHeartbeatTimedOut = false;
+    // The timer only runs while waiting for the next line, not while the caller
+    // handles a line, so a slow caller does not cause a heartbeat timeout.
+    const startHeartbeatTimer = () => {
+        if (heartbeatTimeoutInMilliseconds === undefined || heartbeatTimer !== undefined) {
+            return;
+        }
+        heartbeatTimer = setTimeout(() => {
+            hasHeartbeatTimedOut = true;
+            reader.cancel().catch(() => {
+                // Intentionally left blank.
+            });
+        }, heartbeatTimeoutInMilliseconds);
+    };
+    const stopHeartbeatTimer = () => {
+        clearTimeout(heartbeatTimer);
+        heartbeatTimer = undefined;
+    };
     const onAbort = () => {
         reader.cancel().catch(() => {
             // Intentionally left blank.
@@ -16,6 +36,7 @@ const readNdJsonStream = async function* (stream, signal) {
     signal.addEventListener('abort', onAbort);
     try {
         while (!signal.aborted) {
+            startHeartbeatTimer();
             // biome-ignore lint/performance/noAwaitInLoops: Awaiting the result is fine here, although we are in a loop.
             const { done, value } = await reader.read();
             if (done) {
@@ -27,13 +48,18 @@ const readNdJsonStream = async function* (stream, signal) {
                 const line = buffer.slice(0, index).trim();
                 buffer = buffer.slice(index + 1);
                 if (line) {
+                    stopHeartbeatTimer();
                     yield JSON.parse(line);
                 }
                 index = buffer.indexOf('\n');
             }
         }
+        if (hasHeartbeatTimedOut) {
+            throw new HeartbeatTimeoutError();
+        }
     }
     finally {
+        stopHeartbeatTimer();
         signal.removeEventListener('abort', onAbort);
         await reader.cancel().catch(() => {
             // Intentionally left blank.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eventsourcingdb",
-  "version": "1.8.10",
+  "version": "1.9.1",
   "description": "The official JavaScript client SDK for EventSourcingDB.",
   "author": {
     "name": "the native web GmbH",
@@ -18,7 +18,7 @@
     "dist"
   ],
   "dependencies": {
-    "testcontainers": "12.1.0"
+    "testcontainers": "12.2.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.14",