@emmett-community/emmett-google-firestore 0.1.0 → 0.3.0

package/README.md

@@ -234,38 +234,17 @@ const state = await eventStore.aggregateStream(
 
 ## Testing
 
-### Testing Utilities
-
-The package includes utilities to make testing easier:
-
-```typescript
-import {
-  setupFirestoreTests,
-  getTestFirestore,
-  clearFirestore,
-} from '@emmett-community/emmett-google-firestore/testing';
-
-describe('My Tests', () => {
-  const { firestore, eventStore, cleanup, clearData } = setupFirestoreTests();
-
-  afterAll(cleanup);
-  beforeEach(clearData);
-
-  it('should work', async () => {
-    await eventStore.appendToStream('test-stream', [/* events */]);
-    // ... assertions
-  });
-});
-```
-
 ### Running Tests
 
 ```bash
 # Unit tests
 npm run test:unit
 
-# Integration tests (requires Firestore Emulator)
-npm run test:integration
+# Integration tests (in-memory)
+npm run test:int
+
+# E2E tests (Firestore Emulator via Testcontainers, requires Docker)
+npm run test:e2e
 
 # All tests
 npm test
@@ -274,9 +253,17 @@ npm test
 npm run test:coverage
 ```
 
+Test files live in `test/` and are selected by filename suffix:
+
+- `*.unit.spec.ts` (unit tests, pure logic)
+- `*.int.spec.ts` (integration tests, in-memory Firestore)
+- `*.e2e.spec.ts` (E2E tests, Firestore emulator via Testcontainers)
+
+Support fixtures live under `test/support` (including Firebase emulator configs in `test/support/firebase`).
+
 ### Using Firestore Emulator
 
-For local development and testing:
+For local development and manual testing:
 
 ```bash
 # Install Firebase CLI
@@ -284,9 +271,6 @@ npm install -g firebase-tools
 
 # Start emulator
 firebase emulators:start --only firestore
-
-# Or use the provided script
-./scripts/start-emulator.sh
 ```
 
 Set environment variables:
@@ -296,6 +280,8 @@ export FIRESTORE_PROJECT_ID=test-project
 export FIRESTORE_EMULATOR_HOST=localhost:8080
 ```
 
+E2E tests start the emulator automatically via Testcontainers.
+
 ## Examples
 
 ### Complete Shopping Cart Example
@@ -507,6 +493,54 @@ try {
 }
 ```
 
+## Observability
+
+The event store supports optional logging and OpenTelemetry tracing.
+
+### Logging
+
+Pass an optional logger compatible with Pino:
+
+```typescript
+import pino from 'pino';
+
+const eventStore = getFirestoreEventStore(firestore, {
+  observability: {
+    logger: pino({ level: 'debug' }),
+  },
+});
+```
+
+**Logging points:**
+
+- `info`: Initialization
+- `debug`: I/O operations (queries, transactions)
+- `warn`: Version conflicts (recoverable)
+- `error`: Failures before rethrowing
+
+**Note:** Event payloads are never logged.
+
+### Tracing
+
+The package uses `@opentelemetry/api` directly. Spans are created passively:
+
+- If your application initializes OpenTelemetry, spans will be recorded
+- If not, the tracing calls are no-ops with zero overhead
+
+**Span names:**
+
+- `emmett.firestore.read_stream`
+- `emmett.firestore.append_to_stream`
+
+**Attributes:**
+
+- `emmett.stream_name`
+- `emmett.event_count`
+- `emmett.new_version`
+- `emmett.created_new_stream`
+
+To enable tracing, initialize OpenTelemetry in your application (this package never initializes tracing itself).
+
 ## TypeScript Support
 
 The package is written in TypeScript and includes full type definitions:

package/dist/index.d.mts

@@ -1,9 +1,143 @@
 import { Firestore, Timestamp } from '@google-cloud/firestore';
-import { F as FirestoreEventStoreOptions, a as FirestoreEventStore, E as ExpectedStreamVersion } from './types-CHnx_sMk.mjs';
-export { A as AppendToStreamOptions, d as AppendToStreamResult, C as CollectionConfig, e as EventDocument, f as ExpectedVersionConflictError, b as FirestoreReadEvent, c as FirestoreReadEventMetadata, R as ReadStreamOptions, S as StreamMetadata } from './types-CHnx_sMk.mjs';
-import { STREAM_DOES_NOT_EXIST } from '@event-driven-io/emmett';
+import { Event, ReadEvent, ReadEventMetadataWithGlobalPosition, ExpectedStreamVersion as ExpectedStreamVersion$1, STREAM_DOES_NOT_EXIST } from '@event-driven-io/emmett';
 export { NO_CONCURRENCY_CHECK, STREAM_DOES_NOT_EXIST, STREAM_EXISTS } from '@event-driven-io/emmett';
 
+/**
+ * Minimal logger interface compatible with Pino and other loggers.
+ * All methods are optional to support varying logger implementations.
+ */
+interface Logger {
+    debug?(msg: string, data?: unknown): void;
+    info?(msg: string, data?: unknown): void;
+    warn?(msg: string, data?: unknown): void;
+    error?(msg: string, err?: unknown): void;
+}
+/**
+ * Observability configuration options
+ */
+interface ObservabilityOptions {
+    /** Optional logger instance. If not provided, no logging occurs. */
+    logger?: Logger;
+}
+/**
+ * Expected version for stream operations
+ * Uses Emmett's standard version constants for full compatibility
+ * - number | bigint: Expect specific version
+ * - STREAM_DOES_NOT_EXIST: Stream must not exist
+ * - STREAM_EXISTS: Stream must exist (any version)
+ * - NO_CONCURRENCY_CHECK: No version check
+ */
+type ExpectedStreamVersion = ExpectedStreamVersion$1<bigint>;
+
+/**
+ * Options for appending events to a stream
+ */
+interface AppendToStreamOptions {
+    expectedStreamVersion?: ExpectedStreamVersion;
+}
+/**
+ * Result of appending events to a stream
+ */
+interface AppendToStreamResult {
+    nextExpectedStreamVersion: bigint;
+    createdNewStream: boolean;
+}
+/**
+ * Options for reading events from a stream
+ */
+interface ReadStreamOptions {
+    from?: bigint;
+    to?: bigint;
+    maxCount?: number;
+}
+/**
+ * Metadata stored in Firestore stream document
+ */
+interface StreamMetadata {
+    version: number;
+    createdAt: Timestamp;
+    updatedAt: Timestamp;
+}
+/**
+ * Event document structure in Firestore
+ */
+interface EventDocument {
+    type: string;
+    data: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    timestamp: Timestamp;
+    globalPosition: number;
+    streamVersion: number;
+}
+/**
+ * Firestore-specific read event metadata
+ */
+interface FirestoreReadEventMetadata extends ReadEventMetadataWithGlobalPosition {
+    streamName: string;
+    streamVersion: bigint;
+    timestamp: Date;
+}
+/**
+ * Firestore read event
+ */
+type FirestoreReadEvent<EventType extends Event = Event> = ReadEvent<EventType, FirestoreReadEventMetadata>;
+/**
+ * Collection configuration for Firestore event store
+ */
+interface CollectionConfig {
+    streams: string;
+    counters: string;
+}
+/**
+ * Firestore event store options
+ */
+interface FirestoreEventStoreOptions {
+    collections?: Partial<CollectionConfig>;
+    observability?: ObservabilityOptions;
+}
+/**
+ * Firestore event store interface
+ */
+interface FirestoreEventStore {
+    /**
+     * The underlying Firestore instance
+     */
+    readonly firestore: Firestore;
+    /**
+     * Collection names configuration
+     */
+    readonly collections: CollectionConfig;
+    /**
+     * Read events from a stream
+     */
+    readStream<EventType extends Event>(streamName: string, options?: ReadStreamOptions): Promise<FirestoreReadEvent<EventType>[]>;
+    /**
+     * Aggregate stream by applying events to state
+     */
+    aggregateStream<State, EventType extends Event>(streamName: string, options: {
+        evolve: (state: State, event: FirestoreReadEvent<EventType>) => State;
+        initialState: () => State;
+        read?: ReadStreamOptions;
+    }): Promise<{
+        state: State;
+        currentStreamVersion: bigint;
+        streamExists: boolean;
+    }>;
+    /**
+     * Append events to a stream
+     */
+    appendToStream<EventType extends Event>(streamName: string, events: EventType[], options?: AppendToStreamOptions): Promise<AppendToStreamResult>;
+}
+/**
+ * Error thrown when expected version doesn't match current version
+ */
+declare class ExpectedVersionConflictError extends Error {
+    readonly streamName: string;
+    readonly expected: ExpectedStreamVersion;
+    readonly actual: bigint | typeof STREAM_DOES_NOT_EXIST;
+    constructor(streamName: string, expected: ExpectedStreamVersion, actual: bigint | typeof STREAM_DOES_NOT_EXIST);
+}
+
 /**
  * Factory function to create a Firestore event store
  *
@@ -82,4 +216,4 @@ declare function getCurrentStreamVersion(streamExists: boolean, version?: number
  */
 declare function calculateNextVersion(currentVersion: bigint | typeof STREAM_DOES_NOT_EXIST, eventCount: number): bigint;
 
-export { ExpectedStreamVersion, FirestoreEventStore, FirestoreEventStoreOptions, assertExpectedVersionMatchesCurrent, calculateNextVersion, getCurrentStreamVersion, getFirestoreEventStore, padVersion, parseStreamName, timestampToDate };
+export { type AppendToStreamOptions, type AppendToStreamResult, type CollectionConfig, type EventDocument, type ExpectedStreamVersion, ExpectedVersionConflictError, type FirestoreEventStore, type FirestoreEventStoreOptions, type FirestoreReadEvent, type FirestoreReadEventMetadata, type Logger, type ObservabilityOptions, type ReadStreamOptions, type StreamMetadata, assertExpectedVersionMatchesCurrent, calculateNextVersion, getCurrentStreamVersion, getFirestoreEventStore, padVersion, parseStreamName, timestampToDate };

package/dist/index.d.ts

@@ -1,9 +1,143 @@
 import { Firestore, Timestamp } from '@google-cloud/firestore';
-import { F as FirestoreEventStoreOptions, a as FirestoreEventStore, E as ExpectedStreamVersion } from './types-CHnx_sMk.js';
-export { A as AppendToStreamOptions, d as AppendToStreamResult, C as CollectionConfig, e as EventDocument, f as ExpectedVersionConflictError, b as FirestoreReadEvent, c as FirestoreReadEventMetadata, R as ReadStreamOptions, S as StreamMetadata } from './types-CHnx_sMk.js';
-import { STREAM_DOES_NOT_EXIST } from '@event-driven-io/emmett';
+import { Event, ReadEvent, ReadEventMetadataWithGlobalPosition, ExpectedStreamVersion as ExpectedStreamVersion$1, STREAM_DOES_NOT_EXIST } from '@event-driven-io/emmett';
 export { NO_CONCURRENCY_CHECK, STREAM_DOES_NOT_EXIST, STREAM_EXISTS } from '@event-driven-io/emmett';
 
+/**
+ * Minimal logger interface compatible with Pino and other loggers.
+ * All methods are optional to support varying logger implementations.
+ */
+interface Logger {
+    debug?(msg: string, data?: unknown): void;
+    info?(msg: string, data?: unknown): void;
+    warn?(msg: string, data?: unknown): void;
+    error?(msg: string, err?: unknown): void;
+}
+/**
+ * Observability configuration options
+ */
+interface ObservabilityOptions {
+    /** Optional logger instance. If not provided, no logging occurs. */
+    logger?: Logger;
+}
+/**
+ * Expected version for stream operations
+ * Uses Emmett's standard version constants for full compatibility
+ * - number | bigint: Expect specific version
+ * - STREAM_DOES_NOT_EXIST: Stream must not exist
+ * - STREAM_EXISTS: Stream must exist (any version)
+ * - NO_CONCURRENCY_CHECK: No version check
+ */
+type ExpectedStreamVersion = ExpectedStreamVersion$1<bigint>;
+
+/**
+ * Options for appending events to a stream
+ */
+interface AppendToStreamOptions {
+    expectedStreamVersion?: ExpectedStreamVersion;
+}
+/**
+ * Result of appending events to a stream
+ */
+interface AppendToStreamResult {
+    nextExpectedStreamVersion: bigint;
+    createdNewStream: boolean;
+}
+/**
+ * Options for reading events from a stream
+ */
+interface ReadStreamOptions {
+    from?: bigint;
+    to?: bigint;
+    maxCount?: number;
+}
+/**
+ * Metadata stored in Firestore stream document
+ */
+interface StreamMetadata {
+    version: number;
+    createdAt: Timestamp;
+    updatedAt: Timestamp;
+}
+/**
+ * Event document structure in Firestore
+ */
+interface EventDocument {
+    type: string;
+    data: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    timestamp: Timestamp;
+    globalPosition: number;
+    streamVersion: number;
+}
+/**
+ * Firestore-specific read event metadata
+ */
+interface FirestoreReadEventMetadata extends ReadEventMetadataWithGlobalPosition {
+    streamName: string;
+    streamVersion: bigint;
+    timestamp: Date;
+}
+/**
+ * Firestore read event
+ */
+type FirestoreReadEvent<EventType extends Event = Event> = ReadEvent<EventType, FirestoreReadEventMetadata>;
+/**
+ * Collection configuration for Firestore event store
+ */
+interface CollectionConfig {
+    streams: string;
+    counters: string;
+}
+/**
+ * Firestore event store options
+ */
+interface FirestoreEventStoreOptions {
+    collections?: Partial<CollectionConfig>;
+    observability?: ObservabilityOptions;
+}
+/**
+ * Firestore event store interface
+ */
+interface FirestoreEventStore {
+    /**
+     * The underlying Firestore instance
+     */
+    readonly firestore: Firestore;
+    /**
+     * Collection names configuration
+     */
+    readonly collections: CollectionConfig;
+    /**
+     * Read events from a stream
+     */
+    readStream<EventType extends Event>(streamName: string, options?: ReadStreamOptions): Promise<FirestoreReadEvent<EventType>[]>;
+    /**
+     * Aggregate stream by applying events to state
+     */
+    aggregateStream<State, EventType extends Event>(streamName: string, options: {
+        evolve: (state: State, event: FirestoreReadEvent<EventType>) => State;
+        initialState: () => State;
+        read?: ReadStreamOptions;
+    }): Promise<{
+        state: State;
+        currentStreamVersion: bigint;
+        streamExists: boolean;
+    }>;
+    /**
+     * Append events to a stream
+     */
+    appendToStream<EventType extends Event>(streamName: string, events: EventType[], options?: AppendToStreamOptions): Promise<AppendToStreamResult>;
+}
+/**
+ * Error thrown when expected version doesn't match current version
+ */
+declare class ExpectedVersionConflictError extends Error {
+    readonly streamName: string;
+    readonly expected: ExpectedStreamVersion;
+    readonly actual: bigint | typeof STREAM_DOES_NOT_EXIST;
+    constructor(streamName: string, expected: ExpectedStreamVersion, actual: bigint | typeof STREAM_DOES_NOT_EXIST);
+}
+
 /**
  * Factory function to create a Firestore event store
  *
@@ -82,4 +216,4 @@ declare function getCurrentStreamVersion(streamExists: boolean, version?: number
  */
 declare function calculateNextVersion(currentVersion: bigint | typeof STREAM_DOES_NOT_EXIST, eventCount: number): bigint;
 
-export { ExpectedStreamVersion, FirestoreEventStore, FirestoreEventStoreOptions, assertExpectedVersionMatchesCurrent, calculateNextVersion, getCurrentStreamVersion, getFirestoreEventStore, padVersion, parseStreamName, timestampToDate };
+export { type AppendToStreamOptions, type AppendToStreamResult, type CollectionConfig, type EventDocument, type ExpectedStreamVersion, ExpectedVersionConflictError, type FirestoreEventStore, type FirestoreEventStoreOptions, type FirestoreReadEvent, type FirestoreReadEventMetadata, type Logger, type ObservabilityOptions, type ReadStreamOptions, type StreamMetadata, assertExpectedVersionMatchesCurrent, calculateNextVersion, getCurrentStreamVersion, getFirestoreEventStore, padVersion, parseStreamName, timestampToDate };

package/dist/index.js

@@ -1,8 +1,9 @@
 'use strict';
 
+var api = require('@opentelemetry/api');
 var emmett = require('@event-driven-io/emmett');
 
-// src/eventStore/types.ts
+// src/eventStore/firestoreEventStore.ts
 var ExpectedVersionConflictError = class _ExpectedVersionConflictError extends Error {
   constructor(streamName, expected, actual) {
     super(
@@ -83,6 +84,14 @@ function calculateNextVersion(currentVersion, eventCount) {
 }
 
 // src/eventStore/firestoreEventStore.ts
+var tracer = api.trace.getTracer("@emmett-community/emmett-google-firestore");
+function safeLog(logger, level, msg, data) {
+  if (!logger) return;
+  const logFn = logger[level];
+  if (typeof logFn === "function") {
+    logFn.call(logger, msg, data);
+  }
+}
 var DEFAULT_COLLECTIONS = {
   streams: "streams",
   counters: "_counters"
@@ -94,39 +103,70 @@ var FirestoreEventStoreImpl = class {
       ...DEFAULT_COLLECTIONS,
       ...options.collections
     };
+    this.logger = options.observability?.logger;
+    safeLog(this.logger, "info", "FirestoreEventStore initialized");
   }
   collections;
+  logger;
   /**
    * Read events from a stream
    */
   async readStream(streamName, options = {}) {
-    const { from, to, maxCount } = options;
-    let query = this.firestore.collection(this.collections.streams).doc(streamName).collection("events").orderBy("streamVersion", "asc");
-    if (from !== void 0) {
-      query = query.where("streamVersion", ">=", Number(from));
-    }
-    if (to !== void 0) {
-      query = query.where("streamVersion", "<=", Number(to));
-    }
-    if (maxCount !== void 0 && maxCount > 0) {
-      query = query.limit(maxCount);
-    }
-    const snapshot = await query.get();
-    return snapshot.docs.map((doc) => {
-      const data = doc.data();
-      return {
-        type: data.type,
-        data: data.data,
-        metadata: {
-          ...data.metadata,
-          streamName,
-          streamVersion: BigInt(data.streamVersion),
-          streamPosition: BigInt(data.streamVersion),
-          globalPosition: BigInt(data.globalPosition),
-          timestamp: timestampToDate(data.timestamp)
-        }
-      };
+    const span = tracer.startSpan("emmett.firestore.read_stream", {
+      attributes: { "emmett.stream_name": streamName }
     });
+    try {
+      safeLog(this.logger, "debug", "Reading stream", {
+        streamName,
+        from: options.from?.toString(),
+        to: options.to?.toString(),
+        maxCount: options.maxCount
+      });
+      const { from, to, maxCount } = options;
+      let query = this.firestore.collection(this.collections.streams).doc(streamName).collection("events").orderBy("streamVersion", "asc");
+      if (from !== void 0) {
+        query = query.where("streamVersion", ">=", Number(from));
+      }
+      if (to !== void 0) {
+        query = query.where("streamVersion", "<=", Number(to));
+      }
+      if (maxCount !== void 0 && maxCount > 0) {
+        query = query.limit(maxCount);
+      }
+      const snapshot = await query.get();
+      const events = snapshot.docs.map((doc) => {
+        const data = doc.data();
+        return {
+          type: data.type,
+          data: data.data,
+          metadata: {
+            ...data.metadata,
+            streamName,
+            streamVersion: BigInt(data.streamVersion),
+            streamPosition: BigInt(data.streamVersion),
+            globalPosition: BigInt(data.globalPosition),
+            timestamp: timestampToDate(data.timestamp)
+          }
+        };
+      });
+      span.setAttribute("emmett.event_count", events.length);
+      span.setStatus({ code: api.SpanStatusCode.OK });
+      safeLog(this.logger, "debug", "Stream read completed", {
+        streamName,
+        eventCount: events.length
+      });
+      return events;
+    } catch (error) {
+      span.recordException(error);
+      span.setStatus({ code: api.SpanStatusCode.ERROR });
+      safeLog(this.logger, "error", "Failed to read stream", {
+        streamName,
+        error
+      });
+      throw error;
+    } finally {
+      span.end();
+    }
   }
   /**
    * Aggregate stream by applying events to state
@@ -147,21 +187,66 @@ var FirestoreEventStoreImpl = class {
    * Append events to a stream with optimistic concurrency control
    */
   async appendToStream(streamName, events, options = {}) {
-    if (events.length === 0) {
-      throw new Error("Cannot append empty event array");
-    }
-    const { expectedStreamVersion = emmett.NO_CONCURRENCY_CHECK } = options;
-    return await this.firestore.runTransaction(async (transaction) => {
-      return await this.appendToStreamInTransaction(
-        transaction,
-        streamName,
-        events,
-        expectedStreamVersion
-      );
+    const span = tracer.startSpan("emmett.firestore.append_to_stream", {
+      attributes: {
+        "emmett.stream_name": streamName,
+        "emmett.event_count": events.length
+      }
     });
+    try {
+      if (events.length === 0) {
+        throw new Error("Cannot append empty event array");
+      }
+      const { expectedStreamVersion = emmett.NO_CONCURRENCY_CHECK } = options;
+      safeLog(this.logger, "debug", "Appending to stream", {
+        streamName,
+        eventCount: events.length,
+        eventTypes: events.map((e) => e.type),
+        expectedVersion: String(expectedStreamVersion)
+      });
+      const result = await this.firestore.runTransaction(async (transaction) => {
+        return await this.appendToStreamInTransaction(
+          transaction,
+          streamName,
+          events,
+          expectedStreamVersion
+        );
+      });
+      span.setAttribute("emmett.new_version", Number(result.nextExpectedStreamVersion));
+      span.setAttribute("emmett.created_new_stream", result.createdNewStream);
+      span.setStatus({ code: api.SpanStatusCode.OK });
+      safeLog(this.logger, "debug", "Append completed", {
+        streamName,
+        newVersion: result.nextExpectedStreamVersion.toString(),
+        createdNewStream: result.createdNewStream
+      });
+      return result;
+    } catch (error) {
+      span.recordException(error);
+      span.setStatus({ code: api.SpanStatusCode.ERROR });
+      if (error instanceof ExpectedVersionConflictError) {
+        safeLog(this.logger, "warn", "Version conflict during append", {
+          streamName,
+          expected: String(error.expected),
+          actual: String(error.actual)
+        });
+      } else {
+        safeLog(this.logger, "error", "Failed to append to stream", {
+          streamName,
+          error
+        });
+      }
+      throw error;
+    } finally {
+      span.end();
+    }
   }
   /**
    * Internal method to append events within a transaction
+   *
+   * Note: No separate span here - this method runs inside appendToStream's span,
+   * and Firestore transaction operations are atomic. The parent span captures
+   * the full transaction duration.
    */
   async appendToStreamInTransaction(transaction, streamName, events, expectedStreamVersion) {
     const streamRef = this.firestore.collection(this.collections.streams).doc(streamName);
@@ -172,6 +257,11 @@ var FirestoreEventStoreImpl = class {
       streamExists,
       streamData?.version
     );
+    safeLog(this.logger, "debug", "Read stream metadata", {
+      streamName,
+      exists: streamExists,
+      currentVersion: currentVersion === emmett.STREAM_DOES_NOT_EXIST ? "none" : currentVersion.toString()
+    });
     assertExpectedVersionMatchesCurrent(
       streamName,
       expectedStreamVersion,
@@ -208,6 +298,11 @@ var FirestoreEventStoreImpl = class {
       value: globalPosition,
       updatedAt: now
     });
+    safeLog(this.logger, "debug", "Events written to transaction", {
+      streamName,
+      count: events.length,
+      newVersion
+    });
     return {
       nextExpectedStreamVersion: BigInt(newVersion),
       createdNewStream: !streamExists