Mongoose + Express + Controllers + Routes + Formatters + Swagger + ReDoc + Command Line Interface

Usage no npm install needed!

<script type="module">
  import expressOn from '';


Express-on is a minimal MVC framework to easily turn mongodb collections into fully fledged RESTful services supporting all http verbs.

Express is the http framwork used to handle the REST service request/response using Mongoose as the ORM layer on top of mongodb and binds the http verbs to the Query operations.

HTTP Verbs

MVC Pattern

  • models folder contains the mongoose schemas/models that defines the object modelling for the document resides in an underlying mongodb collection, it is also used for document level validation and any other mongoose specific hooks as per the Document api, more on mongoose schemas
  • routes folders containes the http routes binding for different verbs to the underlying controllers method passing the http request query params along the request. more on Express router
  • controllers folder containes the business logic needed for each operation pre submitting the operation to mongodb by simply overrding any of base Controller implementation

Controller Class

Controller class is a base class with a constructor that takes the mongoose Model as the only parameter, and implements the following methods that can be overriden to implement any custom logic, checks, etc

Controller class implementation for the methods also handles the following query parameters that might present in the request url and invokes the relevant mongoose Query method

  • find={Object} specifies the mongodb selector. If not specified, returns all documents.
  • limit=Number specifies the maximum number of documents the query will return, defaults to 10, and return all when explicitly set to 0.
  • skip=Number specifies the number of documents to skip. useful for pagination when combined with limit.
  • count=Boolean set to true to count documents matching the mongodb selector if specified, otherwise returns the total count of documents
  • distinct=String specifies a single path to get the distict values of.
  • sort=String sets the sort order, it must be a space delimited list of path names. The sort order of each path is ascending unless the path name is prefixed with - which will be treated as descending.
  • select=String specifies which document fields to include or exclude, prefixing a path with - will flag that path as excluded. When a path does not have the - prefix, it is included.

Express Router

Express routers is used to bind the http requests to the underlying controller that implements the requested operation, example

Getting Started

Install with peer dependencies:

npm install --save express

npm install --save mongoose

npm install --save express-on

Edit package.json to add start script:

  "main": "node_modules/express-on",
  "scripts": {
    "start": "node_modules/.bin/express-on"

Create models\currencies.js with a basic Mongoose model:

const mongoose = require('mongoose')
let schema = new mongoose.Schema({
    _id: String,
    name: String,
    country: String
module.exports = mongoose.model('currency', schema,'currencies');

Create controllers\currencies.js with a basic controller

const Model = require('../models/currencies');
const { Controller } = require('express');

class CurrenciesController extends Controller {
    constructor() {

module.exports = CurrenciesController;

Create routers\index.js to bind http routes to controller methods

const Controller = require('../controllers/currencies');
const { Router } = require('express');

const controller = new Controller();
const router = Router();

router.delete('/currencies/:id', controller.findByIdAndDelete.bind(controller));
router.patch('/currencies/:id', controller.findByIdAndUpdate.bind(controller));
router.put('/currencies/:id', controller.findByIdAndReplace.bind(controller));
router.get('/currencies/:id', controller.findById.bind(controller));

router.delete('/currencies/', controller.deleteMany.bind(controller));
router.patch('/currencies/', controller.updateMany.bind(controller));'/currencies/', controller.insertMany.bind(controller));
router.put('/currencies/', controller.replaceMany.bind(controller));
router.get('/currencies/', controller.find.bind(controller));

module.exports = router;

Configure mongodb connection string:

set MONGO_URI=mongodb://localhost/test

Configure http port to liste on:

set PORT=80

Start via

npm start