@abejarano/ts-mongodb-criteria 1.2.1

package/README.md

@@ -0,0 +1,329 @@
+# 🔍 TypeScript MongoDB Criteria Pattern
+
+[![npm version](https://badge.fury.io/js/@abejarano%2Fts-mongodb-criteria.svg)](https://www.npmjs.com/package/@abejarano/ts-mongodb-criteria)
+[![GitHub Package](https://img.shields.io/badge/GitHub-Package-blue.svg)](https://github.com/abejarano/ts-mongo-criteria/packages)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue.svg)](https://www.typescriptlang.org/)
+[![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)
+
+> 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.
+
+## 📚 Table of Contents
+
+- [🎯 Overview](#-overview)
+- [✨ Key Features](#-key-features)
+- [📦 Installation](#-installation)
+- [🚀 Quick Start](#-quick-start)
+- [📖 Documentation](#-documentation)
+- [🧪 Testing](#-testing)
+- [🤝 Contributing](#-contributing)
+- [📄 License](#-license)
+
+## 🎯 Overview
+
+The **Criteria Pattern** is a powerful design pattern that enables dynamic query construction without writing raw database queries. This library provides a type-safe, MongoDB-specific implementation that helps you:
+
+- **Build queries dynamically** based on runtime conditions
+- **Maintain type safety** throughout your query construction
+- **Compose and reuse** query components across your application
+- **Separate concerns** between query logic and data models
+- **Test queries easily** with a mockable interface
+
+### What is the Criteria Pattern?
+
+The Criteria pattern encapsulates query logic in a structured, object-oriented way. Instead of building query strings or objects directly, you compose `Criteria` objects that represent your search intentions. This approach provides flexibility, reusability, testability, and type safety.
+
+## ✨ Key Features
+
+### 🔒 **Type Safety First**
+
+- Full TypeScript support with strict typing
+- Compile-time validation of query structure
+- IntelliSense support for all operations
+
+### 🧩 **Flexible Query Building**
+
+- Support for all common MongoDB operators (EQUAL, NOT_EQUAL, GT, GTE, LT, LTE, CONTAINS, NOT_CONTAINS)
+- **NEW**: OR operator for complex logical combinations
+- Composable filters that can be combined and reused
+- Dynamic query construction based on runtime conditions
+
+### 📊 **Advanced Querying**
+
+```typescript
+// Simple equality
+{ status: { $eq: "active" } }
+
+// Complex OR conditions
+{ $or: [
+  { name: { $regex: "john" } },
+  { email: { $regex: "john" } }
+]}
+
+// Range queries
+{ age: { $gte: 18 }, price: { $lte: 999.99 } }
+```
+
+### 🎯 **MongoDB Optimized**
+
+- Native MongoDB 6.0+ support
+- Efficient query generation
+- Automatic index-friendly query structure
+
+### 📦 **Zero Dependencies**
+
+- Only peer dependencies (MongoDB driver)
+- Lightweight bundle size
+
+### 🏗️ **Clean Architecture**
+
+- Repository pattern implementation
+- Domain-driven design principles
+- Separation of concerns
+
+## 📦 Installation
+
+```bash
+# Using npm
+npm install @abejarano/ts-mongodb-criteria
+
+# Using yarn
+yarn add @abejarano/ts-mongodb-criteria
+
+# Using pnpm
+pnpm add @abejarano/ts-mongodb-criteria
+```
+
+### Peer Dependencies
+
+```bash
+# MongoDB driver (required)
+npm install mongodb@^6.0.0
+
+# TypeScript (for development)
+npm install -D typescript@^5.0.0
+```
+
+### System Requirements
+
+- **Node.js**: 20.0.0 or higher
+- **TypeScript**: 5.0.0 or higher (for development)
+- **MongoDB**: 6.0.0 or higher
+
+## 🚀 Quick Start
+
+```typescript
+import {
+  Criteria,
+  Filters,
+  Order,
+  Operator,
+  MongoRepository,
+} from "@abejarano/ts-mongodb-criteria"
+
+// 1. Create filters using a simple Map-based syntax
+const filters = [
+  new Map([
+    ["field", "status"],
+    ["operator", Operator.EQUAL],
+    ["value", "active"],
+  ]),
+  new Map([
+    ["field", "age"],
+    ["operator", Operator.GTE],
+    ["value", "18"],
+  ]),
+]
+
+// 2. Build criteria with filters, sorting, and pagination
+const criteria = new Criteria(
+  Filters.fromValues(filters),
+  Order.desc("createdAt"),
+  20, // limit
+  1 // page
+)
+
+// 3. Use with your MongoDB repository
+class UserRepository extends MongoRepository<User> {
+  collectionName(): string {
+    return "users"
+  }
+}
+
+const userRepo = new UserRepository()
+const users = await userRepo.searchByCriteria(criteria)
+```
+
+**Your First Query in 30 Seconds:**
+
+```typescript
+// Find active users over 18, sorted by creation date
+const activeAdultUsers = new Criteria(
+  Filters.fromValues([
+    new Map([
+      ["field", "status"],
+      ["operator", Operator.EQUAL],
+      ["value", "active"],
+    ]),
+    new Map([
+      ["field", "age"],
+      ["operator", Operator.GTE],
+      ["value", "18"],
+    ]),
+  ]),
+  Order.desc("createdAt"),
+  10, // Get 10 results
+  1 // First page
+)
+
+const results = await repository.searchByCriteria(activeAdultUsers)
+```
+
+## 📖 Documentation
+
+### 📖 Complete Documentation
+
+- **[📘 Quick Start Guide](./docs/quick-start.md)** - Get up and running in minutes
+- **[🏗️ Criteria Pattern Guide](./docs/criteria-pattern.md)** - Deep dive into the pattern, architecture, and theory
+- **[🔧 Operators Reference](./docs/operators.md)** - Complete guide to all available operators and their usage
+- **[⚡ Performance Guide](./docs/performance.md)** - Optimization strategies and best practices
+- **[🔄 Migration Guide](./docs/migration.md)** - Migrate from other query systems to Criteria pattern
+
+### 🎯 Key Concepts
+
+#### 1. **Criteria** - The main query builder
+
+```typescript
+const criteria = new Criteria(filters, order, limit?, page?)
+```
+
+#### 2. **Filters** - Collection of filter conditions
+
+```typescript
+const filters = Filters.fromValues([...filterMaps])
+```
+
+#### 3. **Order** - Sorting specification
+
+```typescript
+const order = Order.desc("createdAt") // or Order.asc("name")
+```
+
+#### 4. **Operators** - Available filter operations
+
+- `EQUAL`, `NOT_EQUAL` - Exact matching
+- `GT`, `GTE`, `LT`, `LTE` - Range operations
+- `BETWEEN` - Inclusive range with lower and upper bounds
+- `CONTAINS`, `NOT_CONTAINS` - Text search
+- `OR` - Logical OR combinations
+
+### 🆕 OR Operator Example
+
+```typescript
+import { OrCondition } from "@abejarano/ts-mongodb-criteria"
+
+// Search across multiple fields
+const searchConditions: OrCondition[] = [
+  { field: "name", operator: Operator.CONTAINS, value: "john" },
+  { field: "email", operator: Operator.CONTAINS, value: "john" },
+]
+
+const filters = [
+  new Map([
+    ["field", "search"],
+    ["operator", Operator.OR],
+    ["value", searchConditions],
+  ]),
+]
+
+// Generates: { $or: [
+//   { name: { $regex: "john" } },
+//   { email: { $regex: "john" } }
+// ]}
+```
+
+### ⏱️ BETWEEN Operator Example
+
+```typescript
+// Filter users created between two dates
+const filters = [
+  new Map([
+    ["field", "createdAt"],
+    ["operator", Operator.BETWEEN],
+    ["value", { start: new Date("2024-01-01"), end: new Date("2024-01-31") }],
+  ]),
+]
+
+const criteria = new Criteria(Filters.fromValues(filters), Order.none())
+
+// Generates: { createdAt: { $gte: 2024-01-01, $lte: 2024-01-31 } }
+```
+
+## 🧪 Testing
+
+The library includes comprehensive test coverage (30/30 tests passing).
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Please follow these guidelines:
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/abejarano/ts-mongo-criteria.git
+cd ts-mongo-criteria
+
+# Install dependencies
+yarn install
+
+# Run tests
+yarn test
+
+# Build the project
+yarn build
+```
+
+### Contribution Process
+
+1. **Fork** the repository
+2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
+3. **Write** tests for your changes
+4. **Ensure** all tests pass (`yarn test`)
+5. **Commit** using conventional commits (`git commit -m 'feat: add amazing feature'`)
+6. **Push** to your branch (`git push origin feature/amazing-feature`)
+7. **Open** a Pull Request
+
+## 📄 License
+
+This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.
+
+---
+
+## 👨‍💻 Author
+
+**Ángel Bejarano**  
+📧 [angel.bejarano@jaspesoft.com](mailto:angel.bejarano@jaspesoft.com)  
+🐙 [GitHub](https://github.com/abejarano)  
+🏢 [Jaspesoft](https://jaspesoft.com)
+
+---
+
+⭐️ **If this project helps you, please give it a star on GitHub!**
+
+🤝 **Questions or suggestions?** Open an issue or start a discussion.
+
+📢 **Follow us** for updates and new features!

package/dist/AggregateRoot.d.ts

@@ -0,0 +1,4 @@
+export declare abstract class AggregateRoot {
+    abstract getId(): string;
+    abstract toPrimitives(): any;
+}

package/dist/AggregateRoot.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AggregateRoot = void 0;
+class AggregateRoot {
+}
+exports.AggregateRoot = AggregateRoot;

package/dist/criteria/Criteria.d.ts

@@ -0,0 +1,11 @@
+import { Filters } from "./Filters";
+import { Order } from "./Order";
+export declare class Criteria {
+    readonly filters: Filters;
+    readonly order: Order;
+    readonly limit?: number;
+    readonly offset?: number;
+    readonly currentPage?: number;
+    constructor(filters: Filters, order: Order, limit?: number, offset?: number);
+    hasFilters(): boolean;
+}

package/dist/criteria/Criteria.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Criteria = void 0;
+class Criteria {
+    constructor(filters, order, limit, offset) {
+        this.filters = filters;
+        this.order = order;
+        this.limit = limit;
+        this.currentPage = offset;
+        this.offset =
+            offset !== undefined && limit !== undefined
+                ? (offset - 1) * limit
+                : undefined;
+    }
+    hasFilters() {
+        return this.filters.filters.length > 0;
+    }
+}
+exports.Criteria = Criteria;

package/dist/criteria/Filter.d.ts

@@ -0,0 +1,10 @@
+import { FilterField } from "./FilterField";
+import { FilterOperator } from "./FilterOperator";
+import { FilterInputValue, FilterValue } from "./FilterValue";
+export declare class Filter {
+    readonly field: FilterField;
+    readonly operator: FilterOperator;
+    readonly value: FilterValue;
+    constructor(field: FilterField, operator: FilterOperator, value: FilterValue);
+    static fromValues(values: Map<string, FilterInputValue>): Filter;
+}

package/dist/criteria/Filter.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Filter = void 0;
+const FilterField_1 = require("./FilterField");
+const FilterOperator_1 = require("./FilterOperator");
+const FilterValue_1 = require("./FilterValue");
+const InvalidArgumentError_exception_1 = require("../exceptions/InvalidArgumentError.exception");
+class Filter {
+    constructor(field, operator, value) {
+        this.field = field;
+        this.operator = operator;
+        this.value = value;
+    }
+    static fromValues(values) {
+        const field = values.get("field");
+        const operator = values.get("operator");
+        const value = values.get("value");
+        if (!field || !operator || value === undefined) {
+            throw new InvalidArgumentError_exception_1.InvalidArgumentError(`The filter is invalid`);
+        }
+        return new Filter(new FilterField_1.FilterField(field), FilterOperator_1.FilterOperator.fromValue(operator), new FilterValue_1.FilterValue(value));
+    }
+}
+exports.Filter = Filter;

package/dist/criteria/FilterField.d.ts

@@ -0,0 +1,4 @@
+import { StringValueObject } from "../valueObject";
+export declare class FilterField extends StringValueObject {
+    constructor(value: string);
+}

package/dist/criteria/FilterField.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilterField = void 0;
+const valueObject_1 = require("../valueObject");
+class FilterField extends valueObject_1.StringValueObject {
+    constructor(value) {
+        super(value);
+    }
+}
+exports.FilterField = FilterField;

package/dist/criteria/FilterOperator.d.ts

@@ -0,0 +1,18 @@
+export declare enum Operator {
+    EQUAL = "=",
+    NOT_EQUAL = "!=",
+    GT = ">",
+    LT = "<",
+    CONTAINS = "CONTAINS",
+    NOT_CONTAINS = "NOT_CONTAINS",
+    GTE = ">=",
+    LTE = "<=",
+    BETWEEN = "BETWEEN",
+    OR = "OR"
+}
+export declare class FilterOperator {
+    value: Operator;
+    constructor(value: Operator);
+    static fromValue(value: string): FilterOperator;
+    protected throwErrorForInvalidValue(value: Operator): void;
+}

package/dist/criteria/FilterOperator.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilterOperator = exports.Operator = void 0;
+const InvalidArgumentError_exception_1 = require("../exceptions/InvalidArgumentError.exception");
+var Operator;
+(function (Operator) {
+    Operator["EQUAL"] = "=";
+    Operator["NOT_EQUAL"] = "!=";
+    Operator["GT"] = ">";
+    Operator["LT"] = "<";
+    Operator["CONTAINS"] = "CONTAINS";
+    Operator["NOT_CONTAINS"] = "NOT_CONTAINS";
+    Operator["GTE"] = ">=";
+    Operator["LTE"] = "<=";
+    Operator["BETWEEN"] = "BETWEEN";
+    Operator["OR"] = "OR";
+})(Operator || (exports.Operator = Operator = {}));
+//export class FilterOperator extends EnumValueObject<Operator> {
+class FilterOperator {
+    constructor(value) {
+        this.value = value;
+        //super(value, Object.values(Operator));
+    }
+    static fromValue(value) {
+        for (const operatorValue of Object.values(Operator)) {
+            if (value === operatorValue.toString()) {
+                return new FilterOperator(operatorValue);
+            }
+        }
+        throw new InvalidArgumentError_exception_1.InvalidArgumentError(`The filter operator ${value} is invalid`);
+    }
+    throwErrorForInvalidValue(value) {
+        throw new InvalidArgumentError_exception_1.InvalidArgumentError(`The filter operator ${value} is invalid`);
+    }
+}
+exports.FilterOperator = FilterOperator;

package/dist/criteria/FilterValue.d.ts

@@ -0,0 +1,30 @@
+import { StringValueObject } from "../valueObject";
+import { Operator } from "./FilterOperator";
+export interface OrCondition {
+    field: string;
+    operator: Operator;
+    value: string;
+}
+export type FilterPrimitive = string | number | boolean | Date;
+export type BetweenValue = {
+    start: FilterPrimitive;
+    end: FilterPrimitive;
+} | {
+    startDate: FilterPrimitive;
+    endDate: FilterPrimitive;
+} | {
+    from: FilterPrimitive;
+    to: FilterPrimitive;
+};
+export type FilterInputValue = FilterPrimitive | FilterPrimitive[] | OrCondition[] | BetweenValue;
+export declare class FilterValue extends StringValueObject {
+    private readonly _originalValue;
+    constructor(value: FilterInputValue);
+    get isOrConditions(): boolean;
+    get asOrConditions(): OrCondition[];
+    get isBetween(): boolean;
+    get asBetween(): {
+        start: FilterPrimitive;
+        end: FilterPrimitive;
+    };
+}

package/dist/criteria/FilterValue.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilterValue = void 0;
+const valueObject_1 = require("../valueObject");
+const isOrConditionArray = (value) => {
+    if (!Array.isArray(value) || value.length === 0) {
+        return false;
+    }
+    const candidate = value[0];
+    return (typeof candidate === "object" &&
+        candidate !== null &&
+        "field" in candidate &&
+        "operator" in candidate &&
+        "value" in candidate);
+};
+const isBetweenObject = (value) => {
+    if (value === null || typeof value !== "object") {
+        return false;
+    }
+    const candidate = value;
+    const hasStartEnd = "start" in candidate && "end" in candidate;
+    const hasStartDateEndDate = "startDate" in candidate && "endDate" in candidate;
+    const hasFromTo = "from" in candidate && "to" in candidate;
+    return hasStartEnd || hasStartDateEndDate || hasFromTo;
+};
+const normalizeBetweenValue = (value) => {
+    if ("start" in value && "end" in value) {
+        return { start: value.start, end: value.end };
+    }
+    if ("startDate" in value && "endDate" in value) {
+        return { start: value.startDate, end: value.endDate };
+    }
+    return { start: value.from, end: value.to };
+};
+class FilterValue extends valueObject_1.StringValueObject {
+    constructor(value) {
+        if (Array.isArray(value) && isOrConditionArray(value)) {
+            // Handle OrCondition[]
+            super(JSON.stringify(value));
+        }
+        else if (Array.isArray(value)) {
+            // Handle primitive arrays (kept for backward compatibility)
+            super(value.join(","));
+        }
+        else if (isBetweenObject(value)) {
+            // Store serialized version but keep original reference
+            super(JSON.stringify(value));
+        }
+        else {
+            // Handle primitive values (string, number, boolean, Date)
+            super(value);
+        }
+        this._originalValue = value;
+    }
+    get isOrConditions() {
+        return isOrConditionArray(this._originalValue);
+    }
+    get asOrConditions() {
+        if (this.isOrConditions) {
+            return this._originalValue;
+        }
+        throw new Error("Value is not an OrCondition array");
+    }
+    get isBetween() {
+        return isBetweenObject(this._originalValue);
+    }
+    get asBetween() {
+        if (this.isBetween) {
+            return normalizeBetweenValue(this._originalValue);
+        }
+        throw new Error("Value is not a BETWEEN structure");
+    }
+}
+exports.FilterValue = FilterValue;

package/dist/criteria/Filters.d.ts

@@ -0,0 +1,8 @@
+import { Filter } from "./Filter";
+import { FilterInputValue } from "./FilterValue";
+export declare class Filters {
+    readonly filters: Filter[];
+    constructor(filters: Filter[]);
+    static fromValues(filters: Array<Map<string, FilterInputValue>>): Filters;
+    static none(): Filters;
+}

package/dist/criteria/Filters.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Filters = void 0;
+const Filter_1 = require("./Filter");
+class Filters {
+    constructor(filters) {
+        this.filters = filters;
+    }
+    static fromValues(filters) {
+        return new Filters(filters.map((values) => Filter_1.Filter.fromValues(values)));
+    }
+    static none() {
+        return new Filters([]);
+    }
+}
+exports.Filters = Filters;

package/dist/criteria/Order.d.ts

@@ -0,0 +1,12 @@
+import { OrderBy } from "./OrderBy";
+import { OrderType } from "./OrderType";
+export declare class Order {
+    readonly orderBy: OrderBy;
+    readonly orderType: OrderType;
+    constructor(orderBy: OrderBy, orderType: OrderType);
+    static fromValues(orderBy?: string, orderType?: string): Order;
+    static none(): Order;
+    static desc(orderBy: string): Order;
+    static asc(orderBy: string): Order;
+    hasOrder(): boolean;
+}

package/dist/criteria/Order.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Order = void 0;
+const OrderBy_1 = require("./OrderBy");
+const OrderType_1 = require("./OrderType");
+class Order {
+    constructor(orderBy, orderType) {
+        this.orderBy = orderBy;
+        this.orderType = orderType;
+    }
+    static fromValues(orderBy, orderType) {
+        if (!orderBy) {
+            return Order.none();
+        }
+        return new Order(new OrderBy_1.OrderBy(orderBy), OrderType_1.OrderType.fromValue(orderType || OrderType_1.OrderTypes.ASC));
+    }
+    static none() {
+        return new Order(new OrderBy_1.OrderBy(""), new OrderType_1.OrderType(OrderType_1.OrderTypes.NONE));
+    }
+    static desc(orderBy) {
+        return new Order(new OrderBy_1.OrderBy(orderBy), new OrderType_1.OrderType(OrderType_1.OrderTypes.DESC));
+    }
+    static asc(orderBy) {
+        return new Order(new OrderBy_1.OrderBy(orderBy), new OrderType_1.OrderType(OrderType_1.OrderTypes.ASC));
+    }
+    hasOrder() {
+        return !this.orderType.isNone();
+    }
+}
+exports.Order = Order;

package/dist/criteria/OrderBy.d.ts

@@ -0,0 +1,7 @@
+import { ValueObject } from "../valueObject/ValueObject";
+export declare class OrderBy extends ValueObject<string> {
+    readonly value: string;
+    constructor(value: string);
+    static create(value: string): OrderBy;
+    getValue(): string;
+}

package/dist/criteria/OrderBy.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrderBy = void 0;
+const ValueObject_1 = require("../valueObject/ValueObject");
+class OrderBy extends ValueObject_1.ValueObject {
+    constructor(value) {
+        super(value);
+        this.value = value;
+    }
+    static create(value) {
+        return new OrderBy(value);
+    }
+    getValue() {
+        return this.value;
+    }
+}
+exports.OrderBy = OrderBy;