{"id":43169,"library":"mongodb-pipeline-builder","title":"MongoDB Pipeline Builder","description":"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.","status":"active","version":"5.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/MikeDev75015/mongodb-pipeline-builder","tags":["javascript","mongodb","mongoose","aggregate","pipeline","builder","helper","constructor","aggregation","typescript"],"install":[{"cmd":"npm install mongodb-pipeline-builder","lang":"bash","label":"npm"},{"cmd":"yarn add mongodb-pipeline-builder","lang":"bash","label":"yarn"},{"cmd":"pnpm add mongodb-pipeline-builder","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM-only. Import as named export; default export not available.","wrong":"const PipelineBuilder = require('mongodb-pipeline-builder')","symbol":"PipelineBuilder","correct":"import { PipelineBuilder } from 'mongodb-pipeline-builder'"},{"note":"Helpers are in a separate subpath export 'mongodb-pipeline-builder/helpers'.","wrong":"import { ProjectOnlyHelper } from 'mongodb-pipeline-builder'","symbol":"ProjectOnlyHelper","correct":"import { ProjectOnlyHelper } from 'mongodb-pipeline-builder/helpers'"},{"note":"Operators are in subpath export 'mongodb-pipeline-builder/operators'.","wrong":"import { $Expression } from 'mongodb-pipeline-builder'","symbol":"$Expression","correct":"import { $Expression } from 'mongodb-pipeline-builder/operators'"},{"note":"GetPagingResult is exported from the main entry point, not from a subpath.","wrong":"import { GetPagingResult } from 'mongodb-pipeline-builder/pagination'","symbol":"GetPagingResult","correct":"import { GetPagingResult } from 'mongodb-pipeline-builder'"}],"quickstart":{"code":"import { PipelineBuilder } from 'mongodb-pipeline-builder';\nimport { ProjectOnlyHelper } from 'mongodb-pipeline-builder/helpers';\nimport { $Expression, $Equal } from 'mongodb-pipeline-builder/operators';\n\nconst collection = { aggregate: (pipeline: any) => ({ toArray: () => Promise.resolve([]) }) } as any;\n\nconst pipeline = new PipelineBuilder('users-query')\n  .Match($Expression($Equal('$status', 'active')))\n  .Project(ProjectOnlyHelper('name', 'email', 'createdAt'))\n  .Sort({ createdAt: -1 })\n  .Limit(10)\n  .build();\n\nasync function main() {\n  const results = await collection.aggregate(pipeline).toArray();\n  console.log(results);\n}\nmain();","lang":"typescript","description":"Build a MongoDB aggregation pipeline with Match, Project, Sort, and Limit stages using the fluent builder, then execute it against a collection."},"warnings":[{"fix":"Always call .build() after chaining stages to obtain the array of pipeline stages.","message":"The PipelineBuilder instance must call .build() to get the pipeline array; otherwise it returns an object with methods.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use $And or $Or for combining multiple conditions, e.g., $Expression($And($Equal(...), $GreaterThan(...))).","message":"Operators like $Expression expect a single expression, not an array. Using an array will cause type errors or unexpected results.","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"Pass an optional string label or omit it entirely: `new PipelineBuilder()`.","message":"The `PipelineBuilder` constructor's first argument (label) is optional and may be removed in future versions.","severity":"deprecated","affected_versions":">=5.0.0"},{"fix":"Call `.build()` on the PipelineBuilder and pass the resulting array to Model.aggregate(pipeline).","message":"Using this library with Mongoose's `Model.aggregate()` requires passing the pipeline array (from .build()) directly; do not pass the builder instance.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'5.0.1':17 'aggreg':14,21,65,78,83 'automat':50 'builder':3,80 'command':33 'common':44 'compar':62 'construct':12 'constructor':82 'databas':32 'design':40 'driver':30 'error':74 'fluent':8 'full':56 'generic':58 'helper':42,81 'improv':68 'javascript':75 'librari':10 'like':46 'maintain':71 'modular':39 'mongodb':1,13,20,29,31,76 'mongoos':35,77 'nativ':28 'oper':24,45 'pagin':47 'pipelin':2,15,53,66,79 'project':49 'provid':37 'raw':64 'readabl':69 'reduc':73 'respons':61 'safe':7 'stage':22,54 'support':18 'type':6,60 'type-saf':5 'typescript':9,57,84 'valid':51 'version':16 'work':25","created_at":"2026-06-05T16:58:30.967315+00:00","updated_at":"2026-06-05T16:58:30.967315+00:00","problems":[{"fix":"Ensure you call .Match() on the PipelineBuilder object before calling .build().","cause":"Attempting to chain .Match() on the result of .build() (which returns an array) instead of on the PipelineBuilder instance.","error":"TypeError: pipeline.Match is not a function"},{"fix":"Update to version 5.0.1 or later, and ensure your bundler/resolver supports package.json exports (Node >=12.7, webpack >=5, etc.).","cause":"Using an older version (pre-5.0) that didn't have subpath exports, or the package manager doesn't support exports field.","error":"Module not found: Can't resolve 'mongodb-pipeline-builder/helpers'"},{"fix":"Use the provided helper like `ProjectOnlyHelper(...)` or a PipelineBuilder instance for .Project().","cause":"Passing a plain object instead of a helper method (e.g., ProjectOnlyHelper) to stages like .Project().","error":"Argument of type '{}' is not assignable to parameter of type 'StageBuilder'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://mikedev75015.github.io","github":"https://github.com/MikeDev75015/mongodb-pipeline-builder","docs":null,"changelog":null,"pypi":null,"npm":"mongodb-pipeline-builder","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}