One model in,a whole REST API out.

Never built a REST API before? Start here.

Skip ahead if router.get('/:id', …) is muscle memory for you.

Words you'll see on every page

What you actually get

Three exports carry almost all the value. The rest is detail.

That is the whole surface for most projects:

import { createRouter, createRouterS3upload, errorHandler } from 'express-controller-sets';

app.use('/api/products', createRouter({ model: Product, /* rules */ }));
app.use('/api/users',    createRouterS3upload({ model: User, /* rules */ }));
app.use(errorHandler);   // always last

Four more exports exist for when you need them: the ControllerSets class (wire handlers into your own routes), fileUploadMiddleware (uploads without the CRUD), compressImage, and HttpError / escapeRegex for your own code.

Install

One command for CRUD. A second one only if you want uploads.

npm install express-controller-sets mongoose express

Uploads need two more packages. They are optional peers — the library imports them lazily, so if you never create an upload router you never pay for them:

npm install multer @aws-sdk/client-s3

# optional: image compression before upload
npm install sharp

Your first API, end to end

Four steps from an empty file to five working endpoints.

1. Define a Mongoose model as you normally would

   Nothing here is special to this library.

   // models/Product.js
   import mongoose from 'mongoose';
   
   const productSchema = new mongoose.Schema({
     name:        { type: String, required: true },
     price:       { type: Number, required: true },
     description: String,
     category:    { type: mongoose.Schema.Types.ObjectId, ref: 'Category' },
     isFeatured:  { type: Boolean, default: false },
   }, { timestamps: true });
   
   export default mongoose.model('Product', productSchema);

   Copy

2. Build a router and state the house rules

   Every option below is an allowlist. Read the comments — they are the whole security model in miniature.

   import express from 'express';
   import { createRouter, errorHandler } from 'express-controller-sets';
   import Product from './models/Product.js';
   
   const app = express();
   app.use(express.json());
   
   const productRouter = createRouter({
     model: Product,
   
     orderBy: '-createdAt',                 // default sort: newest first
   
     // What a client may FILTER on:  /api/products?category=65a…
     query: ['category', 'isFeatured'],
   
     // What a client may SEARCH in:  /api/products?s=laptop
     search: ['name', 'description', 'category.name'],
   
     // What a client may WRITE. Without this line, every schema field
     // is writable — including any you never meant to expose.
     allowedFields: ['name', 'price', 'description', 'category'],
   
     // What a client may use with ?compareField= / ?rangeField= and ?sort=
     filterableFields: ['price', 'category'],
     sortableFields: ['price', 'name', 'createdAt'],
   });
   
   app.use('/api/products', productRouter);
   app.use(errorHandler);                   // must be after your routes
   
   app.listen(3000);

   Copy

3. Connect to MongoDB and start the server

   import mongoose from 'mongoose';
   await mongoose.connect(process.env.MONGODB_URI);

   Copy

4. Call it

   curl localhost:3000/api/products
   curl localhost:3000/api/products?s=laptop&sort=-price&page=1
   curl -X POST localhost:3000/api/products \
     -H 'Content-Type: application/json' \
     -d '{"name":"Laptop","price":1299}'

   Copy

A request, step by step

What happens between GET /api/products?s=laptop and the JSON that comes back.

A write (POST or PATCH) follows the same path with two differences: on an upload router the file middleware runs first and replaces the file with its URL, and the request body is filtered down to the fields you allowed before it reaches Mongoose.

Nothing is open until you open it

One idea explains almost every option in this library. Learn it once and the rest of the page reads itself.

What is closed, and the key that opens it

Fields no configuration can unlock

Regardless of what you allow, these are stripped from every request body — they are database bookkeeping or MongoDB syntax, never client data:

Options at a glance

Both router factories take one object. Five keys are consumed by the router itself; everything else is passed straight through to the controller.

createRouterS3upload({
  // ---- router-level ----
  middlewares: [requireAuth],          // run before every route in this router
  path: 'products/',                   // S3 key prefix           (upload routers)
  fields: [{ name: 'image', maxCount: 1 }],  //  form fields      (upload routers)
  imgOptimizations: 'medium',          // compression level       (upload routers)
  upload: { acl: 'private' },          // everything else S3      (upload routers)

  // ---- controller-level ----
  model: Product,                      // the only required option
  orderBy: '-createdAt',
  query: ['category'],
  search: ['name', 'category.name'],
  allowedFields: ['name', 'price'],
  blockedFields: ['isFeatured'],
  filterableFields: ['price'],
  sortableFields: ['price', 'createdAt'],
  maxLimit: 100,
  maxSearchLength: 128,
  allowRawRegex: false,
  lean: false,
  runAfterCreate: async (doc) => {},
  strictAfterCreate: false,
  onGet: async (req, res) => ({ populates: [], selects: '' }),
  logger: console,
  legacyMode: false,
});

Full descriptions and defaults live in Every option. The sections in between explain the ones with real consequences.

The five endpoints

Identical for every model, whether you use createRouter or createRouterS3upload.

Mount the router wherever you like — the paths above are relative to the mount point:

app.use('/api/products', createRouter({ model: Product }));
// → GET /api/products, POST /api/products, GET /api/products/:id, …

What "update" really does

The update is a single atomic query (findByIdAndUpdate), not read-then-write, so two simultaneous updates cannot clobber each other in the gap. Schema validators run with context: 'query', which is what makes custom validators that use this behave correctly on updates. A missing record returns 404 rather than creating one.

Filtering

Three ways to narrow a list, each gated by an allowlist.

createRouter({ model: Product, query: ['category', 'isFeatured'] });

// GET /api/products?category=65af…&isFeatured=true
//   → { category: '65af…', isFeatured: 'true' }

// Repeat a parameter to match any of several values:
// GET /api/products?category=65af…&category=65b0…
//   → { category: { $in: ['65af…', '65b0…'] } }

# price between 10 and 100 (inclusive)
GET /api/products?rangeField=price&range=10-100

# 18 and over — omit the upper bound
GET /api/users?rangeField=age&range=18-

# 100 and under — omit the lower bound
GET /api/products?rangeField=price&range=-100

# price > 50
GET /api/products?compareField=price&compareValue=50&compareOperator=gt

# combine freely with equality filters
GET /api/users?status=active&compareField=age&compareValue=30&compareOperator=lte

Search

One parameter, ?s= (or ?search=), across as many fields as you list — including fields on related models.

createRouter({
  model: Product,
  search: ['name', 'description', 'category.name'],
});

// GET /api/products?s=wireless
//   matches products whose name OR description contains "wireless",
//   OR whose category's name contains "wireless"

How relational search works

A field with a dot is split at the first dot. The part before it must be a field on your schema declared with ref; the rest is the path to search on the referenced model. The library looks up the matching documents there first, then filters your collection by their IDs — no aggregation pipeline required.

Search terms are treated as text, not patterns

Regex metacharacters in the term are escaped, so ?s=c++ searches for the literal string c++. Terms longer than maxSearchLength (128 characters) are rejected with 400.

The single-field shorthand

createRouter({ model: Post, search: 'title' });
// Still read from ?s= / ?search= — a string just means "one field".

Sorting & pagination

Two knobs the client turns, both bounded by you.

Sorting

createRouter({
  model: Product,
  orderBy: '-createdAt',                        // your default: newest first
  sortableFields: ['price', 'name', 'createdAt'],  // what clients may choose
});

// GET /api/products?sort=price     → cheapest first
// GET /api/products?sort=-price    → dearest first  (the '-' means descending)
// GET /api/products?sort=secretKey → 400 Field 'secretKey' is not sortable.

Your own orderBy is never checked against the allowlist — it's your decision, not the client's. Only a client-supplied ?sort= is validated. If you omit sortableFields, it defaults to everything in query plus whatever field orderBy names.

Pagination

GET /api/products?page=2&pageSize=20

Adding ?page= switches the response into paginated form, with a pagination block alongside the data:

{
  "success": true,
  "data": [ /* … */ ],
  "pagination": {
    "currentPage": 2,
    "pageSize": 20,
    "totalPages": 7,
    "totalRecords": 132
  }
}

Shaping responses with onGet

One hook that decides, per request, which relations to expand and which fields to return.

Populating relations is expensive, and different callers need different amounts of data. A mobile list view wants names; an admin screen wants everything. onGet lets one router serve both.

onGet: (req, res) => ({
  populates: [],   // Mongoose .populate() argument — string, object, or array
  selects: '',     // Mongoose .select() argument — e.g. 'name price -_id'
})

createRouter({
  model: Product,
  onGet: () => ({
    populates: 'category',
    selects: 'name price category',
  }),
});

createRouter({
  model: Order,
  middlewares: [requireAuth],
  onGet: (req) => {
    if (req.user?.role === 'admin') {
      return {
        populates: [
          { path: 'customer', select: 'name email phone' },
          { path: 'items.product', select: 'name price' },
        ],
        selects: '',                       // everything
      };
    }
    return { populates: 'items.product', selects: '-internalNotes -margin' };
  },
});

const onGet = async (req) => {
  const isDetail = Boolean(req.params.id);
  return {
    populates: isDetail ? ['category', 'reviews'] : 'category',
    selects: isDetail ? '' : 'name price category',
  };
};

createRouter({ model: Product, onGet });   // reuse across routers

Create & update

The request body is filtered before Mongoose ever sees it. This section is the single most important one for security.

Say what a client may write

// Allowlist — name what IS writable (recommended)
createRouter({
  model: User,
  allowedFields: ['name', 'email', 'avatar'],
});

// Blocklist — name what is NOT writable
createRouter({
  model: User,
  blockedFields: ['role', 'isAdmin', 'balance'],
});

// Per verb — stricter on update than on create
createRouter({
  model: User,
  allowedFields: {
    create: ['name', 'email', 'password'],
    update: ['name', 'avatar'],          // email and password need their own flow
  },
});

Both options may be combined; blockedFields is applied after allowedFields, so a field on both lists is blocked.

What a client sends vs. what gets saved

// allowedFields: ['name', 'email']

// The client POSTs:
{
  "name":  "Ayesha",
  "email": "ayesha@example.com",
  "role":  "admin",          // ✘ not allowlisted        → dropped
  "_id":   "65af…",          // ✘ always immutable       → dropped
  "$where": "1 === 1"        // ✘ Mongo operator syntax  → dropped
}

// What reaches the database:
{ "name": "Ayesha", "email": "ayesha@example.com" }

Dropped fields are dropped quietly — the request still succeeds with the fields that survived. One exception: if nothing survives, you get 400 "Request body contains no writable fields." rather than an empty record being created.

The after-create hook

Run something once a record exists — send a welcome email, push a job onto a queue, warm a cache.

createRouter({
  model: User,
  allowedFields: ['name', 'email'],

  runAfterCreate: async (user) => {
    await sendWelcomeEmail(user.email);
    await queue.add('index-user', { id: user._id });
  },
});

The hook receives the created document and is awaited before the 201 goes out.

Errors & status codes

Every failure comes back in the same shape. Mount the handler once and stop writing try/catch in route files.

import { errorHandler } from 'express-controller-sets';

app.use('/api/products', productRouter);
app.use('/api/users', userRouter);

app.use(errorHandler);   // AFTER all routes — Express requires this order

The error response

{
  "success": false,
  "error": "Validation Error: price is required",
  "requestId": "0f2a5b8c-…"
}

requestId is echoed into your server log alongside the full message and stack. When a user reports "it said Internal Server Error", that ID takes you straight to the line. A stack field is added only when NODE_ENV=development.

What each status code means

Duplicate keys are a 409, not a 500

{ "success": false, "error": "Duplicate value for: email.", "requestId": "…" }

A unique-constraint collision is something the caller can fix by sending a different value, so it is reported as a conflict rather than a server fault. Your front end can show "that email is already registered" without parsing message text.

How uploads work

Swap one function name and POST/PATCH start accepting files.

import { createRouterS3upload } from 'express-controller-sets';

const userRouter = createRouterS3upload({
  model: User,
  allowedFields: ['name', 'email', 'avatar'],   // 'avatar' must be writable!

  path: 'avatars/',                             // key prefix inside the bucket
  fields: [{ name: 'avatar', maxCount: 1 }],    // the multipart field name
  imgOptimizations: 'medium',                   // optional compression
});

app.use('/api/users', userRouter);

From the browser, send multipart/form-data — regular fields and the file together:

const form = new FormData();
form.append('name', 'Ayesha');
form.append('avatar', fileInput.files[0]);

await fetch('/api/users', { method: 'POST', body: form });
// Don't set Content-Type yourself — the browser adds the multipart boundary.

What happens to the file

1. Received into memory

   Multer buffers it — no temp files on disk. Size and count limits apply here.

2. The bytes are identified

   The library reads the file's own signature. The Content-Type the client sent is ignored: it is a claim, and the bytes are the fact. An unrecognised file is rejected with 400.

3. Checked against the allowlist

   Only the detected type is compared to allowedMimeTypes. Renaming payload.html to photo.png changes nothing.

4. Optionally compressed

   JPEG, PNG and WebP are re-encoded if imgOptimizations is set. See Image optimization.

5. Uploaded with a safe key and headers

   Stored as <path>/<timestamp>-<random>.<ext>, with the extension and Content-Type derived from the final bytes, an ACL of private, and Content-Disposition: attachment for anything not on the inline-safe list.

6. The URL replaces the file in req.body

   The CRUD controller then saves it like any other field — which is why the field must appear in allowedFields.

// After the middleware, before the controller:
req.body.avatar === 'https://your-endpoint/bucket/avatars/1721736000000-482913746.jpg'

// Prefer an object? Set formatToUrlObject on the field:
fields: [{ name: 'avatar', maxCount: 1, formatToUrlObject: true }]
req.body.avatar === { url: 'https://…' }

// maxCount > 1 gives you an array:
fields: [{ name: 'gallery', maxCount: 5 }]
req.body.gallery === ['https://…', 'https://…']

Which types are accepted, inline, or refused

Upload options

Everything about files lives in three top-level keys plus the upload object.

createRouterS3upload({
  model: Document,

  path: 'documents/',                                  // key prefix
  fields: [
    { name: 'file',  maxCount: 1 },
    { name: 'pages', maxCount: 10, formatToUrlObject: true },
  ],
  imgOptimizations: 'high',

  upload: {
    acl: 'public-read',                                // opt in deliberately
    allowedMimeTypes: ['image/jpeg', 'image/png', 'application/pdf'],
    maxFileSize: 5 * 1024 * 1024,                      // 5 MB per file
    maxFiles: 5,
    allowClientImageOptions: false,
  },
});

Image optimization

Shrink images on the way to S3, without picking quality numbers yourself.

Set a level and the library re-encodes the image toward a target size, binary-searching encoder quality (bounded between 25 and 95, at most seven attempts) until it lands in range. You get predictable output sizes instead of a fixed quality that ruins some photos and barely touches others.

// On a router
createRouterS3upload({ model: Post, imgOptimizations: 'high' });

// Or directly, on a buffer you already have
import { compressImage } from 'express-controller-sets';
const smaller = await compressImage(buffer, 'image/jpeg', 'medium');

What is and isn't touched

S3 environment

Five variables. Only needed if you use an upload router.

S3_ENDPOINT=https://nyc3.digitaloceanspaces.com   # required
S3_SPACES_KEY=your-access-key                     # required
S3_SPACES_SECRET=your-secret-key                  # required
S3_BUCKET_NAME=your-bucket                        # required
S3_REGION=us-east-1                               # optional, defaults to us-east-1

The variable names carry "SPACES" because the client is configured with path-style addressing, which works with DigitalOcean Spaces, MinIO, Cloudflare R2 and Amazon S3 alike. Any S3-compatible endpoint will do.

import 'dotenv/config';   // first import in your entry file

Auth & middlewares

The library builds the routes. Deciding who may call them is entirely yours.

createRouter({
  model: Order,
  middlewares: [requireAuth, requireRole('staff')],   // run before every route
  allowedFields: ['status', 'note'],
});

Everything in middlewares is applied with router.use(), so it guards all five endpoints in that router. When different verbs need different rules, use two routers on the same path:

// Public: anyone may read the catalogue
app.use('/api/products', createRouter({
  model: Product,
  query: ['category'],
  allowedFields: [],                       // no writes get through here
}));

// Private: only staff may change it
app.use('/api/admin/products', createRouter({
  model: Product,
  middlewares: [requireAuth, requireRole('staff')],
  query: ['category'],
  allowedFields: ['name', 'price', 'category', 'isFeatured'],
}));

// A tenancy guard: force every request to be scoped to the caller
const onlyMine = (req, res, next) => {
  req.query.owner = String(req.user._id);   // 'owner' must be in `query`
  next();
};

createRouter({
  model: Order,
  middlewares: [requireAuth, onlyMine],
  query: ['owner', 'status'],
});

Before you go live

Nine checks. None of them takes more than a minute.

# write a field you never allowlisted
curl -X POST …/api/users -H 'Content-Type: application/json' \
     -d '{"name":"x","role":"admin"}'          # role must not persist

# sort by something private
curl '…/api/users?sort=passwordHash'           # expect 400

# read the whole collection
curl '…/api/users' | jq '.data | length'       # expect ≤ maxLimit

# upload HTML disguised as an image
curl -F 'avatar=@evil.html;type=image/png' …   # expect 400

Upgrading from 2.x

3.0 is a security release. Every breaking change is a default that used to be unsafe.

The fastest path

createRouter({ model: Product, legacyMode: true });

That restores 2.x behaviour so you can deploy today — then remove it one option at a time. legacyMode re-enables every vulnerability below and is scheduled for removal in 4.0. The full guide is in MIGRATION.md.

Constructor form

// Still supported, deprecated
new ControllerSets(Model, '-createdAt', ['category'], ['name']);

// Preferred — and required for any 3.0 option
new ControllerSets({ model: Model, orderBy: '-createdAt', query: ['category'] });

Every option

The complete list, with defaults.

Controller options

Accepted by createRouter, createRouterS3upload and the ControllerSets constructor alike.

Router-only options

Exports

Every query parameter

Everything GET / understands.

Putting several together

# featured laptops between 500 and 1500, cheapest first, second page of 20
GET /api/products
      ?isFeatured=true
      &s=laptop
      &rangeField=price&range=500-1500
      &sort=price
      &page=2&pageSize=20

Filters combine with AND. The search term is the one exception: it becomes an OR across your search fields, and that whole group is ANDed with everything else.

Response shapes

Four shapes, and success is always there to branch on.

// GET /api/products
{
  "success": true,
  "data": [ { "_id": "65af…", "name": "Laptop", "price": 1299 } ]
}

// GET /api/products?page=2&pageSize=20
{
  "success": true,
  "data": [ /* … */ ],
  "pagination": {
    "currentPage": 2,
    "pageSize": 20,
    "totalPages": 7,
    "totalRecords": 132
  }
}

// GET /api/products/65af…   ·   POST /api/products   ·   PATCH /api/products/65af…
{
  "success": true,
  "data": { "_id": "65af…", "name": "Laptop", "price": 1299 }
}

// DELETE /api/products/65af…
{ "success": true, "message": "Item successfully deleted." }

// Any failure
{ "success": false, "error": "Entry not found.", "requestId": "0f2a…" }

const res  = await fetch('/api/products?page=1');
const body = await res.json();

if (!body.success) throw new Error(body.error);
body.data;                    // always an array here
body.pagination.totalPages;   // present because ?page was sent

TypeScript

Type declarations ship with the package. Nothing to install.

import express from 'express';
import { createRouter, errorHandler, type RouterOptions } from 'express-controller-sets';
import Product, { type IProduct } from './models/Product.js';

const options: RouterOptions<IProduct> = {
  model: Product,
  orderBy: '-createdAt',
  query: ['category'],
  allowedFields: ['name', 'price'],
  onGet: async (req, res) => ({ populates: 'category', selects: 'name price' }),
};

const app = express();
app.use('/api/products', createRouter(options));
app.use(errorHandler);

Exported types you'll reach for: ControllerOptions, RouterOptions, RouterS3Options, UploadOptions, UploadField, OnGetFn, OnGetResult, FieldPolicy, ImageOptimizationLevel and Logger.

Custom routes

When the five generated endpoints aren't quite the shape you need.

Use the handlers on your own router

Every controller method is a plain Express handler, so you can mount them individually — different middleware per verb, extra routes alongside, whatever you like.

import express from 'express';
import { ControllerSets } from 'express-controller-sets';
import Product from './models/Product.js';

const controller = new ControllerSets({
  model: Product,
  query: ['category'],
  allowedFields: ['name', 'price'],
});

const router = express.Router();

router.get('/',      controller.getAll);                    // public
router.get('/:id',   controller.getById);                   // public
router.post('/',     requireAuth, controller.create);       // staff only
router.patch('/:id', requireAuth, controller.update);
router.delete('/:id', requireAuth, requireAdmin, controller.delete);

// …and add whatever the generated set doesn't cover
router.get('/:id/related', myOwnHandler);

export default router;

Add routes to a generated router

A generated router is an ordinary Express router. Mount your own routes on the same path — declare the more specific ones first so they aren't captured by /:id.

const extras = express.Router();
extras.get('/featured', listFeatured);      // would otherwise hit /:id

app.use('/api/products', extras);
app.use('/api/products', createRouter({ model: Product }));

Uploads without CRUD

import { fileUploadMiddleware } from 'express-controller-sets';

const upload = (req, res, next) => fileUploadMiddleware(req, res, next, {
  uploadPath: 'invoices/',
  fields: [{ name: 'invoice', maxCount: 1 }],
  allowedMimeTypes: ['application/pdf'],
  maxFileSize: 2 * 1024 * 1024,
});

app.post('/api/invoices', requireAuth, upload, (req, res) => {
  res.json({ url: req.body.invoice });   // already uploaded and validated
});

Common questions

The things people hit in the first hour.