Coral 🪸

Coral is a lightweight Node.js framework designed to dynamically generate RESTful API routes for Express applications using Mongoose models. It eliminates boilerplate code by automatically creating CRUD routes with built-in support for pagination, sorting, filtering, and nested sub-documents.

Features

• ⚡ Auto-generated CRUD: Instantly create GET, POST, PUT, and DELETE routes.
• 🔍 Powerful Queries: Built-in support for skip, limit, sort, and order via query parameters.
• 📂 Sub-document Support: Easily manage nested Mongoose documents.
• 🛡️ Middleware Support: Inject custom Express middlewares into your routes.
• 🔗 Reference Updates: Automatically update references in related models (via updateRef).
• 🛠️ Configurable: Fine-tune available methods, pagination limits, and more.

Installation

npm install coral

Usage

🚀 Basic Example

Creating a full REST API for a "Product" model:

import express from 'express';
import mongoose from 'mongoose';
import Coral from 'coral';

const app = express();
app.use(express.json());

// 1. Define Mongoose Schema & Model
const ProductSchema = new mongoose.Schema({ name: String, price: Number });
const Product = mongoose.model('Product', ProductSchema);

// 2. Initialize Coral Router
const productRouter = Coral({
  path: '/products',
  model: Product
});

// 3. Use the generated router
app.use(productRouter);

app.listen(3000, () => console.log('Server running on port 3000'));

Advanced Documentation

🛠️ Configuration API

The Coral constructor takes a configuration object. Here are the available options with examples for each:

| Property | Type | Description | | :--- | :--- | :--- | | path | string | The base path for the routes. | | model | Model | The Mongoose model to bind to. | | methods | string[] | Allowed HTTP methods. Default: ['GET', 'POST', 'PUT', 'DELETE']. | | middlewares | RequestHandler[] | Custom Express middlewares to run before handlers. | | conditions | QueryConditions | Base Mongoose filter used for all operations. | | options | QueryOptions | Base Mongoose query options (sort, skip, limit, etc.). | | fields | QueryFields | Base field projection for query results. | | perPage | number | Default records per page for pagination. | | idAttribute | string | Custom field used for finding records by ID. Default: _id. | | idParam | string | URL param name used to read the route identifier (instead of idAttribute). | | query | QueryDefaults | Additional defaults merged with conditions, options, and fields. | | subDoc | SubDocConfig | Configuration for nested sub-documents. | | updateRef | UpdateRefConfig| Update a reference in a parent model on create. | | bodyFilter | string[] | Whitelist of request body keys to persist on create/update. |

1. Path & Model (path, model)

Define the endpoint and the Mongoose model it interacts with.

Coral({
  path: '/api/v1/users',
  model: User
});

2. Restrict HTTP Methods (methods)

If you want to create a read-only endpoint:

Coral({
  path: '/products',
  model: Product,
  methods: ['GET'] // Only GET /products and GET /products/:id will be created
});

3. Custom Middlewares (middlewares)

Secure your routes with authentication or add logging:

const auth = (req, res, next) => {
  if (req.headers.authorization === 'secret') return next();
  res.status(401).send('Unauthorized');
};

Coral({
  path: '/secure-data',
  model: SecureModel,
  middlewares: [auth]
});

4. Pagination Settings (perPage)

Control the default number of records returned for list requests:

Coral({
  path: '/logs',
  model: Log,
  perPage: 50 // Default is 10
});

5. Custom ID Attribute (idAttribute)

Use a field other than _id for lookup (e.g., lookup by slug or email):

Coral({
  path: '/profiles',
  model: Profile,
  idAttribute: 'username' 
});
// Endpoint becomes: GET /profiles/:username

6. Nested Sub-Documents (subDoc)

Manage embedded arrays in your Mongoose models:

// Model: { name: String, comments: [{ body: String }] }
Coral({
  path: '/posts',
  model: Post,
  subDoc: {
    path: 'comments',
    idAttribute: '_id'
  }
});
// Generates: POST /posts/:postId/comments, DELETE /posts/:postId/comments/:commentId, etc.

7. Custom Route Param Name (idParam)

Bind route params to a lookup field without using the default :idAttribute param name:

Coral({
  path: '/profiles/:username',
  model: Profile,
  idAttribute: 'username',
  idParam: 'username'
});

8. Query Defaults (conditions, options, fields, query)

Set base query behavior and then layer overrides in query:

Coral({
  path: '/users',
  model: User,
  conditions: { active: true },
  options: { sort: '-createdAt' },
  fields: 'name email',
  query: {
    conditions: { role: { $in: ['admin', 'member'] } },
    options: { limit: 20 },
    fields: 'name email role'
  }
});

9. Request Body Whitelisting (bodyFilter)

Only allow selected fields from the request payload:

Coral({
  path: '/customers',
  model: Customer,
  bodyFilter: ['email', 'name']
});

10. Reference Updates (updateRef)

Automatically push the ID of a newly created record into a parent model's array:

Coral({
  path: '/articles',
  model: Article,
  updateRef: {
    model: User,
    path: 'articles', // Array field in User model
    findOneId: (req) => req.body.authorId // Find the user using this ID from request
  }
});

🔍 Querying & Pagination Reference

Coral supports the following query parameters for all GET list requests:

• ?limit=20 - Limit results.
• ?skip=10 - Skip results.
• ?page=2 - Pagination (multiplies by perPage).
• ?sort=createdAt&order=desc - Sorting (order can be asc, desc, 1, or -1).
• ?select=name,email - Field projection (translated to 'name email').

Examples Directory

A complete set of copy-paste examples is available in examples/.

It includes focused core-framework scenarios:

• Basic CRUD setup: examples/basic-crud.js
• Methods + middleware configuration: examples/methods-and-middlewares.js
• Custom idAttribute and idParam: examples/custom-id-attribute-and-param.js
• Query defaults (conditions, options, fields, query): examples/query-defaults-and-overrides.js
• Pagination (perPage) and query overrides (sort, order, select): examples/pagination-and-limit-control.js
• Request body filtering (bodyFilter): examples/body-filter.js
• Reference updates on create (updateRef): examples/update-ref.js
• Single-level and multi-level sub-document routing (subDoc): examples/subdoc-single-level.js, examples/subdoc-multi-level.js

🛡️ Security

Here are a few tips to keep your data extra secure:

• Mass Assignment: Use Mongoose's strict mode (default) and express-validator to ensure only the right fields (like email and name) are saved to your database.
• Resource Protection: Coral automatically caps ?limit= to prevent your server from being overwhelmed. For heavy traffic, also try express-rate-limit.

// Example: Using express-validator to sanitize inputs
const validateUser = [
  body('email').isEmail(),
  body('name').notEmpty(),
  (req, res, next) => {
    req.body = matchedData(req); // Only keep validated fields!
    next();
  }
];

Coral({ path: '/users', model: User, middlewares: [validateUser] });

Developer Setup

To contribute or run tests locally:

1. Clone the repo: git clone https://github.com/prathamesh7pute/coral.git
2. Install deps: npm install
3. Build: npm run build
4. Check: npm run check (Lint & format)
5. Test: npm test

Contributing

Please see CONTRIBUTING.md for details on how to contribute and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.