Fast CRUD API

A lightweight and flexible REST API generator for Fastify and MongoDB. Create fully-featured CRUD APIs with minimal configuration.

Quick Install

npm install @ferjssilva/fast-crud-api

Dependencies

• fastify (peer dependency)
• mongoose (peer dependency)
• fastify-plugin

Features

• 🚀 Full CRUD operations out of the box
• 📄 Automatic pagination
• 🔍 Text search across string fields
• 🔗 Reference population support
• 📱 Nested routes for relationships
• 🎯 Method restrictions per model
• � User-scoped resources with automatic filtering
• �🛠 Query building with filtering and sorting
• ⚡ MongoDB integration with proper document transformation
• 🔄 Clean REST API endpoints
• 🚨 Comprehensive error handling
• ✅ 100% Test Coverage

How to Use

Basic Setup

const fastify = require('fastify')()
const mongoose = require('mongoose')
const fastCrudApi = require('@ferjssilva/fast-crud-api')

// Your mongoose models
const User = require('./models/User')
const Post = require('./models/Post')

// Register the plugin
fastify.register(fastCrudApi, {
  prefix: '/api',
  models: [User, Post],
  methods: {
    // Optional: restrict methods per model
    users: ['GET', 'POST', 'PUT', 'DELETE'],
    posts: ['GET', 'POST']
  },
  userScoped: ['posts'] // Optional: automatically filter resources by userId
})

API Usage

List Resources

GET /api/users?page=1&limit=10
GET /api/users?sort={"createdAt":-1}
GET /api/users?name=John&age=25
GET /api/users?search=john

Get Single Resource

GET /api/users/:id
GET /api/users/:id?populate=posts

Create Resource

POST /api/users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "[email protected]"
}

Update Resource

PUT /api/users/:id
Content-Type: application/json

{
  "name": "John Updated"
}

Delete Resource

DELETE /api/users/:id

Nested Routes

GET /api/users/:userId/posts

User-Scoped Resources

Automatically filter and secure resources by user ID. Perfect for multi-tenant applications where users should only access their own data.

fastify.register(fastCrudApi, {
  prefix: '/api',
  models: [User, Post, UserHabit],
  userScoped: ['user-habits'] // Resources that require user isolation
})

How it works:

1. Authentication Required: User-scoped resources require request.userId to be set (typically by an authentication middleware)

2. Automatic Filtering:

   • GET requests automatically filter by userId
   • POST requests automatically inject userId into new documents
   • PUT/DELETE requests verify ownership atomically

3. Security:

   • Users cannot access other users' data
   • Users cannot modify userId on their resources
   • Ownership checks prevent TOCTOU vulnerabilities

Example with Authentication:

// Authentication middleware to set request.userId
fastify.addHook('preHandler', async (request, reply) => {
  const token = request.headers.authorization?.split(' ')[1];
  const user = await verifyToken(token);
  
  if (user) {
    request.userId = user.id; // Set userId for user-scoped resources
  }
});

// User-scoped resources
fastify.register(fastCrudApi, {
  prefix: '/api',
  models: [UserHabit, UserProfile],
  userScoped: ['user-habits', 'user-profiles']
});

Usage:

# List user's own habits (automatically filtered)
GET /api/user-habits
Authorization: Bearer <token>

# Create habit (userId injected automatically)
POST /api/user-habits
Authorization: Bearer <token>
Content-Type: application/json

{
  "habitId": "exercise-daily",
  "frequency": "daily"
}

# Update only if user owns the resource
PUT /api/user-habits/:id
Authorization: Bearer <token>

# Delete only if user owns the resource
DELETE /api/user-habits/:id
Authorization: Bearer <token>

Response Format

List Response

{
  "data": [...],
  "pagination": {
    "total": 100,
    "page": 1,
    "limit": 10,
    "pages": 10
  }
}

Single Resource Response

{
  "id": "...",
  "field1": "value1",
  "field2": "value2"
}

Error Response

{
  "error": "ErrorType",
  "message": "Error description",
  "details": [] // Optional validation details
}

Project Structure

The library is organized in a modular structure for better maintainability:

src/
├── index.js               # Main plugin module
├── utils/
│   ├── document.js        # Document transformation utilities
│   └── query.js           # Query building utilities
├── middleware/
│   ├── error-handler.js   # Error handling middleware
│   └── user-scope.js      # User-scoped resource middleware
├── routes/
│   ├── crud.js            # CRUD route handlers
│   └── nested.js          # Nested route handlers
└── validators/
    └── method.js          # Method validation utilities

Issues and Contact

If you encounter any issues or have suggestions for improvements, please open an issue on our GitHub repository. We appreciate your feedback and contributions!

Open an Issue

Testing

The library includes comprehensive unit tests to ensure the correct functioning of all components:

# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

# Run tests in watch mode (useful during development)
npm run test:watch

Code coverage results:

• Lines of code: 100%
• Functions: 100%
• Branches: 100%
• Statements: 100%

We've achieved complete coverage for all components:

• Utils: 100%
• Validators: 100%
• Middleware: 100%
• Routes: 100%

License

ISC License