@nimbus-cqrs/eventsourcingdb 2.5.0 → 3.0.0-beta.1

package/README.md

@@ -6,7 +6,6 @@
 # Nimbus EventSourcingDB
 
 Integration between Nimbus and [EventSourcingDB](https://www.eventsourcingdb.io/). The package wraps the official `eventsourcingdb` client with:
-
 - a **singleton setup** that pings the server, verifies the API token and registers long-running observers in one call,
 - typed **`writeEvents` / `readEvents`** helpers that translate between Nimbus events and EventSourcingDB events while preserving correlation IDs, data schemas and W3C trace context (`traceparent` / `tracestate`),
 - resilient **event observers** with exponential-backoff retries, jitter, position tracking across reconnects and OpenTelemetry span linking back to the original writer.
@@ -18,17 +17,29 @@ Also refer to the [EventSourcingDB documentation](https://docs.eventsourcingdb.i
 ## Install
 
 ```bash
-# Deno
-deno add npm:@nimbus-cqrs/eventsourcingdb
-
-# NPM
+# npm
 npm install @nimbus-cqrs/eventsourcingdb
 
+# pnpm
+pnpm add @nimbus-cqrs/eventsourcingdb
+
 # Bun
 bun add @nimbus-cqrs/eventsourcingdb
+
+# Deno
+deno add npm:@nimbus-cqrs/eventsourcingdb
 ```
 
-`eventsourcingdb` is a peer dependency — install it (or use one of the runtimes that resolves it via `npm:`/`jsr:` specifiers).
+`eventsourcingdb` (version 2 or later) is a peer dependency — install it alongside this package. The SDK talks to both the v2 API of EventSourcingDB 1.3+ and the v1 API of older versions and picks the right one at runtime.
+
+## Upgrading from `eventsourcingdb` 1.x
+
+If you upgrade an existing application from the 1.x SDK, see the [SDK migration guide](https://github.com/thenativeweb/eventsourcingdb-client-javascript#upgrading-from-version-1). The points that matter for Nimbus users:
+- **Server errors** are `DbApiError` instances with a `code`. Replace checks like `error.message.includes("409")` with `error instanceof DbApiError && error.code === ErrorCode.preconditionViolated`.
+- **Failed writes** whose outcome is unknown (stalled connection, abort after sending) throw an `OutcomeUnknownError` whose `cause` is the original error.
+- **Observers** no longer end quietly when the server closes the stream. Nimbus treats this as a connection failure and reconnects according to `connectionRetryOptions`.
+- **Proxies** in front of EventSourcingDB 1.3+ must allow the HTTP method `QUERY`, which the SDK uses for all reads.
+- **`writeEvents`** now returns the written events instead of `void`.
 
 # Examples
 
@@ -41,23 +52,23 @@ The snippets below use a tiny `Todo` domain to walk through the package — even
 A typical wiring at application startup: configure the client, register the observers you want to keep running, then write events from your command handlers.
 
 ```typescript
-import { createEvent } from "@nimbus-cqrs/core";
+import { createEvent } from '@nimbus-cqrs/core';
 import {
     eventSourcingDBEventToNimbusEvent,
     setupEventSourcingDBClient,
     writeEvents,
-} from "@nimbus-cqrs/eventsourcingdb";
+} from '@nimbus-cqrs/eventsourcingdb';
 
 await setupEventSourcingDBClient({
-    url: new URL(process.env.ESDB_URL ?? ""),
-    apiToken: process.env.ESDB_API_TOKEN ?? "",
+    url: new URL(process.env.ESDB_URL ?? ''),
+    apiToken: process.env.ESDB_API_TOKEN ?? '',
     eventObservers: [
         {
-            subject: "/todos",
+            subject: '/todos',
             recursive: true,
             eventHandler: async (event) => {
                 const nimbusEvent = eventSourcingDBEventToNimbusEvent(event);
-                console.log("reacting to", nimbusEvent.type, nimbusEvent.data);
+                console.log('reacting to', nimbusEvent.type, nimbusEvent.data);
             },
         },
     ],
@@ -65,10 +76,10 @@ await setupEventSourcingDBClient({
 
 await writeEvents([
     createEvent({
-        type: "com.example.todo.added",
-        source: "https://app.example.com",
-        subject: "/todos/todo-1",
-        data: { id: "todo-1", title: "Write the README" },
+        type: 'com.example.todo.added',
+        source: 'https://app.example.com',
+        subject: '/todos/todo-1',
+        data: { id: 'todo-1', title: 'Write the README' },
     }),
 ]);
 ```
@@ -81,11 +92,13 @@ await writeEvents([
 import {
     getEventSourcingDBClient,
     setupEventSourcingDBClient,
-} from "@nimbus-cqrs/eventsourcingdb";
+} from '@nimbus-cqrs/eventsourcingdb';
 
 await setupEventSourcingDBClient({
-    url: new URL(process.env.ESDB_URL ?? ""),
-    apiToken: process.env.ESDB_API_TOKEN ?? "",
+    url: new URL(process.env.ESDB_URL ?? ''),
+    apiToken: process.env.ESDB_API_TOKEN ?? '',
+    // Optional: fail a request once nothing arrives for 10 s (default 30 s).
+    stallTimeout: 10_000,
 });
 
 // Anywhere else:
@@ -94,36 +107,60 @@ const client = getEventSourcingDBClient();
 
 The `eventObservers` array is optional; passing observers here is just a convenience that calls `initEventObserver` for each entry once the client is ready.
 
+`stallTimeout` is optional as well. A request that receives nothing from the server for that long throws a `ConnectionStalledError`. Every event, row or heartbeat that arrives resets the timer, so healthy long-running streams are never cut off.
+
 ## writeEvents
 
 `writeEvents` takes an array of Nimbus events and persists them to EventSourcingDB. Before writing it wraps each event payload with Nimbus metadata (`payload` + `nimbusMeta`) so the correlation ID and optional `dataschema` survive a round-trip, and it injects the active OpenTelemetry context as `traceparent` / `tracestate` so distributed traces stitch together end-to-end.
 
 ```typescript
-import { createEvent } from "@nimbus-cqrs/core";
-import { writeEvents } from "@nimbus-cqrs/eventsourcingdb";
+import { createEvent } from '@nimbus-cqrs/core';
+import { writeEvents } from '@nimbus-cqrs/eventsourcingdb';
 
 await writeEvents([
     createEvent({
-        type: "com.example.todo.added",
-        source: "https://app.example.com",
-        subject: "/todos/todo-1",
-        data: { id: "todo-1", title: "Write the README" },
+        type: 'com.example.todo.added',
+        source: 'https://app.example.com',
+        subject: '/todos/todo-1',
+        data: { id: 'todo-1', title: 'Write the README' },
     }),
 ]);
 ```
 
-The second argument accepts EventSourcingDB [preconditions](https://docs.eventsourcingdb.io/getting-started/writing-events/#using-preconditions) — useful for optimistic concurrency, e.g. only appending an event when no event of a given type already exists for a subject:
+`writeEvents` returns the written EventSourcingDB events including the server-assigned fields (`id`, `time`, `hash`, ...). The `id` of the last written event is the new revision of the subject. This is useful for subsequent writes to the same subject or to hand it back to the client.
+
+The second argument accepts EventSourcingDB [preconditions](https://docs.eventsourcingdb.io/getting-started/writing-events/#using-preconditions) which are useful for optimistic concurrency, e.g. only appending an event when the subject has no events yet:
 
 ```typescript
-await writeEvents(
+import { isSubjectPristine } from 'eventsourcingdb';
+
+const writtenEvents = await writeEvents(
     [todoAddedEvent],
-    [
-        {
-            type: "isSubjectPristine",
-            payload: { subject: "/todos/todo-1" },
-        },
-    ],
+    [isSubjectPristine('/todos/todo-1')],
 );
+
+const revision = writtenEvents[writtenEvents.length - 1].id;
+```
+
+A violated precondition surfaces as a `DbApiError` with the code `ErrorCode.preconditionViolated`. A write whose outcome is unknown (e.g. the connection stalled after the request was sent) throws an `OutcomeUnknownError`. Better replay the subject's stream before writing again. An optional `AbortSignal` can be passed as the third argument.
+
+```typescript
+import { DbApiError, ErrorCode, isSubjectOnEventId } from 'eventsourcingdb';
+
+try {
+    await writeEvents(
+        [todoRenamedEvent],
+        [isSubjectOnEventId('/todos/todo-1', expectedRevision)],
+    );
+} catch (error) {
+    if (
+        error instanceof DbApiError &&
+        error.code === ErrorCode.preconditionViolated
+    ) {
+        // Somebody else modified the todo in the meantime.
+    }
+    throw error;
+}
 ```
 
 ## readEvents
@@ -134,9 +171,9 @@ await writeEvents(
 import {
     eventSourcingDBEventToNimbusEvent,
     readEvents,
-} from "@nimbus-cqrs/eventsourcingdb";
+} from '@nimbus-cqrs/eventsourcingdb';
 
-for await (const event of readEvents("/todos/todo-1", { recursive: false })) {
+for await (const event of readEvents('/todos/todo-1', { recursive: false })) {
     const nimbusEvent = eventSourcingDBEventToNimbusEvent(event);
     // ...rebuild your aggregate, replay state, etc.
 }
@@ -147,8 +184,7 @@ Pass an `AbortSignal` as the third argument if you need to cancel a long-running
 ## Event observers
 
 An `EventObserver` is a long-running consumer attached to a subject. `initEventObserver` (or the `eventObservers` array on `setupEventSourcingDBClient`) starts it in the background and keeps it alive. Connection and handler failures are retried separately with exponential backoff plus jitter (defaults: 3 retries, 3000 ms initial delay for each):
-
-- **Connection failures** reconnect the observe stream (`connectionRetryOptions`; deprecated alias: `retryOptions`).
+- **Connection failures** reconnect the observe stream (`connectionRetryOptions`; deprecated alias: `retryOptions`). Observing never ends on its own. A stream closed by the server (e.g. during a restart) or a stalled connection counts as a connection failure, so size the retries for the longest outage an observer should survive.
 - **Handler failures** are retried in-place without reconnecting (`handlerRetryOptions`). After handler retries are exhausted the event is skipped (optional `onHandlerError`) and observation continues.
 
 On every handled or skipped event the observer advances its lower bound so a reconnection resumes from exactly where it left off — no replays, no gaps.
@@ -156,19 +192,19 @@ On every handled or skipped event the observer advances its lower bound so a rec
 Each event handler runs inside an OpenTelemetry span. If the source event carries a `traceparent`, that span is linked back to the writer's trace, giving you end-to-end visibility from the command that produced the event to every subscriber that reacted to it.
 
 ```typescript
-import { getLogger } from "@nimbus-cqrs/core";
-import { initEventObserver } from "@nimbus-cqrs/eventsourcingdb";
+import { getLogger } from '@nimbus-cqrs/core';
+import { initEventObserver } from '@nimbus-cqrs/eventsourcingdb';
 
 initEventObserver({
-    subject: "/todos",
+    subject: '/todos',
     recursive: true,
     fromLatestEvent: {
-        subject: "/todos",
-        type: "com.example.todo.added",
-        ifEventIsMissing: "read-everything",
+        subject: '/todos',
+        type: 'com.example.todo.added',
+        ifEventIsMissing: 'read-everything',
     },
     eventHandler: async (event) => {
-        if (event.type === "com.example.todo.added") {
+        if (event.type === 'com.example.todo.added') {
             // ...update a read model, send a notification, ...
         }
     },
@@ -182,7 +218,7 @@ initEventObserver({
     },
     onHandlerError: (error, event) => {
         getLogger().error({
-            category: "EventObserver",
+            category: 'EventObserver',
             message: `Skipping event after handler retries: ${event.id}`,
             error,
         });
@@ -215,7 +251,7 @@ import {
     eventSourcingDBEventToNimbusEvent,
     isEventData,
     nimbusEventToEventSourcingDBEventCandidate,
-} from "@nimbus-cqrs/eventsourcingdb";
+} from '@nimbus-cqrs/eventsourcingdb';
 ```
 
 - `nimbusEventToEventSourcingDBEventCandidate(event)` — manual conversion, e.g. when batching with the raw client.

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './lib/client.ts';
+export * from './lib/eventConsumer.ts';
+export * from './lib/eventMapping.ts';
+export * from './lib/eventObserver.ts';
+export * from './lib/observerRegistry.ts';
+export * from './lib/readEvents.ts';
+export * from './lib/writeEvents.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./lib/client.js";
+export * from "./lib/eventConsumer.js";
+export * from "./lib/eventMapping.js";
+export * from "./lib/eventObserver.js";
+export * from "./lib/observerRegistry.js";
+export * from "./lib/readEvents.js";
+export * from "./lib/writeEvents.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC"}

package/{esm → dist}/lib/client.d.ts

@@ -1,5 +1,5 @@
 import { Client } from 'eventsourcingdb';
-import { type EventObserver } from './eventObserver.js';
+import { type EventObserver } from './eventObserver.ts';
 /**
  * Configuration options for setting up the EventSourcingDB client.
  */
@@ -12,6 +12,14 @@ export type SetupEventSourcingDBClientInput = {
      * The API token for authenticating with EventSourcingDB.
      */
     apiToken: string;
+    /**
+     * The stall timeout in milliseconds. A request fails with a
+     * `ConnectionStalledError` once nothing arrives from the server for
+     * this long. Every item received (events, rows, heartbeats) resets the
+     * timer, so long-running streams are never cut off while they are
+     * healthy. Defaults to 30000ms (the SDK default).
+     */
+    stallTimeout?: number;
     /**
      * An optional array of event observers to observe events.
      */
@@ -24,41 +32,44 @@ export type SetupEventSourcingDBClientInput = {
  * the server, and validates the provided API token. It should be called once at
  * application startup before using {@link getEventSourcingDBClient}.
  *
- * Optionally, you can provide event observers that will start observing events
- * in the background after the client is initialized.
+ * Optionally, you can provide event observers. They are started one after
+ * another once the client is initialized. Each one loads its consumers'
+ * checkpoints before the function resolves, so a checkpoint store that
+ * cannot be reached fails the setup.
  *
  * @param {SetupEventSourcingDBClientInput} options - The configuration options
  * @param {URL} options.url - The URL of the EventSourcingDB server
  * @param {string} options.apiToken - The API token for authentication
+ * @param {number} [options.stallTimeout] - Optional stall timeout in milliseconds (defaults to 30000)
  * @param {EventObserver[]} [options.eventObservers] - Optional array of event observers
  *
  * @throws {GenericException} If the connection to EventSourcingDB fails
  * @throws {GenericException} If the API token is invalid
+ * @throws {GenericException} If an event observer cannot be started
  *
  * @example
  * ```ts
+ * import { InMemoryCheckpointStore } from '@nimbus-cqrs/core';
  * import { setupEventSourcingDBClient } from '@nimbus-cqrs/eventsourcingdb';
- * import type { Event } from 'eventsourcingdb';
  *
  * await setupEventSourcingDBClient({
  *     url: new URL(process.env.ESDB_URL ?? ''),
  *     apiToken: process.env.ESDB_API_TOKEN ?? '',
  *     eventObservers: [
  *         {
+ *             name: 'users',
  *             subject: '/users',
  *             recursive: true,
- *             lowerBound: {
- *                 id: 'last-processed-event-id',
- *                 type: 'exclusive',
- *             },
- *             fromLatestEvent: {
- *                 subject: '/users',
- *                 type: 'io.nimbus.users.invited',
- *                 ifEventIsMissing: 'read-everything',
- *             },
- *             eventHandler: async (event: Event) => {
- *                 console.log('Received event:', event);
- *             },
+ *             checkpointStore: new InMemoryCheckpointStore(),
+ *             consumers: [
+ *                 {
+ *                     name: 'users.projection',
+ *                     handles: (event) => event.type.startsWith('io.nimbus.users.'),
+ *                     handle: async (event) => {
+ *                         console.log('Received event:', event);
+ *                     },
+ *                 },
+ *             ],
  *             connectionRetryOptions: {
  *                 maxRetries: 3,
  *                 initialRetryDelayMs: 3000,
@@ -72,7 +83,7 @@ export type SetupEventSourcingDBClientInput = {
  * });
  * ```
  */
-export declare const setupEventSourcingDBClient: ({ url, apiToken, eventObservers }: SetupEventSourcingDBClientInput) => Promise<void>;
+export declare const setupEventSourcingDBClient: ({ url, apiToken, stallTimeout, eventObservers, }: SetupEventSourcingDBClientInput) => Promise<void>;
 /**
  * Get the EventSourcingDB client instance.
  *

package/{esm → dist}/lib/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,KAAK,aAAa,EAAqB,MAAM,oBAAoB,CAAC;AAI3E;;GAEG;AACH,MAAM,MAAM,+BAA+B,GAAG;IAC1C;;OAEG;IACH,GAAG,EAAE,GAAG,CAAC;IACT;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;CACpC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,eAAO,MAAM,0BAA0B,GACnC,mCAAmC,+BAA+B,KACnE,OAAO,CAAC,IAAI,CA0Cd,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,wBAAwB,QAAO,MAQ3C,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,KAAK,aAAa,EAAqB,MAAM,oBAAoB,CAAC;AAI3E;;GAEG;AACH,MAAM,MAAM,+BAA+B,GAAG;IAC1C;;OAEG;IACH,GAAG,EAAE,GAAG,CAAC;IACT;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;CACpC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,eAAO,MAAM,0BAA0B,GAAU,kDAK9C,+BAA+B,KAAG,OAAO,CAAC,IAAI,CA2ChD,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,wBAAwB,QAAO,MAQ3C,CAAC"}

package/{esm → dist}/lib/client.js

@@ -1,6 +1,6 @@
 import { GenericException, getLogger } from '@nimbus-cqrs/core';
 import { Client } from 'eventsourcingdb';
-import { initEventObserver } from './eventObserver.js';
+import { initEventObserver } from "./eventObserver.js";
 let eventSourcingDBClient = null;
 /**
  * Initialize and configure the EventSourcingDB client.
@@ -9,41 +9,44 @@ let eventSourcingDBClient = null;
  * the server, and validates the provided API token. It should be called once at
  * application startup before using {@link getEventSourcingDBClient}.
  *
- * Optionally, you can provide event observers that will start observing events
- * in the background after the client is initialized.
+ * Optionally, you can provide event observers. They are started one after
+ * another once the client is initialized. Each one loads its consumers'
+ * checkpoints before the function resolves, so a checkpoint store that
+ * cannot be reached fails the setup.
  *
  * @param {SetupEventSourcingDBClientInput} options - The configuration options
  * @param {URL} options.url - The URL of the EventSourcingDB server
  * @param {string} options.apiToken - The API token for authentication
+ * @param {number} [options.stallTimeout] - Optional stall timeout in milliseconds (defaults to 30000)
  * @param {EventObserver[]} [options.eventObservers] - Optional array of event observers
  *
  * @throws {GenericException} If the connection to EventSourcingDB fails
  * @throws {GenericException} If the API token is invalid
+ * @throws {GenericException} If an event observer cannot be started
  *
  * @example
  * ```ts
+ * import { InMemoryCheckpointStore } from '@nimbus-cqrs/core';
  * import { setupEventSourcingDBClient } from '@nimbus-cqrs/eventsourcingdb';
- * import type { Event } from 'eventsourcingdb';
  *
  * await setupEventSourcingDBClient({
  *     url: new URL(process.env.ESDB_URL ?? ''),
  *     apiToken: process.env.ESDB_API_TOKEN ?? '',
  *     eventObservers: [
  *         {
+ *             name: 'users',
  *             subject: '/users',
  *             recursive: true,
- *             lowerBound: {
- *                 id: 'last-processed-event-id',
- *                 type: 'exclusive',
- *             },
- *             fromLatestEvent: {
- *                 subject: '/users',
- *                 type: 'io.nimbus.users.invited',
- *                 ifEventIsMissing: 'read-everything',
- *             },
- *             eventHandler: async (event: Event) => {
- *                 console.log('Received event:', event);
- *             },
+ *             checkpointStore: new InMemoryCheckpointStore(),
+ *             consumers: [
+ *                 {
+ *                     name: 'users.projection',
+ *                     handles: (event) => event.type.startsWith('io.nimbus.users.'),
+ *                     handle: async (event) => {
+ *                         console.log('Received event:', event);
+ *                     },
+ *                 },
+ *             ],
  *             connectionRetryOptions: {
  *                 maxRetries: 3,
  *                 initialRetryDelayMs: 3000,
@@ -57,8 +60,8 @@ let eventSourcingDBClient = null;
  * });
  * ```
  */
-export const setupEventSourcingDBClient = async ({ url, apiToken, eventObservers }) => {
-    eventSourcingDBClient = new Client(url, apiToken);
+export const setupEventSourcingDBClient = async ({ url, apiToken, stallTimeout, eventObservers, }) => {
+    eventSourcingDBClient = new Client(url, apiToken, stallTimeout !== undefined ? { stallTimeout } : undefined);
     try {
         await eventSourcingDBClient.ping();
     }
@@ -86,8 +89,10 @@ export const setupEventSourcingDBClient = async ({ url, apiToken, eventObservers
         message: 'EventSourcingDB client initialized successfully',
     });
     if (eventObservers?.length) {
+        // Sequential on purpose: observers register in declaration order
+        // and the first one that cannot start fails the setup.
         for (const eventObserver of eventObservers) {
-            initEventObserver(eventObserver);
+            await initEventObserver(eventObserver); // NOSONAR
         }
     }
 };
@@ -114,3 +119,4 @@ export const getEventSourcingDBClient = () => {
     }
     return eventSourcingDBClient;
 };
+//# sourceMappingURL=client.js.map

package/dist/lib/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAsB,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE3E,IAAI,qBAAqB,GAAkB,IAAI,CAAC;AA4BhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,KAAK,EAAE,EAC7C,GAAG,EACH,QAAQ,EACR,YAAY,EACZ,cAAc,GACgB,EAAiB,EAAE;IACjD,qBAAqB,GAAG,IAAI,MAAM,CAC9B,GAAG,EACH,QAAQ,EACR,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,SAAS,CAC5D,CAAC;IAEF,IAAI,CAAC;QACD,MAAM,qBAAqB,CAAC,IAAI,EAAE,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,SAAS,EAAE,CAAC,QAAQ,CAAC;YACjB,QAAQ,EAAE,QAAQ;YAClB,OAAO,EAAE,sCAAsC;YAC/C,KAAK,EAAE,KAAc;SACxB,CAAC,CAAC;QACH,MAAM,IAAI,gBAAgB,CAAC,sCAAsC,CAAC,CAAC;IACvE,CAAC;IAED,IAAI,CAAC;QACD,MAAM,qBAAqB,CAAC,cAAc,EAAE,CAAC;IACjD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,SAAS,EAAE,CAAC,KAAK,CAAC;YACd,QAAQ,EAAE,QAAQ;YAClB,OAAO,EAAE,iDAAiD;YAC1D,KAAK,EAAE,KAAc;SACxB,CAAC,CAAC;QACH,MAAM,IAAI,gBAAgB,CACtB,iDAAiD,CACpD,CAAC;IACN,CAAC;IAED,SAAS,EAAE,CAAC,IAAI,CAAC;QACb,QAAQ,EAAE,QAAQ;QAClB,OAAO,EAAE,iDAAiD;KAC7D,CAAC,CAAC;IAEH,IAAI,cAAc,EAAE,MAAM,EAAE,CAAC;QACzB,iEAAiE;QACjE,uDAAuD;QACvD,KAAK,MAAM,aAAa,IAAI,cAAc,EAAE,CAAC;YACzC,MAAM,iBAAiB,CAAC,aAAa,CAAC,CAAC,CAAC,UAAU;QACtD,CAAC;IACL,CAAC;AACL,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAW,EAAE;IACjD,IAAI,CAAC,qBAAqB,EAAE,CAAC;QACzB,MAAM,IAAI,gBAAgB,CACtB,6FAA6F,CAChG,CAAC;IACN,CAAC;IAED,OAAO,qBAAqB,CAAC;AACjC,CAAC,CAAC"}

package/dist/lib/consumerRunner.d.ts

@@ -0,0 +1,62 @@
+import { type CheckpointStore } from '@nimbus-cqrs/core';
+import type { Event as EventSourcingDBEvent } from 'eventsourcingdb';
+import type { ConsumerStatus, EventConsumer } from './eventConsumer.ts';
+/**
+ * Where an observer starts reading the stream.
+ */
+export type Bound = {
+    id: string;
+    type: 'inclusive' | 'exclusive';
+};
+/**
+ * Runs the consumers of one observer and keeps their checkpoints.
+ */
+export type ConsumerRunner = {
+    /**
+     * The lowest position of all consumers, from where the observer has
+     * to resume so that every consumer sees what it still misses.
+     */
+    readonly lowerBound: Bound;
+    /**
+     * Offers one event to every consumer in declaration order. Rejects
+     * when at least one consumer failed so the observer retries in place.
+     */
+    readonly handle: (raw: EventSourcingDBEvent) => Promise<void>;
+    /**
+     * Halts the consumers that failed on the most recent attempt and
+     * persists their failure. Called once handler retries are exhausted.
+     */
+    readonly onExhausted: (error: Error, raw: EventSourcingDBEvent) => Promise<void>;
+    /**
+     * The current state of every consumer.
+     */
+    readonly status: () => ConsumerStatus[];
+};
+export type CreateConsumerRunnerOptions = {
+    observer: string;
+    consumers: readonly EventConsumer[];
+    checkpointStore: CheckpointStore;
+    head: string | null;
+};
+/**
+ * Wires the consumers of one observer onto a shared stream.
+ *
+ * Consumers run sequentially in declaration order. Every non-halted
+ * consumer advances its position on every event — handled or not — which
+ * keeps the position contiguous and lets a restart resume exactly where it
+ * stopped.
+ *
+ * A consumer that throws holds its position while its siblings advance, as
+ * does every consumer that depends on it. The handler then rejects so the
+ * observer retries in place. On the next retry the advanced consumers skip
+ * themselves, so only the failing ones run again. Once retries are
+ * exhausted those consumers are halted. They are skipped for the rest of
+ * the process lifetime and their checkpoint stays at the last event they
+ * finished, so a restart resumes at the event they could not handle.
+ *
+ * Consumers with `startFrom: 'head'` ignore their stored position and
+ * start at the head of the subject on every start. Their checkpoint is
+ * still written like any other, so operators see where they are.
+ */
+export declare const createConsumerRunner: ({ observer, consumers, checkpointStore, head, }: CreateConsumerRunnerOptions) => Promise<ConsumerRunner>;
+//# sourceMappingURL=consumerRunner.d.ts.map

package/dist/lib/consumerRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumerRunner.d.ts","sourceRoot":"","sources":["../../src/lib/consumerRunner.ts"],"names":[],"mappings":"AAAA,OAAO,EAEH,KAAK,eAAe,EAKvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,KAAK,IAAI,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGxE;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,GAAG,WAAW,CAAC;CACnC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IACzB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,oBAAoB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,CAClB,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,oBAAoB,KACxB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,cAAc,EAAE,CAAC;CAC3C,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;IACpC,eAAe,EAAE,eAAe,CAAC;IACjC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AA8NF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,oBAAoB,GAAU,iDAKxC,2BAA2B,KAAG,OAAO,CAAC,cAAc,CAmStD,CAAC"}