@saga-bus/store-mongo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Dean Foran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# @saga-bus/store-mongo
+
+MongoDB saga store for saga-bus.
+
+## Installation
+
+```bash
+pnpm add @saga-bus/store-mongo mongodb
+```
+
+## Usage
+
+```typescript
+import { MongoClient } from "mongodb";
+import { MongoSagaStore } from "@saga-bus/store-mongo";
+import { createBus } from "@saga-bus/core";
+
+const client = new MongoClient("mongodb://localhost:27017");
+await client.connect();
+
+const store = new MongoSagaStore({
+  db: client.db("myapp"),
+  collectionName: "saga_instances",
+});
+
+const bus = createBus({
+  sagas: [{ definition: mySaga, store }],
+  transport,
+});
+```
+
+## Document Schema
+
+Documents are stored with this structure:
+
+```typescript
+{
+  _id: "OrderSaga:saga-123",      // Composite key
+  sagaName: "OrderSaga",
+  sagaId: "saga-123",
+  correlationId: "order-456",
+  version: 1,
+  isCompleted: false,
+  state: { /* saga state */ },
+  createdAt: ISODate("..."),
+  updatedAt: ISODate("...")
+}
+```
+
+## Indexes
+
+The store automatically creates indexes on:
+
+- `_id` (primary key)
+- `sagaName + correlationId` (for correlation lookups)
+- `isCompleted + updatedAt` (for cleanup queries)
+
+## Features
+
+- Optimistic concurrency via version field
+- Atomic updates with `findOneAndUpdate`
+- Efficient correlation ID lookups
+- TTL-based cleanup support
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `db` | `Db` | required | MongoDB database instance |
+| `collectionName` | `string` | `"saga_instances"` | Collection name |
+
+## Sharing Across Sagas
+
+A single store instance can be shared across multiple sagas:
+
+```typescript
+const store = new MongoSagaStore({ db });
+
+const bus = createBus({
+  transport,
+  store, // shared by all sagas
+  sagas: [
+    { definition: orderSaga },
+    { definition: paymentSaga },
+  ],
+});
+```
+
+Data is isolated by `sagaName` in the collection, so different saga types won't conflict.
+
+## Cleanup
+
+Query completed sagas for cleanup:
+
+```typescript
+const completedSagas = await db
+  .collection("saga_instances")
+  .find({
+    isCompleted: true,
+    updatedAt: { $lt: thirtyDaysAgo },
+  })
+  .toArray();
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,175 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MongoSagaStore: () => MongoSagaStore
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/MongoSagaStore.ts
+var import_core = require("@saga-bus/core");
+var MongoSagaStore = class {
+  collection;
+  constructor(options) {
+    const collectionName = options.collectionName ?? "saga_instances";
+    this.collection = options.db.collection(collectionName);
+  }
+  /**
+   * Create indexes for optimal query performance.
+   * Call once during application startup.
+   */
+  async ensureIndexes() {
+    await this.collection.createIndex(
+      { sagaName: 1, correlationId: 1 },
+      { unique: true }
+    );
+    await this.collection.createIndex({
+      sagaName: 1,
+      isCompleted: 1,
+      updatedAt: 1
+    });
+    await this.collection.createIndex({ sagaName: 1, sagaId: 1 });
+  }
+  makeId(sagaName, sagaId) {
+    return `${sagaName}:${sagaId}`;
+  }
+  async getById(sagaName, sagaId) {
+    const doc = await this.collection.findOne({
+      _id: this.makeId(sagaName, sagaId)
+    });
+    if (!doc) {
+      return null;
+    }
+    return this.documentToState(doc);
+  }
+  async getByCorrelationId(sagaName, correlationId) {
+    const doc = await this.collection.findOne({
+      sagaName,
+      correlationId
+    });
+    if (!doc) {
+      return null;
+    }
+    return this.documentToState(doc);
+  }
+  async insert(sagaName, correlationId, state) {
+    const { sagaId, version, isCompleted, createdAt, updatedAt } = state.metadata;
+    const doc = {
+      _id: this.makeId(sagaName, sagaId),
+      sagaName,
+      sagaId,
+      correlationId,
+      version,
+      isCompleted,
+      state,
+      createdAt,
+      updatedAt
+    };
+    await this.collection.insertOne(doc);
+  }
+  async update(sagaName, state, expectedVersion) {
+    const { sagaId, version, isCompleted, updatedAt } = state.metadata;
+    const result = await this.collection.updateOne(
+      {
+        _id: this.makeId(sagaName, sagaId),
+        version: expectedVersion
+      },
+      {
+        $set: {
+          version,
+          isCompleted,
+          state,
+          updatedAt
+        }
+      }
+    );
+    if (result.matchedCount === 0) {
+      const existing = await this.getById(sagaName, sagaId);
+      if (existing) {
+        throw new import_core.ConcurrencyError(
+          sagaId,
+          expectedVersion,
+          existing.metadata.version
+        );
+      } else {
+        throw new Error(`Saga ${sagaId} not found`);
+      }
+    }
+  }
+  async delete(sagaName, sagaId) {
+    await this.collection.deleteOne({
+      _id: this.makeId(sagaName, sagaId)
+    });
+  }
+  documentToState(doc) {
+    const state = doc.state;
+    return {
+      ...state,
+      metadata: {
+        ...state.metadata,
+        sagaId: doc.sagaId,
+        version: doc.version,
+        isCompleted: doc.isCompleted,
+        createdAt: doc.createdAt,
+        updatedAt: doc.updatedAt
+      }
+    };
+  }
+  // ============ Query Helpers ============
+  /**
+   * Find sagas by name with pagination.
+   */
+  async findByName(sagaName, options) {
+    const filter = { sagaName };
+    if (options?.completed !== void 0) {
+      filter.isCompleted = options.completed;
+    }
+    const cursor = this.collection.find(filter).sort({ createdAt: -1 }).skip(options?.offset ?? 0).limit(options?.limit ?? 100);
+    const docs = await cursor.toArray();
+    return docs.map((doc) => this.documentToState(doc));
+  }
+  /**
+   * Count sagas by name.
+   */
+  async countByName(sagaName, options) {
+    const filter = { sagaName };
+    if (options?.completed !== void 0) {
+      filter.isCompleted = options.completed;
+    }
+    return this.collection.countDocuments(filter);
+  }
+  /**
+   * Delete completed sagas older than a given date.
+   */
+  async deleteCompletedBefore(sagaName, before) {
+    const result = await this.collection.deleteMany({
+      sagaName,
+      isCompleted: true,
+      updatedAt: { $lt: before }
+    });
+    return result.deletedCount;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MongoSagaStore
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/MongoSagaStore.ts"],"sourcesContent":["export { MongoSagaStore } from \"./MongoSagaStore.js\";\nexport type { MongoSagaStoreOptions, SagaInstanceDocument } from \"./types.js\";\n","import type { Collection } from \"mongodb\";\nimport type { SagaStore, SagaState } from \"@saga-bus/core\";\nimport { ConcurrencyError } from \"@saga-bus/core\";\nimport type { MongoSagaStoreOptions, SagaInstanceDocument } from \"./types.js\";\n\n/**\n * MongoDB-backed saga store.\n *\n * @example\n * ```typescript\n * import { MongoClient } from \"mongodb\";\n *\n * const client = new MongoClient(\"mongodb://localhost:27017\");\n * await client.connect();\n * const db = client.db(\"saga_bus\");\n *\n * const store = new MongoSagaStore<OrderState>({ db });\n * await store.ensureIndexes();\n * ```\n */\nexport class MongoSagaStore<TState extends SagaState>\n  implements SagaStore<TState>\n{\n  private readonly collection: Collection<SagaInstanceDocument>;\n\n  constructor(options: MongoSagaStoreOptions) {\n    const collectionName = options.collectionName ?? \"saga_instances\";\n    this.collection =\n      options.db.collection<SagaInstanceDocument>(collectionName);\n  }\n\n  /**\n   * Create indexes for optimal query performance.\n   * Call once during application startup.\n   */\n  async ensureIndexes(): Promise<void> {\n    await this.collection.createIndex(\n      { sagaName: 1, correlationId: 1 },\n      { unique: true }\n    );\n    await this.collection.createIndex({\n      sagaName: 1,\n      isCompleted: 1,\n      updatedAt: 1,\n    });\n    await this.collection.createIndex({ sagaName: 1, sagaId: 1 });\n  }\n\n  private makeId(sagaName: string, sagaId: string): string {\n    return `${sagaName}:${sagaId}`;\n  }\n\n  async getById(sagaName: string, sagaId: string): Promise<TState | null> {\n    const doc = await this.collection.findOne({\n      _id: this.makeId(sagaName, sagaId),\n    });\n\n    if (!doc) {\n      return null;\n    }\n\n    return this.documentToState(doc);\n  }\n\n  async getByCorrelationId(\n    sagaName: string,\n    correlationId: string\n  ): Promise<TState | null> {\n    const doc = await this.collection.findOne({\n      sagaName,\n      correlationId,\n    });\n\n    if (!doc) {\n      return null;\n    }\n\n    return this.documentToState(doc);\n  }\n\n  async insert(sagaName: string, correlationId: string, state: TState): Promise<void> {\n    const { sagaId, version, isCompleted, createdAt, updatedAt } =\n      state.metadata;\n\n    const doc: SagaInstanceDocument = {\n      _id: this.makeId(sagaName, sagaId),\n      sagaName,\n      sagaId,\n      correlationId,\n      version,\n      isCompleted,\n      state: state as unknown,\n      createdAt,\n      updatedAt,\n    };\n\n    await this.collection.insertOne(doc);\n  }\n\n  async update(\n    sagaName: string,\n    state: TState,\n    expectedVersion: number\n  ): Promise<void> {\n    const { sagaId, version, isCompleted, updatedAt } = state.metadata;\n\n    const result = await this.collection.updateOne(\n      {\n        _id: this.makeId(sagaName, sagaId),\n        version: expectedVersion,\n      },\n      {\n        $set: {\n          version,\n          isCompleted,\n          state: state as unknown,\n          updatedAt,\n        },\n      }\n    );\n\n    if (result.matchedCount === 0) {\n      const existing = await this.getById(sagaName, sagaId);\n      if (existing) {\n        throw new ConcurrencyError(\n          sagaId,\n          expectedVersion,\n          existing.metadata.version\n        );\n      } else {\n        throw new Error(`Saga ${sagaId} not found`);\n      }\n    }\n  }\n\n  async delete(sagaName: string, sagaId: string): Promise<void> {\n    await this.collection.deleteOne({\n      _id: this.makeId(sagaName, sagaId),\n    });\n  }\n\n  private documentToState(doc: SagaInstanceDocument): TState {\n    const state = doc.state as TState;\n\n    return {\n      ...state,\n      metadata: {\n        ...state.metadata,\n        sagaId: doc.sagaId,\n        version: doc.version,\n        isCompleted: doc.isCompleted,\n        createdAt: doc.createdAt,\n        updatedAt: doc.updatedAt,\n      },\n    };\n  }\n\n  // ============ Query Helpers ============\n\n  /**\n   * Find sagas by name with pagination.\n   */\n  async findByName(\n    sagaName: string,\n    options?: {\n      limit?: number;\n      offset?: number;\n      completed?: boolean;\n    }\n  ): Promise<TState[]> {\n    const filter: Record<string, unknown> = { sagaName };\n\n    if (options?.completed !== undefined) {\n      filter.isCompleted = options.completed;\n    }\n\n    const cursor = this.collection\n      .find(filter)\n      .sort({ createdAt: -1 })\n      .skip(options?.offset ?? 0)\n      .limit(options?.limit ?? 100);\n\n    const docs = await cursor.toArray();\n    return docs.map((doc) => this.documentToState(doc));\n  }\n\n  /**\n   * Count sagas by name.\n   */\n  async countByName(\n    sagaName: string,\n    options?: { completed?: boolean }\n  ): Promise<number> {\n    const filter: Record<string, unknown> = { sagaName };\n\n    if (options?.completed !== undefined) {\n      filter.isCompleted = options.completed;\n    }\n\n    return this.collection.countDocuments(filter);\n  }\n\n  /**\n   * Delete completed sagas older than a given date.\n   */\n  async deleteCompletedBefore(sagaName: string, before: Date): Promise<number> {\n    const result = await this.collection.deleteMany({\n      sagaName,\n      isCompleted: true,\n      updatedAt: { $lt: before },\n    });\n\n    return result.deletedCount;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,83 @@
+import { SagaState, SagaStore } from '@saga-bus/core';
+import { Db } from 'mongodb';
+
+/**
+ * MongoDB saga store configuration options.
+ */
+interface MongoSagaStoreOptions {
+    /**
+     * MongoDB database instance.
+     */
+    db: Db;
+    /**
+     * Collection name for saga instances.
+     * @default "saga_instances"
+     */
+    collectionName?: string;
+}
+/**
+ * Shape of a saga instance document in MongoDB.
+ */
+interface SagaInstanceDocument {
+    _id: string;
+    sagaName: string;
+    sagaId: string;
+    correlationId: string;
+    version: number;
+    isCompleted: boolean;
+    state: unknown;
+    createdAt: Date;
+    updatedAt: Date;
+}
+
+/**
+ * MongoDB-backed saga store.
+ *
+ * @example
+ * ```typescript
+ * import { MongoClient } from "mongodb";
+ *
+ * const client = new MongoClient("mongodb://localhost:27017");
+ * await client.connect();
+ * const db = client.db("saga_bus");
+ *
+ * const store = new MongoSagaStore<OrderState>({ db });
+ * await store.ensureIndexes();
+ * ```
+ */
+declare class MongoSagaStore<TState extends SagaState> implements SagaStore<TState> {
+    private readonly collection;
+    constructor(options: MongoSagaStoreOptions);
+    /**
+     * Create indexes for optimal query performance.
+     * Call once during application startup.
+     */
+    ensureIndexes(): Promise<void>;
+    private makeId;
+    getById(sagaName: string, sagaId: string): Promise<TState | null>;
+    getByCorrelationId(sagaName: string, correlationId: string): Promise<TState | null>;
+    insert(sagaName: string, correlationId: string, state: TState): Promise<void>;
+    update(sagaName: string, state: TState, expectedVersion: number): Promise<void>;
+    delete(sagaName: string, sagaId: string): Promise<void>;
+    private documentToState;
+    /**
+     * Find sagas by name with pagination.
+     */
+    findByName(sagaName: string, options?: {
+        limit?: number;
+        offset?: number;
+        completed?: boolean;
+    }): Promise<TState[]>;
+    /**
+     * Count sagas by name.
+     */
+    countByName(sagaName: string, options?: {
+        completed?: boolean;
+    }): Promise<number>;
+    /**
+     * Delete completed sagas older than a given date.
+     */
+    deleteCompletedBefore(sagaName: string, before: Date): Promise<number>;
+}
+
+export { MongoSagaStore, type MongoSagaStoreOptions, type SagaInstanceDocument };

package/dist/index.d.ts

@@ -0,0 +1,83 @@
+import { SagaState, SagaStore } from '@saga-bus/core';
+import { Db } from 'mongodb';
+
+/**
+ * MongoDB saga store configuration options.
+ */
+interface MongoSagaStoreOptions {
+    /**
+     * MongoDB database instance.
+     */
+    db: Db;
+    /**
+     * Collection name for saga instances.
+     * @default "saga_instances"
+     */
+    collectionName?: string;
+}
+/**
+ * Shape of a saga instance document in MongoDB.
+ */
+interface SagaInstanceDocument {
+    _id: string;
+    sagaName: string;
+    sagaId: string;
+    correlationId: string;
+    version: number;
+    isCompleted: boolean;
+    state: unknown;
+    createdAt: Date;
+    updatedAt: Date;
+}
+
+/**
+ * MongoDB-backed saga store.
+ *
+ * @example
+ * ```typescript
+ * import { MongoClient } from "mongodb";
+ *
+ * const client = new MongoClient("mongodb://localhost:27017");
+ * await client.connect();
+ * const db = client.db("saga_bus");
+ *
+ * const store = new MongoSagaStore<OrderState>({ db });
+ * await store.ensureIndexes();
+ * ```
+ */
+declare class MongoSagaStore<TState extends SagaState> implements SagaStore<TState> {
+    private readonly collection;
+    constructor(options: MongoSagaStoreOptions);
+    /**
+     * Create indexes for optimal query performance.
+     * Call once during application startup.
+     */
+    ensureIndexes(): Promise<void>;
+    private makeId;
+    getById(sagaName: string, sagaId: string): Promise<TState | null>;
+    getByCorrelationId(sagaName: string, correlationId: string): Promise<TState | null>;
+    insert(sagaName: string, correlationId: string, state: TState): Promise<void>;
+    update(sagaName: string, state: TState, expectedVersion: number): Promise<void>;
+    delete(sagaName: string, sagaId: string): Promise<void>;
+    private documentToState;
+    /**
+     * Find sagas by name with pagination.
+     */
+    findByName(sagaName: string, options?: {
+        limit?: number;
+        offset?: number;
+        completed?: boolean;
+    }): Promise<TState[]>;
+    /**
+     * Count sagas by name.
+     */
+    countByName(sagaName: string, options?: {
+        completed?: boolean;
+    }): Promise<number>;
+    /**
+     * Delete completed sagas older than a given date.
+     */
+    deleteCompletedBefore(sagaName: string, before: Date): Promise<number>;
+}
+
+export { MongoSagaStore, type MongoSagaStoreOptions, type SagaInstanceDocument };

package/dist/index.js

@@ -0,0 +1,148 @@
+// src/MongoSagaStore.ts
+import { ConcurrencyError } from "@saga-bus/core";
+var MongoSagaStore = class {
+  collection;
+  constructor(options) {
+    const collectionName = options.collectionName ?? "saga_instances";
+    this.collection = options.db.collection(collectionName);
+  }
+  /**
+   * Create indexes for optimal query performance.
+   * Call once during application startup.
+   */
+  async ensureIndexes() {
+    await this.collection.createIndex(
+      { sagaName: 1, correlationId: 1 },
+      { unique: true }
+    );
+    await this.collection.createIndex({
+      sagaName: 1,
+      isCompleted: 1,
+      updatedAt: 1
+    });
+    await this.collection.createIndex({ sagaName: 1, sagaId: 1 });
+  }
+  makeId(sagaName, sagaId) {
+    return `${sagaName}:${sagaId}`;
+  }
+  async getById(sagaName, sagaId) {
+    const doc = await this.collection.findOne({
+      _id: this.makeId(sagaName, sagaId)
+    });
+    if (!doc) {
+      return null;
+    }
+    return this.documentToState(doc);
+  }
+  async getByCorrelationId(sagaName, correlationId) {
+    const doc = await this.collection.findOne({
+      sagaName,
+      correlationId
+    });
+    if (!doc) {
+      return null;
+    }
+    return this.documentToState(doc);
+  }
+  async insert(sagaName, correlationId, state) {
+    const { sagaId, version, isCompleted, createdAt, updatedAt } = state.metadata;
+    const doc = {
+      _id: this.makeId(sagaName, sagaId),
+      sagaName,
+      sagaId,
+      correlationId,
+      version,
+      isCompleted,
+      state,
+      createdAt,
+      updatedAt
+    };
+    await this.collection.insertOne(doc);
+  }
+  async update(sagaName, state, expectedVersion) {
+    const { sagaId, version, isCompleted, updatedAt } = state.metadata;
+    const result = await this.collection.updateOne(
+      {
+        _id: this.makeId(sagaName, sagaId),
+        version: expectedVersion
+      },
+      {
+        $set: {
+          version,
+          isCompleted,
+          state,
+          updatedAt
+        }
+      }
+    );
+    if (result.matchedCount === 0) {
+      const existing = await this.getById(sagaName, sagaId);
+      if (existing) {
+        throw new ConcurrencyError(
+          sagaId,
+          expectedVersion,
+          existing.metadata.version
+        );
+      } else {
+        throw new Error(`Saga ${sagaId} not found`);
+      }
+    }
+  }
+  async delete(sagaName, sagaId) {
+    await this.collection.deleteOne({
+      _id: this.makeId(sagaName, sagaId)
+    });
+  }
+  documentToState(doc) {
+    const state = doc.state;
+    return {
+      ...state,
+      metadata: {
+        ...state.metadata,
+        sagaId: doc.sagaId,
+        version: doc.version,
+        isCompleted: doc.isCompleted,
+        createdAt: doc.createdAt,
+        updatedAt: doc.updatedAt
+      }
+    };
+  }
+  // ============ Query Helpers ============
+  /**
+   * Find sagas by name with pagination.
+   */
+  async findByName(sagaName, options) {
+    const filter = { sagaName };
+    if (options?.completed !== void 0) {
+      filter.isCompleted = options.completed;
+    }
+    const cursor = this.collection.find(filter).sort({ createdAt: -1 }).skip(options?.offset ?? 0).limit(options?.limit ?? 100);
+    const docs = await cursor.toArray();
+    return docs.map((doc) => this.documentToState(doc));
+  }
+  /**
+   * Count sagas by name.
+   */
+  async countByName(sagaName, options) {
+    const filter = { sagaName };
+    if (options?.completed !== void 0) {
+      filter.isCompleted = options.completed;
+    }
+    return this.collection.countDocuments(filter);
+  }
+  /**
+   * Delete completed sagas older than a given date.
+   */
+  async deleteCompletedBefore(sagaName, before) {
+    const result = await this.collection.deleteMany({
+      sagaName,
+      isCompleted: true,
+      updatedAt: { $lt: before }
+    });
+    return result.deletedCount;
+  }
+};
+export {
+  MongoSagaStore
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/MongoSagaStore.ts"],"sourcesContent":["import type { Collection } from \"mongodb\";\nimport type { SagaStore, SagaState } from \"@saga-bus/core\";\nimport { ConcurrencyError } from \"@saga-bus/core\";\nimport type { MongoSagaStoreOptions, SagaInstanceDocument } from \"./types.js\";\n\n/**\n * MongoDB-backed saga store.\n *\n * @example\n * ```typescript\n * import { MongoClient } from \"mongodb\";\n *\n * const client = new MongoClient(\"mongodb://localhost:27017\");\n * await client.connect();\n * const db = client.db(\"saga_bus\");\n *\n * const store = new MongoSagaStore<OrderState>({ db });\n * await store.ensureIndexes();\n * ```\n */\nexport class MongoSagaStore<TState extends SagaState>\n  implements SagaStore<TState>\n{\n  private readonly collection: Collection<SagaInstanceDocument>;\n\n  constructor(options: MongoSagaStoreOptions) {\n    const collectionName = options.collectionName ?? \"saga_instances\";\n    this.collection =\n      options.db.collection<SagaInstanceDocument>(collectionName);\n  }\n\n  /**\n   * Create indexes for optimal query performance.\n   * Call once during application startup.\n   */\n  async ensureIndexes(): Promise<void> {\n    await this.collection.createIndex(\n      { sagaName: 1, correlationId: 1 },\n      { unique: true }\n    );\n    await this.collection.createIndex({\n      sagaName: 1,\n      isCompleted: 1,\n      updatedAt: 1,\n    });\n    await this.collection.createIndex({ sagaName: 1, sagaId: 1 });\n  }\n\n  private makeId(sagaName: string, sagaId: string): string {\n    return `${sagaName}:${sagaId}`;\n  }\n\n  async getById(sagaName: string, sagaId: string): Promise<TState | null> {\n    const doc = await this.collection.findOne({\n      _id: this.makeId(sagaName, sagaId),\n    });\n\n    if (!doc) {\n      return null;\n    }\n\n    return this.documentToState(doc);\n  }\n\n  async getByCorrelationId(\n    sagaName: string,\n    correlationId: string\n  ): Promise<TState | null> {\n    const doc = await this.collection.findOne({\n      sagaName,\n      correlationId,\n    });\n\n    if (!doc) {\n      return null;\n    }\n\n    return this.documentToState(doc);\n  }\n\n  async insert(sagaName: string, correlationId: string, state: TState): Promise<void> {\n    const { sagaId, version, isCompleted, createdAt, updatedAt } =\n      state.metadata;\n\n    const doc: SagaInstanceDocument = {\n      _id: this.makeId(sagaName, sagaId),\n      sagaName,\n      sagaId,\n      correlationId,\n      version,\n      isCompleted,\n      state: state as unknown,\n      createdAt,\n      updatedAt,\n    };\n\n    await this.collection.insertOne(doc);\n  }\n\n  async update(\n    sagaName: string,\n    state: TState,\n    expectedVersion: number\n  ): Promise<void> {\n    const { sagaId, version, isCompleted, updatedAt } = state.metadata;\n\n    const result = await this.collection.updateOne(\n      {\n        _id: this.makeId(sagaName, sagaId),\n        version: expectedVersion,\n      },\n      {\n        $set: {\n          version,\n          isCompleted,\n          state: state as unknown,\n          updatedAt,\n        },\n      }\n    );\n\n    if (result.matchedCount === 0) {\n      const existing = await this.getById(sagaName, sagaId);\n      if (existing) {\n        throw new ConcurrencyError(\n          sagaId,\n          expectedVersion,\n          existing.metadata.version\n        );\n      } else {\n        throw new Error(`Saga ${sagaId} not found`);\n      }\n    }\n  }\n\n  async delete(sagaName: string, sagaId: string): Promise<void> {\n    await this.collection.deleteOne({\n      _id: this.makeId(sagaName, sagaId),\n    });\n  }\n\n  private documentToState(doc: SagaInstanceDocument): TState {\n    const state = doc.state as TState;\n\n    return {\n      ...state,\n      metadata: {\n        ...state.metadata,\n        sagaId: doc.sagaId,\n        version: doc.version,\n        isCompleted: doc.isCompleted,\n        createdAt: doc.createdAt,\n        updatedAt: doc.updatedAt,\n      },\n    };\n  }\n\n  // ============ Query Helpers ============\n\n  /**\n   * Find sagas by name with pagination.\n   */\n  async findByName(\n    sagaName: string,\n    options?: {\n      limit?: number;\n      offset?: number;\n      completed?: boolean;\n    }\n  ): Promise<TState[]> {\n    const filter: Record<string, unknown> = { sagaName };\n\n    if (options?.completed !== undefined) {\n      filter.isCompleted = options.completed;\n    }\n\n    const cursor = this.collection\n      .find(filter)\n      .sort({ createdAt: -1 })\n      .skip(options?.offset ?? 0)\n      .limit(options?.limit ?? 100);\n\n    const docs = await cursor.toArray();\n    return docs.map((doc) => this.documentToState(doc));\n  }\n\n  /**\n   * Count sagas by name.\n   */\n  async countByName(\n    sagaName: string,\n    options?: { completed?: boolean }\n  ): Promise<number> {\n    const filter: Record<string, unknown> = { sagaName };\n\n    if (options?.completed !== undefined) {\n      filter.isCompleted = options.completed;\n    }\n\n    return this.collection.countDocuments(filter);\n  }\n\n  /**\n   * Delete completed sagas older than a given date.\n   */\n  async deleteCompletedBefore(sagaName: string, before: Date): Promise<number> {\n    const result = await this.collection.deleteMany({\n      sagaName,\n      isCompleted: true,\n      updatedAt: { $lt: before },\n    });\n\n    return result.deletedCount;\n  }\n}\n"],"mappings":";AAEA,SAAS,wBAAwB;AAkB1B,IAAM,iBAAN,MAEP;AAAA,EACmB;AAAA,EAEjB,YAAY,SAAgC;AAC1C,UAAM,iBAAiB,QAAQ,kBAAkB;AACjD,SAAK,aACH,QAAQ,GAAG,WAAiC,cAAc;AAAA,EAC9D;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,gBAA+B;AACnC,UAAM,KAAK,WAAW;AAAA,MACpB,EAAE,UAAU,GAAG,eAAe,EAAE;AAAA,MAChC,EAAE,QAAQ,KAAK;AAAA,IACjB;AACA,UAAM,KAAK,WAAW,YAAY;AAAA,MAChC,UAAU;AAAA,MACV,aAAa;AAAA,MACb,WAAW;AAAA,IACb,CAAC;AACD,UAAM,KAAK,WAAW,YAAY,EAAE,UAAU,GAAG,QAAQ,EAAE,CAAC;AAAA,EAC9D;AAAA,EAEQ,OAAO,UAAkB,QAAwB;AACvD,WAAO,GAAG,QAAQ,IAAI,MAAM;AAAA,EAC9B;AAAA,EAEA,MAAM,QAAQ,UAAkB,QAAwC;AACtE,UAAM,MAAM,MAAM,KAAK,WAAW,QAAQ;AAAA,MACxC,KAAK,KAAK,OAAO,UAAU,MAAM;AAAA,IACnC,CAAC;AAED,QAAI,CAAC,KAAK;AACR,aAAO;AAAA,IACT;AAEA,WAAO,KAAK,gBAAgB,GAAG;AAAA,EACjC;AAAA,EAEA,MAAM,mBACJ,UACA,eACwB;AACxB,UAAM,MAAM,MAAM,KAAK,WAAW,QAAQ;AAAA,MACxC;AAAA,MACA;AAAA,IACF,CAAC;AAED,QAAI,CAAC,KAAK;AACR,aAAO;AAAA,IACT;AAEA,WAAO,KAAK,gBAAgB,GAAG;AAAA,EACjC;AAAA,EAEA,MAAM,OAAO,UAAkB,eAAuB,OAA8B;AAClF,UAAM,EAAE,QAAQ,SAAS,aAAa,WAAW,UAAU,IACzD,MAAM;AAER,UAAM,MAA4B;AAAA,MAChC,KAAK,KAAK,OAAO,UAAU,MAAM;AAAA,MACjC;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAEA,UAAM,KAAK,WAAW,UAAU,GAAG;AAAA,EACrC;AAAA,EAEA,MAAM,OACJ,UACA,OACA,iBACe;AACf,UAAM,EAAE,QAAQ,SAAS,aAAa,UAAU,IAAI,MAAM;AAE1D,UAAM,SAAS,MAAM,KAAK,WAAW;AAAA,MACnC;AAAA,QACE,KAAK,KAAK,OAAO,UAAU,MAAM;AAAA,QACjC,SAAS;AAAA,MACX;AAAA,MACA;AAAA,QACE,MAAM;AAAA,UACJ;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAEA,QAAI,OAAO,iBAAiB,GAAG;AAC7B,YAAM,WAAW,MAAM,KAAK,QAAQ,UAAU,MAAM;AACpD,UAAI,UAAU;AACZ,cAAM,IAAI;AAAA,UACR;AAAA,UACA;AAAA,UACA,SAAS,SAAS;AAAA,QACpB;AAAA,MACF,OAAO;AACL,cAAM,IAAI,MAAM,QAAQ,MAAM,YAAY;AAAA,MAC5C;AAAA,IACF;AAAA,EACF;AAAA,EAEA,MAAM,OAAO,UAAkB,QAA+B;AAC5D,UAAM,KAAK,WAAW,UAAU;AAAA,MAC9B,KAAK,KAAK,OAAO,UAAU,MAAM;AAAA,IACnC,CAAC;AAAA,EACH;AAAA,EAEQ,gBAAgB,KAAmC;AACzD,UAAM,QAAQ,IAAI;AAElB,WAAO;AAAA,MACL,GAAG;AAAA,MACH,UAAU;AAAA,QACR,GAAG,MAAM;AAAA,QACT,QAAQ,IAAI;AAAA,QACZ,SAAS,IAAI;AAAA,QACb,aAAa,IAAI;AAAA,QACjB,WAAW,IAAI;AAAA,QACf,WAAW,IAAI;AAAA,MACjB;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,WACJ,UACA,SAKmB;AACnB,UAAM,SAAkC,EAAE,SAAS;AAEnD,QAAI,SAAS,cAAc,QAAW;AACpC,aAAO,cAAc,QAAQ;AAAA,IAC/B;AAEA,UAAM,SAAS,KAAK,WACjB,KAAK,MAAM,EACX,KAAK,EAAE,WAAW,GAAG,CAAC,EACtB,KAAK,SAAS,UAAU,CAAC,EACzB,MAAM,SAAS,SAAS,GAAG;AAE9B,UAAM,OAAO,MAAM,OAAO,QAAQ;AAClC,WAAO,KAAK,IAAI,CAAC,QAAQ,KAAK,gBAAgB,GAAG,CAAC;AAAA,EACpD;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,YACJ,UACA,SACiB;AACjB,UAAM,SAAkC,EAAE,SAAS;AAEnD,QAAI,SAAS,cAAc,QAAW;AACpC,aAAO,cAAc,QAAQ;AAAA,IAC/B;AAEA,WAAO,KAAK,WAAW,eAAe,MAAM;AAAA,EAC9C;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,sBAAsB,UAAkB,QAA+B;AAC3E,UAAM,SAAS,MAAM,KAAK,WAAW,WAAW;AAAA,MAC9C;AAAA,MACA,aAAa;AAAA,MACb,WAAW,EAAE,KAAK,OAAO;AAAA,IAC3B,CAAC;AAED,WAAO,OAAO;AAAA,EAChB;AACF;","names":[]}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@saga-bus/store-mongo",
+  "version": "0.1.0",
+  "description": "MongoDB saga store for saga-bus",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deanforan/saga-bus.git",
+    "directory": "packages/store-mongo"
+  },
+  "keywords": [
+    "saga",
+    "message-bus",
+    "store",
+    "mongodb",
+    "mongo"
+  ],
+  "dependencies": {
+    "mongodb": "^6.8.0",
+    "@saga-bus/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@testcontainers/mongodb": "^10.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.0.0",
+    "@repo/eslint-config": "0.0.0",
+    "@repo/typescript-config": "0.0.0"
+  },
+  "peerDependencies": {
+    "mongodb": ">=6.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}