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

package/src/lib/readEvents.ts

@@ -0,0 +1,28 @@
+import type { Event, ReadEventsOptions } from 'eventsourcingdb';
+import { getEventSourcingDBClient } from './client.ts';
+import { withAsyncGeneratorSpan } from './tracing.ts';
+
+/**
+ * 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: string,
+    options: ReadEventsOptions,
+    signal?: AbortSignal,
+): AsyncGenerator<Event, void, void> => {
+    return withAsyncGeneratorSpan('readEvents', () => {
+        const eventSourcingDBClient = getEventSourcingDBClient();
+
+        return eventSourcingDBClient.readEvents(subject, options, signal);
+    });
+};

package/src/lib/tracing.ts

@@ -0,0 +1,295 @@
+import {
+    metrics,
+    context as otelContext,
+    propagation,
+    type Span,
+    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',
+    },
+);
+
+/**
+ * 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',
+        unit: 'By',
+    },
+);
+
+/**
+ * Counter of events handled by an event observer, labeled with
+ * `status: success|skipped`.
+ */
+export const observerEventsHandledCounter = meter.createCounter(
+    'eventsourcingdb_observer_events_handled_total',
+    {
+        description:
+            'Total number of events handled by EventSourcingDB observers',
+    },
+);
+
+/**
+ * Histogram of observer handler duration in seconds (includes retries).
+ */
+export const observerHandlingDuration = meter.createHistogram(
+    'eventsourcingdb_observer_handling_duration_seconds',
+    {
+        description:
+            'Duration of EventSourcingDB observer event handling in seconds',
+        unit: 's',
+    },
+);
+
+/**
+ * Counter of in-place handler retry attempts for event observers.
+ */
+export const observerHandlerRetryAttemptsCounter = meter.createCounter(
+    'eventsourcingdb_observer_handler_retry_attempts_total',
+    {
+        description:
+            'Total number of handler retry attempts for EventSourcingDB observers',
+    },
+);
+
+/**
+ * Counter of connection reconnect attempts scheduled after stream failure.
+ */
+export const observerConnectionRetryAttemptsCounter = meter.createCounter(
+    'eventsourcingdb_observer_connection_retry_attempts_total',
+    {
+        description:
+            'Total number of connection retry attempts for EventSourcingDB observers',
+    },
+);
+
+/**
+ * Counter of successful reconnects after one or more connection retries.
+ */
+export const observerConnectionReconnectsCounter = meter.createCounter(
+    'eventsourcingdb_observer_connection_reconnects_total',
+    {
+        description:
+            'Total number of successful connection reconnects for EventSourcingDB observers',
+    },
+);
+
+/**
+ * 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 const withSpan = <T>(
+    operation: string,
+    fn: () => Promise<T>,
+    traceContext?: TraceContext,
+): Promise<T> => {
+    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();
+            }
+        },
+    );
+};
+
+/**
+ * Starts a consumer span for observing a single EventSourcingDB event,
+ * optionally linked to the writer's trace via {@link TraceContext}.
+ *
+ * @param event - The observed EventSourcingDB event.
+ * @param observerSubject - The observer's configured subject.
+ * @param traceContext - Optional writer trace context from the event.
+ * @param fn - Work to run inside the active span.
+ */
+export const withObserveEventSpan = <T>(
+    event: { id: string; type: string; subject: string },
+    observerSubject: string,
+    traceContext: TraceContext | undefined,
+    fn: (span: Span) => Promise<T>,
+): Promise<T> => {
+    const parentContext = traceContext
+        ? propagation.extract(otelContext.active(), traceContext)
+        : otelContext.active();
+
+    return tracer.startActiveSpan(
+        'eventsourcingdb.observeEvent',
+        {
+            kind: SpanKind.CONSUMER,
+            attributes: {
+                'db.system': DB_SYSTEM,
+                'db.operation': 'observeEvent',
+                'messaging.system': 'eventsourcingdb',
+                'messaging.operation': 'process',
+                'messaging.destination': event.type,
+                'cloudevents.event_id': event.id,
+                'cloudevents.event_type': event.type,
+                'cloudevents.event_subject': event.subject,
+                'eventsourcingdb.observer.subject': observerSubject,
+            },
+        },
+        parentContext,
+        async (span) => {
+            try {
+                return await fn(span);
+            } 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<T>(
+    operation: string,
+    fn: () => AsyncGenerator<T, void, void>,
+): AsyncGenerator<T, void, void> {
+    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/src/lib/writeEvents.ts

@@ -0,0 +1,72 @@
+import type { Event } from '@nimbus-cqrs/core';
+import { context, propagation } from '@opentelemetry/api';
+import type {
+    EventCandidate,
+    Event as EventSourcingDBEvent,
+    Precondition,
+} from 'eventsourcingdb';
+import { getEventSourcingDBClient } from './client.ts';
+import { nimbusEventToEventSourcingDBEventCandidate } from './eventMapping.ts';
+import { eventSizeBytes, withSpan } from './tracing.ts';
+
+const textEncoder = new TextEncoder();
+
+/**
+ * Returns the UTF-8 byte length of a serialized Nimbus event.
+ */
+const getEventSizeBytes = (event: Event): number =>
+    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: Event[],
+    preconditions?: Precondition[],
+    signal?: AbortSignal,
+): Promise<EventSourcingDBEvent[]> => {
+    return withSpan('writeEvents', async () => {
+        const eventSourcingDBClient = getEventSourcingDBClient();
+
+        const carrier: Record<string, string> = {};
+        propagation.inject(context.active(), carrier);
+
+        const eventCandidates: EventCandidate[] = events.map((event) => {
+            eventSizeBytes.record(getEventSizeBytes(event));
+
+            return nimbusEventToEventSourcingDBEventCandidate(
+                event,
+                carrier.traceparent,
+                carrier.tracestate,
+            );
+        });
+
+        return await eventSourcingDBClient.writeEvents(
+            eventCandidates,
+            preconditions,
+            signal,
+        );
+    });
+};

package/esm/_dnt.polyfills.d.ts

@@ -1,7 +0,0 @@
-declare global {
-    interface Error {
-        cause?: unknown;
-    }
-}
-export {};
-//# sourceMappingURL=_dnt.polyfills.d.ts.map

package/esm/_dnt.polyfills.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"_dnt.polyfills.d.ts","sourceRoot":"","sources":["../src/_dnt.polyfills.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,KAAK;QACb,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CACF;AAED,OAAO,EAAE,CAAC"}

package/esm/_dnt.polyfills.js

@@ -1 +0,0 @@
-export {};

package/esm/_dnt.shims.d.ts

@@ -1,2 +0,0 @@
-export declare const dntGlobalThis: Omit<typeof globalThis, never>;
-//# sourceMappingURL=_dnt.shims.d.ts.map

package/esm/_dnt.shims.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"_dnt.shims.d.ts","sourceRoot":"","sources":["../src/_dnt.shims.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,gCAA2C,CAAC"}

package/esm/_dnt.shims.js

@@ -1,57 +0,0 @@
-const dntGlobals = {};
-export const dntGlobalThis = createMergeProxy(globalThis, dntGlobals);
-function createMergeProxy(baseObj, extObj) {
-    return new Proxy(baseObj, {
-        get(_target, prop, _receiver) {
-            if (prop in extObj) {
-                return extObj[prop];
-            }
-            else {
-                return baseObj[prop];
-            }
-        },
-        set(_target, prop, value) {
-            if (prop in extObj) {
-                delete extObj[prop];
-            }
-            baseObj[prop] = value;
-            return true;
-        },
-        deleteProperty(_target, prop) {
-            let success = false;
-            if (prop in extObj) {
-                delete extObj[prop];
-                success = true;
-            }
-            if (prop in baseObj) {
-                delete baseObj[prop];
-                success = true;
-            }
-            return success;
-        },
-        ownKeys(_target) {
-            const baseKeys = Reflect.ownKeys(baseObj);
-            const extKeys = Reflect.ownKeys(extObj);
-            const extKeysSet = new Set(extKeys);
-            return [...baseKeys.filter((k) => !extKeysSet.has(k)), ...extKeys];
-        },
-        defineProperty(_target, prop, desc) {
-            if (prop in extObj) {
-                delete extObj[prop];
-            }
-            Reflect.defineProperty(baseObj, prop, desc);
-            return true;
-        },
-        getOwnPropertyDescriptor(_target, prop) {
-            if (prop in extObj) {
-                return Reflect.getOwnPropertyDescriptor(extObj, prop);
-            }
-            else {
-                return Reflect.getOwnPropertyDescriptor(baseObj, prop);
-            }
-        },
-        has(_target, prop) {
-            return prop in extObj || prop in baseObj;
-        },
-    });
-}