{"id":17277646,"url":"https://github.com/thre4dripper/express-master-controller","last_synced_at":"2026-02-14T07:01:22.880Z","repository":{"id":214983002,"uuid":"737572619","full_name":"Thre4dripper/express-master-controller","owner":"Thre4dripper","description":"Npm package for master controller based express package that can help you create apis and sockets super fast.","archived":false,"fork":false,"pushed_at":"2024-12-29T05:55:36.000Z","size":130,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-27T04:43:20.008Z","etag":null,"topics":["express","node","npm-package","rest-api","socket-io","swagger","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/express-master-controller","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Thre4dripper.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-12-31T15:18:42.000Z","updated_at":"2024-12-29T05:54:27.000Z","dependencies_parsed_at":"2024-01-02T13:09:06.653Z","dependency_job_id":"16d3fd5a-c1bd-444f-9d29-228cd72ebe8a","html_url":"https://github.com/Thre4dripper/express-master-controller","commit_stats":null,"previous_names":["thre4dripper/node-master-controller","thre4dripper/express-master-controller"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/Thre4dripper/express-master-controller","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thre4dripper%2Fexpress-master-controller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thre4dripper%2Fexpress-master-controller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thre4dripper%2Fexpress-master-controller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thre4dripper%2Fexpress-master-controller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Thre4dripper","download_url":"https://codeload.github.com/Thre4dripper/express-master-controller/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thre4dripper%2Fexpress-master-controller/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29438977,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T05:24:35.651Z","status":"ssl_error","status_checked_at":"2026-02-14T05:24:34.830Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["express","node","npm-package","rest-api","socket-io","swagger","typescript"],"created_at":"2024-10-15T09:09:36.583Z","updated_at":"2026-02-14T07:01:22.859Z","avatar_url":"https://github.com/Thre4dripper.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# express-master-controller\n\nexpress-master-controller is a powerful express middleware designed to help you create APIs and sockets super fast.\nIt is a master-controller-based express package that provides a streamlined way to manage your routes and socket events.\nIt also\nautomates the creation of Swagger documentation for your express application\n\n## Features\n\n- Easy creation of APIs and sockets\n- Automated Swagger documentation\n- Joi validation\n- TypeScript support\n\n## Installation\n\n```bash\nnpm install express-master-controller\n```\n\nor\n\n```bash\nyarn add express-master-controller\n```\n\n## Initialization\n\n```typescript\nimport { masterController } from 'express-master-controller';\n\nconst app = express();\n\napp.use(\n        masterController({\n          // path to the routes directory (optional)\n          routesFolder: path.join(__dirname, 'routes'),\n          // path to the cron directory (optional)\n          cronFolder: path.join(__dirname, 'cron'),\n          // whether to enable sockets or not (optional)\n          enableSockets: true,\n          // swagger config (optional)\n          swaggerConfig: {\n            // swagger definition (required)\n            title: 'API Documentation',\n            description: 'API Documentation',\n            version: '1.0.0',\n            // swagger docs endpoint (optional)\n            swaggerDocsEndpoint: '/api-docs',\n            // if you want to give your swagger doc (optional)\n            swaggerDocPath: path.join(__dirname, 'swagger.json'),\n            // whether to modify your provided swagger doc or not (optional)\n            modifySwaggerDoc: true,\n          },\n        }),\n);\n\napp.listen(3000, () =\u003e {\n  console.log('Server started');\n});\n```\n\n### masterController Parameters\n\n- **routesFolder:** Absolute path to the routes directory (required)\n- **swaggerConfig:** Swagger configuration (optional), if not provided, no swagger documentation will be generated\n    - **title:** Swagger title (required)\n    - **description:** Swagger description (required)\n    - **version:** Swagger version (required)\n    - **swaggerDocsEndpoint:** Swagger docs endpoint (optional), default: `/api-docs`\n    - **swaggerDocPath:** Absolute path to the swagger doc file (optional)\n    - **modifySwaggerDoc:** Whether to modify your provided swagger doc or not (optional), default: `false`\n\n## Creating APIs\n\n### Controller\n\n```typescript\nimport {\n    MasterController,\n    RequestBuilder,\n    ResponseBuilder,\n} from 'express-master-controller';\nimport Joi from 'joi';\n\nclass Controller extends MasterController\u003cIParams, IQuery, IBody\u003e {\n    // swagger documetation for the api\n    static doc() {\n        return {\n            tags: ['User'],\n            summary: 'Register User',\n            description: 'Register User',\n        };\n    }\n\n    // add your validations here,\n    // rest of the swagger documentation will be generated automatically from the validation\n    public static validate(): RequestBuilder {\n        const payload = new RequestBuilder();\n\n        // request body validation\n        payload.addToBody(\n            Joi.object().keys({\n                name: Joi.string().required(),\n                lastName: Joi.string().required(),\n                email: Joi.string().email().required(),\n                password: Joi.string().min(8).max(20).required(),\n            }),\n        );\n\n        // request query validation\n        payload.addToQuery(\n            Joi.object().keys({\n                limit: Joi.number().required(),\n                offset: Joi.number().required(),\n            }),\n        );\n\n        // request params validation\n        payload.addToParams(\n            Joi.object().keys({\n                id: Joi.number().required(),\n            }),\n        );\n        return payload;\n    }\n\n    // controller function\n    async restController(\n        params: IParams,\n        query: IQuery,\n        body: IBody,\n        headers: any,\n        allData: any): Promise\u003cResponseBuilder\u003e {\n        // your code here\n        return new ResponseBuilder(200, Response, 'Success Message');\n    }\n\n    // socket controller function\n    socketController(io: Server, socket: Socket, payload: any): void {\n        // your code here\n        // Socket data will be available in payload, recieved from the client on socket event, which is setup in the route file\n        // You can emit data back to the client using io.emit or socket.emit\n    }\n\n    // cron controller function\n    cronController(): void {\n        // your scheduled code here (if any)\n    }\n}\n\nexport default Controller;\n```\n\n#### Controller Generics\n\n- **IParams:** Request params interface/type\n- **IQuery:** Request query interface/type\n- **IBody:** Request body interface/type\n\n#### restController Parameters\n\n- **params:** Request params (eg. /user/:id)\n- **query:** Request query (eg. /user?limit=10\u0026offset=0)\n- **body:** Request body\n- **headers:** Request headers\n- **allData:** All request data (all the above-combined + custom data from middlewares)\n\n#### socketController Parameters\n\n- **io:** Socket.io instance\n- **socket:** Socket instance\n- **payload:** Data sent from the client\n\n### Router File\n\n```typescript\nimport express from 'express'\nimport Controller from '../Controller'\n\nexport default (app: express.Application) =\u003e {\n    // REST Routes\n    Controller.get(app, '/user/:id', [\n        /* Comma separated middlewares */\n    ])\n    Controller.post(app, '/user/:id', [])\n    Controller.put(app, '/user/:id', [])\n    Controller.delete(app, '/user/:id', [])\n    Controller.patch(app, '/user/:id', [])\n\n    // Socket Events\n    // Any payload you send from the client to this event will be available in the socketController function\n    Controller.socketIO('Event Name')\n}\n```\n\n\u003e **Important**: Make sure to name your router file as `*.routes.ts` or `*.routes.js`\n\n\u003e **Note:** You don't need to import your router file to anywhere,\n\u003e put it in the routes directory, and it will be automatically\n\u003e taken care by the package.\n\n### Cron File\n\n```typescript\nimport { MasterController, CronBuilder, CronMonth, CronWeekday } from 'express-master-controller';\n\nclass DemoCron extends MasterController\u003cnull, null, null\u003e {\n    cronController() {\n        console.log('Cron job is running');\n    }\n}\n\n// Unix Crontab format\nDemoCron.cronJob('*/5 * * * * *');\n\n// Using CronBuilder\nDemoCron.cronJob(\n    new CronBuilder()\n    .every()\n    .second()\n    .every()\n    .specificMinute([10, 20, 30])\n    .every()\n    .dayOfMonth(CronMonth.January)\n    .every()\n    .dayOfWeek(CronWeekday.Friday)\n    .build(),\n);\n```\n\n\u003e **Important**: Make sure to name your cron file as `*.cron.ts` or `*.cron.js`\n\n\u003e **Note:** You don't need to import your cron file to anywhere,\n\u003e put it in cron directory, and it will be automatically\n\u003e taken care by the package.\n\n### External Dependencies (You need to install these packages)\n\n- [joi](https://www.npmjs.com/package/joi) (For validation)\n- [socket.io](https://www.npmjs.com/package/socket.io) (For sockets)\n- [cron](https://www.npmjs.com/package/cron) (For cron jobs)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthre4dripper%2Fexpress-master-controller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthre4dripper%2Fexpress-master-controller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthre4dripper%2Fexpress-master-controller/lists"}