vanta-api 1.1.1 → 1.1.3

package/.gitattributes

@@ -1,2 +1,2 @@
-# Auto detect text files and perform LF normalization
-* text=auto
+# Auto detect text files and perform LF normalization
+* text=auto

package/LICENSE

@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -1,439 +1,290 @@
-
-
-# VantaApi: Advanced API Features & Security Config for MongoDB
-
-This repository provides a robust, feature-rich, and secure solution for building, customizing, and optimizing your Node.js APIs powered by MongoDB. **VantaApi** processes incoming query parameters and builds an aggregation pipeline step by step, offering powerful features such as advanced filtering, sorting, field selection, pagination, and document population with comprehensive security controls.
-
----
-
-## Table of Contents
-
-1. [Installation & Setup](#installation--setup)
-2. [Overview](#overview)
-3. [ApiFeatures Class Methods](#ApiFeatures-class-methods)
-   - [filter()](#filter)
-   - [sort()](#sort)
-   - [limitFields()](#limitfields)
-   - [paginate()](#paginate)
-   - [populate()](#populate)
-   - [addManualFilters()](#addmanualfilters)
-   - [execute()](#execute)
-4. [Input Types & Supported Operators](#input-types--supported-operators)
-5. [Additional Conditions](#additional-conditions)
-6. [Security Configuration](#security-configuration)
-7. [Security & Performance Enhancements](#security--performance-enhancements)
-8. [Error Handling Middleware](#error-handling-middleware)
-9. [Full Examples](#full-examples)
-10. [Summary](#summary)
-
----
-
-## Installation & Setup
-
-### Prerequisites
-
-- Node.js 16+
-- MongoDB 5+
-- Mongoose 7+
-
-### Install Dependencies
-
-Install core dependencies:
-
-```bash
-npm install mongoose lodash dotenv winston
-```
-
-For testing purposes, install Jest:
-
-```bash
-npm install --save-dev jest
-```
-
----
-
-## Overview
-
-The **ApiFeatures** class processes incoming query parameters and progressively builds an aggregation pipeline. The package supports:
-
-- **Advanced filtering, sorting, and field selection.**
-- **Pagination with defaults** (defaults to page 1 and limit 10 if not provided), with the maximum limit based on the user's role.
-- **Document population:** Supports joining related documents, including nested population.
-- **Automatic Conditions:** If the model includes an `isActive` field and the user is not an admin, `isActive: true` is added automatically.
-- **Input Sanitization & Validation:** Sanitizes inputs, validates numeric fields, and enforces security through a dedicated configuration.
-- **Enhanced Logging & Error Handling:** Uses winston for logging and employs a custom error class for centralized error management.
-- **Performance Improvements:** Features aggregation cursor support and optimized pipeline ordering.
-- **Error Middleware:** Provides a centralized error handling middleware for consistent API error responses.
-
----
-
-## ApiFeatures Class Methods
-
-### filter()
-- **Description:**  
-  Parses query parameters, merges them with manually added filters (if provided), and applies security filters. If the model includes an `isActive` field and the user is not "admin," it automatically adds `isActive: true`.
-- **Usage Example:**
-
-  ```javascript
-  // URL: /api/products?status=active&price[gte]=100
-  const features = new ApiFeatures(Product, req.query);
-  features.filter();
-  // Pipeline adds: { $match: { status: "active", price: { $gte: 100 }, isActive: true } }
-  ```
-
-### sort()
-- **Description:**  
-  Converts a comma-separated list of sorting fields into a `$sort` object. A "-" prefix indicates descending order.
-- **Usage Example:**
-
-  ```javascript
-  // URL: /api/products?sort=-price,createdAt
-  const features = new ApiFeatures(Product, req.query);
-  features.sort();
-  // Pipeline adds: { $sort: { price: -1, createdAt: 1 } }
-  ```
-
-### limitFields()
-- **Description:**  
-  Uses `$project` to return only the specified fields while excluding forbidden fields (such as "password").
-- **Usage Example:**
-
-  ```javascript
-  // URL: /api/products?fields=name,price,category,password
-  const features = new ApiFeatures(Product, req.query);
-  features.limitFields();
-  // Pipeline adds: { $project: { name: 1, price: 1, category: 1 } }
-  ```
-
-### paginate()
-- **Description:**  
-  Determines the page and limit values, applying pagination with defaults (page 1 and limit 10 if not provided). The maximum limit is based on the user's role as defined in the security configuration.
-- **Usage Example:**
-
-  ```javascript
-  // URL: /api/products?page=2&limit=20
-  const features = new ApiFeatures(Product, req.query, "user");
-  features.paginate();
-  // Pipeline adds: { $skip: 20 } and { $limit: 20 }
-  ```
-
-### populate()
-- **Description:**  
-  Joins related documents using `$lookup` and `$unwind`. It supports:
-  - **String Input:** A comma-separated list of field names.
-  - **Object Input:** An object with properties `path` (required) and `select` (optional).
-  - **Array Input:** An array of strings or objects for multiple or nested population.
-- **Usage Examples:**
-  - **String Input:**
-
-    ```javascript
-    // URL: /api/products?populate=category,brand
-    const features = new ApiFeatures(Product, req.query);
-    features.populate();
-    ```
-
-  - **Object Input:**
-
-    ```javascript
-    const populateOptions = { path: "category", select: "name description" };
-    const features = new ApiFeatures(Product, req.query);
-    features.populate(populateOptions);
-    ```
-
-  - **Array Input:**
-
-    ```javascript
-    const populateArray = [
-      "brand",
-      { path: "category", select: "name description" },
-      { path: "category", select: "name", populate: { path: "subCategory", select: "title" } }
-    ];
-    const features = new ApiFeatures(Product, req.query, "admin");
-    features.populate(populateArray);
-    ```
-
-### addManualFilters()
-- **Description:**  
-  Merges additional manual filters with the parsed query filters. **Note:** Call `addManualFilters()` before `filter()` to incorporate the manual filters properly.
-- **Usage Example:**
-
-  ```javascript
-  const manualFilter = { category: "electronics" };
-  const features = new ApiFeatures(Product, { status: "active" });
-  features.addManualFilters(manualFilter).filter();
-  ```
-
-### execute()
-- **Description:**  
-  Executes the built aggregation pipeline using Mongoose and returns an object containing a success flag, total document count, and result data. Supports aggregation cursor for handling large datasets.
-- **Usage Example:**
-
-  ```javascript
-  const features = new ApiFeatures(Product, req.query);
-  const result = await features
-    .filter()
-    .sort()
-    .limitFields()
-    .paginate()
-    .populate()
-    .execute();
-  console.log(result);
-  ```
-
----
-
-## Input Types & Supported Operators
-
-### Filtering Operators
-
-The class translates query parameters into MongoDB operators:
-
-| Operator | Query Example             | Description                |
-|----------|---------------------------|----------------------------|
-| eq       | `?age=25`                 | Equal to                   |
-| ne       | `?status[ne]=inactive`    | Not equal to               |
-| gt       | `?price[gt]=100`          | Greater than               |
-| gte      | `?stock[gte]=50`          | Greater than or equal to   |
-| lt       | `?weight[lt]=500`         | Less than                  |
-| lte      | `?rating[lte]=3`          | Less than or equal to      |
-| in       | `?colors[in]=red,blue`    | In the list                |
-| nin      | `?size[nin]=xl`           | Not in the list            |
-| regex    | `?name[regex]=^A`         | Regex search               |
-| exists   | `?discount[exists]=true`  | Field existence            |
-
-Additional aspects like sorting, projection, and pagination are handled via `$sort`, `$project`, `$skip`, and `$limit`.
-
----
-
-## Additional Conditions
-
-- **isActive Condition:**  
-  If the model includes an `isActive` field and the user is not an admin, `filter()` automatically adds `isActive: true`.
-- **Default Pagination:**  
-  Defaults are applied (page 1 and limit 10) when no pagination parameters are provided.
-- **Numeric Validation:**  
-  Validates that fields such as `page` and `limit` contain only numeric values.
-- **Removal of Dangerous Operators:**  
-  Operators such as `$where`, `$accumulator`, and `$function` are removed from the query.
-- **Ordering of Manual Filters:**  
-  Ensure that `addManualFilters()` is called before `filter()` so that manual filters are merged correctly.
-
----
-
-## Security Configuration
-
-Security settings enforce allowed operators, exclude forbidden fields (e.g., "password"), and apply role-based access limits:
-
-```javascript
-export const securityConfig = {
-  allowedOperators: [
-    "eq", "ne", "gt", "gte", "lt", "lte", "in", "nin", "regex", "exists", "size", "or", "and"
-  ],
-  forbiddenFields: ["password"],
-  accessLevels: {
-    guest: { maxLimit: 50, allowedPopulate: ["*"] },
-    user: { maxLimit: 100, allowedPopulate: ["*"] },
-    admin: { maxLimit: 1000, allowedPopulate: ["*"] },
-    superAdmin: { maxLimit: 1000, allowedPopulate: ["*"] }
-  }
-};
-```
-
-These configurations are applied automatically in methods such as `filter()`, `paginate()`, and `limitFields()`.
-
----
-
-## Security & Performance Enhancements
-
-- **Enhanced Logging:**  
-  Uses winston to log events and errors with detailed timestamps and stack traces.
-- **Improved Error Handling:**  
-  A custom error class (HandleERROR) coupled with dedicated error middleware centralizes error management.
-- **Dynamic Configuration:**  
-  Security settings are maintained in a separate config file (`config.js`) for easy modifications without changing core code.
-- **Performance Optimization:**  
-  Features aggregation cursor support in `execute()` and optimized pipeline ordering for resource-efficient execution.
-
----
-
-## Error Handling Middleware
-
-Vanta-API provides a centralized error handling system featuring three components:
-
-### 1. handleError
-
-**Purpose:**  
-A custom error class that extends the native JavaScript `Error`.  
-It adds:
-- **`statusCode`:** HTTP status code.
-- **`status`:** Determines if the error is a `"fail"` (client error) or `"error"` (server error).
-- **`isOperational`:** Flags if the error is an expected operational error.
-- **Stack Trace:** Captures the call stack for easier debugging.
-
-**Usage Example in an Async Function:**
-
-Inside an asynchronous function wrapped by **catchAsync**, you can use:
-
-```javascript
-// Inside your async route handler
-if (someConditionFails) {
-  return next(new handleError("Custom error message", 400));
-}
-```
-
-### 2. catchAsync
-
-**Purpose:**  
-A helper function that wraps asynchronous route handlers.  
-It automatically catches any thrown errors and forwards them via `next()`, avoiding repetitive try/catch blocks.
-
-**Usage Example:**
-
-```javascript
-app.get("/example", catchAsync(async (req, res, next) => {
-  // Your async logic here
-  // If an error occurs, use handleError as shown above
-  res.status(200).json({ data: "Success" });
-}));
-```
-
-### 3. catchError
-
-**Purpose:**  
-An Express middleware that catches any error passed along (either from synchronous or asynchronous routes).  
-It sets the appropriate HTTP status and returns a JSON response containing the error’s status and message.
-
-**Usage Example:**
-
-```javascript
-// At the end of your middleware stack:
-app.use(catchError);
-```
-
----
-
-
----
-
-## Full Examples
-
-### Example 1: Basic Query
-To import the package along with the error handling components, use:
-
-```javascript
-import ApiFeatures, { handleError, catchAsync, catchError } from "vanta-api";
-```
-
-```javascript
-import Product from "./models/product.js";
-
-// URL: /api/products?status=active&price[gte]=100&sort=-price,createdAt&fields=name,price,category&page=1&limit=10&populate=category,brand
-const features = new ApiFeatures(Product, req.query, "user");
-const result = await features
-  .filter()
-  .sort()
-  .limitFields()
-  .paginate()
-  .populate()
-  .execute();
-console.log(result);
-```
-
-### Example 2: Query with Manual Filters
-
-*(Call `addManualFilters()` before `filter()`)*
-
-```javascript
-const query = { status: "active" };
-const manualFilter = { category: "electronics" };
-const features = new ApiFeatures(Product, query, "user");
-features.addManualFilters(manualFilter).filter();
-const result = await features.execute();
-console.log(result);
-```
-
-### Example 3: Advanced Nested Populate with Array Input
-
-```javascript
-const populateArray = [
-  "brand", // Simple string input
-  { path: "category", select: "name description" },
-  { path: "category", select: "name", populate: { path: "subCategory", select: "title" } }
-];
-const features = new ApiFeatures(Product, req.query, "admin");
-const result = await features.populate(populateArray).execute();
-console.log(result);
-```
-
-### Example 4: Full Advanced Query Example
-
-```http
-GET /api/products?
-  page=1&
-  limit=10&
-  sort=-createdAt,price&
-  fields=name,price,category&
-  populate=category,brand&
-  price[gte]=1000&
-  category[in]=electronics,phones&
-  name[regex]=^Samsung
-```
-
-### Example 5: Using Default Pagination (when page and limit are not provided)
-
-```javascript
-// URL: /api/products?status=active
-const features = new ApiFeatures(Product, req.query);
-const result = await features
-  .filter() // Defaults to page 1 and limit 10
-  .execute();
-console.log(result);
-```
-
----
-
-## Summary
-
-- **Filtering:**  
-  Combines query parameters with manual filters and applies a safe `$match` with an automatic `isActive: true` condition for non-admin users.
-- **Sorting:**  
-  Converts a comma-separated string into a proper `$sort` object.
-- **Field Selection:**  
-  Uses `$project` to include only permitted fields while excluding forbidden fields.
-- **Pagination:**  
-  Applies `$skip` and `$limit` with default values (page 1, limit 10) and role-based limits.
-- **Populate:**  
-  Joins related documents using `$lookup` and `$unwind`, supporting nested and varied input types.
-- **Security:**  
-  Enforces allowed operators, sanitizes inputs, validates numeric fields, and removes dangerous operators via the security configuration.
-- **Logging & Error Handling:**  
-  Integrated advanced logging using winston and centralized error handling with a custom error class and middleware.
-- **Performance Optimizations:**  
-  Supports aggregation cursor for large datasets and optimizes aggregation pipelines for efficient resource usage.
-  
-- **ApiFeatures:**  
-  Provides advanced query capabilities such as filtering, sorting, pagination, and document population for your MongoDB data.
-
-- **Error Handling Components:**
-  - **handleError:**  
-    Throw consistent, structured errors with custom messages and status codes.
-  - **catchAsync:**  
-    Wrap asynchronous route handlers to automatically propagate errors.
-  - **catchError:**  
-    Centralized middleware to catch and respond to errors uniformly.
-
-- **Importing:**  
-  Use the following statement to access all features:
-
-  ```javascript
-  import ApiFeatures, { handleError, catchAsync, catchError } from "vanta-api";
-  ```
-
-By following these guidelines, you can integrate and use Vanta-API for advanced, secure query handling and robust error management in your Node.js/Express projects.
-
----
-
-VantaApi provides a complete solution for integrating powerful, secure, and customizable query capabilities into any Node.js/MongoDB project.
-
----
-
+# 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** 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
+
+```bash
+npm install vanta-api
+```
+
+or
+
+```bash
+yarn add vanta-api
+```
+
+Also install peer dependencies in your project:
+
+```bash
+npm install mongoose winston pluralize
+```
+
+---
+
+## 🔧 Configuration
+
+Centralize security and behavior settings in `config.js`:
+
+```js
+export const securityConfig = {
+  // Allowed filter operators
+  allowedOperators: [
+    'eq','ne','gt','gte','lt','lte','in','nin','regex','exists','size','or','and'
+  ],
+
+  // 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
+};
+```
+
+* **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
+
+```js
+import ApiFeatures, { HandleERROR, catchAsync, catchError } from 'vanta-api';
+```
+
+### 2. Express Integration
+
+```js
+import express from 'express';
+import Product from './models/product.js';
+
+const router = express.Router();
+
+router.get(
+  '/',
+  catchAsync(async (req, res) => {
+    const features = new ApiFeatures(Product, req.query, req.user.role);
+    const result = await features
+      .filter()
+      .sort()
+      .limitFields()
+      .paginate()
+      .populate()
+      .execute({ debug: req.query.debug === 'true' });
+
+    res
+      .set('X-Total-Count', result.count)
+      .status(200)
+      .json(result);
+  })
+);
+
+// Global error handler
+app.use(catchError);
+```
+
+### 3. Chaining Methods
+
+All methods (except `addManualFilters`) are chainable and return `this`.
+
+```js
+const api = new ApiFeatures(Model, req.query, 'user');
+api
+  .addManualFilters({ status: 'active' }) // optional
+  .filter()
+  .sort()
+  .limitFields()
+  .paginate()
+  .populate(['category','brand'])
+  .execute();
+```
+
+---
+
+## 📚 ApiFeatures Class Methods
+
+### `.filter()`
+
+* **Purpose**: Parse `req.query` and merge with optional manual filters, apply security filters (`forbiddenFields`, `isActive:true` for non-admin).
+* **Behavior**:
+
+  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`.
+
+### `.sort()`
+
+* **Purpose**: Generate `$sort` stage.
+* **Behavior**:
+
+  1. Split comma-separated list.
+  2. Determine direction (`-` prefix = descending).
+  3. Validate against schema paths.
+  4. Push `{ $sort: {...} }` if valid.
+* **Returns**: `this`.
+
+### `.limitFields()`
+
+* **Purpose**: Generate `$project` stage for field selection.
+* **Behavior**:
+
+  1. Split comma-separated fields.
+  2. Exclude `forbiddenFields`.
+  3. Validate against schema paths.
+  4. Push `{ $project: {...} }`.
+* **Returns**: `this`.
+
+### `.paginate()`
+
+* **Purpose**: Add `$skip` and `$limit` for pagination.
+* **Behavior**:
+
+  1. Parse `page` and `limit`, default to 1 and 10.
+  2. Enforce `maxLimit` per role.
+  3. Push `{ $skip }` and `{ $limit }`.
+* **Returns**: `this`.
+
+### `.populate(input?)`
+
+* **Purpose**: Add `$lookup`/`$unwind` stages for population.
+* **Input Types**: `string`, `{ path, select, populate? }`, `array`
+* **Behavior**:
+
+  1. Collect inputs and `req.query.populate`.
+  2. Deduplicate and enforce `allowedPopulate` per role.
+  3. For each field:
+
+     * Determine `collection` via `pluralize`.
+     * Build `$lookup` with optional `pipeline` for projections.
+     * Add `$unwind` preserving nulls.
+* **Returns**: `this`.
+
+### `.addManualFilters(filters)`
+
+* **Purpose**: Inject custom filters before calling `.filter()`.
+* **Behavior**: Merge into internal `manualFilters`.
+* **Returns**: `this`.
+
+### `.execute(options?)`
+
+* **Purpose**: Execute the aggregation pipeline and return results.
+* **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**:
+
+  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 }`.
+
+---
+
+## 🔄 Error Handling Utilities
+
+### `HandleERROR`
+
+Custom error class:
+
+```js
+throw new HandleERROR('Not Found', 404);
+```
+
+### `catchAsync(fn)`
+
+Wrap async handlers:
+
+```js
+app.get('/', catchAsync(async (req,res) => { /* ... */ }));
+```
+
+### `catchError`
+
+Express error middleware:
+
+```js
+app.use(catchError);
+```
+
+---
+
+## 🌟 Examples
+
+See the `examples/` directory for a full Express app demonstrating basic and advanced use cases.
+
+---
+
+## 🔬 Testing
+
+Unit tests powered by Jest:
+
+```bash
+npm test
+```
+
+---
+
+## 🤝 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
+
+Please follow existing code style, include tests, and update documentation if needed.
+
+---
+
+## 📜 License
+
+Licensed under the MIT License. See [LICENSE](./LICENSE) for details.

package/bin/create-security-config.js

@@ -19,7 +19,9 @@ export const securityConfig = {
     user: { maxLimit: 100, allowedPopulate: ["*"] },
     admin: { maxLimit: 1000, allowedPopulate: ["*"] },
     superAdmin: { maxLimit: 1000, allowedPopulate: ["*"] }
-  }
+  },
+  // Aggregation safeguards
+  maxPipelineStages: 20
 };
 `;
 

package/package.json

@@ -1,29 +1,30 @@
-{
-  "name": "vanta-api",
-  "version": "1.1.1",
-  "description": "Advanced API features and security configuration for Node.js/MongoDB.",
-  "main": "index.js",
-  "scripts": {
-    "postinstall": "node bin/create-security-config.js",
-    "test": "jest",
-    "start": "node index.js"
-  },
-  "keywords": [
-    "api",
-    "mongodb",
-    "mongoose",
-    "aggregation",
-    "security",
-    "nodejs"
-  ],
-  "author": "Alireza Aghaee",
-  "license": "MIT",
-  "dependencies": {
-    "mongoose": "^7.0.0",
-    "winston": "^3.0.0"
-  },
-  "devDependencies": {
-    "jest": "^29.0.0"
-  },
-  "type": "module"
-}
+{
+  "name": "vanta-api",
+  "version": "1.1.3",
+  "description": "Advanced API features and security configuration for Node.js/MongoDB.",
+  "main": "index.js",
+  "scripts": {
+    "postinstall": "node bin/create-security-config.js",
+    "test": "jest",
+    "start": "node index.js"
+  },
+  "keywords": [
+    "api",
+    "mongodb",
+    "mongoose",
+    "aggregation",
+    "security",
+    "nodejs"
+  ],
+  "author": "Alireza Aghaee",
+  "license": "MIT",
+  "dependencies": {
+    "mongoose": "^7.0.0",
+    "pluralize": "^8.0.0",
+    "winston": "^3.0.0"
+  },
+  "devDependencies": {
+    "jest": "^29.0.0"
+  },
+  "type": "module"
+}

package/src/api-features.js

@@ -1,8 +1,10 @@
 import mongoose from "mongoose";
 import winston from "winston";
-import { securityConfig } from "./config.js";
+import pluralize from "pluralize";
 import HandleERROR from "./handleError.js";
+import { securityConfig } from "./config.js";
 
+// Logger setup
 const logger = winston.createLogger({
   level: "info",
   format: winston.format.combine(
@@ -13,338 +15,218 @@ const logger = winston.createLogger({
 });
 
 export class ApiFeatures {
-  constructor(model, query, userRole = "guest") {
-    this.Model = model;
+  constructor(model, query = {}, userRole = "guest") {
+    this.model = model;
     this.query = { ...query };
     this.userRole = userRole;
+
     this.pipeline = [];
     this.countPipeline = [];
     this.manualFilters = {};
     this.useCursor = false;
-    this.#initialSanitization();
+
+    this._sanitization();
   }
 
   // ---------- Core Methods ----------
-  filter() {
-    const queryFilters = this.#parseQueryFilters();
-    const mergedFilters = { ...queryFilters, ...this.manualFilters };
-    const safeFilters = this.#applySecurityFilters(mergedFilters);
 
-    if (Object.keys(safeFilters).length > 0) {
-      this.pipeline.push({ $match: safeFilters });
-      this.countPipeline.push({ $match: safeFilters });
+  filter() {
+    // Parse and sanitize both query and manual filters
+    const queryFilters = this._parseQueryFilters();
+    const manual = this._sanitizeFilters(this.manualFilters);
+    const merged = { ...queryFilters, ...manual };
+    const safe = this._applySecurityFilters(merged);
+
+    if (Object.keys(safe).length) {
+      this.pipeline.push({ $match: safe });
+      this.countPipeline.push({ $match: safe });
     }
     return this;
   }
 
   sort() {
-    if (this.query.sort) {
-      const sortObject = this.query.sort.split(",").reduce((acc, field) => {
-        const [key, order] = field.startsWith("-")
-          ? [field.slice(1), -1]
-          : [field, 1];
-        acc[key] = order;
-        return acc;
-      }, {});
-      this.pipeline.push({ $sort: sortObject });
+    if (!this.query.sort) return this;
+    const parts = this.query.sort.split(",");
+    const validFields = Object.keys(this.model.schema.paths);
+    const sortObj = {};
+
+    for (const part of parts) {
+      const dir = part.startsWith("-") ? -1 : 1;
+      const key = part.replace(/^[-+]/, "");
+      if (validFields.includes(key)) sortObj[key] = dir;
     }
+
+    if (Object.keys(sortObj).length) this.pipeline.push({ $sort: sortObj });
     return this;
   }
 
   limitFields() {
-    if (this.query.fields) {
-      const allowedFields = this.query.fields
-        .split(",")
-        .filter((f) => !securityConfig.forbiddenFields.includes(f))
-        .reduce((acc, curr) => ({ ...acc, [curr]: 1 }), {});
+    if (!this.query.fields) return this;
+    const validFields = Object.keys(this.model.schema.paths).filter(f => !securityConfig.forbiddenFields.includes(f));
+    const project = {};
 
-      this.pipeline.push({ $project: allowedFields });
-    }
+    this.query.fields.split(",").forEach(f => {
+      if (validFields.includes(f)) project[f] = 1;
+    });
+
+    if (Object.keys(project).length) this.pipeline.push({ $project: project });
     return this;
   }
 
   paginate() {
-    const { maxLimit } = securityConfig.accessLevels[this.userRole] || {
-      maxLimit: 100,
-    };
+    const { maxLimit } = securityConfig.accessLevels[this.userRole] || { maxLimit: 100 };
     const page = Math.max(parseInt(this.query.page, 10) || 1, 1);
-    const limit = Math.min(parseInt(this.query.limit, 10) || 10, maxLimit);
+    const lim = Math.min(Math.max(parseInt(this.query.limit, 10) || 10, 1), maxLimit);
 
-    this.pipeline.push({ $skip: (page - 1) * limit }, { $limit: limit });
+    this.pipeline.push({ $skip: (page - 1) * lim }, { $limit: lim });
     return this;
   }
 
   populate(input = "") {
-    let populateOptions = [];
-
-    if (Array.isArray(input)) {
-      input.forEach((item) => {
-        if (typeof item === "object" && item.path) {
-          populateOptions.push(item);
-        } else if (typeof item === "string") {
-          populateOptions.push(item);
-        }
-      });
-    } else if (typeof input === "object" && input.path) {
-      populateOptions.push(input);
-    } else if (typeof input === "string" && input.trim().length > 0) {
-      input
-        .split(",")
-        .filter(Boolean)
-        .forEach((item) => {
-          populateOptions.push(item.trim());
-        });
-    }
+    // Build list from input and query.populate
+    let list = [];
+    const raw = Array.isArray(input) ? input : [input];
+    if (this.query.populate) raw.push(...this.query.populate.split(","));
+
+    raw.forEach(item => {
+      if (typeof item === 'string' && item.trim()) list.push(item.trim());
+      else if (item?.path) list.push(item);
+    });
 
-    if (this.query.populate) {
-      this.query.populate
-        .split(",")
-        .filter(Boolean)
-        .forEach((item) => {
-          populateOptions.push(item.trim());
-        });
-    }
+    // Deduplicate
+    const map = new Map();
+    list.forEach(opt => {
+      const key = typeof opt === 'string' ? opt : opt.path;
+      map.set(key, opt);
+    });
 
-    const uniqueMap = new Map();
-    populateOptions.forEach((item) => {
-      if (typeof item === "object" && item.path) {
-        uniqueMap.set(item.path, item);
-      } else if (typeof item === "string") {
-        uniqueMap.set(item, item);
-      }
+    // Enforce role-based populate
+    const allowed = securityConfig.accessLevels[this.userRole]?.allowedPopulate || [];
+    const final = [];
+    map.forEach((opt, key) => {
+      if (allowed.includes('*') || allowed.includes(key)) final.push(opt);
     });
-    const uniquePopulateOptions = Array.from(uniqueMap.values());
-
-    uniquePopulateOptions.forEach((option) => {
-      let field,
-        projection = {};
-      if (typeof option === "object") {
-        field = option.path;
-        if (option.select) {
-          option.select.split(" ").forEach((fieldName) => {
-            if (fieldName) projection[fieldName.trim()] = 1;
-          });
-        }
-      } else if (typeof option === "string") {
-        field = option;
-      }
 
-      field = field.trim();
-      const { collection, isArray } = this.#getCollectionInfo(field);
-
-      let lookupStage = {};
-      if (Object.keys(projection).length > 0) {
-        lookupStage = {
-          $lookup: {
-            from: collection,
-            let: { localId: `$${field}` },
-            pipeline: [
-              {
-                $match: {
-                  $expr: { $eq: ["$_id", "$$localId"] },
-                },
-              },
-              { $project: projection },
-            ],
-            as: field,
-          },
-        };
-      } else {
-        lookupStage = {
-          $lookup: {
-            from: collection,
-            localField: field,
-            foreignField: "_id",
-            as: field,
-          },
-        };
-      }
+    // Apply lookups
+    for (const opt of final) {
+      const field = typeof opt === 'string' ? opt : opt.path;
+      const proj = typeof opt === 'object' && opt.select
+        ? opt.select.split(' ').reduce((a, f) => { a[f]=1; return a; }, {})
+        : {};
 
-      this.pipeline.push(lookupStage);
-      this.pipeline.push({
-        $unwind: {
-          path: `$${field}`,
-          preserveNullAndEmptyArrays: true,
-        },
-      });
-    });
+      const { collection } = this._getCollectionInfo(field);
+      const lookup = proj && Object.keys(proj).length
+        ? { from: collection, let: { id: `$${field}` }, pipeline: [ { $match: { $expr: { $eq: ['$_id','$$id'] } } }, { $project: proj } ], as: field }
+        : { from: collection, localField: field, foreignField: '_id', as: field };
+
+      this.pipeline.push({ $lookup: lookup });
+      this.pipeline.push({ $unwind: { path: `$${field}`, preserveNullAndEmptyArrays: true } });
+    }
 
     return this;
   }
 
   addManualFilters(filters) {
-    if (filters) {
-      this.manualFilters = { ...this.manualFilters, ...filters };
-    }
+    if (filters) this.manualFilters = { ...this.manualFilters, ...filters };
     return this;
   }
 
   async execute(options = {}) {
     try {
-      if (options.useCursor === true) {
-        this.useCursor = true;
-      }
-      const [countResult, dataResult] = await Promise.all([
-        this.Model.aggregate([...this.countPipeline, { $count: "total" }]),
-        this.useCursor
-          ? this.Model.aggregate(this.pipeline)
-              .cursor({ batchSize: 100 })
-              .exec()
-          : this.Model.aggregate(this.pipeline)
-              .allowDiskUse(options.allowDiskUse || false)
-              .readConcern("majority"),
-      ]);
-
-      const count = countResult[0]?.total || 0;
-      let data = [];
-      if (this.useCursor) {
-        const cursor = dataResult;
-        for await (const doc of cursor) {
-          data.push(doc);
-        }
-      } else {
-        data = dataResult;
+      if (options.useCursor) this.useCursor = true;
+      if (options.debug) logger.info('Pipeline:', this.pipeline);
+      if (this.pipeline.length > (securityConfig.maxPipelineStages || 20)) {
+        throw new HandleERROR('Too many pipeline stages', 400);
       }
 
-      return {
-        success: true,
-        count,
-        data,
-      };
-    } catch (error) {
-      this.#handleError(error);
+     let agg = this.model.aggregate(pipeline).option({ maxTimeMS: 10000 });
+      const [cnt] = await this.model.aggregate([...this.countPipeline, { $count: 'total' }]);
+      const cursorOrData = this.useCursor
+        ? agg.cursor({ batchSize: 100 }).exec()
+        : agg.allowDiskUse(options.allowDiskUse || false).readConcern('majority');
+
+      const data = this.useCursor
+        ? await cursorOrData.toArray()
+        : await cursorOrData;
+
+      const result = { success: true, count: cnt?.total || 0, data };
+      if (options.projection) {
+        result.data = result.data.map(doc => {
+          const projDoc = {};
+          Object.keys(options.projection).forEach(f => {
+            if (options.projection[f]) projDoc[f] = doc[f];
+          });
+          return projDoc;
+        });
+      }
+      return result;
+    } catch (err) {
+      this._handleError(err);
     }
   }
 
-  // ---------- Security and Sanitization Methods ----------
-  #initialSanitization() {
-    ["$where", "$accumulator", "$function"].forEach((op) => {
+  // ---------- Private Helpers ----------
+
+  _sanitization() {
+    // Remove unsafe ops
+    ['$', '$where', '$accumulator', '$function'].forEach(op => {
       delete this.query[op];
-      delete this.manualFilters[op];
     });
-    ["page", "limit"].forEach((field) => {
-      if (this.query[field] && !/^\d+$/.test(this.query[field])) {
-        throw new HandleERROR(`Invalid value for ${field}`, 400);
+    // Validate numeric
+    ['page','limit'].forEach(f => {
+      if (this.query[f] && !/^[0-9]+$/.test(this.query[f])) {
+        throw new HandleERROR(`Invalid ${f}`,400);
       }
     });
   }
 
-  #parseQueryFilters() {
-    const queryObj = { ...this.query };
-    ["page", "limit", "sort", "fields", "populate"].forEach(
-      (el) => delete queryObj[el]
-    );
-
-    return JSON.parse(
-      JSON.stringify(queryObj).replace(
-        /\b(gte|gt|lte|lt|in|nin|eq|ne|regex|exists|size)\b/g,
-        "$$$&"
-      )
-    );
-  }
-
-  #applySecurityFilters(filters) {
-    let result = { ...filters };
-
-    securityConfig.forbiddenFields.forEach((field) => delete result[field]);
-
-    if (this.userRole !== "admin" && this.Model.schema.path("isActive")) {
-      result.isActive = true;
-      result = this.#sanitizeNestedObjects(result);
-    }
-
-    return result;
-  }
+  _parseQueryFilters() {
+    const obj = { ...this.query };
+    ['page','limit','sort','fields','populate'].forEach(k => delete obj[k]);
 
-  #sanitizeNestedObjects(obj) {
-    return Object.entries(obj).reduce((acc, [key, value]) => {
-      // Handle ObjectId fields with nested operators
-      if (
-        key.endsWith("Id") &&
-        typeof value === "object" &&
-        !Array.isArray(value)
-      ) {
-        const sanitizedObj = {};
-        for (const [op, val] of Object.entries(value)) {
-          if (
-            ["$eq", "$ne", "$gt", "$gte", "$lt", "$lte"].includes(op) &&
-            mongoose.isValidObjectId(val)
-          ) {
-            sanitizedObj[op] = new mongoose.Types.ObjectId(val);
-          } else if (["$in", "$nin"].includes(op) && Array.isArray(val)) {
-            sanitizedObj[op] = val
-              .filter((v) => mongoose.isValidObjectId(v))
-              .map((v) => new mongoose.Types.ObjectId(v));
-          } else {
-            sanitizedObj[op] = val;
-          }
-        }
-        acc[key] = sanitizedObj;
-      } else if (typeof value === "object" && !Array.isArray(value)) {
-        acc[key] = this.#sanitizeNestedObjects(value);
+    // Whitelist operators
+    const out = {};
+    for (const [k,v] of Object.entries(obj)) {
+      if (['or','and'].includes(k)) {
+        out[`$${k}`] = Array.isArray(v) ? v : [v];
       } else {
-        acc[key] = this.#sanitizeValue(key, value);
+        out[k] = typeof v === 'string' && v.includes(',')
+          ? v.split(',')
+          : v;
       }
-      return acc;
-    }, {});
-  }
-
-  #sanitizeValue(key, value) {
-    if (key.endsWith("Id") && mongoose.isValidObjectId(value)) {
-      return new mongoose.Types.ObjectId(value);
-    }
-    if (typeof value === "string") {
-      if (value === "true") return true;
-      if (value === "false") return false;
-      if (/^\d+$/.test(value)) return parseInt(value, 10);
     }
-    return value;
+    return out;
   }
 
-  #isVowel(char) {
-    return ["a", "e", "i", "o", "u"].includes(char.toLowerCase());
+  _sanitizeFilters(filters) {
+    // Simple deep clone with ObjectId and boolean parsing
+    return JSON.parse(JSON.stringify(filters), (key,val) => {
+      if (key.endsWith('Id') && mongoose.isValidObjectId(val)) return new mongoose.Types.ObjectId(val);
+      if (val === 'true') return true;
+      if (val === 'false') return false;
+      if (/^[0-9]+$/.test(val)) return parseInt(val,10);
+      return val;
+    });
   }
-  #getCollectionName(modelName) {
-    const lowerName = modelName.toLowerCase();
-    const lastChar = lowerName.slice(-1);
-    const lastTwoChars = lowerName.slice(-2);
-
-    if (lastChar === "y") {
-      const secondLastChar = lowerName.slice(-2, -1);
-      if (!this.#isVowel(secondLastChar)) {
-        return lowerName.slice(0, -1) + "ies";
-      }
-    }
 
-    if (
-      lastTwoChars === "ch" ||
-      lastTwoChars === "sh" ||
-      lastChar === "s" ||
-      lastChar === "x" ||
-      lastChar === "z"
-    ) {
-      return lowerName + "es";
+  _applySecurityFilters(filters) {
+    let res = { ...filters };
+    securityConfig.forbiddenFields.forEach(f => delete res[f]);
+    if (this.userRole !== 'admin' && this.model.schema.path('isActive')) {
+      res.isActive = true;
     }
-
-    return lowerName + "s";
+    return res;
   }
-  #getCollectionInfo(field) {
-    const schemaPath = this.Model.schema.path(field);
-    if (!schemaPath?.options?.ref) {
-      throw new HandleERROR(`Invalid populate field: ${field}`, 400);
-    }
-    return {
-      collection: this.#getCollectionName(schemaPath?.options?.ref),
-      isArray: schemaPath.instance === "Array",
-    };
+
+  _getCollectionInfo(field) {
+    const path = this.model.schema.path(field);
+    if (!path?.options?.ref) throw new HandleERROR(`Invalid populate: ${field}`,400);
+    return { collection: pluralize(path.options.ref), isArray: path.instance==='Array' };
   }
 
-  #handleError(error) {
-    // ثبت خطا در logger همراه با stack trace
-    logger.error(`[API Features Error]: ${error.message}`, {
-      stack: error.stack,
-    });
-    throw error;
+  _handleError(err) {
+    logger.error(`[ApiFeatures] ${err.message}`, { stack: err.stack });
+    throw err;
   }
 }