mongozen

🧠 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

interface User {
  id: number;
  name: string;
}

interface Post {
  id: number;
  title: string;
  userId: number;
}

Step 2: Use the Builder

import { AggregationBuilder, AutoRelations } from 'mongozen';

type Models = { post: Post; user: User };

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

const builder = new AggregationBuilder<Models, 'post', typeof relations>(relations);

const pipeline = 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:

await PostModel.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:

const relations: 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

git clone https://github.com/webcoderspeed/mongozen.git
cd mongozen
npm install

🧑‍💻 Run Locally

npm run dev

📢 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