crud-api-express
Version:
    
## Installation
Install the package using npm:
```bash
npm install crud-api-express
```
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
- [Introduction](#introduction)
- [Installation](#installation)
- [Usage](#usage)
- [API](#api)
- [Options](#options)
- [License](#license)
---
## Introduction
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.
---
## Usage
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';
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 },
},
{ 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 });
},
onError: (res, method, error) => {
console.error(`Error in ${method} operation:`, error);
res.status(500).json({ error: error.message });
},
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);
const mongoURI = 'mongodb://localhost:27017/mydatabase';
mongoose
.connect(mongoURI, { useNewUrlParser: true, useUnifiedTopology: true })
.then(() => {
console.log('Connected to MongoDB');
const app = express();
app.use(express.json());
app.use('/api', exampleController.getRouter());
console.log(exampleController.getRoutes());
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);
});
```
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');
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 },
},
{ 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 });
},
onError: (res, method, error) => {
console.error(`Error in ${method} operation:`, error);
res.status(500).json({ error: error.message });
},
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);
const mongoURI = 'mongodb://localhost:27017/mydatabase';
mongoose
.connect(mongoURI, { useNewUrlParser: true, useUnifiedTopology: true })
.then(() => {
console.log('Connected to MongoDB');
const app = express();
app.use(express.json());
app.use('/api', exampleController.getRouter());
console.log(exampleController.getRoutes());
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);
});
```
---
## API
### `getRouter(): Router`
Returns the Express Router instance configured with CRUD routes.
```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 }
]
```
## Options
### `CrudOptions<T>`
| 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 |
---
## 📖 Fetch All Records with Query Params (GET)
**🛠️ URL:**
`GET http://localhost:3000/api/examples?filter={"status":"Active"}&sort={"expiry_date":1}&page=1&limit=10`
### 🔍 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.
## License
This project is licensed under the **ISC License**.
## Support Me! ❤️
If you find this package useful, consider supporting me:
[Buy Me a Coffee ☕](https://buymeacoffee.com/mrider007)