vanta-api 1.0.0

package/.gitattributes

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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AlirezaAghaee1996
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+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.

package/README.md

@@ -0,0 +1,370 @@
+
+
+# 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. [VantaApi Class Methods](#VantaApi-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 **VantaApi** 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.
+
+---
+
+## VantaApi 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 VantaApi(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 VantaApi(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 VantaApi(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 VantaApi(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 VantaApi(Product, req.query);
+    features.populate();
+    ```
+
+  - **Object Input:**
+
+    ```javascript
+    const populateOptions = { path: "category", select: "name description" };
+    const features = new VantaApi(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 VantaApi(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 VantaApi(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 VantaApi(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
+
+A dedicated error-handling middleware is available to centralize error responses:
+
+```javascript
+import catchError from "./errorHandler.js";
+
+// In your Express app:
+// app.use(catchError);
+```
+
+This middleware sets the appropriate HTTP status code and JSON error message when an error occurs.
+
+---
+
+## Full Examples
+
+### Example 1: Basic Query
+
+```javascript
+import VantaApi from "./api-features.js";
+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 VantaApi(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 VantaApi(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 VantaApi(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 VantaApi(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.
+
+---
+
+VantaApi provides a complete solution for integrating powerful, secure, and customizable query capabilities into any Node.js/MongoDB project.
+
+---

package/bin/create-security-config.js

@@ -0,0 +1,30 @@
+// bin/create-security-config.js
+import { existsSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+// Define the target path for the security-config file.
+// This example creates it in the current working directory.
+const configPath = join(process.cwd(), 'security-config.js');
+
+// If the file does not exist, create it with default content.
+if (!existsSync(configPath)) {
+  const defaultConfig = `// Default Security Configuration
+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: ["*"] }
+  }
+};
+`;
+
+  writeFileSync(configPath, defaultConfig);
+  console.log('Default security-config.js created in your project root. You can customize it as needed.');
+} else {
+  console.log('security-config.js already exists. Using custom configuration.');
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "vanta-api",
+  "version": "1.0.0",
+  "description": "Advanced API features and security configuration for Node.js/MongoDB.",
+  "main": "src/api-features.js",
+  "scripts": {
+    "postinstall": "node bin/create-security-config.js",
+    "test": "jest",
+    "start": "node src/api-features.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"
+}

package/src/api-features.js

@@ -0,0 +1,306 @@
+// api-features.js
+import mongoose from "mongoose";
+import winston from "winston";
+import { securityConfig } from "./config.js";
+import HandleERROR from "./handleError.js";
+
+// تنظیم logger با winston
+const logger = winston.createLogger({
+  level: "info",
+  format: winston.format.combine(
+    winston.format.timestamp(),
+    winston.format.json()
+  ),
+  transports: [new winston.transports.Console()]
+});
+
+export class ApiFeatures {
+  constructor(model, query, userRole = "guest") {
+    this.Model = model;
+    this.query = { ...query };
+    this.userRole = userRole;
+    this.pipeline = [];
+    this.countPipeline = [];
+    this.manualFilters = {};
+    // انتخاب استفاده از cursor برای پردازش داده‌های حجیم
+    this.useCursor = false;
+    this.#initialSanitization();
+  }
+
+  // ---------- Core Methods ----------
+  filter() {
+    const queryFilters = this.#parseQueryFilters();
+    const mergedFilters = { ...queryFilters, ...this.manualFilters };
+    const safeFilters = this.#applySecurityFilters(mergedFilters);
+
+    if (Object.keys(safeFilters).length > 0) {
+      // اضافه کردن فیلتر به ابتدای pipeline جهت بهبود عملکرد
+      this.pipeline.push({ $match: safeFilters });
+      this.countPipeline.push({ $match: safeFilters });
+    }
+    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 });
+    }
+    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 }), {});
+
+      this.pipeline.push({ $project: allowedFields });
+    }
+    return this;
+  }
+
+  paginate() {
+    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
+    );
+    
+    this.pipeline.push(
+      { $skip: (page - 1) * limit },
+      { $limit: limit }
+    );
+    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());
+      });
+    }
+  
+    if (this.query.populate) {
+      this.query.populate.split(",").filter(Boolean).forEach(item => {
+        populateOptions.push(item.trim());
+      });
+    }
+  
+    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);
+      }
+    });
+    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: { localField: `$${field}` },
+            pipeline: [
+              {
+                $match: {
+                  $expr: { $eq: ["$_id", "$$localField"] }
+                }
+              },
+              { $project: projection }
+            ],
+            as: field
+          }
+        };
+      } else {
+        lookupStage = {
+          $lookup: {
+            from: collection,
+            localField: field,
+            foreignField: "_id",
+            as: field
+          }
+        };
+      }
+  
+      this.pipeline.push(lookupStage);
+      this.pipeline.push({
+        $unwind: {
+          path: `$${field}`,
+          preserveNullAndEmptyArrays: true
+        }
+      });
+    });
+  
+    // پشتیبانی از nested populate: در صورت نیاز، منطق تو در تو را می‌توانید اینجا اضافه کنید.
+  
+    return this;
+  }
+  
+  addManualFilters(filters) {
+    if (filters) {
+      this.manualFilters = { ...this.manualFilters, ...filters };
+    }
+    return this;
+  }
+
+  async execute(options = {}) {
+    try {
+      // انتخاب حالت cursor در مواقع پردازش داده‌های حجیم
+      if (options.useCursor === true) {
+        this.useCursor = true;
+      }
+      // اجرای موازی pipeline‌های شمارش و داده
+      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;
+      }
+      
+      return {
+        success: true,
+        count,
+        data
+      };
+    } catch (error) {
+      this.#handleError(error);
+    }
+  }
+
+  // ---------- Security and Sanitization Methods ----------
+  #initialSanitization() {
+    ["$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);
+      }
+    });
+  }
+
+  #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;
+  }
+
+  #sanitizeNestedObjects(obj) {
+    return Object.entries(obj).reduce((acc, [key, value]) => {
+      if (typeof value === "object" && !Array.isArray(value)) {
+        acc[key] = this.#sanitizeNestedObjects(value);
+      } else {
+        acc[key] = this.#sanitizeValue(key, value);
+      }
+      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);
+    }
+    return value;
+  }
+
+  #getCollectionInfo(field) {
+    const schemaPath = this.Model.schema.path(field);
+    if (!schemaPath?.options?.ref) {
+      throw new HandleERROR(`Invalid populate field: ${field}`, 400);
+    }
+
+    const refModel = mongoose.model(schemaPath.options.ref);
+    if (refModel.schema.options.restricted && this.userRole !== "admin") {
+      throw new HandleERROR(`Unauthorized to populate ${field}`, 403);
+    }
+
+    return {
+      collection: refModel.collection.name,
+      isArray: schemaPath.instance === "Array"
+    };
+  }
+
+  #handleError(error) {
+    // ثبت خطا در logger همراه با stack trace
+    logger.error(`[API Features Error]: ${error.message}`, { stack: error.stack });
+    throw error;
+  }
+}
+
+export default ApiFeatures;

package/src/config.js

@@ -0,0 +1,31 @@
+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: ["*"]
+      },
+
+    }
+  };

package/src/errorHandler.js

@@ -0,0 +1,9 @@
+const catchError=(err,req,res,next)=>{
+    err.statusCode=err.statusCode || 500
+    err.status=err.status||'error'  
+    res.status(err.statusCode).json({
+        status:err.status,
+        message:err.message
+    })
+}
+export default catchError

package/src/handleError.js

@@ -0,0 +1,10 @@
+class HandleERROR extends Error{
+    constructor(message,statusCode){
+        super(message)
+        this.statusCode=statusCode
+        this.status=`${statusCode}`.startsWith('4')?'fail':'error'
+        this.isOperational=true
+        Error.captureStackTrace(this,this.constructor)
+    }
+}
+export default HandleERROR