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

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

@@ -1,4 +1,4 @@
-import { context as otelContext, metrics, propagation, SpanKind, SpanStatusCode, trace, } from '@opentelemetry/api';
+import { metrics, context as otelContext, propagation, SpanKind, SpanStatusCode, trace, } from '@opentelemetry/api';
 export const tracer = trace.getTracer('nimbus');
 export const DB_SYSTEM = 'eventsourcingdb';
 const meter = metrics.getMeter('nimbus');
@@ -11,6 +11,9 @@ const operationDuration = meter.createHistogram('eventsourcingdb_operation_durat
 });
 /**
  * Histogram of serialized Nimbus event sizes written via writeEvents.
+ *
+ * Recorded without attributes so the series count does not grow with
+ * streams or event types.
  */
 export const eventSizeBytes = meter.createHistogram('eventsourcingdb_event_size_bytes', {
     description: 'Size of events written to EventSourcingDB in bytes',
@@ -186,3 +189,4 @@ export async function* withAsyncGeneratorSpan(operation, fn) {
         span.end();
     }
 }
+//# sourceMappingURL=tracing.js.map

package/dist/lib/tracing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.js","sourceRoot":"","sources":["../../src/lib/tracing.ts"],"names":[],"mappings":"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"}

package/dist/lib/writeEvents.d.ts

@@ -0,0 +1,29 @@
+import type { Event } from '@nimbus-cqrs/core';
+import type { Event as EventSourcingDBEvent, Precondition } from 'eventsourcingdb';
+/**
+ * Writes one or more Nimbus events to EventSourcingDB. Each event is
+ * converted into an EventSourcingDB event candidate before being persisted.
+ *
+ * Returns the written EventSourcingDB events including the fields assigned
+ * by the server (`id`, `time`, `hash`, ...). The `id` of the last written
+ * event is the new revision of the subject and can be used with the
+ * `isSubjectOnEventId` precondition for subsequent writes.
+ *
+ * The SDK never retries a write on its own. Errors are passed through:
+ * - A `DbApiError` (from `eventsourcingdb`) when the server rejects the
+ *   write, e.g. with `code === ErrorCode.preconditionViolated` when a
+ *   precondition does not hold.
+ * - An `OutcomeUnknownError` when the write may have been stored although
+ *   the response was lost (stalled connection, abort after sending, ...).
+ *   Its `cause` holds the original error. Read the subject back before
+ *   writing again.
+ *
+ * @param events - The Nimbus events to write.
+ * @param preconditions - Optional preconditions that must be met for the write to succeed.
+ * @param signal - An optional abort signal to cancel the write. Aborting
+ *   after the request has been sent does not undo the write; the call then
+ *   throws an `OutcomeUnknownError`.
+ * @returns The written EventSourcingDB events.
+ */
+export declare const writeEvents: (events: Event[], preconditions?: Precondition[], signal?: AbortSignal) => Promise<EventSourcingDBEvent[]>;
+//# sourceMappingURL=writeEvents.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"writeEvents.d.ts","sourceRoot":"","sources":["../../src/lib/writeEvents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C,OAAO,KAAK,EAER,KAAK,IAAI,oBAAoB,EAC7B,YAAY,EACf,MAAM,iBAAiB,CAAC;AAazB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,WAAW,GACpB,QAAQ,KAAK,EAAE,EACf,gBAAgB,YAAY,EAAE,EAC9B,SAAS,WAAW,KACrB,OAAO,CAAC,oBAAoB,EAAE,CAuBhC,CAAC"}

package/dist/lib/writeEvents.js

@@ -0,0 +1,47 @@
+import { context, propagation } from '@opentelemetry/api';
+import { getEventSourcingDBClient } from "./client.js";
+import { nimbusEventToEventSourcingDBEventCandidate } from "./eventMapping.js";
+import { eventSizeBytes, withSpan } from "./tracing.js";
+const textEncoder = new TextEncoder();
+/**
+ * Returns the UTF-8 byte length of a serialized Nimbus event.
+ */
+const getEventSizeBytes = (event) => textEncoder.encode(JSON.stringify(event)).length;
+/**
+ * Writes one or more Nimbus events to EventSourcingDB. Each event is
+ * converted into an EventSourcingDB event candidate before being persisted.
+ *
+ * Returns the written EventSourcingDB events including the fields assigned
+ * by the server (`id`, `time`, `hash`, ...). The `id` of the last written
+ * event is the new revision of the subject and can be used with the
+ * `isSubjectOnEventId` precondition for subsequent writes.
+ *
+ * The SDK never retries a write on its own. Errors are passed through:
+ * - A `DbApiError` (from `eventsourcingdb`) when the server rejects the
+ *   write, e.g. with `code === ErrorCode.preconditionViolated` when a
+ *   precondition does not hold.
+ * - An `OutcomeUnknownError` when the write may have been stored although
+ *   the response was lost (stalled connection, abort after sending, ...).
+ *   Its `cause` holds the original error. Read the subject back before
+ *   writing again.
+ *
+ * @param events - The Nimbus events to write.
+ * @param preconditions - Optional preconditions that must be met for the write to succeed.
+ * @param signal - An optional abort signal to cancel the write. Aborting
+ *   after the request has been sent does not undo the write; the call then
+ *   throws an `OutcomeUnknownError`.
+ * @returns The written EventSourcingDB events.
+ */
+export const writeEvents = (events, preconditions, signal) => {
+    return withSpan('writeEvents', async () => {
+        const eventSourcingDBClient = getEventSourcingDBClient();
+        const carrier = {};
+        propagation.inject(context.active(), carrier);
+        const eventCandidates = events.map((event) => {
+            eventSizeBytes.record(getEventSizeBytes(event));
+            return nimbusEventToEventSourcingDBEventCandidate(event, carrier.traceparent, carrier.tracestate);
+        });
+        return await eventSourcingDBClient.writeEvents(eventCandidates, preconditions, signal);
+    });
+};
+//# sourceMappingURL=writeEvents.js.map

package/dist/lib/writeEvents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeEvents.js","sourceRoot":"","sources":["../../src/lib/writeEvents.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAM1D,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,0CAA0C,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExD,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;AAEtC;;GAEG;AACH,MAAM,iBAAiB,GAAG,CAAC,KAAY,EAAU,EAAE,CAC/C,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CACvB,MAAe,EACf,aAA8B,EAC9B,MAAoB,EACW,EAAE;IACjC,OAAO,QAAQ,CAAC,aAAa,EAAE,KAAK,IAAI,EAAE;QACtC,MAAM,qBAAqB,GAAG,wBAAwB,EAAE,CAAC;QAEzD,MAAM,OAAO,GAA2B,EAAE,CAAC;QAC3C,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,OAAO,CAAC,CAAC;QAE9C,MAAM,eAAe,GAAqB,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YAC3D,cAAc,CAAC,MAAM,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC;YAEhD,OAAO,0CAA0C,CAC7C,KAAK,EACL,OAAO,CAAC,WAAW,EACnB,OAAO,CAAC,UAAU,CACrB,CAAC;QACN,CAAC,CAAC,CAAC;QAEH,OAAO,MAAM,qBAAqB,CAAC,WAAW,CAC1C,eAAe,EACf,aAAa,EACb,MAAM,CACT,CAAC;IACN,CAAC,CAAC,CAAC;AACP,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-cqrs/eventsourcingdb",
-  "version": "2.4.0",
+  "version": "3.0.0-beta.1",
   "description": "Simplify Event-Driven Applications - EventSourcingDB integration for the Nimbus framework.",
   "keywords": [
     "nimbus",
@@ -13,34 +13,53 @@
     "event-store",
     "event-stream"
   ],
+  "license": "Apache-2.0",
   "author": "Daniel Gördes <d.goerdes@overlap.at> (https://overlap.at)",
   "homepage": "https://nimbus.overlap.at",
   "repository": {
     "type": "git",
-    "url": "https://github.com/overlap-dev/Nimbus"
+    "url": "https://github.com/overlap-dev/Nimbus",
+    "directory": "packages/eventsourcingdb"
   },
-  "license": "Apache-2.0",
   "bugs": {
     "url": "https://github.com/overlap-dev/Nimbus/issues"
   },
-  "module": "./esm/index.js",
+  "type": "module",
   "exports": {
     ".": {
-      "import": "./esm/index.js"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
-  "scripts": {},
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.metrics_worker.ts"
+  ],
   "engines": {
-    "node": ">=20"
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
+    "@nimbus-cqrs/core": "^3.0.0-beta.1",
     "@opentelemetry/api": "^1.9.1",
-    "eventsourcingdb": "^1.8.2",
-    "zod": "^4.4.3",
-    "@nimbus-cqrs/core": "^2.4.0"
+    "ulid": "^3.0.2"
+  },
+  "peerDependencies": {
+    "eventsourcingdb": "^2.0.0"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0"
+    "@opentelemetry/sdk-metrics": "^3.0.0",
+    "@types/node": "^26.6.5",
+    "eventsourcingdb": "^2.2.3",
+    "typescript": "^5.9.3"
   },
-  "_generatedBy": "dnt@dev"
-}
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc --noEmit",
+    "test": "node --test --test-force-exit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+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';

package/src/lib/client.ts

@@ -0,0 +1,166 @@
+import { GenericException, getLogger } from '@nimbus-cqrs/core';
+import { Client } from 'eventsourcingdb';
+import { type EventObserver, initEventObserver } from './eventObserver.ts';
+
+let eventSourcingDBClient: Client | null = null;
+
+/**
+ * Configuration options for setting up the EventSourcingDB client.
+ */
+export type SetupEventSourcingDBClientInput = {
+    /**
+     * The URL of the EventSourcingDB server.
+     */
+    url: URL;
+    /**
+     * 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.
+     */
+    eventObservers?: EventObserver[];
+};
+
+/**
+ * Initialize and configure the EventSourcingDB client.
+ *
+ * This function creates a singleton client instance, verifies connectivity by pinging
+ * 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. 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';
+ *
+ * await setupEventSourcingDBClient({
+ *     url: new URL(process.env.ESDB_URL ?? ''),
+ *     apiToken: process.env.ESDB_API_TOKEN ?? '',
+ *     eventObservers: [
+ *         {
+ *             name: 'users',
+ *             subject: '/users',
+ *             recursive: true,
+ *             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,
+ *             },
+ *             handlerRetryOptions: {
+ *                 maxRetries: 3,
+ *                 initialRetryDelayMs: 3000,
+ *             },
+ *         },
+ *     ],
+ * });
+ * ```
+ */
+export const setupEventSourcingDBClient = async ({
+    url,
+    apiToken,
+    stallTimeout,
+    eventObservers,
+}: SetupEventSourcingDBClientInput): Promise<void> => {
+    eventSourcingDBClient = new Client(
+        url,
+        apiToken,
+        stallTimeout !== undefined ? { stallTimeout } : undefined,
+    );
+
+    try {
+        await eventSourcingDBClient.ping();
+    } catch (error) {
+        getLogger().critical({
+            category: 'Nimbus',
+            message: 'Could not connect to EventSourcingDB',
+            error: error as Error,
+        });
+        throw new GenericException('Could not connect to EventSourcingDB');
+    }
+
+    try {
+        await eventSourcingDBClient.verifyApiToken();
+    } catch (error) {
+        getLogger().error({
+            category: 'Nimbus',
+            message: 'Invalid API token. Please check your API token.',
+            error: error as Error,
+        });
+        throw new GenericException(
+            'Invalid API token. Please check your API token.',
+        );
+    }
+
+    getLogger().info({
+        category: 'Nimbus',
+        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) {
+            await initEventObserver(eventObserver); // NOSONAR
+        }
+    }
+};
+
+/**
+ * Get the EventSourcingDB client instance.
+ *
+ * Returns the singleton client instance that was created by {@link setupEventSourcingDBClient}.
+ * This function must be called after the client has been initialized.
+ *
+ * @returns {Client} The EventSourcingDB client instance
+ *
+ * @throws {GenericException} If the client has not been initialized via setupEventSourcingDBClient
+ *
+ * @example
+ * ```ts
+ * import { getEventSourcingDBClient } from '@nimbus-cqrs/eventsourcingdb';
+ *
+ * const client = getEventSourcingDBClient();
+ * ```
+ */
+export const getEventSourcingDBClient = (): Client => {
+    if (!eventSourcingDBClient) {
+        throw new GenericException(
+            'EventSourcingDB client not yet initialized. Please call setupEventSourcingDBClient() first.',
+        );
+    }
+
+    return eventSourcingDBClient;
+};