createRouter

createRouter({
  // ── Model & response ──
  // required — the Mongoose model to serve
  model: Product,
  // default sort for lists ('-' = descending)
  orderBy: '-createdAt',
  // per-request populate & select on reads
  onGet: (req, res) => ({ populates: 'category', selects: '-secret' }),
  // true = plain objects: faster, but skips toJSON transforms
  lean: false,
  // where warnings go (pino, winston…)
  logger: console,

  // ── Filtering, search & sorting ──
  // exact-match filters: ?category=chairs
  query: ['category', 'inStock'],
  // fields ?s= searches; dotted = referenced model
  search: ['name', 'category.name'],
  // range/compare + QUERY filter fields (default: query)
  filterableFields: ['price', 'category'],
  // fields ?sort= accepts (default: query + orderBy)
  sortableFields: ['price', 'name', 'createdAt'],
  // longer search terms are a 400
  maxSearchLength: 128,
  // cap on ids a relational search pulls
  maxRelationMatches: 1000,
  // true = search terms run as regex — trusted callers only
  allowRawRegex: false,

  // ── Pagination & limits ──
  // 'offset' (page numbers) or 'cursor' (nextCursor)
  pagination: 'offset',
  // page size when the client sends none
  defaultPageSize: 50,
  // most documents any response returns
  maxLimit: 100,
  // deepest offset page allowed (default: off)
  maxPage: 500,
  // 'exact' | 'estimated' | 'none' — how totals are counted
  countStrategy: 'exact',
  // server-side time limit per query (default: off)
  maxTimeMS: 5000,
  // allow sorts over MongoDB's 100 MB memory limit
  allowDiskUse: false,
  // documents per driver round trip (default: driver's)
  batchSize: 1000,

  // ── Writing & validation ──
  // fields clients may write — or { create, update }
  allowedFields: ['name', 'price', 'category', 'inStock'],
  // fields clients may never write (wins over allowedFields)
  blockedFields: ['internalCode'],
  // checks writes before saving — { create, update } or one function for both
  validate: {
    // runs on POST — return an object to replace the payload, throw ValidationError to reject
    create: (payload, { req, res, operation, id, model }) => payload,
    // runs on PATCH — same contract
    update: (payload, ctx) => payload,
  },
  // side effect after a create, before the 201
  runAfterCreate: async (doc) => {},
  // true = a runAfterCreate failure becomes a 500
  strictAfterCreate: false,

  // ── Cache (Redis) ── or cache: true to use every default
  cache: {
    // seconds an entry lives (env CACHE_TTL)
    ttl: 60,
    // Redis connection URL (env REDIS_URL)
    url: process.env.REDIS_URL,
    // reuse an existing ioredis / node-redis client instead of url
    client: undefined,
    // any { get, set } store, e.g. createMemoryCacheStore()
    store: undefined,
    // key prefix, to share one Redis (env CACHE_PREFIX)
    prefix: 'cs:',
    // what else a response depends on (default: signed-in user)
    vary: (req) => req.auth?.userId,
    // give up on the cache and use the database after this
    timeoutMs: 150,
    // override the router part of the key (default: mount path)
    namespace: undefined,
  },

  // ── Router ──
  // guards run before every route (auth, rate limit…)
  middlewares: [],
  // mount the QUERY / route (needs Node 22.2+)
  enableQuery: true,
  // restore unsafe 2.x behaviour — migration only, removed in 4.0
  legacyMode: false,

  // ── File upload ── off when omitted; upload: true uses every default
  upload: {
    // folder (key prefix) in the bucket
    path: 'products/',
    // form fields that carry files (default: one field named 'file')
    fields: [
      // one file → saved as a URL string
      { name: 'cover', maxCount: 1 },
      // several files → saved as an array of URLs
      { name: 'gallery', maxCount: 6 },
      // saved as { url } instead of a string
      { name: 'manual', maxCount: 1, formatToUrlObject: true },
    ],
    // 'private' or 'public-read' (URL opens in a browser)
    acl: 'private',
    // checked from the file's bytes
    allowedMimeTypes: ['image/jpeg', 'image/png', 'image/webp', 'application/pdf'],
    // bytes per file (default 10 MB)
    maxFileSize: 10 * 1024 * 1024,
    // files per request
    maxFiles: 10,
    // 'low' | 'medium' | 'high' compression (needs sharp; default off)
    imgOptimizations: 'medium',
    // true = clients pick the level — costs CPU
    allowClientImageOptions: false,
  },
});

createRouter({
  model: Product,
  query: ['category', 'inStock'],
  search: ['name', 'description', 'brand.name'],
  filterableFields: ['price', 'category'],
  sortableFields: ['price', 'name', 'createdAt'],
  allowedFields: ['name', 'price'],
});

createRouter({
  model: Event,
  orderBy: '-createdAt',
  pagination: 'cursor',       // clients follow pagination.nextCursor
  defaultPageSize: 25,
  maxLimit: 200,
  maxTimeMS: 2000,
  allowedFields: [],
});

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

createRouter({
  model: Post,
  allowedFields: { create: ['title', 'body', 'slug'], update: ['title', 'body'] },
  blockedFields: ['views'],
  validate: {
    create: (payload, { req }) => {
      if (!payload.title?.trim()) throw new ValidationError('Check the fields.', { title: 'is required' });
      return { ...payload, author: req.auth.userId };       // server-owned field
    },
  },
  runAfterCreate: async (post) => notifySubscribers(post),
});

createRouter({ model: Product, cache: { ttl: 300 }, allowedFields: ['name', 'price'] });

// Anyone can read; only admins can write — two routers, one model
const readOnly = (req, res, next) =>
  ['GET', 'HEAD', 'OPTIONS', 'QUERY'].includes(req.method)
    ? next()
    : res.status(405).json({ success: false, error: 'Method not allowed.' });

app.use('/api/products', createRouter({ model: Product, middlewares: [readOnly], allowedFields: [] }));
app.use('/api/admin/products', createRouter({
  model: Product,
  middlewares: [auth.requireAuth, auth.requireRole('admin')],
  allowedFields: ['name', 'price'],
}));

npm install multer @aws-sdk/client-s3     # plus sharp for image compression

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

createRouter({
  // Every option above works here too, for example:
  model: Product,
  middlewares: [auth.requireAuth],
  allowedFields: ['name', 'price', 'cover', 'gallery'],   // include the file fields

  upload: {
    path: 'products/',                                    // folder in the bucket
    fields: [
      { name: 'cover', maxCount: 1 },                     // saved as a URL string
      { name: 'gallery', maxCount: 6 },                   // saved as an array of URLs
      { name: 'manual', maxCount: 1, formatToUrlObject: true },  // saved as { url }
    ],
    imgOptimizations: 'medium',                           // 'low' | 'medium' | 'high' (needs sharp)
    acl: 'private',                                       // or 'public-read'
    allowedMimeTypes: ['image/jpeg', 'image/png', 'image/webp', 'application/pdf'],
    maxFileSize: 10 * 1024 * 1024,                        // per file, bytes
    maxFiles: 10,                                         // per request
    allowClientImageOptions: false,
  },
});

{ "success": true,
  "data": { "_id": "65af…", "name": "Chair", "price": 120,
            "cover": "https://s3.us-east-1.amazonaws.com/acme-uploads/products/1726…-51234.jpg",
            "gallery": ["https://…/products/1726…-11.jpg", "https://…/products/1726…-12.jpg"] } }

// 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"         // ✘ MongoDB syntax        → dropped
}
// What reaches the database:
{ "name": "Ayesha", "email": "ayesha@example.com" }

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

createRouter({
  model: Product,
  middlewares: [auth.requireAuth],
  allowedFields: { create: ['name', 'price', 'sku'], update: ['name', 'price'] },   // sku is set once
  validate: {
    create: async (payload, { req, model }) => {
      if (payload.price !== undefined && !(payload.price >= 0)) {
        throw new ValidationError('Check the submitted values.', { price: 'must be zero or more' });
      }
      if (await model.exists({ sku: payload.sku })) {
        throw new ValidationError('That SKU is taken.', { sku: 'already in use' });
      }
      // Returning an object replaces the payload: normalise, and set server-owned fields.
      return {
        ...payload,
        ...(payload.name ? { name: payload.name.trim() } : {}),
        ownerId: req.auth.userId,
      };
    },
    update: (payload) => {
      if (payload.price === 0) throw new ValidationError('Price cannot be zero.');
    },
  },
});

// 400 Bad Request
{ "success": false, "error": "Check the submitted values.", "fields": { "price": "must be zero or more" } }

createRouter({
  model: User,
  allowedFields: ['name', 'email'],
  runAfterCreate: async (user) => {
    await queue.add('send-welcome', { id: user._id });
  },
});

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

// Schema: eventSchema.index({ createdAt: -1, _id: -1 });

createRouter({
  model: Event,
  orderBy: '-createdAt',
  pagination: 'cursor',
  defaultPageSize: 25,
  maxTimeMS: 2000,            // a slow query is cut off, not left running
  allowedFields: [],
});

const products = express.Router();

products.get('/stats', async (req, res) => {
  const [row] = await Product.aggregate([{ $group: { _id: null, avg: { $avg: '$price' }, n: { $sum: 1 } } }]);
  res.json({ success: true, data: row ?? { avg: 0, n: 0 } });
});

products.use(createRouter({ model: Product, allowedFields: ['name', 'price'] }));

app.use('/api/products', products);   // GET /api/products/stats + the six generated routes