@emmett-community/emmett-google-firestore 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+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';
+export { NO_CONCURRENCY_CHECK, STREAM_DOES_NOT_EXIST, STREAM_EXISTS } from '@event-driven-io/emmett';
+
+/**
+ * Factory function to create a Firestore event store
+ *
+ * @param firestore - Firestore instance
+ * @param options - Optional configuration
+ * @returns Firestore event store instance
+ *
+ * @example
+ * ```typescript
+ * import { Firestore } from '@google-cloud/firestore';
+ * import { getFirestoreEventStore } from '@emmett-community/emmett-google-firestore';
+ *
+ * const firestore = new Firestore({ projectId: 'my-project' });
+ * const eventStore = getFirestoreEventStore(firestore);
+ * ```
+ */
+declare function getFirestoreEventStore(firestore: Firestore, options?: FirestoreEventStoreOptions): FirestoreEventStore;
+
+/**
+ * Pad version number with leading zeros for Firestore document IDs
+ * This ensures automatic ordering by version in Firestore
+ *
+ * @param version - The version number to pad
+ * @returns Zero-padded string of length 10
+ *
+ * @example
+ * padVersion(0) // "0000000000"
+ * padVersion(42) // "0000000042"
+ * padVersion(12345) // "0000012345"
+ */
+declare function padVersion(version: number | bigint): string;
+/**
+ * Parse a stream name into type and ID components
+ *
+ * @param streamName - Stream name in format "Type-id" or "Type-with-dashes-id"
+ * @returns Object with streamType and streamId
+ *
+ * @example
+ * parseStreamName("User-123") // { streamType: "User", streamId: "123" }
+ * parseStreamName("ShoppingCart-abc-def-123") // { streamType: "ShoppingCart", streamId: "abc-def-123" }
+ */
+declare function parseStreamName(streamName: string): {
+    streamType: string;
+    streamId: string;
+};
+/**
+ * Convert Firestore Timestamp to JavaScript Date
+ *
+ * @param timestamp - Firestore Timestamp
+ * @returns JavaScript Date object
+ */
+declare function timestampToDate(timestamp: Timestamp): Date;
+/**
+ * Validate expected version against current version
+ *
+ * @param streamName - Stream name for error messages
+ * @param expectedVersion - Expected version constraint
+ * @param currentVersion - Current stream version (or STREAM_DOES_NOT_EXIST if stream doesn't exist)
+ * @throws ExpectedVersionConflictError if versions don't match
+ */
+declare function assertExpectedVersionMatchesCurrent(streamName: string, expectedVersion: ExpectedStreamVersion, currentVersion: bigint | typeof STREAM_DOES_NOT_EXIST): void;
+/**
+ * Get the current stream version from metadata
+ *
+ * @param streamExists - Whether the stream document exists
+ * @param version - Version number from Firestore (if stream exists)
+ * @returns Current version as bigint or STREAM_DOES_NOT_EXIST
+ */
+declare function getCurrentStreamVersion(streamExists: boolean, version?: number): bigint | typeof STREAM_DOES_NOT_EXIST;
+/**
+ * Calculate the next expected stream version after appending events
+ *
+ * @param currentVersion - Current stream version
+ * @param eventCount - Number of events being appended
+ * @returns Next expected version as bigint
+ */
+declare function calculateNextVersion(currentVersion: bigint | typeof STREAM_DOES_NOT_EXIST, eventCount: number): bigint;
+
+export { ExpectedStreamVersion, FirestoreEventStore, FirestoreEventStoreOptions, assertExpectedVersionMatchesCurrent, calculateNextVersion, getCurrentStreamVersion, getFirestoreEventStore, padVersion, parseStreamName, timestampToDate };

package/dist/index.js

@@ -0,0 +1,242 @@
+'use strict';
+
+var emmett = require('@event-driven-io/emmett');
+
+// src/eventStore/types.ts
+var ExpectedVersionConflictError = class _ExpectedVersionConflictError extends Error {
+  constructor(streamName, expected, actual) {
+    super(
+      `Expected version conflict for stream '${streamName}': expected ${String(expected)}, actual ${String(actual)}`
+    );
+    this.streamName = streamName;
+    this.expected = expected;
+    this.actual = actual;
+    this.name = "ExpectedVersionConflictError";
+    Object.setPrototypeOf(this, _ExpectedVersionConflictError.prototype);
+  }
+};
+
+// src/eventStore/utils.ts
+function padVersion(version) {
+  return version.toString().padStart(10, "0");
+}
+function parseStreamName(streamName) {
+  const firstDashIndex = streamName.indexOf("-");
+  if (firstDashIndex === -1) {
+    return {
+      streamType: streamName,
+      streamId: ""
+    };
+  }
+  return {
+    streamType: streamName.substring(0, firstDashIndex),
+    streamId: streamName.substring(firstDashIndex + 1)
+  };
+}
+function timestampToDate(timestamp) {
+  return timestamp.toDate();
+}
+function assertExpectedVersionMatchesCurrent(streamName, expectedVersion, currentVersion) {
+  if (expectedVersion === emmett.NO_CONCURRENCY_CHECK) {
+    return;
+  }
+  if (expectedVersion === emmett.STREAM_DOES_NOT_EXIST) {
+    if (currentVersion !== emmett.STREAM_DOES_NOT_EXIST) {
+      throw new ExpectedVersionConflictError(
+        streamName,
+        expectedVersion,
+        currentVersion
+      );
+    }
+    return;
+  }
+  if (expectedVersion === emmett.STREAM_EXISTS) {
+    if (currentVersion === emmett.STREAM_DOES_NOT_EXIST) {
+      throw new ExpectedVersionConflictError(
+        streamName,
+        expectedVersion,
+        currentVersion
+      );
+    }
+    return;
+  }
+  const expectedBigInt = BigInt(expectedVersion);
+  if (currentVersion === emmett.STREAM_DOES_NOT_EXIST || currentVersion !== expectedBigInt) {
+    throw new ExpectedVersionConflictError(
+      streamName,
+      expectedVersion,
+      currentVersion
+    );
+  }
+}
+function getCurrentStreamVersion(streamExists, version) {
+  if (!streamExists) {
+    return emmett.STREAM_DOES_NOT_EXIST;
+  }
+  return BigInt(version ?? -1);
+}
+function calculateNextVersion(currentVersion, eventCount) {
+  if (currentVersion === emmett.STREAM_DOES_NOT_EXIST) {
+    return BigInt(eventCount - 1);
+  }
+  return currentVersion + BigInt(eventCount);
+}
+
+// src/eventStore/firestoreEventStore.ts
+var DEFAULT_COLLECTIONS = {
+  streams: "streams",
+  counters: "_counters"
+};
+var FirestoreEventStoreImpl = class {
+  constructor(firestore, options = {}) {
+    this.firestore = firestore;
+    this.collections = {
+      ...DEFAULT_COLLECTIONS,
+      ...options.collections
+    };
+  }
+  collections;
+  /**
+   * 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)
+        }
+      };
+    });
+  }
+  /**
+   * Aggregate stream by applying events to state
+   */
+  async aggregateStream(streamName, options) {
+    const { evolve, initialState, read } = options;
+    const events = await this.readStream(streamName, read);
+    const streamExists = events.length > 0;
+    const state = events.reduce(evolve, initialState());
+    const currentStreamVersion = streamExists ? events[events.length - 1].metadata.streamVersion : BigInt(0);
+    return {
+      state,
+      currentStreamVersion,
+      streamExists
+    };
+  }
+  /**
+   * 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
+      );
+    });
+  }
+  /**
+   * Internal method to append events within a transaction
+   */
+  async appendToStreamInTransaction(transaction, streamName, events, expectedStreamVersion) {
+    const streamRef = this.firestore.collection(this.collections.streams).doc(streamName);
+    const streamDoc = await transaction.get(streamRef);
+    const streamExists = streamDoc.exists;
+    const streamData = streamDoc.data();
+    const currentVersion = getCurrentStreamVersion(
+      streamExists,
+      streamData?.version
+    );
+    assertExpectedVersionMatchesCurrent(
+      streamName,
+      expectedStreamVersion,
+      currentVersion
+    );
+    const counterRef = this.firestore.collection(this.collections.counters).doc("global_position");
+    const counterDoc = await transaction.get(counterRef);
+    let globalPosition = counterDoc.exists ? counterDoc.data()?.value ?? 0 : 0;
+    const baseVersion = currentVersion === emmett.STREAM_DOES_NOT_EXIST ? -1 : Number(currentVersion);
+    const TimestampClass = this.firestore.constructor;
+    const now = TimestampClass.Timestamp.now();
+    events.forEach((event, index) => {
+      const eventVersion = baseVersion + 1 + index;
+      const eventRef = streamRef.collection("events").doc(padVersion(eventVersion));
+      const metadata = event.metadata;
+      const eventDocument = {
+        type: event.type,
+        data: event.data,
+        ...metadata && { metadata },
+        timestamp: now,
+        globalPosition: globalPosition++,
+        streamVersion: eventVersion
+      };
+      transaction.set(eventRef, eventDocument);
+    });
+    const newVersion = baseVersion + events.length;
+    const updatedMetadata = {
+      version: newVersion,
+      createdAt: streamData?.createdAt ?? now,
+      updatedAt: now
+    };
+    transaction.set(streamRef, updatedMetadata);
+    transaction.set(counterRef, {
+      value: globalPosition,
+      updatedAt: now
+    });
+    return {
+      nextExpectedStreamVersion: BigInt(newVersion),
+      createdNewStream: !streamExists
+    };
+  }
+};
+function getFirestoreEventStore(firestore, options) {
+  return new FirestoreEventStoreImpl(firestore, options);
+}
+
+Object.defineProperty(exports, "NO_CONCURRENCY_CHECK", {
+  enumerable: true,
+  get: function () { return emmett.NO_CONCURRENCY_CHECK; }
+});
+Object.defineProperty(exports, "STREAM_DOES_NOT_EXIST", {
+  enumerable: true,
+  get: function () { return emmett.STREAM_DOES_NOT_EXIST; }
+});
+Object.defineProperty(exports, "STREAM_EXISTS", {
+  enumerable: true,
+  get: function () { return emmett.STREAM_EXISTS; }
+});
+exports.ExpectedVersionConflictError = ExpectedVersionConflictError;
+exports.assertExpectedVersionMatchesCurrent = assertExpectedVersionMatchesCurrent;
+exports.calculateNextVersion = calculateNextVersion;
+exports.getCurrentStreamVersion = getCurrentStreamVersion;
+exports.getFirestoreEventStore = getFirestoreEventStore;
+exports.padVersion = padVersion;
+exports.parseStreamName = parseStreamName;
+exports.timestampToDate = timestampToDate;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/eventStore/types.ts","../src/eventStore/utils.ts","../src/eventStore/firestoreEventStore.ts"],"names":["NO_CONCURRENCY_CHECK","STREAM_DOES_NOT_EXIST","STREAM_EXISTS"],"mappings":"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","file":"index.js","sourcesContent":["import type { Firestore, Timestamp } from '@google-cloud/firestore';\nimport type { Event, ReadEvent, ReadEventMetadataWithGlobalPosition } from '@event-driven-io/emmett';\nimport {\n  STREAM_DOES_NOT_EXIST,\n  STREAM_EXISTS,\n  NO_CONCURRENCY_CHECK,\n  type ExpectedStreamVersion as EmmettExpectedStreamVersion,\n} from '@event-driven-io/emmett';\n\n/**\n * Expected version for stream operations\n * Uses Emmett's standard version constants for full compatibility\n * - number | bigint: Expect specific version\n * - STREAM_DOES_NOT_EXIST: Stream must not exist\n * - STREAM_EXISTS: Stream must exist (any version)\n * - NO_CONCURRENCY_CHECK: No version check\n */\nexport type ExpectedStreamVersion = EmmettExpectedStreamVersion<bigint>;\n\n// Re-export Emmett constants for convenience\nexport { STREAM_DOES_NOT_EXIST, STREAM_EXISTS, NO_CONCURRENCY_CHECK };\n\n/**\n * Options for appending events to a stream\n */\nexport interface AppendToStreamOptions {\n  expectedStreamVersion?: ExpectedStreamVersion;\n}\n\n/**\n * Result of appending events to a stream\n */\nexport interface AppendToStreamResult {\n  nextExpectedStreamVersion: bigint;\n  createdNewStream: boolean;\n}\n\n/**\n * Options for reading events from a stream\n */\nexport interface ReadStreamOptions {\n  from?: bigint;\n  to?: bigint;\n  maxCount?: number;\n}\n\n/**\n * Metadata stored in Firestore stream document\n */\nexport interface StreamMetadata {\n  version: number;\n  createdAt: Timestamp;\n  updatedAt: Timestamp;\n}\n\n/**\n * Event document structure in Firestore\n */\nexport interface EventDocument {\n  type: string;\n  data: Record<string, unknown>;\n  metadata?: Record<string, unknown>;\n  timestamp: Timestamp;\n  globalPosition: number;\n  streamVersion: number;\n}\n\n/**\n * Firestore-specific read event metadata\n */\nexport interface FirestoreReadEventMetadata extends ReadEventMetadataWithGlobalPosition {\n  streamName: string;\n  streamVersion: bigint;\n  timestamp: Date;\n}\n\n/**\n * Firestore read event\n */\nexport type FirestoreReadEvent<EventType extends Event = Event> = ReadEvent<\n  EventType,\n  FirestoreReadEventMetadata\n>;\n\n/**\n * Collection configuration for Firestore event store\n */\nexport interface CollectionConfig {\n  streams: string;\n  counters: string;\n}\n\n/**\n * Firestore event store options\n */\nexport interface FirestoreEventStoreOptions {\n  collections?: Partial<CollectionConfig>;\n}\n\n/**\n * Firestore event store interface\n */\nexport interface FirestoreEventStore {\n  /**\n   * The underlying Firestore instance\n   */\n  readonly firestore: Firestore;\n\n  /**\n   * Collection names configuration\n   */\n  readonly collections: CollectionConfig;\n\n  /**\n   * Read events from a stream\n   */\n  readStream<EventType extends Event>(\n    streamName: string,\n    options?: ReadStreamOptions,\n  ): Promise<FirestoreReadEvent<EventType>[]>;\n\n  /**\n   * Aggregate stream by applying events to state\n   */\n  aggregateStream<State, EventType extends Event>(\n    streamName: string,\n    options: {\n      evolve: (state: State, event: FirestoreReadEvent<EventType>) => State;\n      initialState: () => State;\n      read?: ReadStreamOptions;\n    },\n  ): Promise<{\n    state: State;\n    currentStreamVersion: bigint;\n    streamExists: boolean;\n  }>;\n\n  /**\n   * Append events to a stream\n   */\n  appendToStream<EventType extends Event>(\n    streamName: string,\n    events: EventType[],\n    options?: AppendToStreamOptions,\n  ): Promise<AppendToStreamResult>;\n}\n\n/**\n * Error thrown when expected version doesn't match current version\n */\nexport class ExpectedVersionConflictError extends Error {\n  constructor(\n    public readonly streamName: string,\n    public readonly expected: ExpectedStreamVersion,\n    public readonly actual: bigint | typeof STREAM_DOES_NOT_EXIST,\n  ) {\n    super(\n      `Expected version conflict for stream '${streamName}': expected ${String(expected)}, actual ${String(actual)}`,\n    );\n    this.name = 'ExpectedVersionConflictError';\n    Object.setPrototypeOf(this, ExpectedVersionConflictError.prototype);\n  }\n}\n","import type { Timestamp } from '@google-cloud/firestore';\nimport type { ExpectedStreamVersion } from './types';\nimport {\n  STREAM_DOES_NOT_EXIST,\n  STREAM_EXISTS,\n  NO_CONCURRENCY_CHECK,\n  ExpectedVersionConflictError,\n} from './types';\n\n/**\n * Pad version number with leading zeros for Firestore document IDs\n * This ensures automatic ordering by version in Firestore\n *\n * @param version - The version number to pad\n * @returns Zero-padded string of length 10\n *\n * @example\n * padVersion(0) // \"0000000000\"\n * padVersion(42) // \"0000000042\"\n * padVersion(12345) // \"0000012345\"\n */\nexport function padVersion(version: number | bigint): string {\n  return version.toString().padStart(10, '0');\n}\n\n/**\n * Parse a stream name into type and ID components\n *\n * @param streamName - Stream name in format \"Type-id\" or \"Type-with-dashes-id\"\n * @returns Object with streamType and streamId\n *\n * @example\n * parseStreamName(\"User-123\") // { streamType: \"User\", streamId: \"123\" }\n * parseStreamName(\"ShoppingCart-abc-def-123\") // { streamType: \"ShoppingCart\", streamId: \"abc-def-123\" }\n */\nexport function parseStreamName(streamName: string): {\n  streamType: string;\n  streamId: string;\n} {\n  const firstDashIndex = streamName.indexOf('-');\n\n  if (firstDashIndex === -1) {\n    return {\n      streamType: streamName,\n      streamId: '',\n    };\n  }\n\n  return {\n    streamType: streamName.substring(0, firstDashIndex),\n    streamId: streamName.substring(firstDashIndex + 1),\n  };\n}\n\n/**\n * Convert Firestore Timestamp to JavaScript Date\n *\n * @param timestamp - Firestore Timestamp\n * @returns JavaScript Date object\n */\nexport function timestampToDate(timestamp: Timestamp): Date {\n  return timestamp.toDate();\n}\n\n/**\n * Validate expected version against current version\n *\n * @param streamName - Stream name for error messages\n * @param expectedVersion - Expected version constraint\n * @param currentVersion - Current stream version (or STREAM_DOES_NOT_EXIST if stream doesn't exist)\n * @throws ExpectedVersionConflictError if versions don't match\n */\nexport function assertExpectedVersionMatchesCurrent(\n  streamName: string,\n  expectedVersion: ExpectedStreamVersion,\n  currentVersion: bigint | typeof STREAM_DOES_NOT_EXIST,\n): void {\n  // NO_CONCURRENCY_CHECK - no validation needed\n  if (expectedVersion === NO_CONCURRENCY_CHECK) {\n    return;\n  }\n\n  // STREAM_DOES_NOT_EXIST - stream must not exist\n  if (expectedVersion === STREAM_DOES_NOT_EXIST) {\n    if (currentVersion !== STREAM_DOES_NOT_EXIST) {\n      throw new ExpectedVersionConflictError(\n        streamName,\n        expectedVersion,\n        currentVersion,\n      );\n    }\n    return;\n  }\n\n  // STREAM_EXISTS - stream must exist\n  if (expectedVersion === STREAM_EXISTS) {\n    if (currentVersion === STREAM_DOES_NOT_EXIST) {\n      throw new ExpectedVersionConflictError(\n        streamName,\n        expectedVersion,\n        currentVersion,\n      );\n    }\n    return;\n  }\n\n  // Specific version number\n  const expectedBigInt = BigInt(expectedVersion);\n  if (currentVersion === STREAM_DOES_NOT_EXIST || currentVersion !== expectedBigInt) {\n    throw new ExpectedVersionConflictError(\n      streamName,\n      expectedVersion,\n      currentVersion,\n    );\n  }\n}\n\n/**\n * Get the current stream version from metadata\n *\n * @param streamExists - Whether the stream document exists\n * @param version - Version number from Firestore (if stream exists)\n * @returns Current version as bigint or STREAM_DOES_NOT_EXIST\n */\nexport function getCurrentStreamVersion(\n  streamExists: boolean,\n  version?: number,\n): bigint | typeof STREAM_DOES_NOT_EXIST {\n  if (!streamExists) {\n    return STREAM_DOES_NOT_EXIST;\n  }\n  return BigInt(version ?? -1);\n}\n\n/**\n * Calculate the next expected stream version after appending events\n *\n * @param currentVersion - Current stream version\n * @param eventCount - Number of events being appended\n * @returns Next expected version as bigint\n */\nexport function calculateNextVersion(\n  currentVersion: bigint | typeof STREAM_DOES_NOT_EXIST,\n  eventCount: number,\n): bigint {\n  if (currentVersion === STREAM_DOES_NOT_EXIST) {\n    return BigInt(eventCount - 1);\n  }\n  // Type assertion needed because TypeScript doesn't narrow ExpectedStreamVersionGeneral properly\n  return (currentVersion as bigint) + BigInt(eventCount);\n}\n","import type { Firestore, Transaction, Timestamp } from '@google-cloud/firestore';\nimport type { Event } from '@event-driven-io/emmett';\nimport type {\n  AppendToStreamOptions,\n  AppendToStreamResult,\n  CollectionConfig,\n  EventDocument,\n  ExpectedStreamVersion,\n  FirestoreEventStore,\n  FirestoreEventStoreOptions,\n  FirestoreReadEvent,\n  ReadStreamOptions,\n  StreamMetadata,\n} from './types';\nimport { NO_CONCURRENCY_CHECK, STREAM_DOES_NOT_EXIST } from './types';\nimport {\n  assertExpectedVersionMatchesCurrent,\n  getCurrentStreamVersion,\n  padVersion,\n  timestampToDate,\n} from './utils';\n\nconst DEFAULT_COLLECTIONS: CollectionConfig = {\n  streams: 'streams',\n  counters: '_counters',\n};\n\n/**\n * Firestore Event Store Implementation\n *\n * Stores events in Firestore using a subcollection pattern:\n * - /streams/{streamName} - Stream metadata (version, timestamps)\n * - /streams/{streamName}/events/{version} - Individual events\n * - /_counters/global_position - Global event counter\n */\nexport class FirestoreEventStoreImpl implements FirestoreEventStore {\n  public readonly collections: CollectionConfig;\n\n  constructor(\n    public readonly firestore: Firestore,\n    options: FirestoreEventStoreOptions = {},\n  ) {\n    this.collections = {\n      ...DEFAULT_COLLECTIONS,\n      ...options.collections,\n    };\n  }\n\n  /**\n   * Read events from a stream\n   */\n  async readStream<EventType extends Event>(\n    streamName: string,\n    options: ReadStreamOptions = {},\n  ): Promise<FirestoreReadEvent<EventType>[]> {\n    const { from, to, maxCount } = options;\n\n    // Reference to events subcollection\n    let query = this.firestore\n      .collection(this.collections.streams)\n      .doc(streamName)\n      .collection('events')\n      .orderBy('streamVersion', 'asc');\n\n    // Apply range filters\n    if (from !== undefined) {\n      query = query.where('streamVersion', '>=', Number(from));\n    }\n    if (to !== undefined) {\n      query = query.where('streamVersion', '<=', Number(to));\n    }\n    if (maxCount !== undefined && maxCount > 0) {\n      query = query.limit(maxCount);\n    }\n\n    // Execute query\n    const snapshot = await query.get();\n\n    // Transform Firestore documents to events\n    return snapshot.docs.map((doc) => {\n      const data = doc.data() as EventDocument;\n      return {\n        type: data.type,\n        data: data.data,\n        metadata: {\n          ...data.metadata,\n          streamName,\n          streamVersion: BigInt(data.streamVersion),\n          streamPosition: BigInt(data.streamVersion),\n          globalPosition: BigInt(data.globalPosition),\n          timestamp: timestampToDate(data.timestamp),\n        },\n      } as FirestoreReadEvent<EventType>;\n    });\n  }\n\n  /**\n   * Aggregate stream by applying events to state\n   */\n  async aggregateStream<State, EventType extends Event>(\n    streamName: string,\n    options: {\n      evolve: (state: State, event: FirestoreReadEvent<EventType>) => State;\n      initialState: () => State;\n      read?: ReadStreamOptions;\n    },\n  ): Promise<{\n    state: State;\n    currentStreamVersion: bigint;\n    streamExists: boolean;\n  }> {\n    const { evolve, initialState, read } = options;\n    const events = await this.readStream<EventType>(streamName, read);\n\n    const streamExists = events.length > 0;\n    const state = events.reduce(evolve, initialState());\n    const currentStreamVersion = streamExists\n      ? events[events.length - 1].metadata.streamVersion\n      : BigInt(0);\n\n    return {\n      state,\n      currentStreamVersion,\n      streamExists,\n    };\n  }\n\n  /**\n   * Append events to a stream with optimistic concurrency control\n   */\n  async appendToStream<EventType extends Event>(\n    streamName: string,\n    events: EventType[],\n    options: AppendToStreamOptions = {},\n  ): Promise<AppendToStreamResult> {\n    if (events.length === 0) {\n      throw new Error('Cannot append empty event array');\n    }\n\n    const { expectedStreamVersion = NO_CONCURRENCY_CHECK } = options;\n\n    // Execute in transaction for atomicity\n    return await this.firestore.runTransaction(async (transaction) => {\n      return await this.appendToStreamInTransaction(\n        transaction,\n        streamName,\n        events,\n        expectedStreamVersion,\n      );\n    });\n  }\n\n  /**\n   * Internal method to append events within a transaction\n   */\n  private async appendToStreamInTransaction<EventType extends Event>(\n    transaction: Transaction,\n    streamName: string,\n    events: EventType[],\n    expectedStreamVersion: ExpectedStreamVersion,\n  ): Promise<AppendToStreamResult> {\n    // 1. Get stream metadata reference\n    const streamRef = this.firestore\n      .collection(this.collections.streams)\n      .doc(streamName);\n\n    const streamDoc = await transaction.get(streamRef);\n    const streamExists = streamDoc.exists;\n    const streamData = streamDoc.data() as StreamMetadata | undefined;\n\n    // 2. Get current version and validate expected version\n    const currentVersion = getCurrentStreamVersion(\n      streamExists,\n      streamData?.version,\n    );\n\n    assertExpectedVersionMatchesCurrent(\n      streamName,\n      expectedStreamVersion,\n      currentVersion,\n    );\n\n    // 3. Get and increment global position counter\n    const counterRef = this.firestore\n      .collection(this.collections.counters)\n      .doc('global_position');\n\n    const counterDoc = await transaction.get(counterRef);\n    let globalPosition = counterDoc.exists\n      ? (counterDoc.data()?.value as number) ?? 0\n      : 0;\n\n    // 4. Calculate starting version for new events\n    const baseVersion =\n      currentVersion === STREAM_DOES_NOT_EXIST ? -1 : Number(currentVersion);\n\n    // 5. Append events to subcollection\n    const TimestampClass = this.firestore.constructor as unknown as { Timestamp: typeof Timestamp };\n    const now = TimestampClass.Timestamp.now();\n\n    events.forEach((event, index) => {\n      const eventVersion = baseVersion + 1 + index;\n      const eventRef = streamRef\n        .collection('events')\n        .doc(padVersion(eventVersion));\n\n      const metadata = (event as { metadata?: Record<string, unknown> }).metadata;\n      const eventDocument: EventDocument = {\n        type: event.type,\n        data: event.data,\n        ...(metadata && { metadata }),\n        timestamp: now,\n        globalPosition: globalPosition++,\n        streamVersion: eventVersion,\n      };\n\n      transaction.set(eventRef, eventDocument);\n    });\n\n    // 6. Update stream metadata\n    const newVersion = baseVersion + events.length;\n    const updatedMetadata: StreamMetadata = {\n      version: newVersion,\n      createdAt: streamData?.createdAt ?? now,\n      updatedAt: now,\n    };\n\n    transaction.set(streamRef, updatedMetadata);\n\n    // 7. Update global position counter\n    transaction.set(counterRef, {\n      value: globalPosition,\n      updatedAt: now,\n    });\n\n    // 8. Return result\n    return {\n      nextExpectedStreamVersion: BigInt(newVersion),\n      createdNewStream: !streamExists,\n    };\n  }\n}\n\n/**\n * Factory function to create a Firestore event store\n *\n * @param firestore - Firestore instance\n * @param options - Optional configuration\n * @returns Firestore event store instance\n *\n * @example\n * ```typescript\n * import { Firestore } from '@google-cloud/firestore';\n * import { getFirestoreEventStore } from '@emmett-community/emmett-google-firestore';\n *\n * const firestore = new Firestore({ projectId: 'my-project' });\n * const eventStore = getFirestoreEventStore(firestore);\n * ```\n */\nexport function getFirestoreEventStore(\n  firestore: Firestore,\n  options?: FirestoreEventStoreOptions,\n): FirestoreEventStore {\n  return new FirestoreEventStoreImpl(firestore, options);\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,222 @@
+import { NO_CONCURRENCY_CHECK, STREAM_DOES_NOT_EXIST, STREAM_EXISTS } from '@event-driven-io/emmett';
+export { NO_CONCURRENCY_CHECK, STREAM_DOES_NOT_EXIST, STREAM_EXISTS } from '@event-driven-io/emmett';
+
+// src/eventStore/types.ts
+var ExpectedVersionConflictError = class _ExpectedVersionConflictError extends Error {
+  constructor(streamName, expected, actual) {
+    super(
+      `Expected version conflict for stream '${streamName}': expected ${String(expected)}, actual ${String(actual)}`
+    );
+    this.streamName = streamName;
+    this.expected = expected;
+    this.actual = actual;
+    this.name = "ExpectedVersionConflictError";
+    Object.setPrototypeOf(this, _ExpectedVersionConflictError.prototype);
+  }
+};
+
+// src/eventStore/utils.ts
+function padVersion(version) {
+  return version.toString().padStart(10, "0");
+}
+function parseStreamName(streamName) {
+  const firstDashIndex = streamName.indexOf("-");
+  if (firstDashIndex === -1) {
+    return {
+      streamType: streamName,
+      streamId: ""
+    };
+  }
+  return {
+    streamType: streamName.substring(0, firstDashIndex),
+    streamId: streamName.substring(firstDashIndex + 1)
+  };
+}
+function timestampToDate(timestamp) {
+  return timestamp.toDate();
+}
+function assertExpectedVersionMatchesCurrent(streamName, expectedVersion, currentVersion) {
+  if (expectedVersion === NO_CONCURRENCY_CHECK) {
+    return;
+  }
+  if (expectedVersion === STREAM_DOES_NOT_EXIST) {
+    if (currentVersion !== STREAM_DOES_NOT_EXIST) {
+      throw new ExpectedVersionConflictError(
+        streamName,
+        expectedVersion,
+        currentVersion
+      );
+    }
+    return;
+  }
+  if (expectedVersion === STREAM_EXISTS) {
+    if (currentVersion === STREAM_DOES_NOT_EXIST) {
+      throw new ExpectedVersionConflictError(
+        streamName,
+        expectedVersion,
+        currentVersion
+      );
+    }
+    return;
+  }
+  const expectedBigInt = BigInt(expectedVersion);
+  if (currentVersion === STREAM_DOES_NOT_EXIST || currentVersion !== expectedBigInt) {
+    throw new ExpectedVersionConflictError(
+      streamName,
+      expectedVersion,
+      currentVersion
+    );
+  }
+}
+function getCurrentStreamVersion(streamExists, version) {
+  if (!streamExists) {
+    return STREAM_DOES_NOT_EXIST;
+  }
+  return BigInt(version ?? -1);
+}
+function calculateNextVersion(currentVersion, eventCount) {
+  if (currentVersion === STREAM_DOES_NOT_EXIST) {
+    return BigInt(eventCount - 1);
+  }
+  return currentVersion + BigInt(eventCount);
+}
+
+// src/eventStore/firestoreEventStore.ts
+var DEFAULT_COLLECTIONS = {
+  streams: "streams",
+  counters: "_counters"
+};
+var FirestoreEventStoreImpl = class {
+  constructor(firestore, options = {}) {
+    this.firestore = firestore;
+    this.collections = {
+      ...DEFAULT_COLLECTIONS,
+      ...options.collections
+    };
+  }
+  collections;
+  /**
+   * 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)
+        }
+      };
+    });
+  }
+  /**
+   * Aggregate stream by applying events to state
+   */
+  async aggregateStream(streamName, options) {
+    const { evolve, initialState, read } = options;
+    const events = await this.readStream(streamName, read);
+    const streamExists = events.length > 0;
+    const state = events.reduce(evolve, initialState());
+    const currentStreamVersion = streamExists ? events[events.length - 1].metadata.streamVersion : BigInt(0);
+    return {
+      state,
+      currentStreamVersion,
+      streamExists
+    };
+  }
+  /**
+   * 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 = NO_CONCURRENCY_CHECK } = options;
+    return await this.firestore.runTransaction(async (transaction) => {
+      return await this.appendToStreamInTransaction(
+        transaction,
+        streamName,
+        events,
+        expectedStreamVersion
+      );
+    });
+  }
+  /**
+   * Internal method to append events within a transaction
+   */
+  async appendToStreamInTransaction(transaction, streamName, events, expectedStreamVersion) {
+    const streamRef = this.firestore.collection(this.collections.streams).doc(streamName);
+    const streamDoc = await transaction.get(streamRef);
+    const streamExists = streamDoc.exists;
+    const streamData = streamDoc.data();
+    const currentVersion = getCurrentStreamVersion(
+      streamExists,
+      streamData?.version
+    );
+    assertExpectedVersionMatchesCurrent(
+      streamName,
+      expectedStreamVersion,
+      currentVersion
+    );
+    const counterRef = this.firestore.collection(this.collections.counters).doc("global_position");
+    const counterDoc = await transaction.get(counterRef);
+    let globalPosition = counterDoc.exists ? counterDoc.data()?.value ?? 0 : 0;
+    const baseVersion = currentVersion === STREAM_DOES_NOT_EXIST ? -1 : Number(currentVersion);
+    const TimestampClass = this.firestore.constructor;
+    const now = TimestampClass.Timestamp.now();
+    events.forEach((event, index) => {
+      const eventVersion = baseVersion + 1 + index;
+      const eventRef = streamRef.collection("events").doc(padVersion(eventVersion));
+      const metadata = event.metadata;
+      const eventDocument = {
+        type: event.type,
+        data: event.data,
+        ...metadata && { metadata },
+        timestamp: now,
+        globalPosition: globalPosition++,
+        streamVersion: eventVersion
+      };
+      transaction.set(eventRef, eventDocument);
+    });
+    const newVersion = baseVersion + events.length;
+    const updatedMetadata = {
+      version: newVersion,
+      createdAt: streamData?.createdAt ?? now,
+      updatedAt: now
+    };
+    transaction.set(streamRef, updatedMetadata);
+    transaction.set(counterRef, {
+      value: globalPosition,
+      updatedAt: now
+    });
+    return {
+      nextExpectedStreamVersion: BigInt(newVersion),
+      createdNewStream: !streamExists
+    };
+  }
+};
+function getFirestoreEventStore(firestore, options) {
+  return new FirestoreEventStoreImpl(firestore, options);
+}
+
+export { ExpectedVersionConflictError, assertExpectedVersionMatchesCurrent, calculateNextVersion, getCurrentStreamVersion, getFirestoreEventStore, padVersion, parseStreamName, timestampToDate };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/eventStore/types.ts","../src/eventStore/utils.ts","../src/eventStore/firestoreEventStore.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["import type { Firestore, Timestamp } from '@google-cloud/firestore';\nimport type { Event, ReadEvent, ReadEventMetadataWithGlobalPosition } from '@event-driven-io/emmett';\nimport {\n  STREAM_DOES_NOT_EXIST,\n  STREAM_EXISTS,\n  NO_CONCURRENCY_CHECK,\n  type ExpectedStreamVersion as EmmettExpectedStreamVersion,\n} from '@event-driven-io/emmett';\n\n/**\n * Expected version for stream operations\n * Uses Emmett's standard version constants for full compatibility\n * - number | bigint: Expect specific version\n * - STREAM_DOES_NOT_EXIST: Stream must not exist\n * - STREAM_EXISTS: Stream must exist (any version)\n * - NO_CONCURRENCY_CHECK: No version check\n */\nexport type ExpectedStreamVersion = EmmettExpectedStreamVersion<bigint>;\n\n// Re-export Emmett constants for convenience\nexport { STREAM_DOES_NOT_EXIST, STREAM_EXISTS, NO_CONCURRENCY_CHECK };\n\n/**\n * Options for appending events to a stream\n */\nexport interface AppendToStreamOptions {\n  expectedStreamVersion?: ExpectedStreamVersion;\n}\n\n/**\n * Result of appending events to a stream\n */\nexport interface AppendToStreamResult {\n  nextExpectedStreamVersion: bigint;\n  createdNewStream: boolean;\n}\n\n/**\n * Options for reading events from a stream\n */\nexport interface ReadStreamOptions {\n  from?: bigint;\n  to?: bigint;\n  maxCount?: number;\n}\n\n/**\n * Metadata stored in Firestore stream document\n */\nexport interface StreamMetadata {\n  version: number;\n  createdAt: Timestamp;\n  updatedAt: Timestamp;\n}\n\n/**\n * Event document structure in Firestore\n */\nexport interface EventDocument {\n  type: string;\n  data: Record<string, unknown>;\n  metadata?: Record<string, unknown>;\n  timestamp: Timestamp;\n  globalPosition: number;\n  streamVersion: number;\n}\n\n/**\n * Firestore-specific read event metadata\n */\nexport interface FirestoreReadEventMetadata extends ReadEventMetadataWithGlobalPosition {\n  streamName: string;\n  streamVersion: bigint;\n  timestamp: Date;\n}\n\n/**\n * Firestore read event\n */\nexport type FirestoreReadEvent<EventType extends Event = Event> = ReadEvent<\n  EventType,\n  FirestoreReadEventMetadata\n>;\n\n/**\n * Collection configuration for Firestore event store\n */\nexport interface CollectionConfig {\n  streams: string;\n  counters: string;\n}\n\n/**\n * Firestore event store options\n */\nexport interface FirestoreEventStoreOptions {\n  collections?: Partial<CollectionConfig>;\n}\n\n/**\n * Firestore event store interface\n */\nexport interface FirestoreEventStore {\n  /**\n   * The underlying Firestore instance\n   */\n  readonly firestore: Firestore;\n\n  /**\n   * Collection names configuration\n   */\n  readonly collections: CollectionConfig;\n\n  /**\n   * Read events from a stream\n   */\n  readStream<EventType extends Event>(\n    streamName: string,\n    options?: ReadStreamOptions,\n  ): Promise<FirestoreReadEvent<EventType>[]>;\n\n  /**\n   * Aggregate stream by applying events to state\n   */\n  aggregateStream<State, EventType extends Event>(\n    streamName: string,\n    options: {\n      evolve: (state: State, event: FirestoreReadEvent<EventType>) => State;\n      initialState: () => State;\n      read?: ReadStreamOptions;\n    },\n  ): Promise<{\n    state: State;\n    currentStreamVersion: bigint;\n    streamExists: boolean;\n  }>;\n\n  /**\n   * Append events to a stream\n   */\n  appendToStream<EventType extends Event>(\n    streamName: string,\n    events: EventType[],\n    options?: AppendToStreamOptions,\n  ): Promise<AppendToStreamResult>;\n}\n\n/**\n * Error thrown when expected version doesn't match current version\n */\nexport class ExpectedVersionConflictError extends Error {\n  constructor(\n    public readonly streamName: string,\n    public readonly expected: ExpectedStreamVersion,\n    public readonly actual: bigint | typeof STREAM_DOES_NOT_EXIST,\n  ) {\n    super(\n      `Expected version conflict for stream '${streamName}': expected ${String(expected)}, actual ${String(actual)}`,\n    );\n    this.name = 'ExpectedVersionConflictError';\n    Object.setPrototypeOf(this, ExpectedVersionConflictError.prototype);\n  }\n}\n","import type { Timestamp } from '@google-cloud/firestore';\nimport type { ExpectedStreamVersion } from './types';\nimport {\n  STREAM_DOES_NOT_EXIST,\n  STREAM_EXISTS,\n  NO_CONCURRENCY_CHECK,\n  ExpectedVersionConflictError,\n} from './types';\n\n/**\n * Pad version number with leading zeros for Firestore document IDs\n * This ensures automatic ordering by version in Firestore\n *\n * @param version - The version number to pad\n * @returns Zero-padded string of length 10\n *\n * @example\n * padVersion(0) // \"0000000000\"\n * padVersion(42) // \"0000000042\"\n * padVersion(12345) // \"0000012345\"\n */\nexport function padVersion(version: number | bigint): string {\n  return version.toString().padStart(10, '0');\n}\n\n/**\n * Parse a stream name into type and ID components\n *\n * @param streamName - Stream name in format \"Type-id\" or \"Type-with-dashes-id\"\n * @returns Object with streamType and streamId\n *\n * @example\n * parseStreamName(\"User-123\") // { streamType: \"User\", streamId: \"123\" }\n * parseStreamName(\"ShoppingCart-abc-def-123\") // { streamType: \"ShoppingCart\", streamId: \"abc-def-123\" }\n */\nexport function parseStreamName(streamName: string): {\n  streamType: string;\n  streamId: string;\n} {\n  const firstDashIndex = streamName.indexOf('-');\n\n  if (firstDashIndex === -1) {\n    return {\n      streamType: streamName,\n      streamId: '',\n    };\n  }\n\n  return {\n    streamType: streamName.substring(0, firstDashIndex),\n    streamId: streamName.substring(firstDashIndex + 1),\n  };\n}\n\n/**\n * Convert Firestore Timestamp to JavaScript Date\n *\n * @param timestamp - Firestore Timestamp\n * @returns JavaScript Date object\n */\nexport function timestampToDate(timestamp: Timestamp): Date {\n  return timestamp.toDate();\n}\n\n/**\n * Validate expected version against current version\n *\n * @param streamName - Stream name for error messages\n * @param expectedVersion - Expected version constraint\n * @param currentVersion - Current stream version (or STREAM_DOES_NOT_EXIST if stream doesn't exist)\n * @throws ExpectedVersionConflictError if versions don't match\n */\nexport function assertExpectedVersionMatchesCurrent(\n  streamName: string,\n  expectedVersion: ExpectedStreamVersion,\n  currentVersion: bigint | typeof STREAM_DOES_NOT_EXIST,\n): void {\n  // NO_CONCURRENCY_CHECK - no validation needed\n  if (expectedVersion === NO_CONCURRENCY_CHECK) {\n    return;\n  }\n\n  // STREAM_DOES_NOT_EXIST - stream must not exist\n  if (expectedVersion === STREAM_DOES_NOT_EXIST) {\n    if (currentVersion !== STREAM_DOES_NOT_EXIST) {\n      throw new ExpectedVersionConflictError(\n        streamName,\n        expectedVersion,\n        currentVersion,\n      );\n    }\n    return;\n  }\n\n  // STREAM_EXISTS - stream must exist\n  if (expectedVersion === STREAM_EXISTS) {\n    if (currentVersion === STREAM_DOES_NOT_EXIST) {\n      throw new ExpectedVersionConflictError(\n        streamName,\n        expectedVersion,\n        currentVersion,\n      );\n    }\n    return;\n  }\n\n  // Specific version number\n  const expectedBigInt = BigInt(expectedVersion);\n  if (currentVersion === STREAM_DOES_NOT_EXIST || currentVersion !== expectedBigInt) {\n    throw new ExpectedVersionConflictError(\n      streamName,\n      expectedVersion,\n      currentVersion,\n    );\n  }\n}\n\n/**\n * Get the current stream version from metadata\n *\n * @param streamExists - Whether the stream document exists\n * @param version - Version number from Firestore (if stream exists)\n * @returns Current version as bigint or STREAM_DOES_NOT_EXIST\n */\nexport function getCurrentStreamVersion(\n  streamExists: boolean,\n  version?: number,\n): bigint | typeof STREAM_DOES_NOT_EXIST {\n  if (!streamExists) {\n    return STREAM_DOES_NOT_EXIST;\n  }\n  return BigInt(version ?? -1);\n}\n\n/**\n * Calculate the next expected stream version after appending events\n *\n * @param currentVersion - Current stream version\n * @param eventCount - Number of events being appended\n * @returns Next expected version as bigint\n */\nexport function calculateNextVersion(\n  currentVersion: bigint | typeof STREAM_DOES_NOT_EXIST,\n  eventCount: number,\n): bigint {\n  if (currentVersion === STREAM_DOES_NOT_EXIST) {\n    return BigInt(eventCount - 1);\n  }\n  // Type assertion needed because TypeScript doesn't narrow ExpectedStreamVersionGeneral properly\n  return (currentVersion as bigint) + BigInt(eventCount);\n}\n","import type { Firestore, Transaction, Timestamp } from '@google-cloud/firestore';\nimport type { Event } from '@event-driven-io/emmett';\nimport type {\n  AppendToStreamOptions,\n  AppendToStreamResult,\n  CollectionConfig,\n  EventDocument,\n  ExpectedStreamVersion,\n  FirestoreEventStore,\n  FirestoreEventStoreOptions,\n  FirestoreReadEvent,\n  ReadStreamOptions,\n  StreamMetadata,\n} from './types';\nimport { NO_CONCURRENCY_CHECK, STREAM_DOES_NOT_EXIST } from './types';\nimport {\n  assertExpectedVersionMatchesCurrent,\n  getCurrentStreamVersion,\n  padVersion,\n  timestampToDate,\n} from './utils';\n\nconst DEFAULT_COLLECTIONS: CollectionConfig = {\n  streams: 'streams',\n  counters: '_counters',\n};\n\n/**\n * Firestore Event Store Implementation\n *\n * Stores events in Firestore using a subcollection pattern:\n * - /streams/{streamName} - Stream metadata (version, timestamps)\n * - /streams/{streamName}/events/{version} - Individual events\n * - /_counters/global_position - Global event counter\n */\nexport class FirestoreEventStoreImpl implements FirestoreEventStore {\n  public readonly collections: CollectionConfig;\n\n  constructor(\n    public readonly firestore: Firestore,\n    options: FirestoreEventStoreOptions = {},\n  ) {\n    this.collections = {\n      ...DEFAULT_COLLECTIONS,\n      ...options.collections,\n    };\n  }\n\n  /**\n   * Read events from a stream\n   */\n  async readStream<EventType extends Event>(\n    streamName: string,\n    options: ReadStreamOptions = {},\n  ): Promise<FirestoreReadEvent<EventType>[]> {\n    const { from, to, maxCount } = options;\n\n    // Reference to events subcollection\n    let query = this.firestore\n      .collection(this.collections.streams)\n      .doc(streamName)\n      .collection('events')\n      .orderBy('streamVersion', 'asc');\n\n    // Apply range filters\n    if (from !== undefined) {\n      query = query.where('streamVersion', '>=', Number(from));\n    }\n    if (to !== undefined) {\n      query = query.where('streamVersion', '<=', Number(to));\n    }\n    if (maxCount !== undefined && maxCount > 0) {\n      query = query.limit(maxCount);\n    }\n\n    // Execute query\n    const snapshot = await query.get();\n\n    // Transform Firestore documents to events\n    return snapshot.docs.map((doc) => {\n      const data = doc.data() as EventDocument;\n      return {\n        type: data.type,\n        data: data.data,\n        metadata: {\n          ...data.metadata,\n          streamName,\n          streamVersion: BigInt(data.streamVersion),\n          streamPosition: BigInt(data.streamVersion),\n          globalPosition: BigInt(data.globalPosition),\n          timestamp: timestampToDate(data.timestamp),\n        },\n      } as FirestoreReadEvent<EventType>;\n    });\n  }\n\n  /**\n   * Aggregate stream by applying events to state\n   */\n  async aggregateStream<State, EventType extends Event>(\n    streamName: string,\n    options: {\n      evolve: (state: State, event: FirestoreReadEvent<EventType>) => State;\n      initialState: () => State;\n      read?: ReadStreamOptions;\n    },\n  ): Promise<{\n    state: State;\n    currentStreamVersion: bigint;\n    streamExists: boolean;\n  }> {\n    const { evolve, initialState, read } = options;\n    const events = await this.readStream<EventType>(streamName, read);\n\n    const streamExists = events.length > 0;\n    const state = events.reduce(evolve, initialState());\n    const currentStreamVersion = streamExists\n      ? events[events.length - 1].metadata.streamVersion\n      : BigInt(0);\n\n    return {\n      state,\n      currentStreamVersion,\n      streamExists,\n    };\n  }\n\n  /**\n   * Append events to a stream with optimistic concurrency control\n   */\n  async appendToStream<EventType extends Event>(\n    streamName: string,\n    events: EventType[],\n    options: AppendToStreamOptions = {},\n  ): Promise<AppendToStreamResult> {\n    if (events.length === 0) {\n      throw new Error('Cannot append empty event array');\n    }\n\n    const { expectedStreamVersion = NO_CONCURRENCY_CHECK } = options;\n\n    // Execute in transaction for atomicity\n    return await this.firestore.runTransaction(async (transaction) => {\n      return await this.appendToStreamInTransaction(\n        transaction,\n        streamName,\n        events,\n        expectedStreamVersion,\n      );\n    });\n  }\n\n  /**\n   * Internal method to append events within a transaction\n   */\n  private async appendToStreamInTransaction<EventType extends Event>(\n    transaction: Transaction,\n    streamName: string,\n    events: EventType[],\n    expectedStreamVersion: ExpectedStreamVersion,\n  ): Promise<AppendToStreamResult> {\n    // 1. Get stream metadata reference\n    const streamRef = this.firestore\n      .collection(this.collections.streams)\n      .doc(streamName);\n\n    const streamDoc = await transaction.get(streamRef);\n    const streamExists = streamDoc.exists;\n    const streamData = streamDoc.data() as StreamMetadata | undefined;\n\n    // 2. Get current version and validate expected version\n    const currentVersion = getCurrentStreamVersion(\n      streamExists,\n      streamData?.version,\n    );\n\n    assertExpectedVersionMatchesCurrent(\n      streamName,\n      expectedStreamVersion,\n      currentVersion,\n    );\n\n    // 3. Get and increment global position counter\n    const counterRef = this.firestore\n      .collection(this.collections.counters)\n      .doc('global_position');\n\n    const counterDoc = await transaction.get(counterRef);\n    let globalPosition = counterDoc.exists\n      ? (counterDoc.data()?.value as number) ?? 0\n      : 0;\n\n    // 4. Calculate starting version for new events\n    const baseVersion =\n      currentVersion === STREAM_DOES_NOT_EXIST ? -1 : Number(currentVersion);\n\n    // 5. Append events to subcollection\n    const TimestampClass = this.firestore.constructor as unknown as { Timestamp: typeof Timestamp };\n    const now = TimestampClass.Timestamp.now();\n\n    events.forEach((event, index) => {\n      const eventVersion = baseVersion + 1 + index;\n      const eventRef = streamRef\n        .collection('events')\n        .doc(padVersion(eventVersion));\n\n      const metadata = (event as { metadata?: Record<string, unknown> }).metadata;\n      const eventDocument: EventDocument = {\n        type: event.type,\n        data: event.data,\n        ...(metadata && { metadata }),\n        timestamp: now,\n        globalPosition: globalPosition++,\n        streamVersion: eventVersion,\n      };\n\n      transaction.set(eventRef, eventDocument);\n    });\n\n    // 6. Update stream metadata\n    const newVersion = baseVersion + events.length;\n    const updatedMetadata: StreamMetadata = {\n      version: newVersion,\n      createdAt: streamData?.createdAt ?? now,\n      updatedAt: now,\n    };\n\n    transaction.set(streamRef, updatedMetadata);\n\n    // 7. Update global position counter\n    transaction.set(counterRef, {\n      value: globalPosition,\n      updatedAt: now,\n    });\n\n    // 8. Return result\n    return {\n      nextExpectedStreamVersion: BigInt(newVersion),\n      createdNewStream: !streamExists,\n    };\n  }\n}\n\n/**\n * Factory function to create a Firestore event store\n *\n * @param firestore - Firestore instance\n * @param options - Optional configuration\n * @returns Firestore event store instance\n *\n * @example\n * ```typescript\n * import { Firestore } from '@google-cloud/firestore';\n * import { getFirestoreEventStore } from '@emmett-community/emmett-google-firestore';\n *\n * const firestore = new Firestore({ projectId: 'my-project' });\n * const eventStore = getFirestoreEventStore(firestore);\n * ```\n */\nexport function getFirestoreEventStore(\n  firestore: Firestore,\n  options?: FirestoreEventStoreOptions,\n): FirestoreEventStore {\n  return new FirestoreEventStoreImpl(firestore, options);\n}\n"]}