@nimbus-cqrs/eventsourcingdb 2.0.0-beta.0

package/esm/lib/eventMapping.d.ts

@@ -0,0 +1,51 @@
+import { type Event } from '../deps/jsr.io/@nimbus/core/2.0.0/src/index.js';
+import type { Event as EventSourcingDBEvent, EventCandidate } from 'eventsourcingdb';
+/**
+ * Metadata that Nimbus attaches to events stored in EventSourcingDB
+ * to preserve correlation and schema information.
+ *
+ * @property {string} correlationid - A globally unique identifier that indicates a correlation to previous and subsequent messages.
+ * @property {string} dataschema - An absolute URL to the schema that the data adheres to (optional).
+ */
+export type NimbusEventMetadata = {
+    correlationid: string;
+    dataschema?: string;
+};
+/**
+ * The data structure used to store Nimbus events in EventSourcingDB.
+ * It wraps the original event payload together with Nimbus-specific metadata.
+ *
+ * @property {Record<string, unknown>} payload - The actual business data of the event.
+ * @property {NimbusEventMetadata} nimbusMeta - Nimbus-specific metadata such as correlation id and data schema.
+ */
+export type EventData = {
+    payload: Record<string, unknown>;
+    nimbusMeta: NimbusEventMetadata;
+};
+/**
+ * Type guard that checks whether the given value conforms to the {@link EventData} structure
+ * by verifying the presence of both `payload` and `nimbusMeta` properties.
+ *
+ * @param data - The value to check.
+ * @returns `true` if the value is an {@link EventData}, `false` otherwise.
+ */
+export declare const isEventData: (data: unknown) => data is EventData;
+/**
+ * Converts a Nimbus {@link Event} into an EventSourcingDB {@link EventCandidate}
+ * by mapping the event properties and wrapping the data with Nimbus metadata.
+ *
+ * @param event - The Nimbus event to convert.
+ * @returns An EventSourcingDB event candidate ready to be written.
+ */
+export declare const nimbusEventToEventSourcingDBEventCandidate: (event: Event, traceparent?: string, tracestate?: string) => EventCandidate;
+/**
+ * Converts an EventSourcingDB event back into a Nimbus {@link Event}.
+ * If the event data contains Nimbus metadata, it extracts the original payload
+ * and correlation information. Otherwise, it treats the entire data as the payload
+ * and generates a new correlation id.
+ *
+ * @param eventSourcingDBEvent - The EventSourcingDB event to convert.
+ * @returns A Nimbus event.
+ */
+export declare const eventSourcingDBEventToNimbusEvent: <TEvent extends Event>(eventSourcingDBEvent: EventSourcingDBEvent) => TEvent;
+//# sourceMappingURL=eventMapping.d.ts.map

package/esm/lib/eventMapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventMapping.d.ts","sourceRoot":"","sources":["../../src/lib/eventMapping.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,gDAAgD,CAAC;AAEzF,OAAO,KAAK,EACR,KAAK,IAAI,oBAAoB,EAC7B,cAAc,EACjB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG;IACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,UAAU,EAAE,mBAAmB,CAAC;CACnC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,OAAO,KAAG,IAAI,IAAI,SAOnD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,0CAA0C,GACnD,OAAO,KAAK,EACZ,cAAc,MAAM,EACpB,aAAa,MAAM,KACpB,cAeF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,iCAAiC,GAAI,MAAM,SAAS,KAAK,EAClE,sBAAsB,oBAAoB,KAC3C,MAwBF,CAAC"}

package/esm/lib/eventMapping.js

@@ -0,0 +1,71 @@
+import { createEvent } from '../deps/jsr.io/@nimbus/core/2.0.0/src/index.js';
+import { ulid } from '../deps/jsr.io/@std/ulid/1.0.0/mod.js';
+/**
+ * Type guard that checks whether the given value conforms to the {@link EventData} structure
+ * by verifying the presence of both `payload` and `nimbusMeta` properties.
+ *
+ * @param data - The value to check.
+ * @returns `true` if the value is an {@link EventData}, `false` otherwise.
+ */
+export const isEventData = (data) => {
+    return (typeof data === 'object' &&
+        data !== null &&
+        'payload' in data &&
+        'nimbusMeta' in data);
+};
+/**
+ * Converts a Nimbus {@link Event} into an EventSourcingDB {@link EventCandidate}
+ * by mapping the event properties and wrapping the data with Nimbus metadata.
+ *
+ * @param event - The Nimbus event to convert.
+ * @returns An EventSourcingDB event candidate ready to be written.
+ */
+export const nimbusEventToEventSourcingDBEventCandidate = (event, traceparent, tracestate) => {
+    return {
+        source: event.source,
+        subject: event.subject,
+        type: event.type,
+        data: {
+            payload: event.data,
+            nimbusMeta: {
+                correlationid: event.correlationid,
+                ...(event.dataschema && { dataschema: event.dataschema }),
+            },
+        },
+        ...(traceparent && { traceparent: traceparent }),
+        ...(tracestate && { tracestate: tracestate }),
+    };
+};
+/**
+ * Converts an EventSourcingDB event back into a Nimbus {@link Event}.
+ * If the event data contains Nimbus metadata, it extracts the original payload
+ * and correlation information. Otherwise, it treats the entire data as the payload
+ * and generates a new correlation id.
+ *
+ * @param eventSourcingDBEvent - The EventSourcingDB event to convert.
+ * @returns A Nimbus event.
+ */
+export const eventSourcingDBEventToNimbusEvent = (eventSourcingDBEvent) => {
+    let data;
+    let correlationid;
+    let dataschema;
+    if (isEventData(eventSourcingDBEvent.data)) {
+        data = eventSourcingDBEvent.data.payload;
+        correlationid = eventSourcingDBEvent.data.nimbusMeta.correlationid;
+        dataschema = eventSourcingDBEvent.data.nimbusMeta.dataschema;
+    }
+    else {
+        data = eventSourcingDBEvent.data;
+        correlationid = ulid();
+    }
+    return createEvent({
+        id: eventSourcingDBEvent.id,
+        time: eventSourcingDBEvent.time.toISOString(),
+        source: eventSourcingDBEvent.source,
+        subject: eventSourcingDBEvent.subject,
+        type: eventSourcingDBEvent.type,
+        correlationid: correlationid,
+        data: data,
+        ...(dataschema && { dataschema: dataschema }),
+    });
+};

package/esm/lib/eventObserver.d.ts

@@ -0,0 +1,85 @@
+import type { Event as EventSourcingDBEvent } from 'eventsourcingdb';
+type Bound = {
+    id: string;
+    type: 'inclusive' | 'exclusive';
+};
+type ObserveFromLatestEvent = {
+    subject: string;
+    type: string;
+    ifEventIsMissing: 'read-everything' | 'wait-for-event';
+};
+export type RetryOptions = {
+    /**
+     * The maximum number of retry attempts before giving up.
+     * Defaults to 3.
+     */
+    maxRetries: number;
+    /**
+     * The initial delay in milliseconds before the first retry.
+     * Subsequent retries will use exponential backoff with jitter.
+     * Defaults to 3000ms.
+     */
+    initialRetryDelayMs: number;
+};
+/**
+ * An event observer defines a handler function which will be applied to each event
+ * and the options to observe the events according to the EventSourcingDB API.
+ *
+ * See https://docs.eventsourcingdb.io/getting-started/observing-events for more information.
+ */
+export type EventObserver = {
+    /**
+     * The subject of the events to observe.
+     */
+    subject: string;
+    /**
+     * Whether to observe events recursively.
+     * Defaults to false.
+     */
+    recursive?: boolean;
+    /**
+     * The lower bound of the events to observe.
+     * Defaults to undefined.
+     */
+    lowerBound?: Bound;
+    /**
+     * The from latest event to observe.
+     * Defaults to undefined.
+     */
+    fromLatestEvent?: ObserveFromLatestEvent;
+    /**
+     * The event handler which will be called when an event is observed.
+     *
+     * @param event - The EventSourcingDB event that was observed.
+     * @returns A promise that resolves when the event has been handled.
+     */
+    eventHandler: (event: EventSourcingDBEvent) => Promise<void> | void;
+    /**
+     * Options for retry behavior when the connection fails.
+     * Uses exponential backoff with jitter between retries.
+     * Defaults to { maxRetries: 3, initialRetryDelayMs: 3000 }.
+     */
+    retryOptions?: RetryOptions;
+};
+/**
+ * Calculates an exponential backoff delay with jitter for a given
+ * retry attempt. The jitter adds up to 30% of the base delay to
+ * avoid thundering-herd effects.
+ *
+ * @param initialDelayMs - The base delay in milliseconds before
+ *   exponential scaling.
+ * @param attempt - The zero-based retry attempt number.
+ * @returns The backoff delay in milliseconds.
+ */
+export declare const calculateBackoffDelay: (initialDelayMs: number, attempt: number) => number;
+/**
+ * Initializes an event observer by starting the observation loop in
+ * the background (non-blocking). The observer will keep running and
+ * reconnecting according to its retry options until the stream ends
+ * or retries are exhausted.
+ *
+ * @param eventObserver - The event observer configuration.
+ */
+export declare const initEventObserver: (eventObserver: EventObserver) => void;
+export {};
+//# sourceMappingURL=eventObserver.d.ts.map

package/esm/lib/eventObserver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventObserver.d.ts","sourceRoot":"","sources":["../../src/lib/eventObserver.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,IAAI,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAIrE,KAAK,KAAK,GAAG;IACT,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,GAAG,WAAW,CAAC;CACnC,CAAC;AAEF,KAAK,sBAAsB,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,iBAAiB,GAAG,gBAAgB,CAAC;CAC1D,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACvB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,mBAAmB,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG;IACxB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,KAAK,CAAC;IACnB;;;OAGG;IACH,eAAe,CAAC,EAAE,sBAAsB,CAAC;IACzC;;;;;OAKG;IACH,YAAY,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpE;;;;OAIG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;CAC/B,CAAC;AAQF;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,GAC9B,gBAAgB,MAAM,EACtB,SAAS,MAAM,KAChB,MAOF,CAAC;AA+KF;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,GAAI,eAAe,aAAa,KAAG,IAEhE,CAAC"}

package/esm/lib/eventObserver.js

@@ -0,0 +1,154 @@
+import { getLogger } from '../deps/jsr.io/@nimbus/core/2.0.0/src/index.js';
+import { getEventSourcingDBClient } from './client.js';
+import { withSpan } from './tracing.js';
+/**
+ * Returns a promise that resolves after the given number of milliseconds.
+ */
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Calculates an exponential backoff delay with jitter for a given
+ * retry attempt. The jitter adds up to 30% of the base delay to
+ * avoid thundering-herd effects.
+ *
+ * @param initialDelayMs - The base delay in milliseconds before
+ *   exponential scaling.
+ * @param attempt - The zero-based retry attempt number.
+ * @returns The backoff delay in milliseconds.
+ */
+export const calculateBackoffDelay = (initialDelayMs, attempt) => {
+    const baseDelay = initialDelayMs * Math.pow(2, attempt);
+    // Add jitter: random value between 0 and 30% of the base delay
+    const jitter = Math.random() * baseDelay * 0.3;
+    return Math.floor(baseDelay + jitter);
+};
+/**
+ * Logs an informational message when an event observer connects or
+ * reconnects to EventSourcingDB. When {@link retryCount} is greater
+ * than zero the message indicates a successful reconnection.
+ *
+ * @param subject - The observed subject.
+ * @param retryCount - The number of retries that preceded this
+ *   connection (0 for the initial connection).
+ * @param data - Additional context logged alongside the message.
+ */
+const logObserverConnection = (subject, retryCount, data) => {
+    const retryLabel = retryCount === 1 ? 'retry' : 'retries';
+    const message = retryCount > 0
+        ? `Reconnected event observer for subject "${subject}" after ${retryCount} ${retryLabel}`
+        : `Observing events for subject "${subject}"`;
+    getLogger().info({ category: 'Nimbus', message, data });
+};
+/**
+ * Handles an observer error by logging it and waiting with exponential
+ * backoff before the next retry attempt. When the maximum number of
+ * retries is exceeded a critical log entry is emitted and no further
+ * retries are attempted.
+ *
+ * @param error - The error that caused the observer to disconnect.
+ * @param subject - The observed subject.
+ * @param retryCount - The current (1-based) retry attempt number.
+ * @param maxRetries - The maximum number of allowed retries.
+ * @param initialRetryDelayMs - The base delay used for exponential
+ *   backoff calculation.
+ * @returns `true` if the observer should retry, `false` if retries
+ *   are exhausted.
+ */
+const handleObserverError = async (error, subject, retryCount, maxRetries, initialRetryDelayMs) => {
+    if (retryCount > maxRetries) {
+        getLogger().critical({
+            category: 'Nimbus',
+            message: `Failed to observe events for subject "${subject}" after ${maxRetries} ${maxRetries === 1 ? 'retry' : 'retries'}.`,
+        });
+        return false;
+    }
+    const backoffDelay = calculateBackoffDelay(initialRetryDelayMs, retryCount - 1);
+    getLogger().error({
+        category: 'Nimbus',
+        message: `Error observing events for subject "${subject}" (retry ${retryCount}/${maxRetries}), retrying in ${backoffDelay}ms`,
+        error: error,
+    });
+    await delay(backoffDelay);
+    return true;
+};
+/**
+ * Starts observing events for the given {@link EventObserver} with
+ * automatic reconnection on failure.
+ *
+ * On each connection attempt the EventSourcingDB server is pinged
+ * first. Events are then consumed from the stream and each one is
+ * passed to the observer's event handler inside an OpenTelemetry
+ * span. If the event carries a `traceparent`, the span is linked to
+ * the original writer's trace for end-to-end distributed tracing.
+ *
+ * After every successfully handled event the lower bound is advanced
+ * so that a reconnection resumes from the last processed position.
+ *
+ * When the connection drops, exponential backoff with jitter is
+ * applied up to the configured maximum number of retries.
+ *
+ * @param eventObserver - The event observer configuration.
+ */
+const observeWithRetry = async (eventObserver) => {
+    const eventSourcingDBClient = getEventSourcingDBClient();
+    const maxRetries = eventObserver.retryOptions?.maxRetries ?? 3;
+    const initialRetryDelayMs = eventObserver.retryOptions?.initialRetryDelayMs ?? 3000;
+    let retryCount = 0;
+    let lastProcessedEventId;
+    while (true) {
+        try {
+            // Once we have a concrete position, use it as lower bound and
+            // drop fromLatestEvent; otherwise fall back to the original options.
+            const lowerBound = lastProcessedEventId
+                ? { id: lastProcessedEventId, type: 'exclusive' }
+                : eventObserver.lowerBound;
+            const fromLatestEvent = lastProcessedEventId
+                ? undefined
+                : eventObserver.fromLatestEvent;
+            // Verify connection
+            await eventSourcingDBClient.ping();
+            logObserverConnection(eventObserver.subject, retryCount, {
+                recursive: eventObserver.recursive ?? false,
+                lowerBound,
+                fromLatestEvent,
+            });
+            retryCount = 0;
+            for await (const event of eventSourcingDBClient.observeEvents(eventObserver.subject, {
+                recursive: eventObserver.recursive ?? false,
+                ...(lowerBound ? { lowerBound } : {}),
+                ...(fromLatestEvent ? { fromLatestEvent } : {}),
+            })) {
+                const traceContext = event.traceparent
+                    ? {
+                        traceparent: event.traceparent,
+                        tracestate: event.tracestate,
+                    }
+                    : undefined;
+                await withSpan('observeEvent', async () => {
+                    await eventObserver.eventHandler(event);
+                }, traceContext);
+                // Track last processed position so retries resume from here
+                lastProcessedEventId = event.id;
+            }
+            // If the loop completes normally (stream ended), we're done
+            return;
+        }
+        catch (error) {
+            retryCount++;
+            const shouldRetry = await handleObserverError(error, eventObserver.subject, retryCount, maxRetries, initialRetryDelayMs);
+            if (!shouldRetry) {
+                return;
+            }
+        }
+    }
+};
+/**
+ * Initializes an event observer by starting the observation loop in
+ * the background (non-blocking). The observer will keep running and
+ * reconnecting according to its retry options until the stream ends
+ * or retries are exhausted.
+ *
+ * @param eventObserver - The event observer configuration.
+ */
+export const initEventObserver = (eventObserver) => {
+    observeWithRetry(eventObserver);
+};

package/esm/lib/readEvents.d.ts

@@ -0,0 +1,16 @@
+import type { Event, ReadEventsOptions } from 'eventsourcingdb';
+/**
+ * Reads events from EventSourcingDB for a given subject.
+ *
+ * Returns an async generator that yields raw EventSourcingDB
+ * {@link Event} instances (not Nimbus events). Use
+ * {@link eventSourcingDBEventToNimbusEvent} to convert them
+ * into Nimbus events if needed.
+ *
+ * @param subject - The subject to read events for.
+ * @param options - Options to control which events are read.
+ * @param signal - An optional abort signal to cancel the read.
+ * @returns An async generator yielding EventSourcingDB events.
+ */
+export declare const readEvents: (subject: string, options: ReadEventsOptions, signal?: AbortSignal) => AsyncGenerator<Event, void, void>;
+//# sourceMappingURL=readEvents.d.ts.map

package/esm/lib/readEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readEvents.d.ts","sourceRoot":"","sources":["../../src/lib/readEvents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAIhE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU,GACnB,SAAS,MAAM,EACf,SAAS,iBAAiB,EAC1B,SAAS,WAAW,KACrB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAUlC,CAAC"}

package/esm/lib/readEvents.js

@@ -0,0 +1,21 @@
+import { getEventSourcingDBClient } from './client.js';
+import { withAsyncGeneratorSpan } from './tracing.js';
+/**
+ * Reads events from EventSourcingDB for a given subject.
+ *
+ * Returns an async generator that yields raw EventSourcingDB
+ * {@link Event} instances (not Nimbus events). Use
+ * {@link eventSourcingDBEventToNimbusEvent} to convert them
+ * into Nimbus events if needed.
+ *
+ * @param subject - The subject to read events for.
+ * @param options - Options to control which events are read.
+ * @param signal - An optional abort signal to cancel the read.
+ * @returns An async generator yielding EventSourcingDB events.
+ */
+export const readEvents = (subject, options, signal) => {
+    return withAsyncGeneratorSpan('readEvents', () => {
+        const eventSourcingDBClient = getEventSourcingDBClient();
+        return eventSourcingDBClient.readEvents(subject, options, signal);
+    });
+};

package/esm/lib/tracing.d.ts

@@ -0,0 +1,37 @@
+export declare const tracer: import("@opentelemetry/api").Tracer;
+export declare const DB_SYSTEM = "eventsourcingdb";
+/**
+ * Trace context extracted from an EventSourcingDB event, used to link
+ * the processing span to the span that originally wrote the event.
+ */
+export type TraceContext = {
+    traceparent: string;
+    tracestate?: string;
+};
+/**
+ * Wraps an async function with OpenTelemetry tracing and metrics.
+ *
+ * Records:
+ * - `eventsourcingdb_operation_total` counter with operation and status labels
+ * - `eventsourcingdb_operation_duration_seconds` histogram with operation label
+ *
+ * @param operation - The EventSourcingDB operation name (e.g., 'readEvents', 'writeEvents')
+ * @param fn - The async function to execute within the span
+ * @param traceContext - Optional trace context from an EventSourcingDB event to
+ *   continue a distributed trace from the event writer.
+ * @returns The result of the async function
+ */
+export declare const withSpan: <T>(operation: string, fn: () => Promise<T>, traceContext?: TraceContext) => Promise<T>;
+/**
+ * Wraps an async generator with OpenTelemetry tracing and metrics.
+ *
+ * Records:
+ * - `eventsourcingdb_operation_total` counter with operation and status labels
+ * - `eventsourcingdb_operation_duration_seconds` histogram with operation label
+ *
+ * @param operation - The EventSourcingDB operation name (e.g., 'readEvents')
+ * @param fn - The function returning an async generator to execute within the span
+ * @returns An async generator that yields the same values as the inner generator
+ */
+export declare function withAsyncGeneratorSpan<T>(operation: string, fn: () => AsyncGenerator<T, void, void>): AsyncGenerator<T, void, void>;
+//# sourceMappingURL=tracing.d.ts.map

package/esm/lib/tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/lib/tracing.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,MAAM,qCAA4B,CAAC;AAEhD,eAAO,MAAM,SAAS,oBAAoB,CAAC;AAmB3C;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EACtB,WAAW,MAAM,EACjB,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,eAAe,YAAY,KAC5B,OAAO,CAAC,CAAC,CA6DX,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAuB,sBAAsB,CAAC,CAAC,EAC3C,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,GACxC,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CA0C/B"}

package/esm/lib/tracing.js

@@ -0,0 +1,114 @@
+import { context as otelContext, metrics, propagation, SpanKind, SpanStatusCode, trace, } from '@opentelemetry/api';
+export const tracer = trace.getTracer('nimbus');
+export const DB_SYSTEM = 'eventsourcingdb';
+const meter = metrics.getMeter('nimbus');
+const operationCounter = meter.createCounter('eventsourcingdb_operation_total', {
+    description: 'Total number of EventSourcingDB operations',
+});
+const operationDuration = meter.createHistogram('eventsourcingdb_operation_duration_seconds', {
+    description: 'Duration of EventSourcingDB operations in seconds',
+    unit: 's',
+});
+/**
+ * Wraps an async function with OpenTelemetry tracing and metrics.
+ *
+ * Records:
+ * - `eventsourcingdb_operation_total` counter with operation and status labels
+ * - `eventsourcingdb_operation_duration_seconds` histogram with operation label
+ *
+ * @param operation - The EventSourcingDB operation name (e.g., 'readEvents', 'writeEvents')
+ * @param fn - The async function to execute within the span
+ * @param traceContext - Optional trace context from an EventSourcingDB event to
+ *   continue a distributed trace from the event writer.
+ * @returns The result of the async function
+ */
+export const withSpan = (operation, fn, traceContext) => {
+    const startTime = performance.now();
+    const metricLabels = {
+        operation,
+    };
+    const parentContext = traceContext
+        ? propagation.extract(otelContext.active(), traceContext)
+        : otelContext.active();
+    return tracer.startActiveSpan(`eventsourcingdb.${operation}`, {
+        kind: SpanKind.CLIENT,
+        attributes: {
+            'db.system': DB_SYSTEM,
+            'db.operation': operation,
+        },
+    }, parentContext, async (span) => {
+        try {
+            const result = await fn();
+            // Record success metrics
+            operationCounter.add(1, {
+                ...metricLabels,
+                status: 'success',
+            });
+            operationDuration.record((performance.now() - startTime) / 1000, metricLabels);
+            return result;
+        }
+        catch (error) {
+            // Record error metrics
+            operationCounter.add(1, {
+                ...metricLabels,
+                status: 'error',
+            });
+            operationDuration.record((performance.now() - startTime) / 1000, metricLabels);
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error
+                    ? error.message
+                    : 'Unknown error',
+            });
+            span.recordException(error instanceof Error ? error : new Error('Unknown error'));
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+};
+/**
+ * Wraps an async generator with OpenTelemetry tracing and metrics.
+ *
+ * Records:
+ * - `eventsourcingdb_operation_total` counter with operation and status labels
+ * - `eventsourcingdb_operation_duration_seconds` histogram with operation label
+ *
+ * @param operation - The EventSourcingDB operation name (e.g., 'readEvents')
+ * @param fn - The function returning an async generator to execute within the span
+ * @returns An async generator that yields the same values as the inner generator
+ */
+export async function* withAsyncGeneratorSpan(operation, fn) {
+    const startTime = performance.now();
+    const metricLabels = {
+        operation,
+    };
+    const span = tracer.startSpan(`eventsourcingdb.${operation}`, {
+        kind: SpanKind.CLIENT,
+        attributes: {
+            'db.system': DB_SYSTEM,
+            'db.operation': operation,
+        },
+    });
+    try {
+        yield* fn();
+        // Record success metrics
+        operationCounter.add(1, { ...metricLabels, status: 'success' });
+        operationDuration.record((performance.now() - startTime) / 1000, metricLabels);
+    }
+    catch (error) {
+        // Record error metrics
+        operationCounter.add(1, { ...metricLabels, status: 'error' });
+        operationDuration.record((performance.now() - startTime) / 1000, metricLabels);
+        span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: error instanceof Error ? error.message : 'Unknown error',
+        });
+        span.recordException(error instanceof Error ? error : new Error('Unknown error'));
+        throw error;
+    }
+    finally {
+        span.end();
+    }
+}

package/esm/lib/writeEvents.d.ts

@@ -0,0 +1,11 @@
+import type { Event } from '../deps/jsr.io/@nimbus/core/2.0.0/src/index.js';
+import type { Precondition } from 'eventsourcingdb';
+/**
+ * Writes one or more Nimbus events to EventSourcingDB. Each event is
+ * converted into an EventSourcingDB event candidate before being persisted.
+ *
+ * @param events - The Nimbus events to write.
+ * @param preconditions - Optional preconditions that must be met for the write to succeed.
+ */
+export declare const writeEvents: (events: Event[], preconditions?: Precondition[]) => Promise<void>;
+//# sourceMappingURL=writeEvents.d.ts.map

package/esm/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,gDAAgD,CAAC;AAE5E,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAKpE;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GACpB,QAAQ,KAAK,EAAE,EACf,gBAAgB,YAAY,EAAE,KAC/B,OAAO,CAAC,IAAI,CAoBd,CAAC"}

package/esm/lib/writeEvents.js

@@ -0,0 +1,20 @@
+import { context, propagation } from '@opentelemetry/api';
+import { getEventSourcingDBClient } from './client.js';
+import { nimbusEventToEventSourcingDBEventCandidate } from './eventMapping.js';
+import { withSpan } from './tracing.js';
+/**
+ * Writes one or more Nimbus events to EventSourcingDB. Each event is
+ * converted into an EventSourcingDB event candidate before being persisted.
+ *
+ * @param events - The Nimbus events to write.
+ * @param preconditions - Optional preconditions that must be met for the write to succeed.
+ */
+export const writeEvents = (events, preconditions) => {
+    return withSpan('writeEvents', async () => {
+        const eventSourcingDBClient = getEventSourcingDBClient();
+        const carrier = {};
+        propagation.inject(context.active(), carrier);
+        const eventCandidates = events.map((event) => nimbusEventToEventSourcingDBEventCandidate(event, carrier['traceparent'], carrier['tracestate']));
+        await eventSourcingDBClient.writeEvents(eventCandidates, preconditions);
+    });
+};

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@nimbus-cqrs/eventsourcingdb",
+  "version": "2.0.0-beta.0",
+  "description": "EventSourcingDB integration for the Nimbus CQRS framework.",
+  "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"
+  },
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/overlap-dev/Nimbus/issues"
+  },
+  "module": "./esm/index.js",
+  "exports": {
+    ".": {
+      "import": "./esm/index.js"
+    }
+  },
+  "scripts": {},
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "eventsourcingdb": "^1.8.1",
+    "zod": "^4.3.6",
+    "@nimbus-cqrs/core": "^2.0.0-beta.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  },
+  "_generatedBy": "dnt@dev"
+}