@emmett-community/emmett-google-firestore 0.1.0 → 0.2.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

package/dist/index.d.mts

@@ -1,9 +1,125 @@
 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';
 
+/**
+ * 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>;
+}
+/**
+ * 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 +198,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 ReadStreamOptions, type StreamMetadata, assertExpectedVersionMatchesCurrent, calculateNextVersion, getCurrentStreamVersion, getFirestoreEventStore, padVersion, parseStreamName, timestampToDate };

package/dist/index.d.ts

@@ -1,9 +1,125 @@
 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';
 
+/**
+ * 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>;
+}
+/**
+ * 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 +198,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 ReadStreamOptions, type StreamMetadata, assertExpectedVersionMatchesCurrent, calculateNextVersion, getCurrentStreamVersion, getFirestoreEventStore, padVersion, parseStreamName, timestampToDate };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emmett-community/emmett-google-firestore",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Google Firestore event store implementation for Emmett",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -15,16 +15,6 @@
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       }
-    },
-    "./testing": {
-      "import": {
-        "types": "./dist/testing/index.d.mts",
-        "default": "./dist/testing/index.mjs"
-      },
-      "require": {
-        "types": "./dist/testing/index.d.ts",
-        "default": "./dist/testing/index.js"
-      }
     }
   },
   "files": [
@@ -33,12 +23,13 @@
   "scripts": {
     "build": "tsup",
     "build:ts": "tsc --noEmit",
-    "test": "jest",
-    "test:unit": "jest test/unit",
-    "test:integration": "jest test/integration",
-    "test:e2e": "jest test/e2e",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage",
+    "test": "npm run test:unit && npm run test:int && npm run test:e2e",
+    "test:unit": "jest --testMatch \"**/*.unit.spec.ts\" --watchman=false",
+    "test:int": "jest --testMatch \"**/*.int.spec.ts\" --watchman=false",
+    "test:integration": "npm run test:int",
+    "test:e2e": "jest --testMatch \"**/*.e2e.spec.ts\" --watchman=false",
+    "test:watch": "jest --watch --watchman=false",
+    "test:coverage": "jest --coverage --watchman=false",
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
     "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
@@ -86,6 +77,7 @@
     "prettier": "^3.4.2",
     "ts-jest": "^29.2.5",
     "ts-node": "^10.9.2",
+    "testcontainers": "^10.28.0",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2"
   },

package/dist/testing/index.d.mts

@@ -1,115 +0,0 @@
-import { Firestore } from '@google-cloud/firestore';
-import { a as FirestoreEventStore } from '../types-CHnx_sMk.mjs';
-import '@event-driven-io/emmett';
-
-/**
- * Testing utilities for Firestore Event Store
- *
- * These utilities help set up and manage the Firestore Emulator
- * for testing purposes.
- */
-
-/**
- * Configuration for Firestore test environment
- */
-interface FirestoreTestConfig {
-    projectId?: string;
-    host?: string;
-    ssl?: boolean;
-}
-/**
- * Get a Firestore instance configured for the emulator
- *
- * @param config - Optional configuration override
- * @returns Configured Firestore instance
- *
- * @example
- * ```typescript
- * const firestore = getTestFirestore();
- * // Use firestore for testing
- * await firestore.terminate();
- * ```
- */
-declare function getTestFirestore(config?: FirestoreTestConfig): Firestore;
-/**
- * Get a test event store instance connected to the emulator
- *
- * @param config - Optional configuration override
- * @returns FirestoreEventStore instance for testing
- *
- * @example
- * ```typescript
- * const eventStore = getTestEventStore();
- * // Use eventStore for testing
- * ```
- */
-declare function getTestEventStore(config?: FirestoreTestConfig): FirestoreEventStore;
-/**
- * Clear all data from a Firestore instance
- * Useful for cleaning up between tests
- *
- * @param firestore - Firestore instance to clear
- * @param batchSize - Number of documents to delete per batch
- *
- * @example
- * ```typescript
- * beforeEach(async () => {
- *   await clearFirestore(firestore);
- * });
- * ```
- */
-declare function clearFirestore(firestore: Firestore, batchSize?: number): Promise<void>;
-/**
- * Delete a specific collection from Firestore
- *
- * @param firestore - Firestore instance
- * @param collectionPath - Path to the collection to delete
- * @param batchSize - Number of documents to delete per batch
- */
-declare function deleteCollection(firestore: Firestore, collectionPath: string, batchSize?: number): Promise<void>;
-/**
- * Wait for the Firestore emulator to be ready
- *
- * @param host - Emulator host (default: localhost:8080)
- * @param timeout - Maximum time to wait in milliseconds (default: 30000)
- * @param interval - Check interval in milliseconds (default: 100)
- * @returns Promise that resolves when emulator is ready
- *
- * @example
- * ```typescript
- * await waitForEmulator();
- * // Emulator is ready
- * ```
- */
-declare function waitForEmulator(host?: string, timeout?: number, interval?: number): Promise<void>;
-/**
- * Setup function for Jest/Vitest tests with Firestore emulator
- *
- * @returns Object with firestore instance and cleanup function
- *
- * @example
- * ```typescript
- * describe('My Tests', () => {
- *   const { firestore, cleanup } = setupFirestoreTests();
- *
- *   afterAll(cleanup);
- *
- *   beforeEach(async () => {
- *     await clearFirestore(firestore);
- *   });
- *
- *   it('should work', async () => {
- *     const eventStore = getFirestoreEventStore(firestore);
- *     // ... test code
- *   });
- * });
- * ```
- */
-declare function setupFirestoreTests(config?: FirestoreTestConfig): {
-    firestore: Firestore;
-    eventStore: FirestoreEventStore;
-    cleanup: () => Promise<void>;
-    clearData: () => Promise<void>;
-};
-
-export { type FirestoreTestConfig, clearFirestore, deleteCollection, getTestEventStore, getTestFirestore, setupFirestoreTests, waitForEmulator };

package/dist/testing/index.d.ts

@@ -1,115 +0,0 @@
-import { Firestore } from '@google-cloud/firestore';
-import { a as FirestoreEventStore } from '../types-CHnx_sMk.js';
-import '@event-driven-io/emmett';
-
-/**
- * Testing utilities for Firestore Event Store
- *
- * These utilities help set up and manage the Firestore Emulator
- * for testing purposes.
- */
-
-/**
- * Configuration for Firestore test environment
- */
-interface FirestoreTestConfig {
-    projectId?: string;
-    host?: string;
-    ssl?: boolean;
-}
-/**
- * Get a Firestore instance configured for the emulator
- *
- * @param config - Optional configuration override
- * @returns Configured Firestore instance
- *
- * @example
- * ```typescript
- * const firestore = getTestFirestore();
- * // Use firestore for testing
- * await firestore.terminate();
- * ```
- */
-declare function getTestFirestore(config?: FirestoreTestConfig): Firestore;
-/**
- * Get a test event store instance connected to the emulator
- *
- * @param config - Optional configuration override
- * @returns FirestoreEventStore instance for testing
- *
- * @example
- * ```typescript
- * const eventStore = getTestEventStore();
- * // Use eventStore for testing
- * ```
- */
-declare function getTestEventStore(config?: FirestoreTestConfig): FirestoreEventStore;
-/**
- * Clear all data from a Firestore instance
- * Useful for cleaning up between tests
- *
- * @param firestore - Firestore instance to clear
- * @param batchSize - Number of documents to delete per batch
- *
- * @example
- * ```typescript
- * beforeEach(async () => {
- *   await clearFirestore(firestore);
- * });
- * ```
- */
-declare function clearFirestore(firestore: Firestore, batchSize?: number): Promise<void>;
-/**
- * Delete a specific collection from Firestore
- *
- * @param firestore - Firestore instance
- * @param collectionPath - Path to the collection to delete
- * @param batchSize - Number of documents to delete per batch
- */
-declare function deleteCollection(firestore: Firestore, collectionPath: string, batchSize?: number): Promise<void>;
-/**
- * Wait for the Firestore emulator to be ready
- *
- * @param host - Emulator host (default: localhost:8080)
- * @param timeout - Maximum time to wait in milliseconds (default: 30000)
- * @param interval - Check interval in milliseconds (default: 100)
- * @returns Promise that resolves when emulator is ready
- *
- * @example
- * ```typescript
- * await waitForEmulator();
- * // Emulator is ready
- * ```
- */
-declare function waitForEmulator(host?: string, timeout?: number, interval?: number): Promise<void>;
-/**
- * Setup function for Jest/Vitest tests with Firestore emulator
- *
- * @returns Object with firestore instance and cleanup function
- *
- * @example
- * ```typescript
- * describe('My Tests', () => {
- *   const { firestore, cleanup } = setupFirestoreTests();
- *
- *   afterAll(cleanup);
- *
- *   beforeEach(async () => {
- *     await clearFirestore(firestore);
- *   });
- *
- *   it('should work', async () => {
- *     const eventStore = getFirestoreEventStore(firestore);
- *     // ... test code
- *   });
- * });
- * ```
- */
-declare function setupFirestoreTests(config?: FirestoreTestConfig): {
-    firestore: Firestore;
-    eventStore: FirestoreEventStore;
-    cleanup: () => Promise<void>;
-    clearData: () => Promise<void>;
-};
-
-export { type FirestoreTestConfig, clearFirestore, deleteCollection, getTestEventStore, getTestFirestore, setupFirestoreTests, waitForEmulator };