vanta-api 1.2.0 → 1.2.1

package/README.md

@@ -1,290 +1,363 @@
-# VantaApi: Advanced MongoDB API Utilities
-
-![npm](https://img.shields.io/npm/v/vanta-api) ![license](https://img.shields.io/github/license/yourusername/vanta-api) ![downloads](https://img.shields.io/npm/dm/vanta-api)
+# VantaApi :: Advanced MongoDB API Utilities
 
 **VantaApi** is a comprehensive toolkit for building secure, performant, and flexible APIs on top of MongoDB with Mongoose. It streamlines common query operations—filtering, sorting, field selection, pagination, and population—while enforcing robust security policies and sanitization.
 
 ---
 
-## 🧩 Features Overview
-
-* **Advanced Query Parsing**: Convert HTTP query parameters into MongoDB aggregation stages.
-* **Filtering**: Support for comparison operators (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`), inclusion (`in`, `nin`), regex, existence, logical (`or`, `and`), and nested filters.
-* **Sorting**: Dynamic, multi-field sorting with ascending/descending options and schema-based validation.
-* **Field Selection**: Whitelisted projection of fields, automatic exclusion of sensitive data.
-* **Pagination**: `$skip`/`$limit` with default values, role-based maximum limits, and helpful HTTP headers.
-* **Population**: Flexible population via `$lookup` and `$unwind`, supporting string, object, array inputs, deep (nested) references, and role-based permissions.
-* **Security & Sanitization**: Whitelist operators, strip dangerous operators (`$where`, `$function`, etc.), sanitize ObjectId and date values, and enforce forbidden fields.
-* **Role-Based Access Control**: Define per-role limits on pagination, allowed populate paths, and other behaviors in a central config.
-* **Performance Safeguards**: Limit maximum pipeline stages, enforce `maxTimeMS` for aggregation, and optional aggregation cursor support for large datasets.
-* **Logging & Debugging**: Integrate with Winston for structured logs, debug flag to print built pipelines.
-* **Error Handling**: Custom error class (`HandleERROR`), `catchAsync` helper, and `catchError` middleware for uniform error responses.
-* **TypeScript-Ready**: Designed with generics and typings in mind for seamless TS integration.
-
----
-
-## 🚀 Installation
-
-### Requirements
-
-* **Node.js** 16 or higher
-* **MongoDB** 5 or higher
-* **Mongoose** 7 or higher
+## 📦 Installation
 
-### Installation
+Install via npm or Yarn:
 
 ```bash
 npm install vanta-api
-```
-
-or
-
-```bash
+# or
 yarn add vanta-api
 ```
 
-Also install peer dependencies in your project:
-
-```bash
-npm install mongoose winston pluralize
-```
+A `postinstall` hook will scaffold a `security-config.js` file in your project root.
 
 ---
 
-## 🔧 Configuration
+## ⚙️ Setup & Initialization
 
-Centralize security and behavior settings in `config.js`:
+### 1. Importing the Package
 
-```js
-export const securityConfig = {
-  // Allowed filter operators
-  allowedOperators: [
-    'eq','ne','gt','gte','lt','lte','in','nin','regex','exists','size','or','and'
-  ],
+#### ECMAScript Module (ESM)
 
-  // Fields never exposed or matched
-  forbiddenFields: ['password','__v'],
-
-  // Role-based settings
-  accessLevels: {
-    guest:      { maxLimit: 50,   allowedPopulate: ['*'] },
-    user:       { maxLimit: 100,  allowedPopulate: ['profile','orders'] },
-    admin:      { maxLimit: 1000, allowedPopulate: ['*'] },
-    superAdmin: { maxLimit: 5000, allowedPopulate: ['*'] }
-  },
-
-  // Aggregation safeguards
-  maxPipelineStages: 20
-};
+```js
+import express from 'express';
+import mongoose from 'mongoose';
+import ApiFeatures, { catchAsync, catchError, HandleERROR } from 'vanta-api';
 ```
 
-* **allowedOperators**: Only these operators pass through parsing.
-* **forbiddenFields**: Always removed from `$match` and `$project`.
-* **accessLevels**: Configure per-role `maxLimit` and `allowedPopulate` paths.
-* **maxPipelineStages**: Prevent overly complex pipelines.
-
----
-
-## 🛠️ Usage Guide
-
-### 1. Importing
+#### CommonJS (CJS)
 
 ```js
-import ApiFeatures, { HandleERROR, catchAsync, catchError } from 'vanta-api';
+const express = require('express');
+const mongoose = require('mongoose');
+const { default: ApiFeatures, catchAsync, catchError, HandleERROR } = require('vanta-api');
 ```
 
-### 2. Express Integration
+### 2. Basic Server Setup
 
 ```js
-import express from 'express';
-import Product from './models/product.js';
+const app = express();
+app.use(express.json());
+
+// Connect to MongoDB
+mongoose.connect(process.env.MONGO_URI, {
+  useNewUrlParser: true,
+  useUnifiedTopology: true
+});
+```
 
-const router = express.Router();
+### 3. Route Definition & Error Handling
 
-router.get(
-  '/',
-  catchAsync(async (req, res) => {
-    const features = new ApiFeatures(Product, req.query, req.user.role);
-    const result = await features
+```js
+// Example route with async handler
+app.get(
+  '/api/v1/items',
+  catchAsync(async (req, res, next) => {
+    const result = await new ApiFeatures(ItemModel, req.query, req.user.role)
       .filter()
       .sort()
       .limitFields()
       .paginate()
       .populate()
-      .execute({ debug: req.query.debug === 'true' });
-
-    res
-      .set('X-Total-Count', result.count)
-      .status(200)
-      .json(result);
+      .execute();
+    res.status(200).json(result);
   })
 );
 
-// Global error handler
+// Global error handler (after all routes)
 app.use(catchError);
+
+// Start server
+app.listen(3000, () => {
+  console.log('Server running on port 3000');
+});
 ```
 
-### 3. Chaining Methods
+---
 
-All methods (except `addManualFilters`) are chainable and return `this`.
+## 🔍 API Reference
 
-```js
-const api = new ApiFeatures(Model, req.query, 'user');
-api
-  .addManualFilters({ status: 'active' }) // optional
-  .filter()
-  .sort()
-  .limitFields()
-  .paginate()
-  .populate(['category','brand'])
-  .execute();
-```
+### 1. catchAsync(fn)
 
----
+Wraps an async function to catch errors and pass them to Express error middleware.
 
-## 📚 ApiFeatures Class Methods
+* **Signature:** `catchAsync(fn: Function): Function`
 
-### `.filter()`
+* **Example:**
 
-* **Purpose**: Parse `req.query` and merge with optional manual filters, apply security filters (`forbiddenFields`, `isActive:true` for non-admin).
-* **Behavior**:
+  ```js
+  app.post(
+    '/api/v1/users',
+    catchAsync(async (req, res) => {
+      // async logic
+    })
+  );
+  ```
 
-  1. Remove pagination/sort/project/populate keys.
-  2. Parse comparison operators and logical (`$or/$and`).
-  3. Sanitize values (ObjectId, boolean, number).
-  4. Apply `$match` with forbidden fields stripped.
-* **Returns**: `this`.
+### 2. catchError(err, req, res, next)
 
-### `.sort()`
+Express error-handling middleware that returns standardized JSON errors.
 
-* **Purpose**: Generate `$sort` stage.
-* **Behavior**:
+* **Response:**
 
-  1. Split comma-separated list.
-  2. Determine direction (`-` prefix = descending).
-  3. Validate against schema paths.
-  4. Push `{ $sort: {...} }` if valid.
-* **Returns**: `this`.
+  ```json
+  {
+    "status": "error" | "fail",
+    "message": "Error description",
+    "errors": [ /* optional array of details */ ]
+  }
+  ```
 
-### `.limitFields()`
+* **Usage:** Place after all routes
 
-* **Purpose**: Generate `$project` stage for field selection.
-* **Behavior**:
+### 3. HandleERROR
 
-  1. Split comma-separated fields.
-  2. Exclude `forbiddenFields`.
-  3. Validate against schema paths.
-  4. Push `{ $project: {...} }`.
-* **Returns**: `this`.
+Custom `Error` subclass for operational errors.
 
-### `.paginate()`
+* **Constructor:** `new HandleERROR(message: string, statusCode: number)`
+* **Example:**
 
-* **Purpose**: Add `$skip` and `$limit` for pagination.
-* **Behavior**:
+  ```js
+  if (!user) {
+    throw new HandleERROR('User not found', 404);
+  }
+  ```
 
-  1. Parse `page` and `limit`, default to 1 and 10.
-  2. Enforce `maxLimit` per role.
-  3. Push `{ $skip }` and `{ $limit }`.
-* **Returns**: `this`.
+---
 
-### `.populate(input?)`
+## 🚀 ApiFeatures Class
 
-* **Purpose**: Add `$lookup`/`$unwind` stages for population.
-* **Input Types**: `string`, `{ path, select, populate? }`, `array`
-* **Behavior**:
+Chainable class that translates HTTP query parameters into a secure MongoDB aggregation pipeline.
 
-  1. Collect inputs and `req.query.populate`.
-  2. Deduplicate and enforce `allowedPopulate` per role.
-  3. For each field:
+```js
+const features = new ApiFeatures(
+  Model,         // Mongoose model
+  req.query,     // HTTP query object
+  req.user.role  // User role for security (guest|user|admin|superAdmin)
+)
+  .filter()           // Filtering
+  .sort()             // Sorting
+  .limitFields()      // Field limiting
+  .paginate()         // Pagination
+  .populate()         // Population
+  .addManualFilters({ isActive: true }) // Manual filters
+;
+const result = await features.execute({ allowDiskUse: true });
+```
 
-     * Determine `collection` via `pluralize`.
-     * Build `$lookup` with optional `pipeline` for projections.
-     * Add `$unwind` preserving nulls.
-* **Returns**: `this`.
+### Constructor
 
-### `.addManualFilters(filters)`
+```ts
+new ApiFeatures(
+  model: mongoose.Model,
+  queryParams: Record<string, any> = {},
+  userRole: string = 'guest'
+)
+```
 
-* **Purpose**: Inject custom filters before calling `.filter()`.
-* **Behavior**: Merge into internal `manualFilters`.
-* **Returns**: `this`.
+* **model**: Mongoose model.
+* **queryParams**: Typically `req.query`.
+* **userRole**: Role key for security rules.
+
+### Chainable Methods
+
+| Method                   | Description                                                                                          |
+| ------------------------ | ---------------------------------------------------------------------------------------------------- |
+| `.filter()`              | Applies MongoDB operators. Supported operators:                                                      |
+|                          | `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `regex` (e.g. `?price[gt]=100&name[regex]=Book`). |
+| `.sort()`                | Sorting (e.g. `?sort=price,-name`).                                                                  |
+| `.limitFields()`         | Field selection (e.g. `?fields=name,price`).                                                         |
+| `.paginate()`            | Pagination (e.g. `?page=2&limit=10`).                                                                |
+| `.populate(paths?)`      | Populate referenced documents. Accepts various input types (see below).                              |
+| `.addManualFilters(obj)` | Add programmatic filters (e.g. `.addManualFilters({ isActive: true })`).                             |
+
+> All methods return `this` for chaining.
+
+#### Populate Input Formats
+
+The `.populate()` method supports multiple ways to specify which paths to populate:
+
+1. **String (comma-separated)**
+
+   ```js
+   .populate('author,comments')
+   ```
+2. **Array of strings**
+
+   ```js
+   .populate(['author', 'comments'])
+   ```
+3. **Dot notation for nested paths**
+
+   ```js
+   // Populating nested field 'comments.author'
+   .populate('comments.author')
+   ```
+4. **Object with options**
+
+   ```js
+   .populate({
+     path: 'author',           // field to populate
+     select: 'name email',     // include only name and email
+     match: { isActive: true}, // only active authors
+     options: { limit: 5 }     // limit populated docs
+   })
+   ```
+5. **Array of objects**
+
+   ```js
+   .populate([
+     { path: 'author', select: 'name' },
+     { path: 'comments', match: { flagged: false } }
+   ])
+   ```
 
-### `.execute(options?)`
+---
 
-* **Purpose**: Execute the aggregation pipeline and return results.
-* **Options**:
+### execute(options)
 
-  * `useCursor` (boolean): Return a cursor for streaming large sets.
-  * `allowDiskUse` (boolean): Enable disk use.
-  * `maxTimeMS` (number): Timeout for aggregation.
-  * `debug` (boolean): Log the pipeline.
-  * `projection` (object): Final projection on returned documents.
-* **Behavior**:
+Executes aggregation pipeline.
+(options)
 
-  1. Validate `maxPipelineStages`.
-  2. Optionally log pipeline.
-  3. Run `countPipeline` + `$count` to get total.
-  4. Run `pipeline` with or without cursor.
-  5. Apply `projection` to results if provided.
-* **Returns**: `{ success: true, count: number, data: array }`.
+Executes aggregation pipeline.
 
----
+* **Signature:**
 
-## 🔄 Error Handling Utilities
+  ````ts
+  async execute(options?: {
+    useCursor?: boolean;      // return cursor if true
+    allowDiskUse?: boolean;   // enable disk use
+    projection?: Record<string, any>; // manual projection map
+  }): Promise<{
+    success: boolean;
+    count: number;
+    data: any[];
+  }>```
 
-### `HandleERROR`
+  ````
+* **Example Response:**
 
-Custom error class:
+  ```json
+  {
+    "success": true,
+    "count": 50,
+    "data": [ /* documents */ ]
+  }
+  ```
 
-```js
-throw new HandleERROR('Not Found', 404);
-```
+---
 
-### `catchAsync(fn)`
+## 🔐 Security Configuration
 
-Wrap async handlers:
+Customize rules in `security-config.js` at your project root (auto-generated):
 
 ```js
-app.get('/', catchAsync(async (req,res) => { /* ... */ }));
+// security-config.js
+export const securityConfig = {
+  allowedOperators: [
+    'eq','ne','gt','gte','lt','lte','in','nin','regex'
+  ],
+  forbiddenFields: ['password','__v'],
+  accessLevels: {
+    guest: {
+      maxLimit: 20,
+      allowedPopulate: []
+    },
+    user: {
+      maxLimit: 100,
+      allowedPopulate: ['orders','profile']
+    },
+    admin: {
+      maxLimit: 1000,
+      allowedPopulate: ['*']
+    }
+  }
+};
 ```
 
-### `catchError`
+* **allowedOperators**: Operators users can use in queries.
+* **forbiddenFields**: Fields excluded from results.
+* **accessLevels**: Per-role limits and populate permissions.
+
+> If you omit `security-config.js`, defaults are applied from the package.
 
-Express error middleware:
+---
+
+## 🔍 Examples
+
+### Filter with Multiple Operators
+
+```http
+GET /api/v1/products?price[gte]=50&price[lte]=200&category[in]=["books","electronics"]
+```
+
+### Manual Filter & Projection
 
 ```js
-app.use(catchError);
+const features = new ApiFeatures(Product, req.query, 'user')
+  .addManualFilters({ isActive: true })
+  .filter()
+  .limitFields()
+  .execute({ projection: { name: 1, price: 1 } });
 ```
 
----
+### Populate Relations
 
-## 🌟 Examples
+```http
+GET /api/v1/posts?populate=author,comments
+```
 
-See the `examples/` directory for a full Express app demonstrating basic and advanced use cases.
+### Complete Controller Example
 
----
+```js
+app.get(
+  '/api/v1/orders',
+  catchAsync(async (req, res) => {
+    const result = await new ApiFeatures(Order, req.query, req.user.role)
+      .filter()
+      .sort()
+      .limitFields()
+      .paginate()
+      .populate()
+      .execute();
 
-## 🔬 Testing
+    res.json(result);
+  })
+);
+```
 
-Unit tests powered by Jest:
+---
+
+## 🧪 Testing
 
 ```bash
 npm test
 ```
 
----
+Tests use Jest. Add tests for your controllers and ApiFeatures behaviors.
 
-## 🤝 Contributing
+---
 
-1. Fork the repo
-2. Create a feature branch: `git checkout -b feature/YourFeature`
-3. Commit: `git commit -m 'Add awesome feature'`
-4. Push: `git push origin feature/YourFeature`
-5. Open a Pull Request
+## 📜 License
 
-Please follow existing code style, include tests, and update documentation if needed.
+MIT © [Alireza Aghaee](https://github.com/alirezaaghaee)
 
 ---
 
 ## 📜 License
 
-Licensed under the MIT License. See [LICENSE](./LICENSE) for details.
+MIT © 2024 Alireza Aghaee
+
+---
+
+## ✒️ Author
+
+**Alireza Aghaee**
+
+* GitHub: [AlirezaAghaee1996](https://github.com/AlirezaAghaee1996)
+* LinkedIn: [alireza-aghaee-mern-dev](https://www.linkedin.com/in/alireza-aghaee-mern-dev)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vanta-api",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Advanced API features and security configuration for Node.js/MongoDB.",
   "main": "index.js",
   "scripts": {