{"id":23010132,"url":"https://github.com/hodfords-solutions/nestjs-response","last_synced_at":"2025-04-07T17:07:47.137Z","repository":{"id":265404545,"uuid":"618188430","full_name":"hodfords-solutions/nestjs-response","owner":"hodfords-solutions","description":"Standardizes and validates API responses in NestJS for consistent and reliable communication","archived":false,"fork":false,"pushed_at":"2025-03-18T07:57:30.000Z","size":627,"stargazers_count":43,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-31T16:19:38.530Z","etag":null,"topics":["nestjs","nodejs","response"],"latest_commit_sha":null,"homepage":"https://opensource.hodfords.uk/nestjs-response","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hodfords-solutions.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-03-23T23:50:57.000Z","updated_at":"2025-03-18T07:57:01.000Z","dependencies_parsed_at":"2025-02-28T04:25:03.566Z","dependency_job_id":null,"html_url":"https://github.com/hodfords-solutions/nestjs-response","commit_stats":null,"previous_names":["hodfords-solutions/nestjs-response"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hodfords-solutions%2Fnestjs-response","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hodfords-solutions%2Fnestjs-response/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hodfords-solutions%2Fnestjs-response/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hodfords-solutions%2Fnestjs-response/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hodfords-solutions","download_url":"https://codeload.github.com/hodfords-solutions/nestjs-response/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247694876,"owners_count":20980733,"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":["nestjs","nodejs","response"],"created_at":"2024-12-15T09:17:02.230Z","updated_at":"2025-04-07T17:07:47.095Z","avatar_url":"https://github.com/hodfords-solutions.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"http://opensource.hodfords.uk\" target=\"blank\"\u003e\u003cimg src=\"https://opensource.hodfords.uk/img/logo.svg\" width=\"320\" alt=\"Nest Logo\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\nNestjs-Response is a simple yet powerful library for managing API responses in a NestJS application. It provides decorators to handle response models, allowing easy integration with Swagger for API documentation and validation.\n\u003c/p\u003e\n\n## Installation 🤖\n\nTo begin using it, we first install the required dependencies.\n\n```\nnpm install @hodfords/nestjs-response\n```\n\n## Interceptor Setup 🚀\n\n- `Global Interceptor (Recommended):`\n\nGlobal interceptors are applied across the entire application. To set up a global interceptor, you can register it in the providers array in your module.\n\n```typescript\nimport { APP_INTERCEPTOR } from '@nestjs/core';\nimport { ResponseInterceptor } from '@hodfords/nestjs-response';\n\n@Module({\n    providers: [\n        {\n            provide: APP_INTERCEPTOR,\n            useClass: ResponseInterceptor\n        }\n    ]\n})\nexport class AppModule {}\n```\n\n- `Interceptor with Decorator:`\n\nFor microservices or specific scenarios, use the @UseInterceptors decorator to apply interceptors at the controller or method level. However, it's generally recommended to use global interceptors.\n\n```typescript\nimport { Controller } from '@nestjs/common';\nimport { UseResponseInterceptor } from '@hodfords/nestjs-response';\n\n@Controller()\n@UseResponseInterceptor()\nexport class AppController {}\n```\n\n## Usage 🚀\n\n`@ResponseModel()`\n\nUse the @ResponseModel decorator when an API return single response type.\n\nParameter:\n\n- `responseClass`: The class that defines the response model.\n- `isArray` (optional): Set to `true` if the response is an array of `responseClass`. Defaults to `false`.\n- `isAllowEmpty` (optional): Set to true if the response can be empty. Defaults to `false`.\n\nExample of usage:\n\n```typescript\nimport { ResponseModel } from '@hodfords/nestjs-response';\nimport { Get } from '@nestjs/common';\nimport { IsNotEmpty, IsString } from 'class-validator';\n\nclass UserResponse {\n    @IsNotEmpty()\n    @IsString()\n    name: string;\n}\n\nexport class UserController {\n    @Get()\n    @ResponseModel(UserResponse, true)\n    getAllUser() {\n        return [{ name: 'John' }];\n    }\n}\n```\n\n`@ResponseModels()`\n\nUse the @ResponseModels decorator when an API might return multiple response types.\n\nParameter:\n\n- `...responseClasses`: A list of response classes or arrays of response classes.\n\nExample of usage:\n\n```typescript\nimport { ResponseModels } from '@hodfords/nestjs-response';\nimport { Controller, Get, Param } from '@nestjs/common';\nimport { UserResponse } from './responses/user.response';\nimport { UserPaginationResponse } from './responses/user-pagination.response';\n\n@Controller()\nexport class AppController {\n    @Get('list-models/:type')\n    @ResponseModels(Number, [Number], UserPaginationResponse, [UserResponse], undefined, null)\n    getModels(@Param('type') type: string) {\n        if (type == 'undefined') {\n            return undefined;\n        }\n        if (type == 'pagination') {\n            return {\n                items: [{ name: 'John' }, { name: 'Daniel' }],\n                total: 2,\n                lastPage: 1,\n                perPage: 10,\n                currentPage: 1\n            };\n        }\n        if (type == 'multiple') {\n            return [{ name: 'John' }, { name: 'Daniel' }];\n        }\n        if (type == 'list-number') {\n            return [123, 456];\n        }\n        if (type == 'number') {\n            return 456;\n        }\n        return null;\n    }\n}\n\n```\n\n### Exception Handling\n\nWhen the response data does not match the expected model, a validation exception will be raised. This ensures that the API returns data conforming to the defined structure.\n\nExample Case: If a property is expected to be a string, but a number is returned, a validation error will occur.\n\n```typescript\nimport { ResponseModel } from '@hodfords/nestjs-response';\nimport { Get } from '@nestjs/common';\nimport { IsString } from 'class-validator';\n\nclass UserResponse {\n    @IsString()\n    name: string;\n}\n\nexport class UserController {\n    @Get()\n    @ResponseModel(UserResponse)\n    getUser() {\n        return { name: 123 }; // Error: name must be a number ...\n    }\n}\n\n```\n\n## License\n\nThis project is licensed under the MIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhodfords-solutions%2Fnestjs-response","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhodfords-solutions%2Fnestjs-response","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhodfords-solutions%2Fnestjs-response/lists"}