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.

@abejarano/ts-mongodb-criteria brings the Criteria Pattern to MongoDB in TypeScript. Instead of writing raw query objects scattered across your codebase, you compose structured Criteria instances that encapsulate filter conditions, sort order, and pagination in a single, reusable object. The result is expressive, testable database logic that fits naturally into Domain-Driven Design (DDD) and Clean Architecture applications — from small Node.js services to large enterprise monorepos.

​
Key Features

Type-Safe Criteria

Every filter, operator, and sort direction is fully typed. TypeScript catches invalid query structures at compile time, long before they reach your database.

12 Filter Operators

EQUAL, NOT_EQUAL, GT, GTE, LT, LTE, CONTAINS, NOT_CONTAINS, BETWEEN, OR, IN, and NOT_IN — covering the full range of MongoDB query patterns.

MongoRepository Base

Extend MongoRepository<T> to get list, one, many, upsert, and delete out of the box. Declare your collection name and indexes — nothing else required.

Atomic Transactions

MongoTransaction.run wraps multiple repository writes in a single MongoDB transaction. One failure rolls back every write in the callback automatically.

DDD Primitives

AggregateRoot, IRepository<T>, Paginate<T>, and value-object base classes give your domain model a clean, framework-agnostic foundation.

CLI Migrations

The bundled ts-mongo CLI wraps migrate-mongo so you can create, run, and roll back database migrations with a single command — no extra config files needed.

​
Why the Criteria Pattern?

Raw MongoDB query objects are quick to write, but they scatter query logic across controllers, services, and repositories. As an application grows, the same filter conditions are duplicated in multiple places and tested indirectly — or not at all. The Criteria Pattern solves this by making queries first-class objects. A Criteria instance carries its own filters, sort order, and pagination. It can be built once in a use-case layer, passed down to any repository, and unit-tested in isolation. 
// ❌ Query logic is inline, opaque, and hard to reuse
const users = await db.collection("users").find({
  status: { $eq: "active" },
  age: { $gte: 18 },
}).sort({ createdAt: -1 }).skip(0).limit(20).toArray();

// Pagination, count, and next-page logic must be
// reimplemented every time.
const count = await db.collection("users").countDocuments({
  status: { $eq: "active" },
  age: { $gte: 18 },
});
The Criteria object is completely decoupled from the MongoDB driver. You can create and test it without a live database connection, then hand it to any MongoRepository implementation when it is time to execute.

​
Requirements

DependencyMinimum version
Node.js20.0.0
MongoDB6.0.0
TypeScript5.0.0
The library ships dual CJS and ESM builds and has no runtime dependencies beyond the mongodb peer dependency and the bundled migrate-mongo CLI dependency.

​
Next Steps

Quickstart

Install the package, define an entity, and run your first paginated query in under five minutes.

Installation

Full install instructions, environment variable reference, and TypeScript configuration options.

Build docs developers (and LLMs) love

Get started for freeTalk to us