crud-api-express 1.2.6 → 2.0.0

package/readme.md

@@ -1,4 +1,4 @@
-# CRUD API Controller
+# crud-api-express
 
 ![npm](https://img.shields.io/npm/v/crud-api-express)
 ![downloads](https://img.shields.io/npm/dm/crud-api-express)
@@ -8,271 +8,396 @@
 ![express](https://img.shields.io/badge/Express.js-000000?style=flat&logo=express&logoColor=white)
 ![MongoDB](https://img.shields.io/badge/MongoDB-47A248?style=flat&logo=mongodb&logoColor=white)
 
+> A powerful, flexible CRUD controller for Express + Mongoose — auto‑generates RESTful endpoints with lifecycle hooks, validation, soft delete, search, bulk operations, pagination metadata, and more.
 
+---
+
+## ✨ Features
+
+- 🚀 **Zero boilerplate** — full CRUD in 3 lines of code
+- 🪝 **Lifecycle hooks** — `beforeCreate`, `afterUpdate`, `beforeDelete`, etc.
+- ✅ **Validation hooks** — reject bad data before it hits Mongoose
+- 🔍 **Search endpoint** — case-insensitive text search across multiple fields
+- 🗑️ **Soft delete** — mark records as deleted + restore endpoint
+- 📦 **Bulk operations** — create, update, and delete in batch
+- 🔒 **Per-route middleware** — different auth/logic for read vs. write
+- 📄 **Pagination metadata** — total, pages, hasNext, hasPrev
+- 🎯 **Field selection & population** — `?select=name,email&populate=author`
+- 🔢 **Count & exists** — lightweight endpoints for checking data
+- 📊 **Dynamic aggregation** — static pipelines or functions of `req`
+- 🏗️ **PATCH support** — partial updates with `$set` semantics
+- 🔗 **Related model cascading** — auto‑create/update/delete linked models
+- 📝 **Full TypeScript support** — exported types, generics, JSDoc
 
-## Installation
+---
 
-Install the package using npm:
+## 📦 Installation
 
 ```bash
 npm install crud-api-express
+# Peer dependencies (install alongside):
+npm install express mongoose
 ```
-This project provides a flexible and reusable CRUD (Create, Read, Update, Delete) API controller for MongoDB using Express.js and Mongoose.
 
-## Docs! ❤️  
-[Doc Page Visit here](https://mukeshdev.vercel.app/crudapi)
+---
 
-## 📌 Table of Contents
+## 🚀 Quick Start
+
+```javascript
+import express from 'express';
+import mongoose from 'mongoose';
+import CrudController from 'crud-api-express';
 
-- [Introduction](#introduction)
-- [Installation](#installation)
-- [Usage](#usage)
-- [API](#api)
-- [Options](#options)
-- [License](#license)
+// 1. Define your model
+const UserSchema = new mongoose.Schema({
+  name:  { type: String, required: true },
+  email: { type: String, required: true, unique: true },
+  role:  { type: String, default: 'user', enum: ['user', 'admin'] },
+}, { timestamps: true, versionKey: false });
 
+const User = mongoose.model('User', UserSchema);
 
+// 2. Create the controller
+const userCtrl = new CrudController(User, 'users');
 
----
+// 3. Mount and go
+const app = express();
+app.use(express.json());
+app.use('/api', userCtrl.getRouter());
 
-## Introduction
+mongoose.connect('mongodb://localhost:27017/mydb').then(() => {
+  app.listen(3000, () => console.log('Server running on port 3000'));
+});
+```
 
-The `CrudController` class simplifies the creation of RESTful APIs in Node.js applications using MongoDB. It abstracts away common CRUD operations, error handling, middleware integration, and supports custom routes and aggregation pipelines.
+That's it — you now have **15+ endpoints** auto-generated. 🎉
 
 ---
 
-## Usage
+## 🛣️ Auto-Generated Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/users` | Create a record |
+| `POST` | `/users/bulk` | Bulk create records |
+| `GET` | `/users` | List all (filter/sort/paginate/select/populate) |
+| `GET` | `/users/:id` | Get one by ID |
+| `GET` | `/users/search` | Text search across fields |
+| `GET` | `/users/count` | Count matching records |
+| `GET` | `/users/exists/:id` | Check if a record exists |
+| `GET` | `/users/aggregate` | Run aggregation pipeline |
+| `PUT` | `/users/:id` | Full update by ID |
+| `PATCH` | `/users/:id` | Partial update by ID |
+| `PATCH` | `/users/bulk` | Bulk update by filter |
+| `PATCH` | `/users/:id/restore` | Restore soft-deleted record *(soft delete only)* |
+| `DELETE` | `/users/:id` | Delete one by ID |
+| `DELETE` | `/users` | Delete by filter |
+| `DELETE` | `/users/bulk` | Bulk delete by IDs array |
 
-Here's a basic example of how to use in Es module `CrudController`:
+---
 
-```javascript
-import express from 'express';
-import mongoose from 'mongoose';
-import CrudController from 'crud-api-express';
+## ⚙️ Full Options Reference
+
+```typescript
+const ctrl = new CrudController(Model, 'endpoint', {
+  // HTTP methods to enable (default: all five)
+  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
+
+  // Global middleware for all routes
+  middleware: [authMiddleware, loggerMiddleware],
 
-const Schema = mongoose.Schema;
-const ExampleSchema = new Schema(
-  {
-    type: { type: String, default: 'Percentage', enum: ['Percentage', 'Flat'] },
-    status: { type: String, default: 'Active', trim: true },
-    expiry_date: { type: Date, index: true, trim: true },
+  // Per-operation middleware
+  routeMiddleware: {
+    create: [validateBody],
+    read:   [],
+    update: [validateBody],
+    delete: [requireAdmin],
   },
-  { timestamps: true, versionKey: false }
-);
-
-const ExampleModel = mongoose.model('Example', ExampleSchema);
-
-const options = {
-  middleware: [
-    (req, res, next) => {
-      const authToken = req.headers.authorization;
-      if (!authToken) {
-        return res.status(401).json({ message: 'Unauthorized' });
-      }
-      next();
-    },
-    (req, res, next) => {
-      console.log(`Request received at ${new Date()}`);
-      next();
-    },
-  ],
-  onSuccess: (res, method, result) => {
-    console.log(`Successful ${method} operation:`, result);
-    res.status(200).json({ success: true, data: result });
+
+  // Custom success/error response shapes
+  onSuccess: (res, method, result, meta) => {
+    res.status(200).json({ success: true, data: result, ...(meta && { pagination: meta }) });
   },
   onError: (res, method, error) => {
-    console.error(`Error in ${method} operation:`, error);
-    res.status(500).json({ error: error.message });
+    res.status(500).json({ success: false, error: error.message });
+  },
+
+  // Lifecycle hooks
+  hooks: {
+    beforeCreate: async (req, data) => ({ ...data, createdBy: req.user.id }),
+    afterCreate:  async (req, result) => { await notifySlack(result); },
+    beforeUpdate: async (req, id, data) => data,
+    afterUpdate:  async (req, result) => {},
+    beforeDelete: async (req, id) => {},
+    afterDelete:  async (req, result) => { await auditLog('delete', result._id); },
+    beforeRead:   async (req, query) => ({ ...query, org: req.user.orgId }),
+    afterRead:    async (req, result) => result,
   },
-  methods: ['GET', 'POST', 'PUT', 'DELETE'],
+
+  // Validation hooks (run before Mongoose validation)
+  validate: {
+    create: (data) => ({
+      valid: !!data.email && !!data.name,
+      errors: [
+        ...(!data.email ? ['Email is required'] : []),
+        ...(!data.name ? ['Name is required'] : []),
+      ],
+    }),
+    update: (data) => ({ valid: true }),
+  },
+
+  // Field selection (Mongoose select syntax)
+  select: 'name email role -_id',
+
+  // Auto-populate references
+  populate: 'department',
+  // or: populate: [{ path: 'department', select: 'name' }],
+
+  // Search fields for GET /endpoint/search
+  searchFields: ['name', 'email'],
+
+  // Soft delete (sets deletedAt instead of removing)
+  softDelete: true,
+
+  // Aggregation pipeline (static or dynamic)
   aggregatePipeline: [
     { $match: { status: 'Active' } },
     { $sort: { createdAt: -1 } },
   ],
+  // or dynamic:
+  // aggregatePipeline: (req) => [{ $match: { region: req.query.region } }],
+
+  // Related model cascading
+  relatedModel: ProfileModel,
+  relatedField: 'userId',
+  relatedMethods: ['POST', 'DELETE'],
+
+  // Custom routes (always registered regardless of methods filter)
   customRoutes: [
     {
       method: 'get',
-      path: '/custom-route',
-      handler: (req, res) => {
-        res.json({ message: 'Custom route handler executed' });
-      },
-    },
-    {
-      method: 'post',
-      path: '/custom-action',
-      handler: (req, res) => {
-        res.json({ message: 'Custom action executed' });
+      path: '/stats',
+      middleware: [cacheMiddleware],
+      handler: async (req, res) => {
+        const count = await Model.countDocuments({ status: 'Active' });
+        res.json({ activeUsers: count });
       },
     },
   ],
-};
+});
+```
 
-const exampleController = new CrudController(ExampleModel, 'examples', options);
+---
 
-const mongoURI = 'mongodb://localhost:27017/mydatabase';
+## 📡 Query Parameters
 
-mongoose
-  .connect(mongoURI, { useNewUrlParser: true, useUnifiedTopology: true })
-  .then(() => {
-    console.log('Connected to MongoDB');
+### GET All — `GET /api/users?...`
 
-    const app = express();
-    app.use(express.json());
-    app.use('/api', exampleController.getRouter());
+| Param | Example | Description |
+|-------|---------|-------------|
+| `filter` | `{"status":"Active"}` | MongoDB filter object |
+| `sort` | `{"createdAt":-1}` | Sort order |
+| `page` | `1` | Page number (default: 1) |
+| `limit` | `10` | Results per page (default: 10) |
+| `select` | `name,email` | Fields to include/exclude |
+| `populate` | `author,comments` | References to populate |
+| `includeDeleted` | `true` | Include soft-deleted records |
 
-    console.log(exampleController.getRoutes());
+### Search — `GET /api/users/search?...`
 
-    const PORT = process.env.PORT || 3000;
-    app.listen(PORT, () => {
-      console.log(`Server is running on port ${PORT}`);
-    });
-  })
-  .catch((err) => {
-    console.error('Error connecting to MongoDB:', err.message);
-    process.exit(1);
-  });
+| Param | Example | Description |
+|-------|---------|-------------|
+| `q` | `john` | Search term (**required**) |
+| `fields` | `name,email` | Override default searchFields |
+| `page` | `1` | Page number |
+| `limit` | `10` | Results per page |
+| `select` | `name,email` | Fields to include  |
+| `populate` | `author` | References to populate |
+
+### Pagination Response Shape
+
+```json
+{
+  "data": [...],
+  "pagination": {
+    "total": 150,
+    "page": 2,
+    "limit": 10,
+    "pages": 15,
+    "hasNext": true,
+    "hasPrev": true
+  }
+}
 ```
-Here's a basic example of how to use in cjs module `CrudController`:
-```javascript
 
-const express = require('express');
-const mongoose = require('mongoose');
-const CrudController = require('crud-api-express');
+---
+
+## 🪝 Lifecycle Hooks
 
-const Schema = mongoose.Schema;
-const ExampleSchema = new Schema(
-  {
-    type: { type: String, default: 'Percentage', enum: ['Percentage', 'Flat'] },
-    status: { type: String, default: 'Active', trim: true },
-    expiry_date: { type: Date, index: true, trim: true },
+Hooks let you inject business logic without fighting the abstraction:
+
+```javascript
+hooks: {
+  // Transform data before saving — return the modified object
+  beforeCreate: async (req, data) => {
+    data.createdBy = req.user.id;
+    data.slug = slugify(data.name);
+    return data;
   },
-  { timestamps: true, versionKey: false }
-);
-
-const ExampleModel = mongoose.model('Example', ExampleSchema);
-
-const options = {
-  middleware: [
-    (req, res, next) => {
-      const authToken = req.headers.authorization;
-      if (!authToken) {
-        return res.status(401).json({ message: 'Unauthorized' });
-      }
-      next();
-    },
-    (req, res, next) => {
-      console.log(`Request received at ${new Date()}`);
-      next();
-    },
-  ],
-  onSuccess: (res, method, result) => {
-    console.log(`Successful ${method} operation:`, result);
-    res.status(200).json({ success: true, data: result });
+
+  // Side-effects after saving
+  afterCreate: async (req, result) => {
+    await sendWelcomeEmail(result.email);
+    await auditLog('user.created', result._id);
   },
-  onError: (res, method, error) => {
-    console.error(`Error in ${method} operation:`, error);
-    res.status(500).json({ error: error.message });
+
+  // Scope all reads to the user's organization
+  beforeRead: async (req, query) => {
+    return { ...query, organizationId: req.user.orgId };
   },
-  methods: ['GET', 'POST', 'PUT', 'DELETE'],
-  aggregatePipeline: [
-    { $match: { status: 'Active' } },
-    { $sort: { createdAt: -1 } },
-  ],
-  customRoutes: [
-    {
-      method: 'get',
-      path: '/custom-route',
-      handler: (req, res) => {
-        res.json({ message: 'Custom route handler executed' });
-      },
-    },
-    {
-      method: 'post',
-      path: '/custom-action',
-      handler: (req, res) => {
-        res.json({ message: 'Custom action executed' });
-      },
-    },
-  ],
-};
 
-const exampleController = new CrudController(ExampleModel, 'examples', options);
+  // Prevent deletion of system records
+  beforeDelete: async (req, id) => {
+    const item = await User.findById(id);
+    if (item?.role === 'system') {
+      throw new Error('Cannot delete system users');
+    }
+  },
+}
+```
 
-const mongoURI = 'mongodb://localhost:27017/mydatabase';
+---
+
+## 🗑️ Soft Delete
 
-mongoose
-  .connect(mongoURI, { useNewUrlParser: true, useUnifiedTopology: true })
-  .then(() => {
-    console.log('Connected to MongoDB');
+Enable soft delete to preserve data while hiding it from default queries:
 
-    const app = express();
-    app.use(express.json());
-    app.use('/api', exampleController.getRouter());
+```javascript
+const ctrl = new CrudController(User, 'users', {
+  softDelete: true,
+});
+```
+
+- `DELETE /users/:id` → Sets `deletedAt: Date` instead of removing
+- `GET /users` → Auto-excludes records with `deletedAt`
+- `GET /users?includeDeleted=true` → Shows everything including deleted
+- `PATCH /users/:id/restore` → Removes `deletedAt` to restore the record
+
+---
 
-    console.log(exampleController.getRoutes());
+## 📦 Bulk Operations
 
-    const PORT = process.env.PORT || 3000;
-    app.listen(PORT, () => {
-      console.log(`Server is running on port ${PORT}`);
-    });
-  })
-  .catch((err) => {
-    console.error('Error connecting to MongoDB:', err.message);
-    process.exit(1);
-  });
+```bash
+# Bulk Create
+POST /api/users/bulk
+Body: [{ "name": "Alice" }, { "name": "Bob" }]
+
+# Bulk Update (by filter)
+PATCH /api/users/bulk
+Body: { "filter": { "role": "user" }, "update": { "status": "inactive" } }
+
+# Bulk Delete (by IDs)
+DELETE /api/users/bulk
+Body: { "ids": ["id1", "id2", "id3"] }
 ```
 
 ---
 
-## API
+## 🔒 Per-Route Middleware
 
-### `getRouter(): Router`
-Returns the Express Router instance configured with CRUD routes.
+Apply different middleware to different operations:
 
-```json
-[
-  { "method": "POST", "path": "/examples", "params": null },
-  { "method": "GET", "path": "/examples", "params": ["filter", "sort", "page", "limit"] },
-  { "method": "GET", "path": "/examples/:id", "params": ["id"] },
-  { "method": "PUT", "path": "/examples/:id", "params": ["id"] },
-  { "method": "DELETE", "path": "/examples", "params": ["filter"] },
-  { "method": "DELETE", "path": "/examples/:id", "params": ["id"] },
-  { "method": "GET", "path": "/examples/aggregate", "params": null },
-  { "method": "GET", "path": "/examples/custom-route", "params": null },
-  { "method": "POST", "path": "/examples/custom-action", "params": null }
-]
+```javascript
+const ctrl = new CrudController(User, 'users', {
+  middleware: [loggerMiddleware],  // applies to ALL routes
+  routeMiddleware: {
+    create: [requireAuth, validateBody],
+    read:   [optionalAuth],
+    update: [requireAuth, requireOwner],
+    delete: [requireAuth, requireAdmin],
+  },
+});
 ```
 
-## Options
+---
+
+## 💡 Multiple Controllers
+
+Mount multiple controllers on the same app:
+
+```javascript
+const userCtrl    = new CrudController(User, 'users', { ... });
+const productCtrl = new CrudController(Product, 'products', { ... });
+const orderCtrl   = new CrudController(Order, 'orders', { ... });
+
+app.use('/api', userCtrl.getRouter());
+app.use('/api', productCtrl.getRouter());
+app.use('/api', orderCtrl.getRouter());
+```
+
+---
+
+## 📋 API Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getRouter()` | `Router` | Express Router with all configured routes |
+| `getRoutes()` | `RouteInfo[]` | Array of registered route definitions |
+
+---
 
+## 🔄 Migration from v1.x
 
-### `CrudOptions<T>`
+### Breaking Changes
 
-| Option             | Type                                                                                                      | Description                                          |
-|--------------------|---------------------------------------------------------------------------------------------------------|------------------------------------------------------|
-| `middleware`      | `((req: Request, res: Response, next: NextFunction) => void)[]`                                         | Array of middleware functions                       |
-| `onSuccess`       | `(res: Response, method: string, result: T \| T[]) => void`                                             | Success handler function                            |
-| `onError`         | `(res: Response, method: string, error: Error) => void`                                                 | Error handler function                              |
-| `methods`         | `('POST' \| 'GET' \| 'PUT' \| 'DELETE')[]`                                                              | Array of HTTP methods to support                   |
-| `relatedModel`    | `Model<any>`                                                                                            | Related Mongoose model for relational operations    |
-| `relatedField`    | `string`                                                                                                | Field name for related models                       |
-| `relatedMethods`  | `('POST' \| 'GET' \| 'PUT' \| 'DELETE')[]`                                                              | Methods to apply on related models                  |
-| `aggregatePipeline` | `object[]`                                                                                            | MongoDB aggregation pipeline stages                 |
-| `customRoutes`    | `{ method: 'post' \| 'get' \| 'put' \| 'delete', path: string, handler: (req: Request, res: Response) => void }[]` | Array of custom route definitions                   |
+1. **`onSuccess` signature** — Now receives an optional 4th `meta` parameter for pagination metadata
+2. **Custom routes** — No longer gated by the `methods` filter; they always register
+3. **Soft delete** — When `softDelete: true`, DELETE behavior changes from removing to marking
+4. **Bulk delete safety** — `DELETE /endpoint` now requires a non-empty filter to prevent accidental full-table deletes
+
+### New Defaults
+
+- Methods array now includes `'PATCH'` by default
+- GET all returns pagination metadata in the default response shape
+
+### Upgrade Steps
+
+1. Update your package: `npm install crud-api-express@latest`
+2. If your `onSuccess` callback has strict arity checks, add the optional `meta` parameter
+3. Test your custom routes — they will now register even if their HTTP method isn't in the `methods` array
+4. If using deletion endpoints, ensure you pass filters for bulk delete
 
 ---
 
-## 📖 Fetch All Records with Query Params (GET)
+## 🔧 CommonJS Usage
 
-**🛠️ URL:**  
-`GET http://localhost:3000/api/examples?filter={"status":"Active"}&sort={"expiry_date":1}&page=1&limit=10`
+```javascript
+const CrudController = require('crud-api-express');
+const User = require('./models/User');
 
-### 🔍 Query Params Explanation:
-- **`filter`** → Filter results (e.g., `{ "status": "Active" }`).
-- **`sort`** → Sort order (e.g., `{ "expiry_date": 1 }` for ascending).
-- **`page`** → Pagination (e.g., `page=1`).
-- **`limit`** → Number of results per page.
+const ctrl = new CrudController(User, 'users', { ... });
+```
 
+---
+
+## 📖 TypeScript Support
+
+All types are exported for full TypeScript support:
+
+```typescript
+import CrudController, {
+  CrudOptions,
+  MiddlewareFunction,
+  SuccessHandler,
+  ErrorHandler,
+  ValidationResult,
+  PaginationMeta,
+  HttpMethod,
+  RouteInfo,
+} from 'crud-api-express';
+```
+
+---
 
 ## License
 
@@ -280,6 +405,5 @@ This project is licensed under the **ISC License**.
 
 ## Support Me! ❤️
 
-If you find this package useful, consider supporting me:  
+If you find this package useful, consider supporting me:
 [Buy Me a Coffee ☕](https://buymeacoffee.com/mrider007)
-