Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/abejarano/ts-mongo-criteria/llms.txt

Use this file to discover all available pages before exploring further.

ts-mongo-criteria is a TypeScript library that brings the Criteria Pattern to MongoDB. Instead of writing raw query objects, you compose type-safe Criteria instances that translate automatically into MongoDB filters, sort specs, and paginated results — with zero boilerplate.

Quickstart

Get a working query running in under 5 minutes.

Installation

Install via npm, yarn, pnpm, or bun and configure your environment.

Criteria Pattern

Understand the design pattern powering the library.

Operators Reference

All 12 filter operators with MongoDB equivalents and examples.

Repository Setup

Build a full repository with indexes, pagination, and upsert.

API Reference

Complete type signatures for every exported class and interface.

​
What you get

12 Operators

EQUAL, GT, BETWEEN, CONTAINS, OR, IN, and more — all mapped to native MongoDB operators.

Pagination Built In

MongoRepository.list() returns Paginate<T> with nextPag, count, and results.

Atomic Transactions

Wrap multi-repository writes in MongoTransaction.run() for all-or-nothing semantics.

Dual CJS + ESM

Ships with CommonJS, ESM, and TypeScript declaration files — works in any modern setup.

Lazy Index Registration

Override ensureIndexes() once; the base class calls it automatically the first time a collection is accessed.

DDD Ready

AggregateRoot, ValueObject, and IRepository<T> primitives integrate cleanly into domain layers.

​
Quick look

import {
  Criteria, Filters, Order, Operator
} from "@abejarano/ts-mongodb-criteria"

const criteria = 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"),
  20,  // limit
  1    // page
)
The Criteria object above converts to the following MongoDB query automatically: 
{
  "filter": { "status": { "$eq": "active" }, "age": { "$gte": 18 } },
  "sort":   { "createdAt": -1 },
  "skip":   0,
  "limit":  20
}
1

Install the package

npm install @abejarano/ts-mongodb-criteria mongodb
2

Set your connection string

MONGO_URI=mongodb+srv://user:pass@cluster.mongodb.net/mydb
3

Extend MongoRepository

Implement collectionName() and ensureIndexes() — the rest is provided by the base class.
4

Build and execute criteria

Compose Filters, choose an Order, set a limit and page, then call repository.list(criteria).

Build docs developers (and LLMs) love

Get started for freeTalk to us