mongodb-pipeline-builder 4.0.2 → 4.2.0

package/Readme.md

@@ -1,2143 +1,555 @@
-++<div style="text-align: center; width: 100%;">
-
-<div style="display: inline-block">
+<div align="center">
 
 [![NPM version](https://img.shields.io/npm/v/mongodb-pipeline-builder.svg)](https://www.npmjs.com/package/mongodb-pipeline-builder)
 ![NPM](https://img.shields.io/npm/l/mongodb-pipeline-builder?registry_uri=https%3A%2F%2Fregistry.npmjs.com)
 ![npm](https://img.shields.io/npm/dw/mongodb-pipeline-builder)
-</div>
-
-<div style="display: inline-block">
 
 ![GitHub branch checks state](https://img.shields.io/github/checks-status/MikeDev75015/mongodb-pipeline-builder/main)
 [![CircleCI](https://circleci.com/gh/MikeDev75015/mongodb-pipeline-builder.svg?style=shield)](https://app.circleci.com/pipelines/github/MikeDev75015/mongodb-pipeline-builder)
 ![Sonar Quality Gate](https://img.shields.io/sonar/quality_gate/MikeDev75015_mongodb-pipeline-builder?server=https%3A%2F%2Fsonarcloud.io)
-</div>
-</div>
-
-<div style="text-align: center; width: 100%;">
-<div style="display: inline-block">
 
 ![Sonar Tests](https://img.shields.io/sonar/tests/MikeDev75015_mongodb-pipeline-builder?server=https%3A%2F%2Fsonarcloud.io)
 ![Sonar Coverage](https://img.shields.io/sonar/coverage/MikeDev75015_mongodb-pipeline-builder?server=https%3A%2F%2Fsonarcloud.io)
 <img src="https://mikedev75015.github.io/mongodb-pipeline-builder/images/coverage-badge-documentation.svg" alt="documentation-badge">
-</div>
-
-<div style="display: inline-block">
-
-![GitHub top language](https://img.shields.io/github/languages/top/MikeDev75015/mongodb-pipeline-builder)
-[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=MikeDev75015_mongodb-pipeline-builder&metric=ncloc)](https://sonarcloud.io/dashboard?id=MikeDev75015_mongodb-pipeline-builder)
-[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=MikeDev75015_mongodb-pipeline-builder&metric=duplicated_lines_density)](https://sonarcloud.io/dashboard?id=MikeDev75015_mongodb-pipeline-builder)
-</div>
-</div>
-
-<div style="text-align: center; width: 100%;">
-<div style="display: inline-block">
-
-![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/MikeDev75015/mongodb-pipeline-builder)
-![GitHub commit activity](https://img.shields.io/github/commit-activity/w/MikeDev75015/mongodb-pipeline-builder)
-![GitHub last commit (branch)](https://img.shields.io/github/last-commit/MikeDev75015/mongodb-pipeline-builder/main)
-</div>
-
-<div style="display: inline-block">
 
 [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=MikeDev75015_mongodb-pipeline-builder&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=MikeDev75015_mongodb-pipeline-builder)
 [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=MikeDev75015_mongodb-pipeline-builder&metric=reliability_rating)](https://sonarcloud.io/dashboard?id=MikeDev75015_mongodb-pipeline-builder)
 [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=MikeDev75015_mongodb-pipeline-builder&metric=security_rating)](https://sonarcloud.io/dashboard?id=MikeDev75015_mongodb-pipeline-builder)
-</div>
-</div>
 
 ---
 
-<div style="text-align: center; width: 100%;">
-
-[-> Technical documentation <-](https://mikedev75015.github.io/mongodb-pipeline-builder)
+[📚 Technical Documentation](https://mikedev75015.github.io/mongodb-pipeline-builder)
 
+# MongoDB Pipeline Builder
 
-
-# mongodb-pipeline-builder
+**A type-safe, fluent API for building MongoDB aggregation pipelines**
 
 </div>
 
+## 🚀 Overview
 
-<p style="text-align: justify; width: 100%;font-size: 15px;">
-
-**mongodb-pipeline-builder** is a pipeline builder for the [db.collection.aggregate](https://docs.mongodb.com/manual/reference/method/db.collection.aggregate/), the [db.aggregate](https://www.mongodb.com/docs/v7.0/reference/method/db.aggregate/) and the mongoose [Model.aggregate](https://mongoosejs.com/docs/api/aggregate.html#Aggregate()) methods.
+**mongodb-pipeline-builder** is a powerful TypeScript library that simplifies the creation of MongoDB aggregation pipelines. It provides a fluent, type-safe API that makes your aggregation pipelines more readable, maintainable, and less error-prone.
 
-- Simplify pipelines by making them more readable
-- Pipelines are easier to edit. 
-- Pipeline stages appear in an array. 
-- Sequential stages for documents
-
-All stages except the Out, Merge, GeoNear, ChangeStream, ChangeStreamSplitLargeEvent and Paging stages can appear multiple times in a pipeline.
-
-</p>
-
----
+### Key Features
 
-## npm package <img src="https://pbs.twimg.com/media/EDoWJbUXYAArclg.png" width="24" height="24" />
+✨ **Type-Safe** - Full TypeScript support with generics for typed responses  
+📖 **Readable** - Fluent API that makes complex pipelines easy to understand  
+🔧 **Maintainable** - Modular design with reusable helpers  
+🎯 **Complete** - Supports all MongoDB aggregation stages and operators  
+⚡ **Efficient** - Built-in pagination support with optimized queries  
+🛡️ **Validated** - Automatic validation of pipeline stages  
 
-`npm i -S mongodb-pipeline-builder`
+### Supported Platforms
 
+- ✅ [MongoDB Native Driver](https://www.mongodb.com/docs/drivers/node/current/) - `db.collection.aggregate()`
+- ✅ [MongoDB Database Commands](https://www.mongodb.com/docs/manual/reference/method/db.aggregate/) - `db.aggregate()`
+- ✅ [Mongoose](https://mongoosejs.com/) - `Model.aggregate()`
 
 ---
 
+## 📦 Installation
 
-### **News and Breaking changes** between **v3** and **v4**
-
-#### **PipelineBuilder:**
- * Renaming `getPipeline()` with `build()`
- * Added new stages: `ChangeStream`, `ChangeStreamSplitLargeEvent`, `Densify`, `Documents`, `Fill`, `ListLocalSessions`, `ListSampledQueries`, `ListSearchIndexes`, `SearchMeta`, `SetWindowFields` and `ShardedDataDistribution`.
- * Added the possibility to insert stages without validation with new `Insert` stage.
- * Checking for non-duplicable stages.
-
-#### **Helpers:**
- * Replacing the `Payload` suffix with `Helper` suffix
- * Prefixed with the name of the pipeline stage where they should be used
-
-#### **Operators:**
- * Prefixed with the **$** symbol
- * Rename `MapOperator` to `$Map`
-
-
-#### **GetResult:**
- * To be used if no Paging stage is set
- * Removing GetDocs method arguments
- * Added new GetElement method to the response object
-
-#### **GetPagingResult:**
- * To be used exclusively with Paging stage.
+```bash
+npm install mongodb-pipeline-builder
+```
 
+```bash
+yarn add mongodb-pipeline-builder
+```
 
-*Welcome generics! `GetResult<Type>` and `GetPagingResult<Type>` now offer the ability to type responses.*
+```bash
+pnpm add mongodb-pipeline-builder
+```
 
 ---
 
-## Usage:
-
-
-### Using `require()`
-
-```typescript
-const PipelineBuilder = require("mongodb-pipeline-builder").PipelineBuilder;
-const { LookupEqualityHelper, ProjectOnlyHelper, Field } = require('mongodb-pipeline-builder/helpers');
-const { $LessThanEqual, $ArrayElementAt, $Equal, $Expression } = require('mongodb-pipeline-builder/operators');
-```
-
-### Using `import`
+## 🎯 Quick Start
 
+### Basic Example
 
 ```typescript
 import { PipelineBuilder } from 'mongodb-pipeline-builder';
-import { LookupEqualityHelper, ProjectOnlyHelper, Field } from 'mongodb-pipeline-builder/helpers';
-import { $LessThanEqual, $ArrayElementAt, $Equal, $Expression } from 'mongodb-pipeline-builder/operators';
-```
+import { ProjectOnlyHelper } from 'mongodb-pipeline-builder/helpers';
+import { $Expression, $Equal } from 'mongodb-pipeline-builder/operators';
 
----
-
-## Pagination example
+const pipeline = new PipelineBuilder('users-query')
+  .Match($Expression($Equal('$status', 'active')))
+  .Project(ProjectOnlyHelper('name', 'email', 'createdAt'))
+  .Sort({ createdAt: -1 })
+  .Limit(10)
+  .build();
 
+// Use with MongoDB
+const results = await db.collection('users').aggregate(pipeline).toArray();
 
-```typescript
-const myNewPipeline = new PipelineBuilder( 'myPagination', { debug: true } )
-    .Match( $Expression( $LessThanEqual( '$id', 20 ) ) )
-    .Project( ProjectOnlyHelper( 'name', 'weight' ) )
-    .Paging( 5, 3 ) // 5 per page, page 3
-    .build();
+// Use with Mongoose
+const results = await User.aggregate(pipeline);
 ```
 
-*is equivalent to*
-
+### With Pagination
 
 ```typescript
-const myNewPipeline = [ {
-    $facet: {
-        docs: [
-            { $match: { $expr: { $lte: ["$id", 20] } } },
-            { $project: { _id: 0, name: 1, weight: 1 } },
-            { $skip: 10 },
-            { $limit: 5 }
-        ],
-        count: [
-            { $match: { $expr: { $lte: ["$id", 20] } } },
-            { $count: "totalElements" }
-        ]
-    }
-} ];
-```
+import { PipelineBuilder, GetPagingResult } from 'mongodb-pipeline-builder';
+import { $Expression, $GreaterThan } from 'mongodb-pipeline-builder/operators';
 
----
+const pipeline = new PipelineBuilder('paginated-users')
+  .Match($Expression($GreaterThan('$age', 18)))
+  .Sort({ createdAt: -1 })
+  .Paging(20, 1) // 20 items per page, page 1
+  .build();
 
-## No pagination example
+const result = await GetPagingResult(User, pipeline);
 
-```typescript
-const myNewPipeline = new PipelineBuilder( 'user-skills' )
-    .Match( $Expression( $Equal( '$id', 123456 ) ) )
-    .Lookup( LookupEqualityHelper( 'profiles', 'profile', 'id', 'profileId' ) )
-    .Project( ProjectOnlyHelper( 'firstname', 'lastname', 'email' ) )
-    .AddFields(
-        Field( 'skills', $ArrayElementAt( '$profile.skills', 0 ) ),
-        Field( 'availability', $ArrayElementAt( '$profile.availability', 0 ) )
-    )
-    .Unset( 'profile' )
-    .build();
+console.log(result.GetDocs());           // Document array
+console.log(result.GetCount());          // Total count
+console.log(result.GetTotalPageNumber()); // Total pages
 ```
 
-*is equivalent to*
+### With Lookups (Joins)
 
 ```typescript
-const myNewPipeline = [
-    { $match: { $expr: { $eq: ["$id", 123456] } } },
-    { $lookup: { from: "profiles", as: "profile", localField: "id", foreignField: "profileId" } },
-    { $project: { _id: 0, firstname: 1, lastname: 1, email: 1 } },
-    { $addFields: {
-        skills: { $arrayElemAt: ["$profile.skills", 0] },
-        availability: { $arrayElemAt: ["$profile.availability", 0] }
-    } },
-    { $unset: "profile" }
-];
-```
-
-___
-
-#  GetResult method (No pagination)
+import { PipelineBuilder } from 'mongodb-pipeline-builder';
+import { LookupEqualityHelper, Field } from 'mongodb-pipeline-builder/helpers';
+import { $ArrayElementAt } from 'mongodb-pipeline-builder/operators';
 
-```typescript
-GetResult<T>(): Promise<GetResultResponse<T>>
+const pipeline = new PipelineBuilder('users-with-profiles')
+  .Lookup(LookupEqualityHelper('profiles', 'profile', 'profileId', '_id'))
+  .AddFields(
+    Field('profileData', $ArrayElementAt('$profile', 0))
+  )
+  .Unset('profile')
+  .build();
 ```
 
-<p style="font-size: 15px;">
-
-`GetResult<T>()` is an **asynchronous** method that provides a very easy way to use aggregation responses.
-
-<p>
-
-
-<p style="font-size: 15px;">
-
-This method returns a `GetResultResponse` object that contains 3 methods:<br>
-
-- `GetDocs(): T[]` to get all the documents that match the request.
-- `GetElement(index: number | 'last'): T` to get a particular document by its index.
-- `GetCount(): number` to get the total number of documents found.
-
-</p>
+---
 
+## 📚 Documentation
 
-```typescript
-const result = await GetResult<DocType>( target, pipeline ); 
-result.GetDocs(); // () => DocType[]
-result.GetElement(index | 'last'); // () => DocType | undefined
-result.GetCount(); // () => number
-```
+### Core Concepts
 
-*$Or*
-```typescript
-GetResult<DocType>( target, pipeline ).then( result => {
-    result.GetDocs(); // () => DocType[]
-    result.GetElement(index | 'last'); // () => DocType | undefined
-    result.GetCount(); // () => number
-} );
-```
+- **[Getting Started Guide](./docs/getting-started.md)** - Detailed introduction and setup
+- **[Migration Guide v3 → v4](./docs/migration-guide.md)** - Upgrade from version 3
 
-### `GetElement(index: number | 'last')` method possibilities:
+### API Reference
 
-<p style="font-size: 15px;">
+- **[Pipeline Stages](./docs/api/stages.md)** - All MongoDB aggregation stages
+- **[Operators](./docs/api/operators.md)** - Aggregation operators ($match, $group, etc.)
+- **[Helpers](./docs/api/helpers.md)** - Utility functions and stage helpers (Field, ProjectHelper, LookupHelper, etc.)
 
-- A particular document can be retrieved by specifying its index.
-- To get the last document, simply provide the string `'last'`. 
-- If the specified index is greater than the index of the last document, `GetElement()` will return undefined.
-</p>
+### Examples & Tutorials
 
-```typescript
-// GetDocs() -> [document1, document2, document3, ..., document51]
-result.GetElement(2); // will return document to index 2, document3
-result.GetElement('last'); // will return the last document, document51
-result.GetElement(99); // will return undefined
-```
+- **[Pagination Examples](./docs/examples/pagination.md)** - Implementing pagination patterns
+- **[Lookup & Join Examples](./docs/examples/lookups.md)** - Working with multiple collections
 
 ---
 
-#  GetPagingResult method (Pagination)
-
-```typescript
-GetPagingResult<T>(): Promise<GetPagingResultResponse<T>>
-```
+## 🔥 What's New in v4
 
-<p style="font-size: 15px;">
+### Breaking Changes
 
-`GetPagingResult<T>()` is an **asynchronous** method that provides a very easy way to use aggregation responses when **Paging** stage is used.
+#### PipelineBuilder
+- ✨ `build()` replaces `getPipeline()`
+- 🆕 New stages: `ChangeStream`, `ChangeStreamSplitLargeEvent`, `Densify`, `Documents`, `Fill`, `ListLocalSessions`, `ListSampledQueries`, `ListSearchIndexes`, `SearchMeta`, `SetWindowFields`, `ShardedDataDistribution`
+- 🆕 `Insert()` stage for adding custom stages without validation
+- ✅ Automatic detection of non-duplicable stages
 
-<p>
+#### Helpers
+- 🔄 `Payload` suffix → `Helper` suffix
+- 🏷️ Prefixed with stage name (e.g., `LookupEqualityHelper`)
 
+#### Operators
+- 🏷️ All operators prefixed with `$` (e.g., `$Add`, `$Match`)
+- 🔄 `MapOperator` → `$Map`
 
-<p style="font-size: 15px;">
+#### Result Methods
+- 🎯 `GetResult<T>()` - For non-paginated queries
+  - ✨ `GetElement(index | 'last')` - New method to get specific document
+  - 🚀 Generic type support for typed responses
+- 🎯 `GetPagingResult<T>()` - Exclusively for paginated queries
+  - 🚀 Generic type support for typed responses
 
-This method returns a `GetPagingResultResponse` object that contains three methods:
-- `GetDocs()` to get the documents found.
-- `GetCount()` to get the total number of documents found.
-- `GetTotalPageNumber()` to get the total number of pages.
-
-</p>
+---
 
+## 💡 Real-World Example
+
+```typescript
+import { PipelineBuilder, GetResult } from 'mongodb-pipeline-builder';
+import { 
+  LookupEqualityHelper, 
+  ProjectOnlyHelper, 
+  Field 
+} from 'mongodb-pipeline-builder/helpers';
+import { 
+  $Expression, 
+  $And,
+  $Equal, 
+  $GreaterThanEqual,
+  $ArrayElementAt 
+} from 'mongodb-pipeline-builder/operators';
+
+// Complex query: Active users with their orders
+const pipeline = new PipelineBuilder('active-users-with-orders', { debug: true })
+  // Filter active users over 18
+  .Match($Expression(
+    $And(
+      $Equal('$status', 'active'),
+      $GreaterThanEqual('$age', 18)
+    )
+  ))
+  
+  // Join with orders collection
+  .Lookup(LookupEqualityHelper('orders', 'orders', '_id', 'userId'))
+  
+  // Project specific fields
+  .Project(ProjectOnlyHelper('name', 'email', 'age'))
+  
+  // Add computed fields
+  .AddFields(
+    Field('totalOrders', { $size: '$orders' }),
+    Field('lastOrder', $ArrayElementAt('$orders', -1))
+  )
+  
+  // Sort by total orders descending
+  .Sort(Field('totalOrders', -1))
+  
+  // Limit results
+  .Limit(50)
+  
+  .build();
+
+// Execute query with typed response
+interface UserWithOrders {
+  name: string;
+  email: string;
+  age: number;
+  totalOrders: number;
+  lastOrder?: any;
+}
 
-```typescript
-const result = await GetPagingResult<DocType>(target, pipeline);
-result.GetDocs(); // () => DocType[]
-result.GetCount(); // () => number
-result.GetTotalPageNumber(); // () => number
-```
+const result = await GetResult<UserWithOrders>(User, pipeline);
 
-*$Or*
-```typescript
-GetPagingResult<DocType>(target, pipeline).then( result => {
-    result.GetDocs(); // () => DocType[]
-    result.GetCount(); // () => number
-    result.GetTotalPageNumber(); // () => number
-} );
+// Access results
+const users = result.GetDocs();        // UserWithOrders[]
+const count = result.GetCount();       // number
+const firstUser = result.GetElement(0); // UserWithOrders | undefined
+const lastUser = result.GetElement('last'); // UserWithOrders | undefined
 ```
 
+---
 
-___
-
+## 🧪 Try It Online
 
-[=> Try the lib on NPM RunKit with the require method <=](https://npm.runkit.com/mongodb-pipeline-builder)
+[→ Try the library on NPM RunKit](https://npm.runkit.com/mongodb-pipeline-builder)
 
 ---
 
-`// builder = new PipelineBuilder('example');`
+## 📊 Comparison: Before & After
 
-## CUSTOM STAGES
-
-### Paging(elementsPerPage, page)
-
-  *The Paging stage automatically adds 3 native stages used to paginate documents ($skip, $limit and $count).
-  <br>Page is optional and defaults to 1.*
+### Before (Raw MongoDB)
 
 ```typescript
-builder.Paging(5, 2).build();
-
-// pipeline
-[
+const pipeline = [
+  { 
+    $match: { 
+      $expr: { 
+        $and: [
+          { $eq: ["$status", "active"] },
+          { $gte: ["$age", 18] }
+        ]
+      } 
+    } 
+  },
   {
-    $facet: {
-      docs: [ { '$skip': 5 }, { '$limit': 5 } ],
-      count: [ { '$count': 'totalElements' } ]
+    $lookup: {
+      from: "orders",
+      localField: "_id",
+      foreignField: "userId",
+      as: "orders"
     }
-  }
-]
-```
-
-### Insert(stage)
-
-  *The Insert stage allows you to insert a stage without validation.
-  <br>Usefully when you need to insert a stage that is not yet implemented
-  or when the value fails validation but for some reason you want to keep it.*
-
-```typescript
-builder.Insert({ '$myCustomStage': { myField: 'myValue' } }).build();
-
-// pipeline
-[ { $myCustomStage: { myField: 'myValue' } } ]
-```
-
-
-## [MONGODB STAGES](https://docs.mongodb.com/manual/reference/operator/aggregation-pipeline/)
-
-### [AddFields](https://www.mongodb.com/docs/manual/reference/operator/aggregation/addFields/)(...values)
-#### Helper: `Field(name, value)`
-```typescript
-builder.AddFields(
-  Field('foo', 'value1'),
-  Field('bar', 'value2'),
-).build();
-
-// pipeline
-[ { $addFields: { foo: 'value1', bar: 'value2' } } ]
-```
-
-### [Bucket](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bucket/)(value)
-#### Helper: `BucketHelper(groupBy, boundaries, optional)`
-```typescript
-builder.Bucket(BucketHelper('$age', [6, 13, 18])).build();
-
-// pipeline
-[ { $bucket: { groupBy: '$age', boundaries: [ 6, 13, 18 ] } } ]
-```
-
-### [BucketAuto](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bucketAuto/)(value)
-#### Helper: `BucketAutoHelper(groupBy, buckets, optional)`
-```typescript
-builder.BucketAuto(BucketAutoHelper('$age', 5)).build();
-
-// pipeline
-[ { $bucketAuto: { groupBy: '$age', buckets: 5 } } ]
-```
-
-### [ChangeStream](https://www.mongodb.com/docs/manual/reference/operator/aggregation/changeStream/)(value)
-#### Helper: `ChangeStreamHelper(optional)`
-```typescript
-builder.ChangeStream(ChangeStreamHelper()).build();
-
-// pipeline
-[ { $changeStream: {} } ]
-```
-
-### [ChangeStreamSplitLargeEvent](https://www.mongodb.com/docs/manual/reference/operator/aggregation/changeStreamSplitLargeEvent/)()
-```typescript
-builder.ChangeStreamSplitLargeEvent().build();
-
-// pipeline
-[ { $changeStreamSplitLargeEvent: {} } ]
-```
-
-### [CollStats](https://www.mongodb.com/docs/manual/reference/operator/aggregation/collStats/)(value)
-#### Helper: `CollStatsHelper(optional)`
-```typescript
-builder.CollStats(CollStatsHelper()).build();
-
-// pipeline
-[ { $collStats: {} } ]
-```
-
-### [Count](https://www.mongodb.com/docs/manual/reference/operator/aggregation/count/)(value)
-```typescript
-builder.Count('counter').build();
-
-// pipeline
-[ { $count: 'counter' } ]
+  },
+  { 
+    $project: { 
+      _id: 0, 
+      name: 1, 
+      email: 1, 
+      age: 1,
+      totalOrders: { $size: "$orders" },
+      lastOrder: { $arrayElemAt: ["$orders", -1] }
+    } 
+  },
+  { $sort: { totalOrders: -1 } },
+  { $limit: 50 }
+];
 ```
 
-### [CurrentOp](https://www.mongodb.com/docs/manual/reference/operator/aggregation/currentOp/)(value)
-#### Helper: `CurrentOpHelper(optional)`
-```typescript
-builder.CurrentOp(CurrentOpHelper()).build();
-
-// pipeline
-[ { $currentOp: {} } ]
-```
+### After (With Pipeline Builder)
 
-### [Densify](https://www.mongodb.com/docs/manual/reference/operator/aggregation/densify/)(value)
-#### Helper: `DensifyHelper(field, range, optional)`
 ```typescript
-builder.Densify(
-    DensifyHelper(
-      'altitude',
-      { bounds: 'full', step: 200 },
-      { partitionByFields: [ 'variety' ] }
-    ),
-).build();
-
-// pipeline
-[
-  {
-    $densify: {
-      field: 'altitude',
-      range: { bounds: 'full', step: 200 }
-      partitionByFields: [ 'variety' ],
-    }
-  }
-]
+const pipeline = new PipelineBuilder('active-users')
+  .Match($Expression($And(
+    $Equal('$status', 'active'),
+    $GreaterThanEqual('$age', 18)
+  )))
+  .Lookup(LookupEqualityHelper('orders', 'orders', '_id', 'userId'))
+  .Project(
+    ProjectOnlyHelper('name', 'email', 'age'),
+    Field('totalOrders', { $size: '$orders' }),
+    Field('lastOrder', $ArrayElementAt('$orders', -1))
+  )
+  .Sort(Field('totalOrders', -1))
+  .Limit(50)
+  .build();
 ```
 
-### [Documents](https://www.mongodb.com/docs/manual/reference/operator/aggregation/documents/)(...values)
-```typescript
-builder.Documents({ docId: 1 }, { docId: 2 }, { docId: 3 }).build();
+---
 
-// pipeline
-[ { $documents: [ { docId: 1 }, { docId: 2 }, { docId: 3 } ] } ]
-```
+## 🔍 Working with Results
 
-### [Facet](https://www.mongodb.com/docs/manual/reference/operator/aggregation/facet/)(...values)
-#### Helper: `Field(name, pipeline)`
-```typescript
-builder.Facet(
-  Field('pipeline1', [{ $match: { tag: 'first' }}]),
-  Field('pipeline2', [{ $match: { tag: 'second' }}]),
-  Field('pipeline3', [{ $match: { tag: 'third' }}]),
-).build();
-
-// pipeline
-[
-  {
-    $facet: {
-      pipeline1: [ { '$match': { tag: 'first' } } ],
-      pipeline2: [ { '$match': { tag: 'second' } } ],
-      pipeline3: [ { '$match': { tag: 'third' } } ]
-    }
-  }
-]
-```
+### GetResult<T> - For Non-Paginated Queries
 
-### [Fill](https://www.mongodb.com/docs/manual/reference/operator/aggregation/fill/)(value)
-#### Helper: `FillHelper(output, optional)`
-```typescript
-builder.Fill(
-  FillHelper({
-    bootsSold: { value: 0 },
-    sandalsSold: { value: 0 },
-    sneakersSold: { value: 0 },
-  }),
-).build();
-
-// pipeline
-[
-  {
-    $fill: {
-      output: {
-        bootsSold: { value: 0 },
-        sandalsSold: { value: 0 },
-        sneakersSold: { value: 0 }
-      }
-    }
-  }
-]
-```
+Use when your pipeline does **not** include the `Paging` stage:
 
-### [GeoNear](https://www.mongodb.com/docs/manual/reference/operator/aggregation/geoNear/)(value)
-#### Helper: `GeoNearHelper(near, distanceField, optional)`
 ```typescript
-builder.GeoNear(
-  GeoNearHelper({ type: "Point", coordinates: [ -73.99279 , 40.719296 ] }, 'calculated')
-).build();
-
-// pipeline
-[
-  {
-    $geoNear: {
-      near: { type: 'Point', coordinates: [ -73.99279, 40.719296 ] },
-      distanceField: 'calculated'
-    }
-  }
-]
-```
+import { GetResult } from 'mongodb-pipeline-builder';
 
-### [GraphLookup](https://www.mongodb.com/docs/manual/reference/operator/aggregation/graphLookup/)(value)
-```typescript
-builder.GraphLookup({
-  from: 'employees', startWith: '$reportsTo', connectFromField: 'reportsTo', connectToField: 'name', as: 'reportingHierarchy',
-}).build();
+interface User {
+  name: string;
+  email: string;
+  age: number;
+}
 
-// pipeline
-[
-  {
-    $graphLookup: {
-      from: 'employees',
-      startWith: '$reportsTo',
-      connectFromField: 'reportsTo',
-      connectToField: 'name',
-      as: 'reportingHierarchy'
-    }
-  }
-]
-```
+const pipeline = new PipelineBuilder('users')
+  .Match($Expression($Equal('$status', 'active')))
+  .build();
 
-### [Group](https://www.mongodb.com/docs/manual/reference/operator/aggregation/group/)(value)
-```typescript
-builder.Group({ _id: null, count: { $count: { } } }).build();
+const result = await GetResult<User>(User, pipeline);
 
-// pipeline
-[
-  { $group: { _id: null, count: { '$count': {} } } }
-]
+const users = result.GetDocs();           // User[] - all documents  
+const count = result.GetCount();          // number - total count
+const firstUser = result.GetElement(0);   // User | undefined
+const lastUser = result.GetElement('last'); // User | undefined
 ```
 
-### [IndexStats](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexStats/)()
-```typescript
-builder.IndexStats().build();
-
-// pipeline
-[ { $indexStats: {} } ]
-```
+---
 
-### [Limit](https://www.mongodb.com/docs/manual/reference/operator/aggregation/limit/)(value)
-```typescript
-builder.Limit(10).build();
+### GetPagingResult<T> - For Paginated Queries
 
-// pipeline
-[ { $limit: 10 } ]
-```
+Use **exclusively** when your pipeline includes the `Paging` stage:
 
-### [ListLocalSessions](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listLocalSessions/)(value)
 ```typescript
-builder.ListLocalSessions({ allUsers: true }).build();
+import { GetPagingResult } from 'mongodb-pipeline-builder';
 
-// pipeline
-[ { $listLocalSessions: { allUsers: true } } ]
-```
+const pipeline = new PipelineBuilder('users')
+  .Match($Expression($Equal('$status', 'active')))
+  .Paging(20, 1) // Required for GetPagingResult
+  .build();
 
-### [ListSampledQueries](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSampledQueries/)(value)
-```typescript
-builder.ListSampledQueries({ namespace: "social.post" }).build();
+const result = await GetPagingResult<User>(User, pipeline);
 
-// pipeline
-[ { $listSampledQueries: { namespace: 'social.post' } } ]
+const users = result.GetDocs();           // User[] - current page
+const totalCount = result.GetCount();     // number - total documents
+const totalPages = result.GetTotalPageNumber(); // number - total pages
 ```
 
-### [ListSearchIndexes](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSearchIndexes/)(value)
-```typescript
-builder.ListSearchIndexes({ name: 'searchIndex01' }).build();
+> 📖 **Learn More:** See [Getting Started Guide](./docs/getting-started.md) for detailed examples
 
-// pipeline
-[ { $listSearchIndexes: { name: 'searchIndex01' } } ]
-```
+---
 
-### [ListSessions](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSessions/)(value)
-```typescript
-builder.ListSessions({ allUsers: true }).build();
+## 📚 API Reference Quick Links
 
-// pipeline
-[ { $listSessions: { allUsers: true } } ]
-```
+### Pipeline Stages
 
-### [Lookup](https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup/)(value)
-#### Helper: `LookupConditionHelper(from, as, optional)`
-```typescript
-builder.Lookup(LookupConditionHelper('users', 'users')).build();
+All MongoDB aggregation stages are supported. See [complete reference](./docs/api/stages.md).
 
-// pipeline
-[ { $lookup: { from: 'users', as: 'users' } } ]
-```
-#### Helper: `LookupEqualityHelper(from, as, localField, foreignField)`
-```typescript
-builder.Lookup(
-  LookupEqualityHelper('users', 'users', 'userId', 'id')
-).build();
+**Common Stages:**
+- `Match()` - Filter documents
+- `Project()` - Select/transform fields
+- `Group()` - Group and aggregate
+- `Sort()` - Sort documents
+- `Limit()` - Limit results
+- `Lookup()` - Join collections
+- `Unwind()` - Deconstruct arrays
+- `AddFields()` - Add computed fields
+- `Paging()` - Add pagination
 
-// pipeline
-[
-  {
-    $lookup: {
-      from: 'users',
-      localField: 'userId',
-      foreignField: 'id',
-      as: 'users'
-    }
-  }
-]
-```
+### Operators
 
-### [Match](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match/)(value)
-#### Helper: `Field(name, value)`
-```typescript
-builder.Match(Field('age', 18)).build();
+100+ MongoDB operators supported. See [complete reference](./docs/api/operators.md).
 
-// pipeline
-[ { $match: { age: 18 } } ]
-```
-#### Operator: `$Expression`
-```typescript
-builder.Match($Expression($GreaterThanEqual('$age', 18))).build();
+**Common Operators:**
+- Comparison: `$Equal`, `$GreaterThan`, `$LessThan`
+- Logical: `$And`, `$Or`, `$Not`
+- Arithmetic: `$Add`, `$Subtract`, `$Multiply`, `$Divide`
+- Array: `$Size`, `$Filter`, `$Map`, `$ArrayElementAt`
+- String: `$Concat`, `$ToLower`, `$ToUpper`, `$Split`
+- Date: `$DateAdd`, `$DateSubtract`, `$DateDifference`
+- Aggregation: `$Sum`, `$Average`, `$Min`, `$Max`
 
-// pipeline
-[ { $match: { '$expr': { '$gte': [ '$age', 18 ] } } } ]
-```
+### Helpers
 
-### [Merge](https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge/)(value)
-#### Helper: `MergeHelper(into, optional)`
-```typescript
-builder.Merge(MergeHelper('newCollection')).build();
+20+ helper functions for common patterns. See [complete list in stages.md](./docs/api/stages.md#complete-helpers-reference).
 
-// pipeline
-[ { $merge: { into: 'newCollection' } } ]
-```
+**Common Helpers:**
+- `Field(name, value)` - Universal field helper
+- `ProjectOnlyHelper(...fields)` - Include specific fields
+- `LookupEqualityHelper(...)` - Simple joins
+- `BucketHelper(...)` - Categorize documents
+- `SearchHelper(...)` - Full-text search
 
-### [Out](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out/)(value)
-#### Helper: `OutHelper(collection, optional)`
-```typescript
-builder.Out(OutHelper('users')).build();
+---
 
-// pipeline
-[ { $out: 'users' } ]
-```
+## 🎓 Quick Examples
 
-### [PlanCacheStats](https://www.mongodb.com/docs/manual/reference/operator/aggregation/planCacheStats/)()
+### Example 1: Simple Query
 ```typescript
-builder.PlanCacheStats().build();
-
-// pipeline
-[ { $planCacheStats: {} } ]
-```
+const pipeline = new PipelineBuilder('active-users')
+  .Match($Expression($Equal('$status', 'active')))
+  .Project(ProjectOnlyHelper('name', 'email'))
+  .Sort({ createdAt: -1 })
+  .Limit(10)
+  .build();
 
-### [Project](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project/)(...values)
-#### Helper: `ProjectHelper(field, value)`
-```typescript
-builder.Project(
-  ProjectHelper('age', '$user.age'),
-  ProjectHelper(
-    'nickname',
-    {
-      $cond: {
-        if: { $eq: [ '', '$user.nickname' ] },
-        then: '$$REMOVE',
-        else: '$user.nickname',
-      },
-    },
-  ),
-).build();
-
-// pipeline
-[
-  {
-    $project: {
-      age: '$user.age',
-      nickname: {
-        $cond: {
-          if: { $eq: [ '', '$user.nickname' ] },
-          then: '$$REMOVE',
-          else: '$user.nickname'
-        }
-      }
-    }
-  }
-]
+const result = await GetResult<User>(User, pipeline);
 ```
-#### Helper: `ProjectIgnoreHelper(...fields)`
-```typescript
-builder.Project(ProjectIgnoreHelper('password', 'refreshToken')).build();
 
-// pipeline
-[ { $project: { password: 0, refreshToken: 0 } } ]
-```
-#### Helper: `ProjectOnlyHelper(...fields)`
+### Example 2: With Pagination
 ```typescript
-builder.Project(ProjectOnlyHelper('password', 'refreshToken')).build();
+const pipeline = new PipelineBuilder('paginated')
+  .Match($Expression($GreaterThan('$price', 100)))
+  .Sort({ price: -1 })
+  .Paging(20, 1)
+  .build();
 
-// pipeline
-[ { $project: { _id: 0, password: 1, refreshToken: 1 } } ]
+const result = await GetPagingResult<Product>(Product, pipeline);
+console.log(`Page 1 of ${result.GetTotalPageNumber()}`);
 ```
 
-### [Redact](https://www.mongodb.com/docs/manual/reference/operator/aggregation/redact/)(value)
+### Example 3: With Joins
 ```typescript
-builder.Redact(
-  $Condition(
-    $GreaterThan($Size($SetIntersection('$tags', ['STLW', 'G'])), 0),
-    '$$DESCEND',
-    '$$PRUNE'
+const pipeline = new PipelineBuilder('users-with-orders')
+  .Lookup(LookupEqualityHelper('orders', 'orders', '_id', 'userId'))
+  .AddFields(
+    Field('orderCount', $Size('$orders')),
+    Field('lastOrder', $ArrayElementAt('$orders', -1))
   )
-).build();
-
-// pipeline
-[
-  {
-    $redact: {
-      '$cond': [
-        { '$gt': [ { '$size': { '$setIntersection': [ '$tags', [ 'STLW', 'G' ] ] } }, 0 ] },
-        '$$DESCEND',
-        '$$PRUNE'
-      ]
-    }
-  }
-]
+  .Match($Expression($GreaterThan('$orderCount', 0)))
+  .build();
 ```
 
-### [ReplaceRoot](https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceRoot/)(value)
+### Example 4: Complex Aggregation
 ```typescript
-builder.ReplaceRoot({
-  newRoot: { full_name: { $concat : [ "$first_name", " ", "$last_name" ] } }
-}).build();
-
-// pipeline
-[
-  {
-    $replaceRoot: {
-      newRoot: {
-        full_name: { '$concat': [ '$first_name', ' ', '$last_name' ] }
-      }
-    }
-  }
-]
-```
-
-### [ReplaceWith](https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceWith/)(value)
-```typescript
-builder.ReplaceWith('$name').build();
-
-// pipeline
-[ { $replaceWith: '$name' } ]
+const pipeline = new PipelineBuilder('sales-by-category')
+  .Match($Expression($Equal('$year', 2024)))
+  .Group({
+    _id: '$category',
+    totalSales: $Sum('$amount'),
+    averagePrice: $Average('$price'),
+    count: $Sum(1)
+  })
+  .Sort({ totalSales: -1 })
+  .Limit(10)
+  .build();
 ```
 
-### [Sample](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sample/)(value)
-#### Helper: `SampleHelper(size)`
-```typescript
-builder.Sample(SampleHelper(6)).build();
-
-// pipeline
-[ { $sample: { size: 6 } } ]
-```
+---
 
-### [Search](https://www.mongodb.com/docs/manual/reference/operator/aggregation/search/)(value)
-#### Helper: `SearchHelper(operator | collector, optional)`
-```typescript
-builder.Search(
-  SearchHelper({
-    near: { path: 'released', origin: date, pivot: 7776000000 },
-  }),
-).build();
-
-// pipeline
-[
-  {
-    $search: {
-      near: { path: 'released', origin: date, pivot: 7776000000 },
-    },
-  }
-]
-```
+## ❓ FAQ
 
-### [SearchMeta](https://www.mongodb.com/docs/manual/reference/operator/aggregation/searchMeta/)(value)
-#### Helper: `SearchMetaHelper(collector, optional)`
-```typescript
-builder.SearchMeta(
-  SearchMetaHelper({
-    facet: {
-      operator: {
-        near: { path: 'released', origin: date, pivot: 7776000000 },
-      },
-      facets: {
-        test: { type: 'number', path: 'released', boundaries: [0, 100] },
-      },
-    },
-  })
-).build();
+<details>
+<summary><strong>When should I use GetResult vs GetPagingResult?</strong></summary>
 
-// pipeline
-[
-  {
-    $searchMeta: {
-      facet: {
-        operator: {
-          near: { path: 'released', origin: date, pivot: 7776000000 },
-        },
-        facets: {
-          test: { type: 'number', path: 'released', boundaries: [0, 100] },
-        },
-      },
-    }
-  }
-]
-```
+- Use `GetResult` for queries **without** the `Paging` stage
+- Use `GetPagingResult` **exclusively** when using the `Paging` stage
 
-### [Set](https://www.mongodb.com/docs/manual/reference/operator/aggregation/set/)(...values)
-#### Helper: `Field(name, value)`
-```typescript
-builder.Set(Field('first', true), Field('second', 2)).build();
+The `Paging` stage wraps your pipeline in `$facet` for efficient pagination.
+</details>
 
-// pipeline
-[ { $set: { first: true, second: 2 } } ]
-```
+<details>
+<summary><strong>Can I use raw MongoDB syntax?</strong></summary>
 
-### [SetWindowFields](https://www.mongodb.com/docs/manual/reference/operator/aggregation/setWindowFields/)(value)
+Yes! Use the `Insert` stage:
 ```typescript
-builder.SetWindowFields({
-  partitionBy: "$state",
-  sortBy: { orderDate: 1 },
-  output: {
-    cumulativeQuantityForState: {
-      $sum: "$quantity",
-      window: { documents: [ "unbounded", "current" ] }
-    }
-  }
-}).build();
-
-// pipeline
-[
-  {
-    $setWindowFields: {
-      partitionBy: '$state',
-      sortBy: { orderDate: 1 },
-      output: {
-        cumulativeQuantityForState: {
-          '$sum': '$quantity',
-          window: { documents: [ 'unbounded', 'current' ] }
-        }
-      }
-    }
-  }
-]
+builder.Insert({ $myCustomStage: { field: 'value' } })
 ```
+Useful for new MongoDB stages or custom implementations.
+</details>
 
-### [ShardedDataDistribution](https://www.mongodb.com/docs/manual/reference/operator/aggregation/shardedDataDistribution/)(value)
-```typescript
-builder.ShardedDataDistribution({}).build();
+<details>
+<summary><strong>Does it work with Mongoose?</strong></summary>
 
-// pipeline
-[ { $shardedDataDistribution: {} } ]
-```
+Yes! Works with:
+- **MongoDB Native Driver:** `db.collection.aggregate()`
+- **Mongoose:** `Model.aggregate()`
+- **MongoDB Database Commands:** `db.aggregate()`
+</details>
 
-### [Skip](https://www.mongodb.com/docs/manual/reference/operator/aggregation/skip/)(value)
-```typescript
-builder.Skip(100).build();
+<details>
+<summary><strong>Are all MongoDB stages supported?</strong></summary>
 
-// pipeline
-[ { $skip: 100 } ]
-```
+Yes! All stages through MongoDB 7.0+ including `$densify`, `$fill`, `$setWindowFields`, `$searchMeta`, and more.
+</details>
 
-### [Sort](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort/)(...values)
-#### Helper: `Field(name, value)`
-```typescript
-builder.Sort(
-  Field('first', -1),
-  Field('second', 1),
-  Field('third', { $meta: "textScore" }),
-).build();
-
-// pipeline
-[
-  {
-    $sort: { first: -1, second: 1, third: { '$meta': 'textScore' } }
-  }
-]
-```
+<details>
+<summary><strong>How do I handle TypeScript types?</strong></summary>
 
-### [SortByCount](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sortByCount/)(value)
+Use generics:
 ```typescript
-builder.SortByCount('$employee').build();
-// pipeline
-
-[ { $sortByCount: '$employee' } ]
+interface User { name: string; email: string; }
+const result = await GetResult<User>(User, pipeline);
+const users: User[] = result.GetDocs(); // Fully typed!
 ```
+</details>
 
-### [UnionWith](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unionWith/)(value)
-#### Helper: `UnionWithHelper(collection, pipeline)`
-```typescript
-builder.UnionWith(
-  UnionWithHelper('cars'),
-).build();
+<details>
+<summary><strong>Can I chain multiple lookups?</strong></summary>
 
-// pipeline
-[
-  {
-    $unionWith: { coll: 'cars' }
-  }
-]
-```
+Yes! Chain as many as needed:
 ```typescript
-builder.UnionWith(
-  UnionWithHelper(
-    undefined,
-    [{ $document: [{ ref: 1 }, { ref: 2 }, { ref: 3 }],  }]),
-).build();
-
-// pipeline
-[
-  {
-    $unionWith: { pipeline: [ { '$document': [ { ref: 1 }, { ref: 2 }, { ref: 3 } ] } ] }
-  }
-]
+builder
+  .Lookup(LookupEqualityHelper('profiles', 'profile', '_id', 'userId'))
+  .Lookup(LookupEqualityHelper('orders', 'orders', '_id', 'userId'))
+  .Lookup(LookupEqualityHelper('subscriptions', 'sub', '_id', 'userId'))
 ```
-```typescript
-builder.UnionWith(
-  UnionWithHelper('cars', [{ $match: { color: 'red' } }]),
-).build();
+See [Lookup Examples](./docs/examples/lookups.md).
+</details>
 
-// pipeline
-[
-  {
-    $unionWith: { coll: 'cars', pipeline: [ { '$match': { color: 'red' } } ] }
-  }
-]
-```
+---
 
-### [Unset](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset/)(...values)
-```typescript
-builder.Unset('users', 'roles').build();
+## 📈 Performance Tips
 
-// pipeline
-[ { $unset: [ 'users', 'roles' ] } ]
-```
+1. **Index your fields** - Create indexes on `$match` and `$sort` fields
+2. **Match early** - Apply `$match` as early as possible
+3. **Project early** - Remove unnecessary fields to reduce memory
+4. **Limit lookups** - Use pipeline syntax to limit joined documents
+5. **Use covered queries** - Query only indexed fields when possible
 
-### [Unwind](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unwind/)(value)
-```typescript
-builder.Unwind({ path: '$sizes', preserveNullAndEmptyArrays: true }).build();
+> 📖 **Learn More:** [Pagination Examples](./docs/examples/pagination.md#performance-tips)
 
-// pipeline
-[ { $unwind: { path: '$sizes', preserveNullAndEmptyArrays: true } } ]
-```
+---
 
-___
+## 🆘 Support
 
+### Getting Help
 
-# [MONGODB OPERATORS](https://docs.mongodb.com/manual/reference/operator/aggregation/)
+- 📖 [Documentation](./docs/getting-started.md)
+- 🐛 [Issue Tracker](https://github.com/MikeDev75015/mongodb-pipeline-builder/issues)
+- 💬 [MongoDB Docs](https://docs.mongodb.com/manual/aggregation/)
 
-#### [$Absolute](https://www.mongodb.com/docs/manual/reference/operator/aggregation/abs/)
-```typescript
-$Absolute(-5)
+### Reporting Issues
 
-// operator
-{ $abs: -5 }
-```
-#### [$Accumulator](https://www.mongodb.com/docs/manual/reference/operator/aggregation/accumulator/)
-```typescript
-$Accumulator(
-  () => ({ count: 0, sum: 0 }),
-  (state: { count: number; sum: number; }, numCopies: number) => ({
-    count: state.count + 1,
-    sum: state.sum + numCopies,
-  }),
-  ['$copies'],
-  (state1: { count: number; sum: number; }, state2: { count: number; sum: number; }) => ({
-    count: state1.count + state2.count,
-    sum: state1.sum + state2.sum,
-  }),
-  { finalize: (state: { sum: number; count: number; }) => (state.sum / state.count) },
-)
-
-// operator
-{
-  '$accumulator': {
-    init: [ () => ({ count: 0, sum: 0 }) ],
-    accumulate: [
-      (state: { count: number; sum: number; }, numCopies: number) => ({
-        count: state.count + 1,
-        sum: state.sum + numCopies,
-      })
-    ],
-    accumulateArgs: [ '$copies' ],
-    merge: [
-      (state1: { count: number; sum: number; }, state2: { count: number; sum: number; }) => ({
-        count: state1.count + state2.count,
-        sum: state1.sum + state2.sum,
-      })
-    ],
-    finalize: [ (state: { sum: number; count: number; }) => (state.sum / state.count) ],
-    lang: 'js'
-  }
-}
-```
-#### [$ArcCosine](https://www.mongodb.com/docs/manual/reference/operator/aggregation/acos/)
-```typescript
-$ArcCosine({ $divide : [ '$side_b', '$hypotenuse' ] })
+Include:
+- Package version
+- Node.js and MongoDB versions
+- Code snippet
+- Expected vs actual behavior
 
-// operator
-{ '$acos': { '$divide': [ '$side_b', '$hypotenuse' ] } }
-```
-#### [$ArcCosineHyperbolic](https://www.mongodb.com/docs/manual/reference/operator/aggregation/acosh/)
-```typescript
-$ArcCosineHyperbolic(3)
+---
 
-// operator
-{ '$acosh': 3 }
-```
-#### [$Add](https://www.mongodb.com/docs/manual/reference/operator/aggregation/add/)
-```typescript
-$Add('$price', 10)
 
-// operator
-{ '$add': [ '$price', 10 ] }
-```
-#### [$AddToSet](https://www.mongodb.com/docs/manual/reference/operator/aggregation/addToSet/)
-```typescript
-$AddToSet('$item')
+## 📜 Changelog
 
-// operator
-{ '$addToSet': '$item' }
-```
-#### [$AllElementsTrue](https://www.mongodb.com/docs/manual/reference/operator/aggregation/allElementsTrue/)
-```typescript
-$AllElementsTrue([ true, 1, "someString" ])
-
-// operator
-{ '$allElementsTrue': [ [ true, 1, 'someString' ] ] }
-```
-#### [$And](https://www.mongodb.com/docs/manual/reference/operator/aggregation/and/)
-```typescript
-$And(1, 'green')
-
-// operator
-{ '$and': [ 1, 'green' ] }
-```
-#### [$AnyElementTrue](https://www.mongodb.com/docs/manual/reference/operator/aggregation/anyElementTrue/)
-```typescript
-$AnyElementTrue([ true, false ])
-
-// operator
-{ '$anyElementTrue': [ [ true, false ] ] }
-```
-#### [$ArrayElementAt](https://www.mongodb.com/docs/manual/reference/operator/aggregation/arrayElemAt/)
-```typescript
-$ArrayElementAt([ 1, 2, 3 ], 0)
-
-// operator
-{ '$arrayElemAt': [ [ 1, 2, 3 ], 0 ] }
-```
-#### [$ArrayToObject](https://www.mongodb.com/docs/manual/reference/operator/aggregation/arrayToObject/)
-```typescript
-$ArrayToObject([ { "k": "item", "v": "abc123" }, { "k": "qty", "v": "$qty" } ])
-
-// operator
-{ '$arrayToObject': [ { k: 'item', v: 'abc123' }, { k: 'qty', v: '$qty' } ] }
-```
-```typescript
-$ArrayToObject([ [ "item", "abc123" ], [ "qty", 25 ] ], true)              
-
-// operator
-{ '$arrayToObject': { '$literal': [ [ 'item', 'abc123' ], [ 'qty', 25 ] ] } }
-```
-#### [$ArcSine](https://www.mongodb.com/docs/manual/reference/operator/aggregation/asin/)
-```typescript
-$ArcSine('$value')
-
-// operator
-{ '$asin': '$value' }
-```
-#### [$ArcSineHyperbolic](https://www.mongodb.com/docs/manual/reference/operator/aggregation/asinh/)
-```typescript
-$ArcSineHyperbolic('$value')
-
-// operator
-{ '$asinh': '$value' }
-```
-#### [$ArcTangent](https://www.mongodb.com/docs/manual/reference/operator/aggregation/atan/)
-```typescript
-$ArcTangent('$value')
-
-// operator
-{ '$atan': '$value' }
-```
-#### [$ArcTangent2](https://www.mongodb.com/docs/manual/reference/operator/aggregation/atan2/)
-```typescript
-$ArcTangent2('$side_b', '$side_a')
-
-// operator
-{ '$atan2': [ '$side_b', '$side_a' ] }
-```
-#### [$ArcTangentHyperbolic](https://www.mongodb.com/docs/manual/reference/operator/aggregation/atanh/)
-```typescript
-$ArcTangentHyperbolic('$value')
-
-// operator
-{ '$atanh': '$value' }
-```
-#### [$Average](https://www.mongodb.com/docs/manual/reference/operator/aggregation/avg/)
-```typescript
-$Average('$value')
-
-// operator
-{ '$avg': '$value' }
-```
-```typescript
-$Average('$value1', '$value2', '$value3')
-
-// operator
-{ '$avg': [ '$value1', '$value2', '$value3' ] }
-```
-#### [$BinarySize](https://www.mongodb.com/docs/manual/reference/operator/aggregation/binarySize/)
-```typescript
-$BinarySize('Hello World!')
-
-// operator
-{ '$binarySize': 'Hello World!' }
-```
-#### [$BitwiseAnd](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bitAnd/#mongodb-expression-exp.-bitAnd)
-```typescript
-$BitwiseAnd('$array')
-
-// operator
-{ '$bitAnd': '$array' }
-```
-```typescript
-$BitwiseAnd(0, 127, 5)
-
-// operator
-{ '$bitAnd': [ 0, 127, 5 ] }
-```
-#### [$BitwiseNot](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bitNot/#mongodb-expression-exp.-bitNot)
-```typescript
-$BitwiseNot('$long')
-
-// operator
-{ '$bitNot': '$long' }
-```
-#### [$BitwiseOr](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bitOr/#mongodb-expression-exp.-bitOr)
-```typescript
-$BitwiseOr('$array')
-
-// operator
-{ '$bitOr': '$array' }
-```
-```typescript
-$BitwiseOr(0, 127, 5)
-
-// operator
-{ '$bitOr': [ 0, 127, 5 ] }
-```
-#### [$BitwiseXor](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bitXor/#mongodb-expression-exp.-bitXor)
-```typescript
-$BitwiseXor('$array')
-
-// operator
-{ '$bitXor': '$array' }
-```
-```typescript
-$BitwiseXor(0, 127, 5)
-
-// operator
-{ '$bitXor': [ 0, 127, 5 ] }
-```
-#### [$Bottom](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bottom/#mongodb-group-grp.-bottom)
-```typescript
-$Bottom(['field1', 'field2'], { field2: -1 })
-
-// operator
-{ '$bottom': { output: [ 'field1', 'field2' ], sortBy: { field2: -1 } } }
-```
-#### [$BottomN](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bottomN/#mongodb-group-grp.-bottomN)
-```typescript
-$BottomN('field', { field: 1 }, 3)
-
-// operator
-{ '$bottomN': { output: 'field', sortBy: { field: 1 }, n: 3 } }
-```
-#### [$BsonSize](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bsonSize/)
-```typescript
-$BsonSize('$$ROOT')
-
-// operator
-{ '$bsonSize': '$$ROOT' }
-```
-#### [$Ceil](https://www.mongodb.com/docs/manual/reference/operator/aggregation/ceil/)
-```typescript
-$Ceil('$value')
-
-// operator
-{ '$ceil': '$value' }
-```
-#### [$Compare](https://www.mongodb.com/docs/manual/reference/operator/aggregation/cmp/)
-```typescript
-$Compare('$age', 25)
-
-// operator
-{ '$cmp': [ '$age', 25 ] }
-```
-#### [$Concat](https://www.mongodb.com/docs/manual/reference/operator/aggregation/concat/)
-```typescript
-$Concat('$first', ' - ', '$second')
-
-// operator
-{ '$concat': [ '$first', ' - ', '$second' ] }
-```
-#### [$ConcatArrays](https://www.mongodb.com/docs/manual/reference/operator/aggregation/concatArrays/)
-```typescript
-$ConcatArrays('$array', [1, 2, 3])
-
-// operator
-{ '$concatArrays': [ '$array', [ 1, 2, 3 ] ] }
-```
-#### [$Condition](https://www.mongodb.com/docs/manual/reference/operator/aggregation/cond/)
-```typescript
-$Condition({ $gte: [ '$quantity', 250 ] }, 'true', 'false')
-
-// operator
-{ '$cond': [ { '$gte': [ '$quantity', 250 ] }, 'true', 'false' ] }
-```
-#### [$Convert](https://www.mongodb.com/docs/manual/reference/operator/aggregation/convert/)
-```typescript
-$Convert(100, 'bool')
-
-// operator
-{ '$convert': { input: 100, to: 'bool' } }
-```
-#### [$Cosine](https://www.mongodb.com/docs/manual/reference/operator/aggregation/cos/)
-```typescript
-$Cosine('$angle')
-
-// operator
-{ '$cos': '$angle' }
-```
-#### [$CosineHyperbolic](https://www.mongodb.com/docs/manual/reference/operator/aggregation/cosh/)
-```typescript
-$CosineHyperbolic({ $degreesToRadians : "$angle" })
-
-// operator
-{ '$cosh': { '$degreesToRadians': '$angle' } }
-```
-#### [$Count](https://www.mongodb.com/docs/manual/reference/operator/aggregation/count-accumulator/)
-```typescript
-$Count()
-
-// operator
-{ '$count': {} }
-```
-#### [$CovariancePopulation](https://www.mongodb.com/docs/manual/reference/operator/aggregation/covariancePop/)
-```typescript
-$CovariancePopulation('$numeric1', '$numeric2')
-
-// operator
-{ '$covariancePopulation': [ '$numeric1', '$numeric2' ] }
-```
-#### [$CovarianceSample](https://www.mongodb.com/docs/manual/reference/operator/aggregation/covarianceSamp/)
-```typescript
-$CovarianceSample('$numeric1', '$numeric2')
-
-// operator
-{ '$covarianceSample': [ '$numeric1', '$numeric2' ] }
-```
-#### [$DateAdd](https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateAdd/)
-```typescript
-$DateAdd('$startDate', 'hour', 2)
-
-// operator
-{ '$dateAdd': { startDate: '$startDate', unit: 'hour', amount: 2 } }
-```
-#### [$DateDifference](https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateDiff/)
-```typescript
-$DateDifference('$startDate', '$endDate', 'second')
-
-// operator
-{ '$dateDiff': { startDate: '$startDate', endDate: '$endDate', unit: 'second' } }
-```
-#### [$DateFromParts](https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateFromParts/)
-```typescript
-$DateFromCalendarParts(2000, { month: 12, day: 31, hour: 12, minute: 25, second: 59, timezone: '+01:00' })
-
-// operator
-{
-  '$dateFromParts': {
-    year: 2000,
-    month: 12,
-    day: 31,
-    hour: 12,
-    minute: 25,
-    second: 59,
-    timezone: '+01:00'
-  }
-}
-```
-```typescript
-$DateFromIsoWeekParts(2000, { isoWeek: 53, isoDayOfWeek: 7, millisecond: 500 })
-
-// operator
-{ '$dateFromParts': { isoWeekYear: 2000, isoWeek: 53, isoDayOfWeek: 7, millisecond: 500 } }
-```
-#### [$DateFromString](https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateFromString/)
-```typescript
-$DateFromString('2017-02-08T12:10:40.787', { timezone: 'America/New_York' })
-
-// operator
-{
-  '$dateFromString': {
-    dateString: '2017-02-08T12:10:40.787',
-    timezone: 'America/New_York'
-  }
-}
-```
-#### [$DateSubtract](https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateSubtract/)
-```typescript
-$DateSubtract(1697382106124, 'month', 1)
-
-// operator
-{ '$dateSubtract': { startDate: 1697382106124, unit: 'month', amount: 1 } }
-```
-#### [$DateToParts](https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateToParts/)
-```typescript
-$DateToParts(1697382106124)
-
-// operator
-{ '$dateToParts': { date: 1697382106124 } }
-```
-#### [$DateToString](https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateToString/)
-```typescript
-$DateToString(1697382106124)
-
-// operator
-{ '$dateToString': { date: 1697382106124 } }
-```
-#### [$DateTrunc](https://www.mongodb.com/docs/manual/reference/operator/aggregation/dateTrunc/)
-```typescript
-$DateTrunc(1697382106124, 'month')
-
-// operator
-{ '$dateTrunc': { date: 1697382106124, unit: 'month' } }
-```
-#### [$DayOfMonth](https://www.mongodb.com/docs/manual/reference/operator/aggregation/dayOfMonth/)
-```typescript
-$DayOfMonth('$date', 'Europe/Paris')
-
-// operator
-{ '$dayOfMonth': { date: '$date', timezone: 'Europe/Paris' } }
-```
-#### [$DayOfWeek](https://www.mongodb.com/docs/manual/reference/operator/aggregation/dayOfWeek/)
-```typescript
-$DayOfWeek('$date', '+03:30')
-
-// operator
-{ '$dayOfWeek': { date: '$date', timezone: '+03:30' } }
-```
-#### [$DayOfYear](https://www.mongodb.com/docs/manual/reference/operator/aggregation/dayOfYear/)
-```typescript
-$DayOfYear('$date')
-
-// operator
-{ '$dayOfYear': { date: '$date' } }
-```
-#### [$DegreesToRadians](https://www.mongodb.com/docs/manual/reference/operator/aggregation/degreesToRadians/)
-```typescript
-$DegreesToRadians('$angle_a')
-
-// operator
-{ '$degreesToRadians': '$angle_a' }
-```
-#### $DenseRank
-```typescript
-
-
-// operator
-
-```
-#### $Derivative
-```typescript
-
-
-// operator
-
-```
-#### $Divide
-```typescript
-
-
-// operator
-
-```
-#### $DocumentNumber
-```typescript
-
-
-// operator
-
-```
-#### $Equal
-```typescript
-
-
-// operator
-
-```
-#### $Exponent
-```typescript
-
-
-// operator
-
-```
-#### $ExponentialMovingAverage
-```typescript
-
-
-// operator
-
-```
-#### $Filter
-```typescript
-
-
-// operator
-
-```
-#### $First
-```typescript
-
-
-// operator
-
-```
-#### $FirstN
-```typescript
-
-
-// operator
-
-```
-```typescript
-
-
-// operator
-
-```
-#### $Floor
-```typescript
-
-
-// operator
-
-```
-#### $Function
-```typescript
-
-
-// operator
-
-```
-#### $GetField
-```typescript
-
-
-// operator
-
-```
-#### $GreaterThan
-```typescript
-
-
-// operator
-
-```
-#### $GreaterThanEqual
-```typescript
-
-
-// operator
-
-```
-#### $Hour
-```typescript
-
-
-// operator
-
-```
-#### $IfNull
-```typescript
-
-
-// operator
-
-```
-#### $In
-```typescript
-
-
-// operator
-
-```
-#### $IndexOfArray
-```typescript
-
-
-// operator
-
-```
-#### $IndexOfBytes
-```typescript
-
-
-// operator
-
-```
-#### $IndexOfCodePoint
-```typescript
-
-
-// operator
-
-```
-#### $Integral
-```typescript
-
-
-// operator
-
-```
-#### $IsArray
-```typescript
-
-
-// operator
-
-```
-#### $IsNumber
-```typescript
-
-
-// operator
-
-```
-#### $IsoDayOfWeek
-```typescript
-
-
-// operator
-
-```
-#### $IsoWeek
-```typescript
-
-
-// operator
-
-```
-#### $IsoWeekYear
-```typescript
-
-
-// operator
-
-```
-#### $Last
-```typescript
-
-
-// operator
-
-```
-#### $LastN
-```typescript
-
-
-// operator
-
-```
-```typescript
-
-
-// operator
-
-```
-#### $LessThan
-```typescript
-
-
-// operator
-
-```
-#### $LessThanEqual
-```typescript
-
-
-// operator
-
-```
-#### $Let
-```typescript
-
-
-// operator
-
-```
-#### $Literal
-```typescript
-
-
-// operator
-
-```
-#### $Log
-```typescript
-
-
-// operator
-
-```
-#### $Log10
-```typescript
-
-
-// operator
-
-```
-#### $Ltrim
-```typescript
-
-
-// operator
-
-```
-#### $Map
-```typescript
-
-
-// operator
-
-```
-#### $Max
-```typescript
-
-
-// operator
-
-```
-#### $MergeObjects
-```typescript
-
-
-// operator
-
-```
-#### $Meta
-```typescript
-
-
-// operator
-
-```
-#### $Millisecond
-```typescript
-
-
-// operator
-
-```
-#### $Min
-```typescript
-
-
-// operator
-
-```
-#### $Minute
-```typescript
-
-
-// operator
-
-```
-#### $Mod
-```typescript
-
-
-// operator
-
-```
-#### $Month
-```typescript
-
-
-// operator
-
-```
-#### $Multiply
-```typescript
-
-
-// operator
-
-```
-#### $NaturalLog
-```typescript
-
-
-// operator
-
-```
-#### $Not
-```typescript
-
-
-// operator
-
-```
-#### $NotEqual
-```typescript
-
-
-// operator
-
-```
-#### $ObjectToArray
-```typescript
-
-
-// operator
-
-```
-#### $Or
-```typescript
-
-
-// operator
-
-```
-#### $Pow
-```typescript
-
-
-// operator
-
-```
-#### $Push
-```typescript
-
-
-// operator
-
-```
-#### $RadiansToDegrees
-```typescript
-
-
-// operator
-
-```
-#### $Rand
-```typescript
-
-
-// operator
-
-```
-#### $Range
-```typescript
-
-
-// operator
-
-```
-#### $Reduce
-```typescript
-
-
-// operator
-
-```
-#### $RegexFind
-```typescript
-
-
-// operator
-
-```
-#### $RegexFindAll
-```typescript
-
-
-// operator
-
-```
-#### $RegexMatch
-```typescript
-
-
-// operator
-
-```
-#### $ReplaceAll
-```typescript
-
-
-// operator
-
-```
-#### $ReplaceOne
-```typescript
-
-
-// operator
-
-```
-#### $ReverseArray
-```typescript
-
-
-// operator
-
-```
-#### $Round
-```typescript
-
-
-// operator
-
-```
-#### $Rtrim
-```typescript
-
-
-// operator
-
-```
-#### $SampleRate
-```typescript
-
-
-// operator
-
-```
-#### $Second
-```typescript
-
-
-// operator
-
-```
-#### $SetDifference
-```typescript
-
-
-// operator
-
-```
-#### $SetEquals
-```typescript
-
-
-// operator
-
-```
-#### $SetIntersection
-```typescript
-
-
-// operator
-
-```
-#### $SetIsSubset
-```typescript
-
-
-// operator
-
-```
-#### $SetUnion
-```typescript
-
-
-// operator
-
-```
-#### $Sin
-```typescript
-
-
-// operator
-
-```
-#### $Sinh
-```typescript
-
-
-// operator
-
-```
-#### $Size
-```typescript
-
-
-// operator
-
-```
-#### $Slice
-```typescript
-
-
-// operator
-
-```
-#### $Split
-```typescript
-
-
-// operator
-
-```
-#### $Sqrt
-```typescript
-
-
-// operator
-
-```
-#### $StdDevPop
-```typescript
-
-
-// operator
-
-```
-#### $StdDevSamp
-```typescript
-
-
-// operator
-
-```
-#### $StrCaseCmp
-```typescript
-
-
-// operator
-
-```
-#### $StrLenBytes
-```typescript
-
-
-// operator
-
-```
-#### $StrLenCP
-```typescript
-
-
-// operator
-
-```
-#### $Substr
-```typescript
-
-
-// operator
-
-```
-#### $SubstrBytes
-```typescript
-
-
-// operator
-
-```
-#### $SubstrCP
-```typescript
-
-
-// operator
-
-```
-#### $Subtract
-```typescript
-
-
-// operator
-
-```
-#### $Sum
-```typescript
-
-
-// operator
-
-```
-#### $Switch
-```typescript
-
-
-// operator
-
-```
-#### $Tan
-```typescript
-
-
-// operator
-
-```
-#### $Tanh
-```typescript
-
-
-// operator
-
-```
-#### $ToBool
-```typescript
-
-
-// operator
-
-```
-#### $ToDate
-```typescript
-
-
-// operator
-
-```
-#### $ToDecimal
-```typescript
-
-
-// operator
-
-```
-#### $ToDouble
-```typescript
-
-
-// operator
-
-```
-#### $ToInt
-```typescript
-
-
-// operator
-
-```
-#### $ToLong
-```typescript
-
-
-// operator
-
-```
-#### $ToLower
-```typescript
-
-
-// operator
-
-```
-#### $ToObjectId
-```typescript
-
-
-// operator
-
-```
-#### $ToString
-```typescript
-
-
-// operator
-
-```
-#### $ToUpper
-```typescript
-
-
-// operator
-
-```
-#### $Trim
-```typescript
-
-
-// operator
-
-```
-#### $Trunc
-```typescript
-
-
-// operator
-
-```
-#### $Type
-```typescript
-
-
-// operator
-
-```
-#### $Week
-```typescript
-
-
-// operator
-
-```
-#### $Year
-```typescript
-
-
-// operator
-
-```
-#### $Zip
-```typescript
-
-
-// operator
-
-```
+See [CHANGELOG.md](./CHANGELOG.md) for version history.
 
+---
 
+**Made with ❤️ by [Mickaël NODANCHE](https://cv-mikeonline.web.app)**