mongozen-1/readme.md

Type-safe, developer-friendly MongoDB aggregation pipeline builder for TypeScript, with auto-relation support and full IntelliSense. Works great with NestJS, Mongoose, or Node.js apps.

# 🧠 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

```bash
npm install mongozen
```

Or if using yarn:

```
    yarn add mongozen
```

Or if using pnpm:

```
    pnpm add mongozen
```

🧩 Usage

## Step 1: Define Your Models

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

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

## Step 2: Use the Builder

```typescript
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:

```typescript
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:

```typescript
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

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

## 🧑‍💻 Run Locally

```typescript
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