crud-api-express

CRUD API Controller

Installation

Install the package using npm:

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

📌 Table of Contents

• Introduction
• Installation
• Usage
• API
• Options
• 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:

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:

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.

[
  { "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 ☕