@abejarano/ts-mongodb-criteria 1.8.6 → 1.10.0

package/README.md

@@ -201,6 +201,43 @@ export interface IUserRepository extends IRepository<User> {
 The goal of `IRepository` is to prevent signature drift (e.g. `upsert` returning
 `void` in your app while the base repository returns `ObjectId | null`).
 
+## Atomic Transactions
+
+`MongoTransaction.run` groups writes from one or more repositories into a
+single MongoDB transaction. Pass the `tx` context to every write that must be
+committed or rolled back together:
+
+```typescript
+import { MongoTransaction } from "@abejarano/ts-mongodb-criteria"
+
+await MongoTransaction.run(async (tx) => {
+  await userRepository.upsert(user, tx)
+  await auditRepository.upsert(auditEntry, tx)
+  await sessionRepository.delete({ userId: user.getId() }, undefined, tx)
+
+  // Reads can observe writes made earlier in this transaction.
+  const persistedUser = await userRepository.one({ id: user.getId() }, tx)
+})
+```
+
+If any operation in the callback fails, MongoDB rolls back all the writes and
+the error is propagated to the caller. The MongoDB driver handles retryable
+transaction errors through `withTransaction`.
+
+Custom repositories can include their protected atomic updates in the same
+transaction by accepting and forwarding `MongoTransaction`:
+
+```typescript
+async deactivateUser(id: string, tx: MongoTransaction): Promise<void> {
+  await this.updateOne({ id }, { $set: { active: false } }, tx)
+}
+```
+
+MongoDB transactions require a replica set or a sharded cluster; standalone
+MongoDB instances do not support them. This initial API applies the transaction
+context to `upsert`, `delete`, protected `updateOne`, `one`, and `list`.
+Pass `tx` as the third argument to `list` after `fieldsToExclude`.
+
 **Your First Query in 30 Seconds:**
 
 ```typescript

package/dist/cjs/mongo/MongoRepository.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MongoRepository = void 0;
 const MongoCriteriaConverter_1 = require("./MongoCriteriaConverter");
 const MongoClientFactory_1 = require("./MongoClientFactory");
+const MongoTransaction_1 = require("./MongoTransaction");
 const mongodb_1 = require("mongodb");
 class MongoRepository {
     constructor(aggregateRootClass) {
@@ -10,9 +11,12 @@ class MongoRepository {
         this.criteriaConverter = new MongoCriteriaConverter_1.MongoCriteriaConverter();
     }
     /** Finds a single entity and hydrates it via the aggregate's fromPrimitives. */
-    async one(filter) {
+    async one(filter, transaction) {
         const collection = await this.collection();
-        const result = await collection.findOne(filter);
+        const session = MongoTransaction_1.MongoTransaction.sessionFor(transaction);
+        const result = session
+            ? await collection.findOne(filter, { session })
+            : await collection.findOne(filter);
         if (!result) {
             return null;
         }
@@ -22,13 +26,13 @@ class MongoRepository {
         });
     }
     /** Upserts an aggregate by delegating to persist with its id. */
-    async upsert(entity) {
-        await this.persist(entity.getId(), entity);
+    async upsert(entity, transaction) {
+        await this.persist(entity.getId(), entity, transaction);
     }
     /** Lists entities by criteria and returns a paginated response. */
-    async list(criteria, fieldsToExclude = []) {
-        const documents = await this.searchByCriteria(criteria, fieldsToExclude);
-        return this.paginate(documents);
+    async list(criteria, fieldsToExclude = [], transaction) {
+        const documents = await this.searchByCriteria(criteria, fieldsToExclude, transaction);
+        return this.paginate(documents, transaction);
     }
     /**
      * Deletes documents from the database based on a filter and optional options.
@@ -37,9 +41,10 @@ class MongoRepository {
      * @param {DeleteOptions} [options] - Optional parameters that modify the behavior of the delete operation.
      * @return {Promise<void>} A promise that resolves when the deletion is complete, or rejects if an error occurs.
      */
-    async delete(filter, options) {
+    async delete(filter, options, transaction) {
         const collection = await this.collection();
-        await collection.deleteMany(filter, options);
+        const session = MongoTransaction_1.MongoTransaction.sessionFor(transaction);
+        await collection.deleteMany(filter, session ? { ...options, session } : options);
     }
     async ensureIndexesOnce() {
         const key = this.collectionName();
@@ -53,18 +58,17 @@ class MongoRepository {
         await this.ensureIndexesOnce();
         return this.collectionRaw();
     }
-    async updateOne(filter, update) {
+    async updateOne(filter, update, transaction) {
         const collection = await this.collection();
-        await collection.updateOne(filter, update, {
-            upsert: true,
-        });
+        const session = MongoTransaction_1.MongoTransaction.sessionFor(transaction);
+        await collection.updateOne(filter, update, session ? { upsert: true, session } : { upsert: true });
     }
     async collectionRaw() {
         return (await MongoClientFactory_1.MongoClientFactory.createClient())
             .db()
             .collection(this.collectionName());
     }
-    async persist(id, aggregateRoot) {
+    async persist(id, aggregateRoot, transaction) {
         let primitives;
         if (aggregateRoot.toPrimitives() instanceof Promise) {
             primitives = await aggregateRoot.toPrimitives();
@@ -77,15 +81,16 @@ class MongoRepository {
                 ...primitives,
                 id: id,
             },
-        });
+        }, transaction);
     }
-    async searchByCriteria(criteria, fieldsToExclude = []) {
+    async searchByCriteria(criteria, fieldsToExclude = [], transaction) {
         this.criteria = criteria;
         this.query = this.criteriaConverter.convert(criteria);
         const collection = await this.collection();
+        const session = MongoTransaction_1.MongoTransaction.sessionFor(transaction);
         if (fieldsToExclude.length === 0) {
             const results = await collection
-                .find(this.query.filter, {})
+                .find(this.query.filter, session ? { session } : {})
                 .sort(this.query.sort)
                 .skip(this.query.skip)
                 .limit(this.query.limit)
@@ -97,16 +102,19 @@ class MongoRepository {
             projection[field] = 0;
         });
         const results = await collection
-            .find(this.query.filter, { projection })
+            .find(this.query.filter, session ? { projection, session } : { projection })
             .sort(this.query.sort)
             .skip(this.query.skip)
             .limit(this.query.limit)
             .toArray();
         return results.map(({ _id, ...rest }) => rest);
     }
-    async paginate(documents) {
+    async paginate(documents, transaction) {
         const collection = await this.collection();
-        const count = await collection.countDocuments(this.query.filter);
+        const session = MongoTransaction_1.MongoTransaction.sessionFor(transaction);
+        const count = session
+            ? await collection.countDocuments(this.query.filter, { session })
+            : await collection.countDocuments(this.query.filter);
         const limit = this.criteria?.limit || 10;
         const currentPage = this.criteria?.currentPage || 1;
         const hasNextPage = currentPage * limit < count;

package/dist/cjs/mongo/MongoTransaction.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MongoTransaction = void 0;
+const MongoClientFactory_1 = require("./MongoClientFactory");
+const sessions = new WeakMap();
+/**
+ * Context passed to repository writes that belong to the same MongoDB transaction.
+ */
+class MongoTransaction {
+    constructor(session) {
+        sessions.set(this, session);
+    }
+    /**
+     * Runs the callback in a MongoDB transaction and releases its session afterwards.
+     */
+    static async run(callback) {
+        const client = await MongoClientFactory_1.MongoClientFactory.createClient();
+        const session = client.startSession();
+        const transaction = new MongoTransaction(session);
+        try {
+            return await session.withTransaction(() => callback(transaction));
+        }
+        finally {
+            await session.endSession();
+        }
+    }
+    /** @internal Retrieves the driver session used by repository implementations. */
+    static sessionFor(transaction) {
+        return transaction ? sessions.get(transaction) : undefined;
+    }
+}
+exports.MongoTransaction = MongoTransaction;

package/dist/cjs/mongo/index.js

@@ -18,3 +18,4 @@ __exportStar(require("./MongoCriteriaConverter"), exports);
 __exportStar(require("./MongoRepository"), exports);
 __exportStar(require("./IRepository"), exports);
 __exportStar(require("./MongoClientFactory"), exports);
+__exportStar(require("./MongoTransaction"), exports);

package/dist/esm/mongo/MongoRepository.js

@@ -1,5 +1,6 @@
 import { MongoCriteriaConverter } from "./MongoCriteriaConverter";
 import { MongoClientFactory } from "./MongoClientFactory";
+import { MongoTransaction } from "./MongoTransaction";
 import { ObjectId, } from "mongodb";
 export class MongoRepository {
     constructor(aggregateRootClass) {
@@ -7,9 +8,12 @@ export class MongoRepository {
         this.criteriaConverter = new MongoCriteriaConverter();
     }
     /** Finds a single entity and hydrates it via the aggregate's fromPrimitives. */
-    async one(filter) {
+    async one(filter, transaction) {
         const collection = await this.collection();
-        const result = await collection.findOne(filter);
+        const session = MongoTransaction.sessionFor(transaction);
+        const result = session
+            ? await collection.findOne(filter, { session })
+            : await collection.findOne(filter);
         if (!result) {
             return null;
         }
@@ -19,13 +23,13 @@ export class MongoRepository {
         });
     }
     /** Upserts an aggregate by delegating to persist with its id. */
-    async upsert(entity) {
-        await this.persist(entity.getId(), entity);
+    async upsert(entity, transaction) {
+        await this.persist(entity.getId(), entity, transaction);
     }
     /** Lists entities by criteria and returns a paginated response. */
-    async list(criteria, fieldsToExclude = []) {
-        const documents = await this.searchByCriteria(criteria, fieldsToExclude);
-        return this.paginate(documents);
+    async list(criteria, fieldsToExclude = [], transaction) {
+        const documents = await this.searchByCriteria(criteria, fieldsToExclude, transaction);
+        return this.paginate(documents, transaction);
     }
     /**
      * Deletes documents from the database based on a filter and optional options.
@@ -34,9 +38,10 @@ export class MongoRepository {
      * @param {DeleteOptions} [options] - Optional parameters that modify the behavior of the delete operation.
      * @return {Promise<void>} A promise that resolves when the deletion is complete, or rejects if an error occurs.
      */
-    async delete(filter, options) {
+    async delete(filter, options, transaction) {
         const collection = await this.collection();
-        await collection.deleteMany(filter, options);
+        const session = MongoTransaction.sessionFor(transaction);
+        await collection.deleteMany(filter, session ? { ...options, session } : options);
     }
     async ensureIndexesOnce() {
         const key = this.collectionName();
@@ -50,18 +55,17 @@ export class MongoRepository {
         await this.ensureIndexesOnce();
         return this.collectionRaw();
     }
-    async updateOne(filter, update) {
+    async updateOne(filter, update, transaction) {
         const collection = await this.collection();
-        await collection.updateOne(filter, update, {
-            upsert: true,
-        });
+        const session = MongoTransaction.sessionFor(transaction);
+        await collection.updateOne(filter, update, session ? { upsert: true, session } : { upsert: true });
     }
     async collectionRaw() {
         return (await MongoClientFactory.createClient())
             .db()
             .collection(this.collectionName());
     }
-    async persist(id, aggregateRoot) {
+    async persist(id, aggregateRoot, transaction) {
         let primitives;
         if (aggregateRoot.toPrimitives() instanceof Promise) {
             primitives = await aggregateRoot.toPrimitives();
@@ -74,15 +78,16 @@ export class MongoRepository {
                 ...primitives,
                 id: id,
             },
-        });
+        }, transaction);
     }
-    async searchByCriteria(criteria, fieldsToExclude = []) {
+    async searchByCriteria(criteria, fieldsToExclude = [], transaction) {
         this.criteria = criteria;
         this.query = this.criteriaConverter.convert(criteria);
         const collection = await this.collection();
+        const session = MongoTransaction.sessionFor(transaction);
         if (fieldsToExclude.length === 0) {
             const results = await collection
-                .find(this.query.filter, {})
+                .find(this.query.filter, session ? { session } : {})
                 .sort(this.query.sort)
                 .skip(this.query.skip)
                 .limit(this.query.limit)
@@ -94,16 +99,19 @@ export class MongoRepository {
             projection[field] = 0;
         });
         const results = await collection
-            .find(this.query.filter, { projection })
+            .find(this.query.filter, session ? { projection, session } : { projection })
             .sort(this.query.sort)
             .skip(this.query.skip)
             .limit(this.query.limit)
             .toArray();
         return results.map(({ _id, ...rest }) => rest);
     }
-    async paginate(documents) {
+    async paginate(documents, transaction) {
         const collection = await this.collection();
-        const count = await collection.countDocuments(this.query.filter);
+        const session = MongoTransaction.sessionFor(transaction);
+        const count = session
+            ? await collection.countDocuments(this.query.filter, { session })
+            : await collection.countDocuments(this.query.filter);
         const limit = this.criteria?.limit || 10;
         const currentPage = this.criteria?.currentPage || 1;
         const hasNextPage = currentPage * limit < count;

package/dist/esm/mongo/MongoTransaction.js

@@ -0,0 +1,28 @@
+import { MongoClientFactory } from "./MongoClientFactory";
+const sessions = new WeakMap();
+/**
+ * Context passed to repository writes that belong to the same MongoDB transaction.
+ */
+export class MongoTransaction {
+    constructor(session) {
+        sessions.set(this, session);
+    }
+    /**
+     * Runs the callback in a MongoDB transaction and releases its session afterwards.
+     */
+    static async run(callback) {
+        const client = await MongoClientFactory.createClient();
+        const session = client.startSession();
+        const transaction = new MongoTransaction(session);
+        try {
+            return await session.withTransaction(() => callback(transaction));
+        }
+        finally {
+            await session.endSession();
+        }
+    }
+    /** @internal Retrieves the driver session used by repository implementations. */
+    static sessionFor(transaction) {
+        return transaction ? sessions.get(transaction) : undefined;
+    }
+}

package/dist/esm/mongo/index.js

@@ -2,3 +2,4 @@ export * from "./MongoCriteriaConverter";
 export * from "./MongoRepository";
 export * from "./IRepository";
 export * from "./MongoClientFactory";
+export * from "./MongoTransaction";

package/dist/types/mongo/IRepository.d.ts

@@ -1,9 +1,10 @@
 import { Criteria, Paginate } from "../criteria";
 import { AggregateRoot } from "../AggregateRoot";
 import { DeleteOptions } from "mongodb";
+import { MongoTransaction } from "./MongoTransaction";
 export interface IRepository<T extends AggregateRoot> {
-    one(filter: object): Promise<T | null>;
-    list<D>(criteria: Criteria, fieldsToExclude?: string[]): Promise<Paginate<D>>;
-    upsert(entity: T): Promise<void>;
-    delete(filter: object, options?: DeleteOptions): Promise<void>;
+    one(filter: object, transaction?: MongoTransaction): Promise<T | null>;
+    list<D>(criteria: Criteria, fieldsToExclude?: string[], transaction?: MongoTransaction): Promise<Paginate<D>>;
+    upsert(entity: T, transaction?: MongoTransaction): Promise<void>;
+    delete(filter: object, options?: DeleteOptions, transaction?: MongoTransaction): Promise<void>;
 }

package/dist/types/mongo/MongoRepository.d.ts

@@ -1,3 +1,4 @@
+import { MongoTransaction } from "./MongoTransaction";
 import { Criteria, Paginate } from "../criteria";
 import { AggregateRoot, AggregateRootClass } from "../AggregateRoot";
 import { Collection, DeleteOptions, Document, UpdateFilter } from "mongodb";
@@ -10,11 +11,11 @@ export declare abstract class MongoRepository<T extends AggregateRoot> {
     protected constructor(aggregateRootClass: AggregateRootClass<T>);
     abstract collectionName(): string;
     /** Finds a single entity and hydrates it via the aggregate's fromPrimitives. */
-    one(filter: object): Promise<T | null>;
+    one(filter: object, transaction?: MongoTransaction): Promise<T | null>;
     /** Upserts an aggregate by delegating to persist with its id. */
-    upsert(entity: T): Promise<void>;
+    upsert(entity: T, transaction?: MongoTransaction): Promise<void>;
     /** Lists entities by criteria and returns a paginated response. */
-    list<D>(criteria: Criteria, fieldsToExclude?: string[]): Promise<Paginate<D>>;
+    list<D>(criteria: Criteria, fieldsToExclude?: string[], transaction?: MongoTransaction): Promise<Paginate<D>>;
     /**
      * Deletes documents from the database based on a filter and optional options.
      *
@@ -22,11 +23,11 @@ export declare abstract class MongoRepository<T extends AggregateRoot> {
      * @param {DeleteOptions} [options] - Optional parameters that modify the behavior of the delete operation.
      * @return {Promise<void>} A promise that resolves when the deletion is complete, or rejects if an error occurs.
      */
-    delete(filter: object, options?: DeleteOptions): Promise<void>;
+    delete(filter: object, options?: DeleteOptions, transaction?: MongoTransaction): Promise<void>;
     protected abstract ensureIndexes(collection: Collection): Promise<void>;
     protected ensureIndexesOnce(): Promise<void>;
     protected collection<U extends Document>(): Promise<Collection<U>>;
-    protected updateOne(filter: object, update: Document[] | UpdateFilter<any>): Promise<void>;
+    protected updateOne(filter: object, update: Document[] | UpdateFilter<any>, transaction?: MongoTransaction): Promise<void>;
     private collectionRaw;
     private persist;
     private searchByCriteria;

package/dist/types/mongo/MongoTransaction.d.ts

@@ -0,0 +1,13 @@
+import { ClientSession } from "mongodb";
+/**
+ * Context passed to repository writes that belong to the same MongoDB transaction.
+ */
+export declare class MongoTransaction {
+    private constructor();
+    /**
+     * Runs the callback in a MongoDB transaction and releases its session afterwards.
+     */
+    static run<T>(callback: (transaction: MongoTransaction) => Promise<T>): Promise<T>;
+    /** @internal Retrieves the driver session used by repository implementations. */
+    static sessionFor(transaction?: MongoTransaction): ClientSession | undefined;
+}

package/dist/types/mongo/index.d.ts

@@ -2,3 +2,4 @@ export * from "./MongoCriteriaConverter";
 export * from "./MongoRepository";
 export * from "./IRepository";
 export * from "./MongoClientFactory";
+export * from "./MongoTransaction";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@abejarano/ts-mongodb-criteria",
   "author": "angel bejarano / angel.bejarano@jaspesoft.com",
-  "version": "1.8.6",
+  "version": "1.10.0",
   "description": "Patrón Criteria para consultas MongoDB en TypeScript",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -65,7 +65,7 @@
     "mongodb": "^7.0.0",
     "prettier": "^3.8.3",
     "rimraf": "^6.1.2",
-    "semantic-release": "^24.2.9",
+    "semantic-release": "^25.0.6",
     "ts-jest": "^29.1.2",
     "typescript": "^5.9.3"
   },
@@ -81,7 +81,7 @@
     "url": "git+https://github.com/abejarano/ts-mongo-criteria.git"
   },
   "publishConfig": {
-    "registry": "https://registry.npmjs.org",
+    "registry": "https://registry.npmjs.org/",
     "access": "public"
   }
 }