# express-master-controller

> Master Controller with automated swagger docs creation for node express app

Latest version **1.2.2** (published 2026-07-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install express-master-controller
pnpm add express-master-controller
yarn add express-master-controller
bun add express-master-controller
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.2.2 |
| Published | 2026-07-10 |
| First published | 2024-01-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 10 |
| Unpacked size | 301.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 0 |
| Author | Ijlal Ahmad |
| Maintainers | thread-ripper |
| Keywords | Node, Express, Typescript, Swagger, Master-Controller, Joi |

## Links

- npm: https://www.npmjs.com/package/express-master-controller
- Repository: https://github.com/Thre4dripper/express-master-controller
- Homepage: https://github.com/Thre4dripper/express-master-controller#readme
- Issues: https://github.com/Thre4dripper/express-master-controller/issues
- npm.io page: https://npm.io/package/express-master-controller

## Dependencies (10)

- [joi](https://npm.io/package/joi.md) ^17.13.3
- [cron](https://npm.io/package/cron.md) ^3.1.7
- [pino](https://npm.io/package/pino.md) ^9.5.0
- [express](https://npm.io/package/express.md) ^4.21.1
- [socket.io](https://npm.io/package/socket.io.md) ^4.8.0
- [pino-pretty](https://npm.io/package/pino-pretty.md) ^11.3.0
- [@grpc/grpc-js](https://npm.io/package/@grpc/grpc-js.md) ^1.11.3
- [joi-to-swagger](https://npm.io/package/joi-to-swagger.md) ^6.2.0
- [reflect-metadata](https://npm.io/package/reflect-metadata.md) ^0.2.2
- [swagger-ui-express](https://npm.io/package/swagger-ui-express.md) ^5.0.1

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 1.2.2 (latest) — 2026-07-10
- 1.2.1 — 2026-07-10
- 1.2.0 — 2026-07-10
- 1.0.42 — 2024-12-29
- 1.0.41 — 2024-10-17
- 1.0.40 — 2024-10-16
- 1.0.39 — 2024-10-16
- 1.0.38 — 2024-10-15
- 1.0.37 — 2024-10-15
- 1.0.36 — 2024-10-14
- 1.0.35 — 2024-10-14
- 1.0.34 — 2024-10-14
- 1.0.33 — 2024-07-10
- 1.0.32 — 2024-05-01
- 1.0.31 — 2024-05-01
- … 13 more at https://npm.io/package/express-master-controller/versions

## README

# express-master-controller

express-master-controller is a powerful express middleware designed to help you create APIs and sockets super fast.
It is a master-controller-based express package that provides a streamlined way to manage your routes and socket events.
It also
automates the creation of Swagger documentation for your express application

## Features

- Easy creation of APIs and sockets
- Automated Swagger documentation
- Joi validation
- TypeScript support

## Installation

```bash
npm install express-master-controller
```

or

```bash
yarn add express-master-controller
```

## Initialization

```typescript
import { masterController } from 'express-master-controller';

const app = express();

app.use(
        masterController({
          // path to the routes directory (optional)
          routesFolder: path.join(__dirname, 'routes'),
          // path to the cron directory (optional)
          cronFolder: path.join(__dirname, 'cron'),
          // whether to enable sockets or not (optional)
          enableSockets: true,
          // swagger config (optional)
          swaggerConfig: {
            // swagger definition (required)
            title: 'API Documentation',
            description: 'API Documentation',
            version: '1.0.0',
            // swagger docs endpoint (optional)
            swaggerDocsEndpoint: '/api-docs',
            // if you want to give your swagger doc (optional)
            swaggerDocPath: path.join(__dirname, 'swagger.json'),
            // whether to modify your provided swagger doc or not (optional)
            modifySwaggerDoc: true,
          },
        }),
);

app.listen(3000, () => {
  console.log('Server started');
});
```

### masterController Parameters

- **routesFolder:** Absolute path to the routes directory (required)
- **swaggerConfig:** Swagger configuration (optional), if not provided, no swagger documentation will be generated
    - **title:** Swagger title (required)
    - **description:** Swagger description (required)
    - **version:** Swagger version (required)
    - **swaggerDocsEndpoint:** Swagger docs endpoint (optional), default: `/api-docs`
    - **swaggerDocPath:** Absolute path to the swagger doc file (optional)
    - **modifySwaggerDoc:** Whether to modify your provided swagger doc or not (optional), default: `false`

## Creating APIs

### Controller

```typescript
import {
    MasterController,
    RequestBuilder,
    ResponseBuilder,
} from 'express-master-controller';
import Joi from 'joi';

class Controller extends MasterController<IParams, IQuery, IBody> {
    // swagger documetation for the api
    static doc() {
        return {
            tags: ['User'],
            summary: 'Register User',
            description: 'Register User',
        };
    }

    // add your validations here,
    // rest of the swagger documentation will be generated automatically from the validation
    public static validate(): RequestBuilder {
        const payload = new RequestBuilder();

        // request body validation
        payload.addToBody(
            Joi.object().keys({
                name: Joi.string().required(),
                lastName: Joi.string().required(),
                email: Joi.string().email().required(),
                password: Joi.string().min(8).max(20).required(),
            }),
        );

        // request query validation
        payload.addToQuery(
            Joi.object().keys({
                limit: Joi.number().required(),
                offset: Joi.number().required(),
            }),
        );

        // request params validation
        payload.addToPath(
            Joi.object().keys({
                id: Joi.number().required(),
            }),
        );
        return payload;
    }

    // controller function
    async restController(
        params: IParams,
        query: IQuery,
        body: IBody,
        headers: any,
        allData: any): Promise<ResponseBuilder> {
        // your code here
        return new ResponseBuilder(200, Response, 'Success Message');
    }

    // socket controller function
    socketController(io: Server, socket: Socket, payload: any): void {
        // your code here
        // Socket data will be available in payload, recieved from the client on socket event, which is setup in the route file
        // You can emit data back to the client using io.emit or socket.emit
    }

    // cron controller function
    cronController(): void {
        // your scheduled code here (if any)
    }
}

export default Controller;
```

#### Controller Generics

- **IParams:** Request params interface/type
- **IQuery:** Request query interface/type
- **IBody:** Request body interface/type

#### restController Parameters

- **params:** Request params (eg. /user/:id)
- **query:** Request query (eg. /user?limit=10&offset=0)
- **body:** Request body
- **headers:** Request headers
- **allData:** All request data (all the above-combined + custom data from middlewares)

#### socketController Parameters

- **io:** Socket.io instance
- **socket:** Socket instance
- **payload:** Data sent from the client

### Router File

```typescript
import express from 'express'
import Controller from '../Controller'

export default (app: express.Application) => {
    // REST Routes
    Controller.get(app, '/user/:id', [
        /* Comma separated middlewares */
    ])
    Controller.post(app, '/user/:id', [])
    Controller.put(app, '/user/:id', [])
    Controller.delete(app, '/user/:id', [])
    Controller.patch(app, '/user/:id', [])

    // Socket Events
    // Any payload you send from the client to this event will be available in the socketController function
    Controller.socketIO('Event Name')
}
```

> **Important**: Make sure to name your router file as `*.routes.ts` or `*.routes.js`

> **Note:** You don't need to import your router file to anywhere,
> put it in the routes directory, and it will be automatically
> taken care by the package.

### Cron File

```typescript
import { MasterController, CronBuilder, CronMonth, CronWeekday } from 'express-master-controller';

class DemoCron extends MasterController<null, null, null> {
    cronController() {
        console.log('Cron job is running');
    }
}

// Unix Crontab format
DemoCron.cronJob('*/5 * * * * *');

// Using CronBuilder
DemoCron.cronJob(
    new CronBuilder()
    .every()
    .second()
    .every()
    .specificMinute([10, 20, 30])
    .every()
    .dayOfMonth(CronMonth.January)
    .every()
    .dayOfWeek(CronWeekday.Friday)
    .build(),
);
```

> **Important**: Make sure to name your cron file as `*.cron.ts` or `*.cron.js`

> **Note:** You don't need to import your cron file to anywhere,
> put it in cron directory, and it will be automatically
> taken care by the package.

### External Dependencies (You need to install these packages)

- [joi](https://www.npmjs.com/package/joi) (For validation)
- [socket.io](https://www.npmjs.com/package/socket.io) (For sockets)
- [cron](https://www.npmjs.com/package/cron) (For cron jobs)

---
_Source: https://npm.io/package/express-master-controller · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
