Registry / database / mongodb-pipeline-builder

mongodb-pipeline-builder

library5.0.1jsnpmunverified

A type-safe, fluent TypeScript library for constructing MongoDB aggregation pipelines. Version 5.0.1 supports all MongoDB aggregation stages and operators, works with the native MongoDB driver, MongoDB Database Commands, and Mongoose. It provides a modular design with helpers for common operations like pagination and projection, automatic validation of pipeline stages, and full TypeScript generics for typed responses. Compared to raw aggregation pipelines, it improves readability and maintainability while reducing errors.

database

npm install mongodb-pipeline-builder

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGODB-PIPELINE-B

mongodb-pipeline-builder

databasejavascriptv5.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PipelineBuilder

✓ import { PipelineBuilder } from 'mongodb-pipeline-builder'

✗ const PipelineBuilder = require('mongodb-pipeline-builder')

ESM-only. Import as named export; default export not available.

ProjectOnlyHelper

✓ import { ProjectOnlyHelper } from 'mongodb-pipeline-builder/helpers'

✗ import { ProjectOnlyHelper } from 'mongodb-pipeline-builder'

Helpers are in a separate subpath export 'mongodb-pipeline-builder/helpers'.

$Expression

✓ import { $Expression } from 'mongodb-pipeline-builder/operators'

✗ import { $Expression } from 'mongodb-pipeline-builder'

Operators are in subpath export 'mongodb-pipeline-builder/operators'.

GetPagingResult

✓ import { GetPagingResult } from 'mongodb-pipeline-builder'

✗ import { GetPagingResult } from 'mongodb-pipeline-builder/pagination'

GetPagingResult is exported from the main entry point, not from a subpath.

Build a MongoDB aggregation pipeline with Match, Project, Sort, and Limit stages using the fluent builder, then execute it against a collection.

import { PipelineBuilder } from 'mongodb-pipeline-builder'; import { ProjectOnlyHelper } from 'mongodb-pipeline-builder/helpers'; import { $Expression, $Equal } from 'mongodb-pipeline-builder/operators'; const collection = { aggregate: (pipeline: any) => ({ toArray: () => Promise.resolve([]) }) } as any; const pipeline = new PipelineBuilder('users-query') .Match($Expression($Equal('$status', 'active'))) .Project(ProjectOnlyHelper('name', 'email', 'createdAt')) .Sort({ createdAt: -1 }) .Limit(10) .build(); async function main() { const results = await collection.aggregate(pipeline).toArray(); console.log(results); } main();

Debug

Known issues

gotchaThe PipelineBuilder instance must call .build() to get the pipeline array; otherwise it returns an object with methods.

fix

Always call .build() after chaining stages to obtain the array of pipeline stages.

affects: >=1.0.0

gotchaOperators like $Expression expect a single expression, not an array. Using an array will cause type errors or unexpected results.

fix

Use $And or $Or for combining multiple conditions, e.g., $Expression($And($Equal(...), $GreaterThan(...))).

affects: >=5.0.0

deprecatedThe `PipelineBuilder` constructor's first argument (label) is optional and may be removed in future versions.

fix

Pass an optional string label or omit it entirely: `new PipelineBuilder()`.

affects: >=5.0.0

gotchaUsing this library with Mongoose's `Model.aggregate()` requires passing the pipeline array (from .build()) directly; do not pass the builder instance.

fix

Call `.build()` on the PipelineBuilder and pass the resulting array to Model.aggregate(pipeline).

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: pipeline.Match is not a function

Attempting to chain .Match() on the result of .build() (which returns an array) instead of on the PipelineBuilder instance.

fix

Ensure you call .Match() on the PipelineBuilder object before calling .build().

Module not found: Can't resolve 'mongodb-pipeline-builder/helpers'

Using an older version (pre-5.0) that didn't have subpath exports, or the package manager doesn't support exports field.

fix

Update to version 5.0.1 or later, and ensure your bundler/resolver supports package.json exports (Node >=12.7, webpack >=5, etc.).

Argument of type '{}' is not assignable to parameter of type 'StageBuilder'

Passing a plain object instead of a helper method (e.g., ProjectOnlyHelper) to stages like .Project().

fix

Use the provided helper like `ProjectOnlyHelper(...)` or a PipelineBuilder instance for .Project().

Upgrade

Version history

5.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/MikeDev75015/mongodb-pipeline-builder ↗

packagemongodb-pipeline-builder ↗

homepagehttps://mikedev75015.github.io ↗