vanta-api 1.3.1 → 1.4.0

package/README.md

@@ -1,363 +1,1129 @@
-# VantaApi :: Advanced MongoDB API Utilities
+# 🚀 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.
+**Vanta API** is a lightweight, reusable API utility toolkit for **Express.js** and **Mongoose** applications.
+
+It helps you build clean, secure, and production-friendly API endpoints with advanced filtering, search, sorting, pagination, populate, centralized error handling, and async route handling.
 
 ---
 
-## 📦 Installation
+## ✨ Features
+
+- Advanced query filtering
+- Manual server-side filters
+- Recursive `$and`, `$or`, `$nor` filter support
+- Automatic `ObjectId` conversion
+- Search using `q`
+- Case-insensitive regex search
+- Sorting
+- Field limiting / projection
+- Pagination
+- Aggregation-based populate
+- Nested populate support
+- Role-based security limits
+- Forbidden field protection
+- Async route wrapper
+- Centralized Express error handler
+- Custom operational error class
 
-Install via npm or Yarn:
+---
+
+## 📦 Installation
 
 ```bash
 npm install vanta-api
-# or
-yarn add vanta-api
 ```
 
-A `postinstall` hook will scaffold a `security-config.js` file in your project root.
+Required dependencies in your app:
+
+```bash
+npm install express mongoose
+```
 
 ---
 
-## ⚙️ Setup & Initialization
+## 📁 Project Files
+
+```txt
+src/
+  api-features.js
+  catchAsync.js
+  config.js
+  errorHandler.js
+  handleError.js
+  security-default-config.js
+```
 
-### 1. Importing the Package
+| File | Purpose |
+|---|---|
+| `api-features.js` | Main API query builder for filtering, search, sorting, pagination, populate, and execution |
+| `catchAsync.js` | Wraps async Express route handlers and forwards errors to `next()` |
+| `errorHandler.js` | Global Express error middleware |
+| `handleError.js` | Custom operational error class |
+| `config.js` | Loads and merges security configuration |
+| `security-default-config.js` | Default security rules and role-based limits |
 
-#### ECMAScript Module (ESM)
+---
+
+# 🇬🇧 English Documentation
+
+## Quick Start
 
 ```js
-import express from 'express';
-import mongoose from 'mongoose';
-import ApiFeatures, { catchAsync, catchError, HandleERROR } from 'vanta-api';
+import ApiFeatures,{catchAsync,catchError,HandleERROR} from "vanta-api";
+
 ```
 
-#### CommonJS (CJS)
+Example controller:
 
 ```js
-const express = require('express');
-const mongoose = require('mongoose');
-const { default: ApiFeatures, catchAsync, catchError, HandleERROR } = require('vanta-api');
+export const getProducts = catchAsync(async (req, res, next) => {
+  const result = await new ApiFeatures(Product, req.query, req.user?.role)
+    .filter()
+    .search(["name", "description"])
+    .sort()
+    .limitFields()
+    .paginate()
+    .execute();
+
+  res.status(200).json(result);
+});
 ```
 
-### 2. Basic Server Setup
+---
 
-```js
-const app = express();
-app.use(express.json());
+# ApiFeatures
 
-// Connect to MongoDB
-mongoose.connect(process.env.MONGO_URI, {
-  useNewUrlParser: true,
-  useUnifiedTopology: true
-});
+`ApiFeatures` is the main class of this package. It converts request query parameters and manual backend filters into a MongoDB aggregation pipeline.
+
+## Constructor
+
+```js
+new ApiFeatures(model, query, userRole)
 ```
 
-### 3. Route Definition & Error Handling
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `model` | Mongoose Model | Yes | The Mongoose model used to run aggregation |
+| `query` | Object | No | Usually `req.query` |
+| `userRole` | String | No | Role name used for security rules |
+
+Example:
 
 ```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();
-    res.status(200).json(result);
-  })
-);
+const features = new ApiFeatures(Product, req.query, req.user?.role);
+```
 
-// Global error handler (after all routes)
-app.use(catchError);
+If `userRole` is missing or invalid, the default role is `guest`.
 
-// Start server
-app.listen(3000, () => {
-  console.log('Server running on port 3000');
-});
+---
+
+## Recommended Chain Order
+
+```js
+const result = await new ApiFeatures(Model, req.query, req.user?.role)
+  .addManualFilters(serverSideFilters)
+  .filter()
+  .populate(populateOptions)
+  .search(["name", "description"])
+  .sort()
+  .limitFields()
+  .paginate()
+  .execute();
 ```
 
+Why this order?
+
+1. `addManualFilters()` adds backend-controlled filters.
+2. `filter()` creates the base `$match`.
+3. `populate()` joins referenced documents.
+4. `search()` searches normal or populated fields.
+5. `sort()` sorts final results.
+6. `limitFields()` controls output fields.
+7. `paginate()` applies paging.
+8. `execute()` runs the aggregation.
+
 ---
 
-## 🔍 API Reference
+## `filter()`
 
-### 1. catchAsync(fn)
+Builds a MongoDB `$match` stage from `req.query`.
+
+```js
+new ApiFeatures(Product, req.query)
+  .filter()
+  .execute();
+```
 
-Wraps an async function to catch errors and pass them to Express error middleware.
+### Simple Filter
 
-* **Signature:** `catchAsync(fn: Function): Function`
+```txt
+GET /api/products?category=phone
+```
 
-* **Example:**
+Generated filter:
 
-  ```js
-  app.post(
-    '/api/v1/users',
-    catchAsync(async (req, res) => {
-      // async logic
-    })
-  );
-  ```
+```js
+{
+  category: "phone"
+}
+```
 
-### 2. catchError(err, req, res, next)
+### Comparison Operators
 
-Express error-handling middleware that returns standardized JSON errors.
+```txt
+GET /api/products?price[gte]=100&price[lte]=500
+```
 
-* **Response:**
+Generated filter:
 
-  ```json
-  {
-    "status": "error" | "fail",
-    "message": "Error description",
-    "errors": [ /* optional array of details */ ]
+```js
+{
+  price: {
+    $gte: 100,
+    $lte: 500
   }
-  ```
+}
+```
 
-* **Usage:** Place after all routes
+### Boolean / Null / Number Conversion
 
-### 3. HandleERROR
+```txt
+GET /api/products?isActive=true&deletedAt=null&price=100
+```
 
-Custom `Error` subclass for operational errors.
+Generated values:
 
-* **Constructor:** `new HandleERROR(message: string, statusCode: number)`
-* **Example:**
+```js
+{
+  isActive: true,
+  deletedAt: null,
+  price: 100
+}
+```
 
-  ```js
-  if (!user) {
-    throw new HandleERROR('User not found', 404);
-  }
-  ```
+Strings with leading zero are preserved:
+
+```txt
+GET /api/users?code=0012
+```
+
+```js
+{
+  code: "0012"
+}
+```
+
+### ObjectId Conversion
+
+Fields like `_id`, `id`, and fields ending with `id` are converted to `ObjectId` when the value is a strict MongoDB ObjectId.
+
+```txt
+GET /api/products?_id=665f0f6f4e7d9a2e2c123456
+```
+
+```js
+{
+  _id: ObjectId("665f0f6f4e7d9a2e2c123456")
+}
+```
+
+Reserved query keys are excluded from normal filtering:
+
+```js
+["page", "limit", "sort", "fields", "populate", "q"]
+```
+
+---
+
+## `addManualFilters(filters)`
+
+Adds backend-controlled filters manually. This is useful when you want to enforce conditions that users should not control from the URL.
+
+```js
+new ApiFeatures(Order, req.query)
+  .addManualFilters({ user: req.user._id })
+  .filter()
+  .execute();
+```
+
+### `$and` Example
+
+```js
+const result = await new ApiFeatures(Product, req.query)
+  .addManualFilters({
+    $and: [
+      { _id: "665f0f6f4e7d9a2e2c123456" },
+      { isActive: true }
+    ]
+  })
+  .filter()
+  .execute();
+```
+
+The `_id` inside `$and` is recursively converted to `ObjectId`.
+
+### `$or` Example
+
+```js
+const result = await new ApiFeatures(Product, req.query)
+  .addManualFilters({
+    $or: [
+      { ownerId: "665f0f6f4e7d9a2e2c123456" },
+      { createdById: "665f0f6f4e7d9a2e2c654321" }
+    ]
+  })
+  .filter()
+  .execute();
+```
+
+### `$nor` Example
+
+```js
+const result = await new ApiFeatures(Product, req.query)
+  .addManualFilters({
+    $nor: [
+      { status: "blocked" },
+      { isDeleted: true }
+    ]
+  })
+  .filter()
+  .execute();
+```
+
+### `$in` Example
+
+```js
+const result = await new ApiFeatures(Product, req.query)
+  .addManualFilters({
+    _id: {
+      $in: [
+        "665f0f6f4e7d9a2e2c123456",
+        "665f0f6f4e7d9a2e2c654321"
+      ]
+    }
+  })
+  .filter()
+  .execute();
+```
+
+---
+
+## `search(fields)`
+
+Searches using the `q` key from `req.query`. It always uses case-insensitive regex search.
+
+```js
+.search(["name", "description"])
+```
+
+```txt
+GET /api/products?q=iphone
+```
+
+```js
+const result = await new ApiFeatures(Product, req.query)
+  .filter()
+  .search(["name", "description", "brand"])
+  .paginate()
+  .execute();
+```
+
+Generated condition:
+
+```js
+{
+  $or: [
+    { name: { $regex: "iphone", $options: "i" } },
+    { description: { $regex: "iphone", $options: "i" } },
+    { brand: { $regex: "iphone", $options: "i" } }
+  ]
+}
+```
+
+`q` is reserved and is not treated as a normal filter.
+
+---
+
+## `sort()`
+
+Sorts results using the `sort` query key.
+
+```txt
+GET /api/products?sort=-createdAt,price
+```
+
+```js
+{
+  createdAt: -1,
+  price: 1
+}
+```
+
+Only fields existing in the model schema are accepted.
 
 ---
 
-## 🚀 ApiFeatures Class
+## `limitFields(input)`
+
+Controls returned fields using projection.
 
-Chainable class that translates HTTP query parameters into a secure MongoDB aggregation pipeline.
+```txt
+GET /api/products?fields=name,price,category
+```
+
+or:
 
 ```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 });
+.limitFields("name,price")
 ```
 
-### Constructor
+Include mode:
 
-```ts
-new ApiFeatures(
-  model: mongoose.Model,
-  queryParams: Record<string, any> = {},
-  userRole: string = 'guest'
-)
+```js
+{ name: 1, price: 1 }
 ```
 
-* **model**: Mongoose model.
-* **queryParams**: Typically `req.query`.
-* **userRole**: Role key for security rules.
+Exclude mode:
+
+```txt
+GET /api/products?fields=-description
+```
+
+```js
+{ description: 0 }
+```
 
-### Chainable Methods
+Mixed include/exclude is not allowed:
 
-| 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 })`).                             |
+```txt
+GET /api/products?fields=name,-password
+```
 
-> All methods return `this` for chaining.
+Throws:
 
-#### Populate Input Formats
+```txt
+Cannot mix include and exclude fields
+```
 
-The `.populate()` method supports multiple ways to specify which paths to populate:
+---
 
-1. **String (comma-separated)**
+## `paginate()`
 
-   ```js
-   .populate('author,comments')
-   ```
-2. **Array of strings**
+Adds `$skip` and `$limit`.
 
-   ```js
-   .populate(['author', 'comments'])
-   ```
-3. **Dot notation for nested paths**
+```txt
+GET /api/products?page=2&limit=10
+```
 
-   ```js
-   // Populating nested field 'comments.author'
-   .populate('comments.author')
-   ```
-4. **Object with options**
+Pipeline:
 
-   ```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
+[
+  { $skip: 10 },
+  { $limit: 10 }
+]
+```
 
-   ```js
-   .populate([
-     { path: 'author', select: 'name' },
-     { path: 'comments', match: { flagged: false } }
-   ])
-   ```
+Limits are capped by role.
 
 ---
 
-### execute(options)
+## `populate(input)`
+
+Performs aggregation-based populate using `$lookup`.
+
+```js
+.populate("user")
+```
+
+From query:
+
+```txt
+GET /api/posts?populate=user
+```
 
-Executes aggregation pipeline.
-(options)
+Multiple populate paths:
 
-Executes aggregation pipeline.
+```js
+.populate(["user", "category"])
+```
 
-* **Signature:**
+Nested populate:
 
-  ````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[];
-  }>```
-
-  ````
-* **Example Response:**
-
-  ```json
-  {
-    "success": true,
-    "count": 50,
-    "data": [ /* documents */ ]
+```js
+.populate({
+  path: "user",
+  populate: {
+    path: "company",
+    populate: {
+      path: "country"
+    }
   }
-  ```
+})
+```
+
+Dot notation:
+
+```js
+.populate("user.company.country")
+```
+
+Populate with select:
+
+```js
+.populate({
+  path: "user",
+  select: "name email"
+})
+```
+
+Exclude fields:
+
+```js
+.populate({
+  path: "user",
+  select: "-password"
+})
+```
+
+Mixed include/exclude is not allowed.
+
+---
+
+## `execute(options)`
+
+Runs the aggregation pipeline.
+
+```js
+const result = await features.execute();
+```
+
+Returns:
+
+```js
+{
+  success: true,
+  count: 25,
+  data: [...]
+}
+```
+
+Options:
+
+```js
+.execute({
+  debug: true,
+  useCursor: false,
+  batchSize: 100,
+  maxTimeMS: 10000,
+  allowDiskUse: true,
+  readConcern: "majority"
+})
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `debug` | Boolean | `false` | Logs the pipeline |
+| `useCursor` | Boolean | `false` | Uses aggregation cursor |
+| `batchSize` | Number | `100` | Cursor batch size |
+| `maxTimeMS` | Number | `10000` | Max execution time |
+| `allowDiskUse` | Boolean | `false` | Allows disk usage |
+| `readConcern` | String | `majority` | MongoDB read concern |
+
+---
+
+# Full Controller Example
+
+```js
+import ApiFeatures,{catchAsync} from "vanta-api";
+import Product from "../models/productModel.js";
+
+export const getProducts = catchAsync(async (req, res, next) => {
+  const result = await new ApiFeatures(Product, req.query, req.user?.role)
+    .addManualFilters({ isDeleted: false })
+    .filter()
+    .populate([
+      {
+        path: "category",
+        select: "name slug"
+      },
+      {
+        path: "createdBy",
+        select: "name email"
+      }
+    ])
+    .search(["name", "description", "category.name"])
+    .sort()
+    .limitFields()
+    .paginate()
+    .execute();
+
+  res.status(200).json(result);
+});
+```
+
+---
+
+# Error Handling
+
+## `HandleERROR`
+
+Custom operational error class.
+
+```js
+import {HandleERROR} from "vanta-api";
+
+throw new HandleERROR("Product not found", 404);
+```
+
+Example properties:
+
+```js
+{
+  message: "Product not found",
+  statusCode: 404,
+  status: "fail",
+  isOperational: true
+}
+```
+
+For `4xx` errors, `status` is `fail`. For `5xx` errors, `status` is `error`.
+
+## `catchAsync`
+
+Wraps async Express handlers and removes repetitive `try/catch`.
+
+```js
+import {catchAsync} from "vanta-api";
+
+app.get(
+  "/products",
+  catchAsync(async (req, res, next) => {
+    const products = await Product.find();
+    res.json(products);
+  })
+);
+```
+
+Any rejected promise is forwarded to Express `next()`.
+
+## `errorHandler`
+
+Global Express error middleware.
+
+```js
+import {catchError} from "vanta-api";
+
+app.use(catchError);
+```
+
+Example response:
+
+```json
+{
+  "status": "fail",
+  "success": false,
+  "message": "Product not found"
+}
+```
+
+Use it after all routes:
+
+```js
+app.use("/api/products", productRouter);
+app.use(catchError);
+```
 
 ---
 
-## 🔐 Security Configuration
+# Security Configuration
+
+Default security settings are stored in:
+
+```txt
+src/security-default-config.js
+```
 
-Customize rules in `security-config.js` at your project root (auto-generated):
+You can override them by creating a `security-config.js` file in your project root.
 
 ```js
-// security-config.js
 export const securityConfig = {
   allowedOperators: [
-    'eq','ne','gt','gte','lt','lte','in','nin','regex'
+    "eq",
+    "ne",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "in",
+    "nin",
+    "regex",
+    "exists"
   ],
-  forbiddenFields: ['password','__v'],
+
+  forbiddenFields: ["password", "refreshToken", "resetPasswordToken"],
+
+  maxPipelineStages: 50,
+
   accessLevels: {
     guest: {
       maxLimit: 20,
-      allowedPopulate: []
+      allowedPopulate: ["category"]
     },
     user: {
       maxLimit: 100,
-      allowedPopulate: ['orders','profile']
+      allowedPopulate: ["category", "createdBy"]
     },
     admin: {
       maxLimit: 1000,
-      allowedPopulate: ['*']
+      allowedPopulate: ["*"]
     }
   }
 };
 ```
 
-* **allowedOperators**: Operators users can use in queries.
-* **forbiddenFields**: Fields excluded from results.
-* **accessLevels**: Per-role limits and populate permissions.
+---
+
+# Express Setup Example
+
+```js
+import express from "express";
+import {catchError} from "vanta-api";
+import productRouter from "./routes/productRoutes.js";
+
+const app = express();
+
+app.use(express.json());
+app.use("/api/products", productRouter);
+app.use(catchError);
+
+export default app;
+```
+
+---
+
+# 🇮🇷 مستندات فارسی
+
+## شروع سریع
+
+```js
+import ApiFeatures,{catchAsync,catchError,HandleERROR} from "vanta-api";
+
+```
+
+مثال controller:
 
-> If you omit `security-config.js`, defaults are applied from the package.
+```js
+export const getProducts = catchAsync(async (req, res, next) => {
+  const result = await new ApiFeatures(Product, req.query, req.user?.role)
+    .filter()
+    .search(["name", "description"])
+    .sort()
+    .limitFields()
+    .paginate()
+    .execute();
+
+  res.status(200).json(result);
+});
+```
 
 ---
 
-## 🔍 Examples
+# ApiFeatures چیست؟
+
+`ApiFeatures` کلاس اصلی پکیج است. این کلاس از روی `req.query` و فیلترهای دستی سمت سرور، یک MongoDB aggregation pipeline می‌سازد.
 
-### Filter with Multiple Operators
+## Constructor
 
-```http
-GET /api/v1/products?price[gte]=50&price[lte]=200&category[in]=["books","electronics"]
+```js
+new ApiFeatures(model, query, userRole)
 ```
 
-### Manual Filter & Projection
+| ورودی | نوع | اجباری | توضیح |
+|---|---|---|---|
+| `model` | Mongoose Model | بله | مدلی که aggregation روی آن اجرا می‌شود |
+| `query` | Object | خیر | معمولاً همان `req.query` |
+| `userRole` | String | خیر | نقش کاربر برای قوانین امنیتی |
+
+اگر `userRole` داده نشود یا معتبر نباشد، role پیش‌فرض `guest` استفاده می‌شود.
+
+---
+
+## ترتیب پیشنهادی استفاده
 
 ```js
-const features = new ApiFeatures(Product, req.query, 'user')
-  .addManualFilters({ isActive: true })
+const result = await new ApiFeatures(Model, req.query, req.user?.role)
+  .addManualFilters(serverSideFilters)
   .filter()
+  .populate(populateOptions)
+  .search(["name", "description"])
+  .sort()
   .limitFields()
-  .execute({ projection: { name: 1, price: 1 } });
+  .paginate()
+  .execute();
 ```
 
-### Populate Relations
+---
+
+## `filter()`
 
-```http
-GET /api/v1/posts?populate=author,comments
+از روی `req.query` مرحله‌ی `$match` می‌سازد.
+
+```txt
+GET /api/products?category=phone
+```
+
+```js
+{
+  category: "phone"
+}
 ```
 
-### Complete Controller Example
+operatorهای مقایسه‌ای:
+
+```txt
+GET /api/products?price[gte]=100&price[lte]=500
+```
 
 ```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();
-
-    res.json(result);
+{
+  price: {
+    $gte: 100,
+    $lte: 500
+  }
+}
+```
+
+تبدیل‌های خودکار:
+
+```txt
+GET /api/products?isActive=true&deletedAt=null&price=100
+```
+
+```js
+{
+  isActive: true,
+  deletedAt: null,
+  price: 100
+}
+```
+
+کلیدهایی مثل `_id`, `id` و کلیدهایی که به `id` ختم می‌شوند، اگر مقدارشان ObjectId معتبر باشد، به `ObjectId` تبدیل می‌شوند.
+
+---
+
+## `addManualFilters(filters)`
+
+برای اضافه کردن فیلترهای دستی سمت سرور استفاده می‌شود.
+
+```js
+new ApiFeatures(Order, req.query)
+  .addManualFilters({ user: req.user._id })
+  .filter()
+  .execute();
+```
+
+استفاده از `$and`:
+
+```js
+const result = await new ApiFeatures(Product, req.query)
+  .addManualFilters({
+    $and: [
+      { _id: "665f0f6f4e7d9a2e2c123456" },
+      { isActive: true }
+    ]
   })
-);
+  .filter()
+  .execute();
+```
+
+در این حالت `_id` داخل `$and` هم به صورت recursive به `ObjectId` تبدیل می‌شود.
+
+استفاده از `$or`:
+
+```js
+const result = await new ApiFeatures(Product, req.query)
+  .addManualFilters({
+    $or: [
+      { ownerId: "665f0f6f4e7d9a2e2c123456" },
+      { createdById: "665f0f6f4e7d9a2e2c654321" }
+    ]
+  })
+  .filter()
+  .execute();
+```
+
+استفاده از `$in`:
+
+```js
+const result = await new ApiFeatures(Product, req.query)
+  .addManualFilters({
+    _id: {
+      $in: [
+        "665f0f6f4e7d9a2e2c123456",
+        "665f0f6f4e7d9a2e2c654321"
+      ]
+    }
+  })
+  .filter()
+  .execute();
 ```
 
 ---
 
-## 🧪 Testing
+## `search(fields)`
 
-```bash
-npm test
+از کلید `q` داخل `req.query` مقدار را می‌گیرد و با regex جستجو می‌کند. جستجو همیشه case-insensitive است.
+
+```txt
+GET /api/products?q=iphone
+```
+
+```js
+const result = await new ApiFeatures(Product, req.query)
+  .filter()
+  .search(["name", "description", "brand"])
+  .paginate()
+  .execute();
+```
+
+نکته: `q` جزو کلیدهای رزرو شده است و وارد filter معمولی نمی‌شود.
+
+---
+
+## `sort()`
+
+از `sort` داخل query برای مرتب‌سازی استفاده می‌کند.
+
+```txt
+GET /api/products?sort=-createdAt,price
+```
+
+```js
+{
+  createdAt: -1,
+  price: 1
+}
+```
+
+---
+
+## `limitFields(input)`
+
+برای کنترل فیلدهای خروجی استفاده می‌شود.
+
+```txt
+GET /api/products?fields=name,price,category
+```
+
+یا مستقیم:
+
+```js
+.limitFields("name,price")
+```
+
+حالت include:
+
+```js
+{ name: 1, price: 1 }
+```
+
+حالت exclude:
+
+```js
+{ description: 0 }
 ```
 
-Tests use Jest. Add tests for your controllers and ApiFeatures behaviors.
+حالت mixed مجاز نیست:
+
+```txt
+GET /api/products?fields=name,-password
+```
 
 ---
 
-## 📜 License
+## `paginate()`
+
+برای صفحه‌بندی استفاده می‌شود.
 
-MIT © [Alireza Aghaee](https://github.com/alirezaaghaee)
+```txt
+GET /api/products?page=2&limit=10
+```
+
+```js
+[
+  { $skip: 10 },
+  { $limit: 10 }
+]
+```
 
 ---
 
-## 📜 License
+## `populate(input)`
+
+با استفاده از aggregation و `$lookup` داده‌های مرتبط را join می‌کند.
+
+```js
+.populate("user")
+```
+
+از query:
+
+```txt
+GET /api/posts?populate=user
+```
+
+چند populate:
+
+```js
+.populate(["user", "category"])
+```
+
+nested populate:
+
+```js
+.populate({
+  path: "user",
+  populate: {
+    path: "company",
+    populate: {
+      path: "country"
+    }
+  }
+})
+```
+
+یا با dot notation:
+
+```js
+.populate("user.company.country")
+```
+
+select در populate:
 
-MIT © 2024 Alireza Aghaee
+```js
+.populate({
+  path: "user",
+  select: "name email"
+})
+```
+
+exclude:
+
+```js
+.populate({
+  path: "user",
+  select: "-password"
+})
+```
 
 ---
 
-## ✒️ Author
+## `execute(options)`
+
+pipeline را اجرا می‌کند.
+
+```js
+const result = await features.execute();
+```
+
+خروجی:
+
+```js
+{
+  success: true,
+  count: 25,
+  data: [...]
+}
+```
+
+---
+
+# مدیریت خطاها
+
+## `HandleERROR`
+
+کلاس خطای اختصاصی.
+
+```js
+throw new HandleERROR("Product not found", 404);
+```
+
+```js
+{
+  message: "Product not found",
+  statusCode: 404,
+  status: "fail",
+  isOperational: true
+}
+```
+
+## `catchAsync`
+
+برای حذف `try/catch` تکراری در route handlerهای async.
+
+```js
+app.get(
+  "/products",
+  catchAsync(async (req, res, next) => {
+    const products = await Product.find();
+    res.json(products);
+  })
+);
+```
+
+## `errorHandler`
+
+middleware مرکزی خطاها:
+
+```js
+app.use(catchError);
+```
+
+نمونه خروجی:
+
+```json
+{
+  "status": "fail",
+  "success": false,
+  "message": "Product not found"
+}
+```
+
+---
+
+# تنظیمات امنیتی
+
+برای override کردن تنظیمات پیش‌فرض، در root پروژه فایل زیر را بسازید:
+
+```txt
+security-config.js
+```
+
+```js
+export const securityConfig = {
+  allowedOperators: ["eq", "ne", "gt", "gte", "lt", "lte", "in", "nin", "regex", "exists"],
+  forbiddenFields: ["password", "refreshToken", "resetPasswordToken"],
+  maxPipelineStages: 50,
+  accessLevels: {
+    guest: {
+      maxLimit: 20,
+      allowedPopulate: ["category"]
+    },
+    user: {
+      maxLimit: 100,
+      allowedPopulate: ["category", "createdBy"]
+    },
+    admin: {
+      maxLimit: 1000,
+      allowedPopulate: ["*"]
+    }
+  }
+};
+```
+
+---
 
-**Alireza Aghaee**
+# License
 
-* GitHub: [AlirezaAghaee1996](https://github.com/AlirezaAghaee1996)
-* LinkedIn: [alireza-aghaee-mern-dev](https://www.linkedin.com/in/alireza-aghaee-mern-dev)
+MIT