@abejarano/ts-mongodb-criteria 1.10.0 → 1.11.1

package/README.md

@@ -6,7 +6,7 @@
 [![MongoDB](https://img.shields.io/badge/MongoDB-6.0+-green.svg)](https://www.mongodb.com/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg)](https://nodejs.org/)
-[![Tests](https://img.shields.io/badge/Tests-30%2F30%20passing-brightgreen.svg)](#testing)
+[![Tests](https://img.shields.io/badge/Tests-46%2F46%20passing-brightgreen.svg)](#testing)
 
 > A robust, type-safe implementation of the **Criteria Pattern** for MongoDB queries in TypeScript. Build complex database queries dynamically with a fluent, composable API designed following Domain-Driven Design (DDD) and Clean Architecture principles.
 
@@ -182,8 +182,9 @@ Use the `collection` argument inside `ensureIndexes` to avoid recursion.
 MongoRepository provides ready-to-use public methods for repositories that extend it:
 
 - `list(criteria, fieldsToExclude?)` for paginated queries
-- `one(filter)` to fetch a single entity
-- `upsert(entity)` to persist an aggregate
+- `many(filter, options?)` to fetch multiple entities matching a filter, with optional `{ transaction?, sort }`
+- `one(filter, transaction?)` to fetch a single entity
+- `upsert(entity, transaction?)` to persist an aggregate
   Internal helpers are private, so repositories should call these public methods
   directly.
 
@@ -198,8 +199,8 @@ 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`).
+The goal of `IRepository` is to prevent signature drift between your app's
+interfaces and the library's repository return types.
 
 ## Atomic Transactions
 
@@ -217,6 +218,10 @@ await MongoTransaction.run(async (tx) => {
 
   // Reads can observe writes made earlier in this transaction.
   const persistedUser = await userRepository.one({ id: user.getId() }, tx)
+  const activeUsers = await userRepository.many(
+    { status: "active" },
+    { transaction: tx, sort: { name: 1 } }
+  )
 })
 ```
 
@@ -235,8 +240,8 @@ async deactivateUser(id: string, tx: MongoTransaction): Promise<void> {
 
 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`.
+context to `upsert`, `delete`, protected `updateOne`, `one`, `list`, and `many`.
+Pass `tx` as the third argument to `list` after `fieldsToExclude`, and inside the options object (`{ transaction: tx }`) to `many`.
 
 **Your First Query in 30 Seconds:**
 
@@ -383,7 +388,7 @@ const criteria = new Criteria(Filters.fromValues(filters), Order.none())
 
 ## 🧪 Testing
 
-The library includes comprehensive test coverage (30/30 tests passing).
+The library includes comprehensive test coverage (46/46 tests passing).
 
 ```bash
 # Run all tests

package/dist/cjs/AggregateRoot.js

@@ -2,8 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AggregateRoot = void 0;
 class AggregateRoot {
-    static fromPrimitives(_data) {
-        throw new Error("fromPrimitives must be implemented in subclasses");
+    constructor(id) {
+        this.aggregateId = id;
+    }
+    getId() {
+        return this.aggregateId;
+    }
+    assignId(mongoId) {
+        if (this.aggregateId !== undefined) {
+            throw new Error("AGGREGATE_ID_ALREADY_ASSIGNED");
+        }
+        this.aggregateId = mongoId;
     }
 }
 exports.AggregateRoot = AggregateRoot;

package/dist/cjs/mongo/MongoRepository.js

@@ -25,9 +25,46 @@ class MongoRepository {
             id: result._id.toString(),
         });
     }
+    async many(filter, options) {
+        const collection = await this.collection();
+        const session = options?.transaction
+            ? MongoTransaction_1.MongoTransaction.sessionFor(options?.transaction)
+            : undefined;
+        const hasFields = options?.fields && options.fields.length > 0;
+        const projection = hasFields ? {} : undefined;
+        if (hasFields) {
+            options.fields.forEach((field) => {
+                projection[field] = 1;
+            });
+        }
+        const findOptions = session
+            ? { ...(projection ? { projection } : {}), session }
+            : projection
+                ? { projection }
+                : undefined;
+        const documents = await collection
+            .find(filter, findOptions)
+            .sort(options?.sort ? options?.sort : { _id: -1 })
+            .toArray();
+        return documents.map((document) => this.aggregateRootClass.fromPrimitives({
+            ...document,
+            id: document._id.toString(),
+        }));
+    }
     /** Upserts an aggregate by delegating to persist with its id. */
     async upsert(entity, transaction) {
-        await this.persist(entity.getId(), entity, transaction);
+        const primitiveResult = entity.toPrimitives();
+        const primitives = await Promise.resolve(primitiveResult);
+        const currentId = entity.getId();
+        const mongoId = currentId === undefined ? new mongodb_1.ObjectId() : new mongodb_1.ObjectId(currentId);
+        if (currentId === undefined) {
+            entity.assignId(mongoId.toString());
+        }
+        await this.updateOne({ _id: mongoId }, {
+            $set: {
+                ...primitives,
+            },
+        }, transaction);
     }
     /** Lists entities by criteria and returns a paginated response. */
     async list(criteria, fieldsToExclude = [], transaction) {
@@ -68,21 +105,6 @@ class MongoRepository {
             .db()
             .collection(this.collectionName());
     }
-    async persist(id, aggregateRoot, transaction) {
-        let primitives;
-        if (aggregateRoot.toPrimitives() instanceof Promise) {
-            primitives = await aggregateRoot.toPrimitives();
-        }
-        else {
-            primitives = aggregateRoot.toPrimitives();
-        }
-        await this.updateOne({ _id: new mongodb_1.ObjectId(id) }, {
-            $set: {
-                ...primitives,
-                id: id,
-            },
-        }, transaction);
-    }
     async searchByCriteria(criteria, fieldsToExclude = [], transaction) {
         this.criteria = criteria;
         this.query = this.criteriaConverter.convert(criteria);

package/dist/cjs/types/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/esm/AggregateRoot.js

@@ -1,5 +1,14 @@
 export class AggregateRoot {
-    static fromPrimitives(_data) {
-        throw new Error("fromPrimitives must be implemented in subclasses");
+    constructor(id) {
+        this.aggregateId = id;
+    }
+    getId() {
+        return this.aggregateId;
+    }
+    assignId(mongoId) {
+        if (this.aggregateId !== undefined) {
+            throw new Error("AGGREGATE_ID_ALREADY_ASSIGNED");
+        }
+        this.aggregateId = mongoId;
     }
 }

package/dist/esm/mongo/MongoRepository.js

@@ -22,9 +22,46 @@ export class MongoRepository {
             id: result._id.toString(),
         });
     }
+    async many(filter, options) {
+        const collection = await this.collection();
+        const session = options?.transaction
+            ? MongoTransaction.sessionFor(options?.transaction)
+            : undefined;
+        const hasFields = options?.fields && options.fields.length > 0;
+        const projection = hasFields ? {} : undefined;
+        if (hasFields) {
+            options.fields.forEach((field) => {
+                projection[field] = 1;
+            });
+        }
+        const findOptions = session
+            ? { ...(projection ? { projection } : {}), session }
+            : projection
+                ? { projection }
+                : undefined;
+        const documents = await collection
+            .find(filter, findOptions)
+            .sort(options?.sort ? options?.sort : { _id: -1 })
+            .toArray();
+        return documents.map((document) => this.aggregateRootClass.fromPrimitives({
+            ...document,
+            id: document._id.toString(),
+        }));
+    }
     /** Upserts an aggregate by delegating to persist with its id. */
     async upsert(entity, transaction) {
-        await this.persist(entity.getId(), entity, transaction);
+        const primitiveResult = entity.toPrimitives();
+        const primitives = await Promise.resolve(primitiveResult);
+        const currentId = entity.getId();
+        const mongoId = currentId === undefined ? new ObjectId() : new ObjectId(currentId);
+        if (currentId === undefined) {
+            entity.assignId(mongoId.toString());
+        }
+        await this.updateOne({ _id: mongoId }, {
+            $set: {
+                ...primitives,
+            },
+        }, transaction);
     }
     /** Lists entities by criteria and returns a paginated response. */
     async list(criteria, fieldsToExclude = [], transaction) {
@@ -65,21 +102,6 @@ export class MongoRepository {
             .db()
             .collection(this.collectionName());
     }
-    async persist(id, aggregateRoot, transaction) {
-        let primitives;
-        if (aggregateRoot.toPrimitives() instanceof Promise) {
-            primitives = await aggregateRoot.toPrimitives();
-        }
-        else {
-            primitives = aggregateRoot.toPrimitives();
-        }
-        await this.updateOne({ _id: new ObjectId(id) }, {
-            $set: {
-                ...primitives,
-                id: id,
-            },
-        }, transaction);
-    }
     async searchByCriteria(criteria, fieldsToExclude = [], transaction) {
         this.criteria = criteria;
         this.query = this.criteriaConverter.convert(criteria);

package/dist/esm/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/types/AggregateRoot.d.ts

@@ -1,8 +1,12 @@
 export declare abstract class AggregateRoot {
-    static fromPrimitives(_data: any): AggregateRoot;
-    abstract getId(): string | undefined;
+    private aggregateId?;
+    protected constructor(id?: string);
+    getId(): string | undefined;
+    assignId(mongoId: string): void;
     abstract toPrimitives(): any;
 }
 export type AggregateRootClass<T extends AggregateRoot> = {
-    fromPrimitives(data: any): T;
+    fromPrimitives(data: Record<string, unknown> & {
+        readonly id: string;
+    }): T;
 };

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./criteria";
 export * from "./mongo";
 export * from "./AggregateRoot";
+export type { MongoSort, MongoDirection } from "./types";

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

@@ -2,7 +2,13 @@ import { Criteria, Paginate } from "../criteria";
 import { AggregateRoot } from "../AggregateRoot";
 import { DeleteOptions } from "mongodb";
 import { MongoTransaction } from "./MongoTransaction";
+import { MongoSort } from "../types";
 export interface IRepository<T extends AggregateRoot> {
+    many(filter: object, options?: {
+        transaction?: MongoTransaction;
+        fields?: string[];
+        sort?: MongoSort;
+    }): Promise<T[]>;
     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>;

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

@@ -1,23 +1,5 @@
 import { Criteria, Filters, Order } from "../criteria";
-type MongoFilterOperator = "$eq" | "$ne" | "$gt" | "$lt" | "$regex" | "$lte" | "$gte" | "$or" | "$in" | "$nin";
-type MongoFilterValue = boolean | string | number | Date;
-type MongoFilterArrayValue = MongoFilterValue[];
-type MongoFilterOperation = {
-    [operator in MongoFilterOperator]?: MongoFilterValue | MongoFilterArrayValue;
-};
-type MongoFilter = {
-    [field: string]: MongoFilterOperation;
-} | {
-    [field: string]: {
-        $not: MongoFilterOperation;
-    };
-} | {
-    $or: any[];
-};
-type MongoDirection = 1 | -1;
-type MongoSort = {
-    [field: string]: MongoDirection;
-};
+import { MongoFilter, MongoSort } from "../types";
 export interface MongoQuery {
     filter: MongoFilter;
     sort: MongoSort;
@@ -43,4 +25,3 @@ export declare class MongoCriteriaConverter {
     private orFilter;
     private betweenFilter;
 }
-export {};

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

@@ -2,6 +2,7 @@ import { MongoTransaction } from "./MongoTransaction";
 import { Criteria, Paginate } from "../criteria";
 import { AggregateRoot, AggregateRootClass } from "../AggregateRoot";
 import { Collection, DeleteOptions, Document, UpdateFilter } from "mongodb";
+import { MongoSort } from "../types";
 export declare abstract class MongoRepository<T extends AggregateRoot> {
     private readonly aggregateRootClass;
     private static indexRegistry;
@@ -12,6 +13,11 @@ export declare abstract class MongoRepository<T extends AggregateRoot> {
     abstract collectionName(): string;
     /** Finds a single entity and hydrates it via the aggregate's fromPrimitives. */
     one(filter: object, transaction?: MongoTransaction): Promise<T | null>;
+    many(filter: object, options?: {
+        transaction?: MongoTransaction;
+        fields?: string[];
+        sort?: MongoSort;
+    }): Promise<T[]>;
     /** Upserts an aggregate by delegating to persist with its id. */
     upsert(entity: T, transaction?: MongoTransaction): Promise<void>;
     /** Lists entities by criteria and returns a paginated response. */
@@ -29,7 +35,6 @@ export declare abstract class MongoRepository<T extends AggregateRoot> {
     protected collection<U extends Document>(): Promise<Collection<U>>;
     protected updateOne(filter: object, update: Document[] | UpdateFilter<any>, transaction?: MongoTransaction): Promise<void>;
     private collectionRaw;
-    private persist;
     private searchByCriteria;
     private paginate;
 }

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

@@ -0,0 +1,25 @@
+export type MongoFilterOperator = "$eq" | "$ne" | "$gt" | "$lt" | "$regex" | "$lte" | "$gte" | "$or" | "$in" | "$nin";
+export type MongoFilterBetween = {
+    [p: string]: {
+        $gte: MongoFilterValue;
+        $lte: MongoFilterValue;
+    };
+};
+export type MongoFilterValue = boolean | string | number | Date;
+export type MongoFilterArrayValue = MongoFilterValue[];
+export type MongoFilterOperation = {
+    [operator in MongoFilterOperator]?: MongoFilterValue | MongoFilterArrayValue;
+};
+export type MongoFilter = {
+    [field: string]: MongoFilterOperation;
+} | {
+    [field: string]: {
+        $not: MongoFilterOperation;
+    };
+} | {
+    $or: any[];
+};
+export type MongoDirection = 1 | -1;
+export type MongoSort = {
+    [field: string]: MongoDirection;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@abejarano/ts-mongodb-criteria",
   "author": "angel bejarano / angel.bejarano@jaspesoft.com",
-  "version": "1.10.0",
+  "version": "1.11.1",
   "description": "Patrón Criteria para consultas MongoDB en TypeScript",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",