{"id":26679620,"url":"https://github.com/xhelpers/xhelpers-api","last_synced_at":"2025-08-16T13:34:26.510Z","repository":{"id":42272342,"uuid":"228101487","full_name":"xhelpers/xhelpers-api","owner":"xhelpers","description":"xhelpers-api is an open source project that enables developers to easily create and manage micro-services into their own environment","archived":false,"fork":false,"pushed_at":"2024-01-25T01:48:35.000Z","size":1616,"stargazers_count":12,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-04-26T09:46:51.375Z","etag":null,"topics":["jwt","nodejs","rest-api"],"latest_commit_sha":null,"homepage":"https://xhelpers.github.io/xhelpers-api/","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/xhelpers.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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":"2019-12-14T23:08:16.000Z","updated_at":"2024-04-26T00:45:11.000Z","dependencies_parsed_at":"2024-01-25T02:44:23.598Z","dependency_job_id":"ee1454db-6a5c-4a2d-86bc-1b81280735af","html_url":"https://github.com/xhelpers/xhelpers-api","commit_stats":{"total_commits":247,"total_committers":6,"mean_commits":"41.166666666666664","dds":0.6234817813765182,"last_synced_commit":"6101a2f0c135c419e801db8e6d7a9d0bd0605859"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xhelpers%2Fxhelpers-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xhelpers%2Fxhelpers-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xhelpers%2Fxhelpers-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xhelpers%2Fxhelpers-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xhelpers","download_url":"https://codeload.github.com/xhelpers/xhelpers-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248560202,"owners_count":21124613,"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":["jwt","nodejs","rest-api"],"created_at":"2025-03-26T06:16:57.906Z","updated_at":"2025-04-12T11:33:22.861Z","avatar_url":"https://github.com/xhelpers.png","language":"TypeScript","readme":"# xHelpers API\n\n[![npm](https://nodei.co/npm/xhelpers-api.png)](https://www.npmjs.com/package/xhelpers-api)\n\n[![Node.js Version](https://img.shields.io/node/v/xhelpers-api.svg?style=flat-square \"Node.js 18\")](http://nodejs.org/download/)\n[![hapi 21.3.0](https://img.shields.io/badge/hapi-21.3.0-brightgreen.svg?style=flat-square \"Latest Hapi.js\")](http://nodejs.org/download/)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/d4cf77276a6f463f9b1a097f5d0adcfc)](https://www.codacy.com/gh/wmkDev/xhelpers-api/dashboard?utm_source=github.com\u0026utm_medium=referral\u0026utm_content=wmkDev/xhelpers-api\u0026utm_campaign=Badge_Grade)\n[![Codacy Badge](https://app.codacy.com/project/badge/Coverage/d4cf77276a6f463f9b1a097f5d0adcfc)](https://www.codacy.com/gh/wmkDev/xhelpers-api/dashboard?utm_source=github.com\u0026utm_medium=referral\u0026utm_content=wmkDev/xhelpers-api\u0026utm_campaign=Badge_Coverage)\n\n![GitHub repo size](https://img.shields.io/github/repo-size/wmkdev/xhelpers-api)\n![GitHub issues](https://img.shields.io/github/issues/wmkdev/xhelpers-api)\n![GitHub pull requests](https://img.shields.io/github/issues-pr/wmkdev/xhelpers-api)\n![GitHub commit activity](https://img.shields.io/github/commit-activity/m/wmkdev/xhelpers-api)\n\n![Node.js Build](https://github.com/wmkDev/xhelpers-api/workflows/Node.js%20Build/badge.svg?branch=master)\n![npm](https://img.shields.io/npm/dw/xhelpers-api)\n[![HitCount](http://hits.dwyl.com/wmkdev/xhelpers-api.svg)](http://hits.dwyl.com/wmkdev/xhelpers-api)\n\n![GitHub package.json dynamic](https://img.shields.io/github/package-json/keywords/wmkdev/xhelpers-api)\n\n## Description\n\nxhelpers-api is an open-source project that aims to simplify the implementation of RESTful APIs. It provides a set of helper functions and plugins to help developers build efficient, secure, and scalable APIs. This documentation will guide you through the different sections and configurations of the project..\n\n- The project is a collection of libraries and tools that can be used to create and deploy micro-services. It has a comprehensive suite of features such as ORM/ODM (Sequelize, Mongoose), API SSL, API SSO (Github, Facebook, Google), API security (JWT, AppKey), API logging (AWS, Sentry), API documentation (Swagger), API queue operator (AMQP, RabbitMQ).\n\n- The project has a CLI tool with usefull functions, check it out: [xhelpers-cli](https://github.com/xhelpers/xhelpers-cli).\n\n- The project is actively maintained and updated to provide the best experience for developers. It is an open source project and anyone can contribute to it and help make it even better.\n\n### Stack\n\n- [TypeScript 4.9.5](https://www.typescriptlang.org/).\n- [Node.js 18.14.1](https://nodejs.org/).\n- [Hapi 21.3.10](https://hapi.dev/).\n- [Mongoose 8.9.5](https://mongoosejs.com/).\n- [Sequelize 6.37.4](https://sequelize.org/).\n\n## Roadmap\n\n- Improve documentation\n- Add more samples\n\n# Getting Started\n\nTo start using xhelpers-api in your project, you need to install it as a dependency:\n\n```bash\n$ npm i xhelpers-api\n```\n\n# Configuration\n\nxhelpers-api allows you to configure different aspects of your API, such as logging, database connections, and security settings. To configure these settings, you can use the options on the method `createServer`.\n\n## Example: Microservice API using xhelpers-api in a single file\n\nHere's an minified example of a microservice API using xhelpers-api:\n\n```js\nimport { createServer } from \"xhelpers-api/lib/server\";\nimport { BaseRouteSimple } from \"xhelpers-api/lib/route\";\nimport { Boom, uuid, Joi, dotenv } from \"xhelpers-api/lib/tools\";\n\ndotenv.config();\n\nclass RequestService {\n\tasync createJob(u: any, server: any): Promise\u003cstring | Boom.Boom\u003e {\n\t\treturn uuid.v4();\n\t}\n}\n\nclass Routes extends BaseRouteSimple {\n\tconstructor(private service = new RequestService()) {\n\t\tsuper([\"api\", \"Jobs\"]);\n\t\tthis.route(\"POST\", \"/api/jobs\", {}, false)\n\t\t\t.validate({\n\t\t\t\tpayload: Joi.object({\n\t\t\t\t\tid: Joi.string().required().description(\"id\"),\n\t\t\t\t}),\n\t\t\t})\n\t\t\t.handler(async (r, h, u) =\u003e {\n\t\t\t\tconst result = await this.service.createJob(u, r.server);\n\t\t\t\treturn Boom.isBoom(result) ? result : h.response(result).code(200);\n\t\t\t})\n\t\t\t.build();\n\t}\n}\n\nexport const start = async () =\u003e {\n\t// create hapijs server with xhelpers options\n\tconst server = await createServer({\n\t\tserverOptions: {},\n\t\toptions: {\n\t\t\tswaggerOptions: {\n\t\t\t\tinfo: {\n\t\t\t\t\ttitle: \"Minified demo\",\n\t\t\t\t\tversion: \"1.0\",\n\t\t\t\t},\n\t\t\t},\n\t\t\trouteOptions: { routes: \"\" },\n\t\t},\n\t});\n\t// register local routes\n\tserver.route(new Routes().buildRoutes());\n\t// start server\n\tserver.start();\n\treturn server;\n};\n\nstart();\n```\n\n## Key Components\n\n### createServer\n\nThe createServer function from the xhelpers-api/lib/server module is used to create a HapiJS server with the provided xhelpers-api options.\n\n```js\nimport { createServer } from \"xhelpers-api/lib/server\";\n```\n\n### BaseRouteSimple\n\nThe BaseRoute/BaseRouteSimple class from the xhelpers-api/lib/route module is used to define routes and their handlers. It provides a simple and organized way to manage routes.\n\n```js\nimport { BaseRouteSimple } from \"xhelpers-api/lib/route\";\n```\n\n### Tools\n\nThe xhelpers-api/lib/tools module provides a set of utilities and tools that simplify common tasks, such as generating UUIDs, validating payloads using Joi, and handling errors with Boom.\n\n```js\nimport { Boom, uuid, Joi, dotenv } from \"xhelpers-api/lib/tools\";\n```\n\n## Defining Services\n\nYou can define services by creating a class and implementing the required methods. In the example above, a RequestService class is defined with a createJob method.\n\n```js\nclass RequestService {\n  async createJob(u: any, server: any): Promise\u003cstring | Boom.Boom\u003e {\n    return uuid.v4();\n  }\n}\n```\n\n## Defining Routes\n\nRoutes can be defined by extending the BaseRoute/BaseRouteSimple class and implementing the required routes. In the example above, a Routes class is defined with a single route for creating a job.\n\n```js\nclass Routes extends BaseRouteSimple {\n\tconstructor(private service = new RequestService()) {\n\t\tsuper([\"api\", \"Jobs\"]);\n\t\tthis.route(\"POST\", \"/api/jobs\", {}, false)\n\t\t\t.validate({\n\t\t\t\tpayload: Joi.object({\n\t\t\t\t\tid: Joi.string().required().description(\"id\"),\n\t\t\t\t}),\n\t\t\t})\n\t\t\t.handler(async (r, h, u) =\u003e {\n\t\t\t\tconst result = await this.service.createJob(u, r.server);\n\t\t\t\treturn Boom.isBoom(result) ? result : h.response(result).code(200);\n\t\t\t})\n\t\t\t.build();\n\t}\n}\n```\n\n# Starting the Server\n\nThe server is started by calling the start function, which initializes the server with the provided options, registers the routes, and starts the server.\n\n```js\nconst server = await createServer({\n  serverOptions: {},\n  options: { routeOptions: { routes: \"\" } },\n});\nserver.start();\n```\n\n#### Output of running server:\n\n```code\nStarting Xhelpers Hapi server API\nSettings API: Mongoose disabled;\nSettings API: Sequelize disabled;\nSettings API: SSL disabled;\nSettings API: SSO disabled;\nSettings API: JWT disabled;\nSettings API: AppKey disabled;\nSettings API: CronJobs disabled;\nSettings API: Sentry disabled;\n====================================================================================================\n🆙  Server doc    : http://localhost:5000/documentation\n🆙  Server api    : http://localhost:5000/\n====================================================================================================\nRouting table:\n        🔎  get -       /documentation\n        🔎  get -       /swagger.json\n        🔎  get -       /health\n        🔎  get -       /liveness\n        📄  post -      /api/jobs\n====================================================================================================\n```\n\n## Default Routes\n\n```code\n🆙  Server doc    : http://127.0.0.1:5000/documentation\n🆙  Server health : http://127.0.0.1:5000/health\n🆙  Server health : http://127.0.0.1:5000/liveness\n```\n\n## Examples\n\nYou can find example code in the examples directory of the [xhelpers-api GitHub repository](https://github.com/xhelpers/xhelpers-api/network/dependents). These examples demonstrate how to use the different features and configurations of xhelpers-api in a real-world scenario.\n\nFeel free to explore these examples and use them as a reference when building your own APIs with xhelpers-api.\n\n# Building/Contributing\n\nContributions to xhelpers-api are welcome! Please refer to the CONTRIBUTING.md file for detailed guidelines on submitting pull requests, reporting issues, and more.\n\nIf you have any questions or need assistance, feel free to open an issue on the xhelpers-api GitHub repository.\n\n```bash\n# build tsc\n$ npm run build\n```\n\n## Test\n\n```bash\n$ npm run test\n```\n\n## Test Coverage\n\n```bash\n$ npm run test:coverage\n$ npm run cover:report\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxhelpers%2Fxhelpers-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxhelpers%2Fxhelpers-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxhelpers%2Fxhelpers-api/lists"}