https://github.com/thre4dripper/express-master-controller
Npm package for master controller based express package that can help you create apis and sockets super fast.
https://github.com/thre4dripper/express-master-controller
express node npm-package rest-api socket-io swagger typescript
Last synced: about 2 months ago
JSON representation
Npm package for master controller based express package that can help you create apis and sockets super fast.
- Host: GitHub
- URL: https://github.com/thre4dripper/express-master-controller
- Owner: Thre4dripper
- License: mit
- Created: 2023-12-31T15:18:42.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-12-29T05:55:36.000Z (5 months ago)
- Last Synced: 2025-04-14T09:14:09.628Z (about 2 months ago)
- Topics: express, node, npm-package, rest-api, socket-io, swagger, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/express-master-controller
- Size: 127 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
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 {
// 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.addToParams(
Joi.object().keys({
id: Joi.number().required(),
}),
);
return payload;
}
// controller function
async restController(
params: IParams,
query: IQuery,
body: IBody,
headers: any,
allData: any): Promise {
// 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 {
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)