🧠 mongozen

A type-safe, intuitive, and developer-friendly MongoDB Aggregation Pipeline Builder for TypeScript.
Designed to work seamlessly with frameworks like NestJS, Express, or any Node.js app.

---

🚀 Features

• ✅ Fully type-safe aggregation builder
• ✅ Auto-detect relations from model schema using generics
• ✅ Only valid $lookup options suggested via IntelliSense
• ✅ Supports over 20+ MongoDB stages
• ✅ Built-in support for NestJS & Mongoose
• ✅ No any used internally — 100% strict TypeScript
• ✅ Modular, composable, extensible
• ✅ CLI/Web UI export support coming soon

---

📦 Installation

npm install mongozen

Or if using yarn:

 yarn add mongozen

Or if using pnpm:

 pnpm add mongozen

🧩 Usage

Step 1: Define Your Models

interfaceUser{id: number;name: string;}interfacePost{id: number;title: string;userId: number;}

Step 2: Use the Builder

import{AggregationBuilder,AutoRelations}from'mongozen';typeModels={post: Post;user: User};constrelations: AutoRelations<Models>={post: ['user'],user: [],};constbuilder=newAggregationBuilder<Models,'post',typeofrelations>(relations);constpipeline=builder.match({title: {$exists: true}}).lookup({from: 'user',localField: 'userId',foreignField: 'id',as: 'userInfo',}).project({title: 1,userInfo: 1}).sort({title: 1}).build();

Now you can use this pipeline in Mongoose, MongoClient, or any MongoDB driver:

awaitPostModel.aggregate(pipeline).exec();

🛠 Supported Stages

• $match, $sort, $project, $limit, $skip, $count
• $lookup (with relation validation)
• $group, $unwind, $set, $unset, $addFields
• $replaceRoot, $replaceWith
• $unionWith, $out, $merge
• $facet

More advanced stages like $graphLookup, $setWindowFields coming soon.

📐 AutoRelations

You don’t need to manually write relationships. Use AutoRelations:

constrelations: AutoRelations<Models>={post: ['user'],user: [],};

It automatically checks for userId, postId etc. and maps them to available models.

🌐 Roadmap

• CLI Support (mongozen build query.ts --out pipeline.json)
• Web UI (drag & drop stages, export pipeline)
• VSCode Extension
• Prisma adapter / Mongoose schema reader
• More custom DSLs (like fromQuery())

👥 Contributing

We welcome all contributions, big or small!

🛠 Setup

gitclone https://github.com/webcoderspeed/mongozen.gitcdmongozennpminstall

🧑‍💻 Run Locally

npmrundev

📢 Open PRs

• Make sure everything passes tsc --noEmit
• Include proper test cases
• Describe your feature clearly in PR title + body

💡 Inspiration

This project was born out of frustration from untyped, verbose, and unsafe aggregation queries. We wanted an elegant and IntelliSense-powered DSL to write complex queries faster — hence, mongozen.

🧑 Author

Made with 💚 by @webcoderspeed

📄 License

MIT License © 2025