{"id":19529112,"url":"https://github.com/thre4dripper/nodets-express-service-based-template","last_synced_at":"2025-04-26T11:34:15.694Z","repository":{"id":214502777,"uuid":"736678169","full_name":"Thre4dripper/NodeTs-Express-Service-Based-Template","owner":"Thre4dripper","description":"Node + Typescript + Express + Sequelize + Mongoose + Validations + Socket + CronJobs + Docker + Swagger + Service Based Template","archived":false,"fork":false,"pushed_at":"2024-10-17T13:17:20.000Z","size":211,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-19T18:30:35.354Z","etag":null,"topics":["cronjob","db2","docker","expressjs","mariadb","mongo","mongoose","mysql","nodejs","orcale","postgres","sequence","snowflake","socket","sqlite","swagger-ui","typescript","validation"],"latest_commit_sha":null,"homepage":"","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}},"created_at":"2023-12-28T15:02:54.000Z","updated_at":"2024-10-17T13:17:24.000Z","dependencies_parsed_at":"2024-01-07T14:23:06.048Z","dependency_job_id":"dfbd99bf-513a-4e1d-98ab-1b1b8dddf364","html_url":"https://github.com/Thre4dripper/NodeTs-Express-Service-Based-Template","commit_stats":{"total_commits":60,"total_committers":1,"mean_commits":60.0,"dds":0.0,"last_synced_commit":"dcfda95fb933c0bb0f6177d35d8956e423459d08"},"previous_names":["thre4dripper/nodets-express-service-based-template"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thre4dripper%2FNodeTs-Express-Service-Based-Template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thre4dripper%2FNodeTs-Express-Service-Based-Template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thre4dripper%2FNodeTs-Express-Service-Based-Template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Thre4dripper%2FNodeTs-Express-Service-Based-Template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Thre4dripper","download_url":"https://codeload.github.com/Thre4dripper/NodeTs-Express-Service-Based-Template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224033291,"owners_count":17244569,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["cronjob","db2","docker","expressjs","mariadb","mongo","mongoose","mysql","nodejs","orcale","postgres","sequence","snowflake","socket","sqlite","swagger-ui","typescript","validation"],"created_at":"2024-11-11T01:22:03.166Z","updated_at":"2024-11-11T01:22:04.265Z","avatar_url":"https://github.com/Thre4dripper.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NodeTs-Express-Service-Based-Template\n\n![Node](https://img.shields.io/badge/-Node-339933?style=flat-square\u0026logo=Node.js\u0026logoColor=white)\n![TypeScript](https://img.shields.io/badge/-TypeScript-007ACC?style=flat-square\u0026logo=TypeScript\u0026logoColor=white)\n![Express](https://img.shields.io/badge/-Express-000000?style=flat-square\u0026logo=Express\u0026logoColor=white)\n![Sequelize](https://img.shields.io/badge/-Sequelize-52B0E7?style=flat-square\u0026logo=Sequelize\u0026logoColor=white)\n![MySQL](https://img.shields.io/badge/-MySQL-4479A1?style=flat-square\u0026logo=MySQL\u0026logoColor=white)\n![PostgresSQL](https://img.shields.io/badge/-PostgreSQL-336791?style=flat-square\u0026logo=PostgreSQL\u0026logoColor=white)\n![Sqlite](https://img.shields.io/badge/-Sqlite-003B57?style=flat-square\u0026logo=Sqlite\u0026logoColor=white)\n![MariaDB](https://img.shields.io/badge/-MariaDB-003545?style=flat-square\u0026logo=MariaDB\u0026logoColor=white)\n![MSSql](https://img.shields.io/badge/-MSSql-CC2927?style=flat-square\u0026logo=Microsoft-SQL-Server\u0026logoColor=white)\n![DB2](https://img.shields.io/badge/-DB2-CC0000?style=flat-square\u0026logo=IBM\u0026logoColor=white)\n![Snowflake](https://img.shields.io/badge/-Snowflake-00BFFF?style=flat-square\u0026logo=Snowflake\u0026logoColor=white)\n![Oracle](https://img.shields.io/badge/-Oracle-F80000?style=flat-square\u0026logo=Oracle\u0026logoColor=white)\n![Mongoose](https://img.shields.io/badge/-Mongoose-880000?style=flat-square\u0026logo=Mongoose\u0026logoColor=white)\n![MongoDB](https://img.shields.io/badge/-MongoDB-47A248?style=flat-square\u0026logo=MongoDB\u0026logoColor=white)\n![Validations](https://img.shields.io/badge/-Validations-FF0000?style=flat-square)\n![Socket](https://img.shields.io/badge/-Socket-FF6900?style=flat-square\u0026logo=Socket.io\u0026logoColor=white)\n![Docker](https://img.shields.io/badge/-Docker-2496ED?style=flat-square\u0026logo=Docker\u0026logoColor=white)\n![Swagger](https://img.shields.io/badge/-Swagger-85EA2D?style=flat-square\u0026logo=Swagger\u0026logoColor=white)\n![CronJobs](https://img.shields.io/badge/-CronJobs-00FFFF?style=flat-square)\n\nA fully configurable Node.js, Express, and TypeScript server template with a service-based architecture\nthat can interact with MySQL, PostgresSQL, Sqlite, MariaDB, MSSql, DB2, Snowflake, Oracle, MongoDB.\nOut-of-the-box validation, documentation generation, and\nmore.\n\n## Features\n\n- **Node.js, Express, TypeScript**: Robust server setup using Node.js, Express, and TypeScript.\n- **Sequelize**: Integration with Sequelize for SQL database operations.\n- **Mongoose**: Integration with Mongoose for MongoDB database operations.\n- **Database Compatibility**: Interact with MySQL, PostgreSQL, MariaDB, Sqlite, MSSql, MongoDB.\n- **Validation Mechanism**: Pre-built validations for request payloads.\n- **Automated Swagger Documentation**: Automatically generated documentation available at `/api-docs`.\n- **Service-Based Architecture**: Modular approach for better organization and scalability.\n- **Socket Events**: Socket event handling using Socket.io.\n- **Docker**: Dockerized for easy deployment.\n- **Cron Jobs**: Schedule tasks using cron jobs.\n\n## Modules\n\n### Automated Swagger Docs\n\n- Swagger documentation auto-generated for all routes.\n- Accessible at `/api-docs`.\n- Generated using the `doc` method in the `MasterController` class and Joi validation schemas.\n\n### MasterController (Heart of the application)\n\nThe `MasterController` is the backbone, providing functionalities for managing HTTP requests, socket events, payload\nvalidation, and more.\n\n#### Features\n\n- **Controller Logic Handling**: `restController` method manages HTTP requests.\n- **Socket Event Handling**: `socketController` method manages socket events.\n- **Cron Job Scheduling**: `cronController` method schedules cron jobs.\n- **Payload Validation**: `joiValidator` method validates incoming request payloads.\n- **Swagger Documentation Generation**: `doc` method generates Swagger documentation.\n- **Route Handling**: `get`, `post`, `put`, and `delete` methods register routes within the Express router.\n\n#### Usage\n\nExtend the `MasterController` to create controller classes for specific routes or socket events. Use the provided\nmethods for efficient request handling, validation, and documentation generation.\n\n## Installation\n\n### Automated (CLI Tool)\n\n\u003e Easily initialize a Node.js server project with custom configurations using our CLI tool:\n\u003e\n\u003e ```bash\n\u003e npx node-server-init \u003cfolder-name\u003e\n\u003e ```\n\u003e\n\u003e If you want to use the current directory as the project folder, run the following command:\n\u003e\n\u003e ```bash\n\u003e npx node-server-init .\n\u003e ```\n\u003e\n\u003e For more information, visit the [CLI Tool](https://www.npmjs.com/package/node-server-init) page or\n\u003e the [GitHub](https://github.com/Thre4dripper/node-server-init) repository.\n\n### Manual\n\n\u003e #### Clone this repo to your local machine using `\n\u003e\n\u003e ```bash\n\u003e $ git clone https://github.com/Thre4dripper/NodeTs-Express-Service-Based-Template\n\u003e ```\n\u003e #### Install dependencies\n\u003e\n\u003e ```bash\n\u003e $ npm install or yarn\n\u003e ```\n\u003e\n\u003e #### Start the server\n\u003e\n\u003e ```bash\n\u003e $ npm run dev or yarn dev\n\u003e ```\n\u003e\n\u003e #### Build the project\n\u003e\n\u003e ```bash\n\u003e $ npm run build or yarn build\n\u003e ```\n\u003e\n\u003e #### Run the project\n\u003e\n\u003e ```bash\n\u003e $ npm run start or yarn start\n\u003e ```\n\n### Database Setup\n\n\u003e Additional dependencies are required for database operations. Install the appropriate dependencies for your database\n\u003e dialect.\n\u003e\n\u003e #### MySQL\n\u003e\n\u003e ```bash\n\u003e $ npm install mysql2\n\u003e ```\n\u003e\n\u003e #### PostgreSQL\n\u003e\n\u003e ```bash\n\u003e $ npm install pg pg-hstore\n\u003e ```\n\u003e\n\u003e #### Sqlite\n\u003e\n\u003e ```bash\n\u003e $ npm install sqlite\n\u003e ```\n\u003e\n\u003e #### MariaDB\n\u003e\n\u003e ```bash\n\u003e $ npm install mariadb\n\u003e ```\n\u003e\n\u003e #### MSSql\n\u003e\n\u003e ```bash\n\u003e $ npm install tedious or mssql\n\u003e ```\n\u003e\n\u003e #### DB2\n\u003e\n\u003e ```bash\n\u003e $ npm install ibm_db\n\u003e ```\n\u003e\n\u003e #### Snowflake\n\u003e\n\u003e ```bash\n\u003e $ npm install snowflake-sdk\n\u003e ```\n\u003e\n\u003e #### Oracle\n\u003e\n\u003e ```bash\n\u003e $ npm install oracledb\n\u003e ```\n\u003e\n\u003e #### MongoDB\n\u003e\n\u003e ```bash\n\u003e $ npm install mongoose\n\u003e ```\n\n## Creating APIs\n\n### Controller\n\n```typescript\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        /* Comma separated middlewares */\n    ])\n    Controller.put(app, '/user/:id', [\n        /* Comma separated middlewares */\n    ])\n    Controller.delete(app, '/user/:id', [\n        /* Comma separated middlewares */\n    ])\n    Controller.patch(app, '/user/:id', [\n        /* Comma separated middlewares */\n    ])\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\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## Docker\n\n\u003e #### Docker Environment variables\n\u003e\n\u003e - `PORT` - Port number for the server to run on.\n\u003e - `DB_DIALECT` - Database dialect to use. (Options: mysql, postgres, mariadb, sqlite, mssql, mongodb)\n\u003e - `DB_HOST` - Database host.\n\u003e - `DB_PORT` - Database port.\n\u003e - `DB_USER` - Database username.\n\u003e - `DB_PASS` - Database password.\n\u003e - `DB_NAME` - Database name.\n\u003e - `MONGO_URI` - MongoDB URI (Only for MongoDB Dialect).\n\u003e - `JWT_SECRET` - Secret key for JWT.\n\u003e\n\u003e #### Build the image\n\u003e\n\u003e ```bash\n\u003e $ docker build -t \u003cimage-name\u003e .\n\u003e ```\n\u003e\n\u003e #### Run the container\n\u003e\n\u003e ```bash\n\u003e $ docker run -e \u003cenv-variable\u003e=\u003cvalue\u003e -p \u003cport\u003e:\u003cport\u003e \u003cimage-name\u003e\n\u003e ```\n\u003e\n\u003e #### Run the container in the background\n\u003e\n\u003e ```bash\n\u003e $ docker run -d -e \u003cenv-variable\u003e=\u003cvalue\u003e -p \u003cport\u003e:\u003cport\u003e \u003cimage-name\u003e\n\u003e ```\n\u003e\n\u003e #### Stop the container\n\u003e\n\u003e ```bash\n\u003e $ docker stop \u003ccontainer-id\u003e\n\u003e ```\n\u003e\n\u003e #### Remove the container\n\u003e\n\u003e ```bash\n\u003e $ docker rm \u003ccontainer-id\u003e\n\u003e ```\n\u003e\n\u003e #### Remove the image\n\u003e\n\u003e ```bash\n\u003e $ docker rmi \u003cimage-name\u003e\n\u003e ```\n\n### Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthre4dripper%2Fnodets-express-service-based-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthre4dripper%2Fnodets-express-service-based-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthre4dripper%2Fnodets-express-service-based-template/lists"}