Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/hodfords-solutions/nestjs-response
Standardizes and validates API responses in NestJS for consistent and reliable communication
https://github.com/hodfords-solutions/nestjs-response
nestjs nodejs response
Last synced: 1 day ago
JSON representation
Standardizes and validates API responses in NestJS for consistent and reliable communication
- Host: GitHub
- URL: https://github.com/hodfords-solutions/nestjs-response
- Owner: hodfords-solutions
- Created: 2023-03-23T23:50:57.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-11-29T08:10:54.000Z (about 1 month ago)
- Last Synced: 2025-01-01T20:06:27.202Z (8 days ago)
- Topics: nestjs, nodejs, response
- Language: TypeScript
- Homepage: https://opensource.hodfords.uk/nestjs-response
- Size: 825 KB
- Stars: 43
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
Nestjs-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.
## Installation 🤖
To begin using it, we first install the required dependencies.
```
npm install @hodfords/nestjs-response
```
## Interceptor Setup 🚀
- `Global Interceptor (Recommended):`
Global interceptors are applied across the entire application. To set up a global interceptor, you can register it in the providers array in your module.
```typescript
import { APP_INTERCEPTOR } from '@nestjs/core';
import { ResponseInterceptor } from '@hodfords/nestjs-response';
@Module({
providers: [
{
provide: APP_INTERCEPTOR,
useClass: ResponseInterceptor
}
]
})
export class AppModule {}
```
- `Interceptor with Decorator:`
For 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.
```typescript
import { Controller } from '@nestjs/common';
import { UseResponseInterceptor } from '@hodfords/nestjs-response';
@Controller()
@UseResponseInterceptor()
export class AppController {}
```
## Usage 🚀
`@ResponseModel()`
Use the @ResponseModel decorator when an API return single response type.
Parameter:
- `responseClass`: The class that defines the response model.
- `isArray` (optional): Set to `true` if the response is an array of `responseClass`. Defaults to `false`.
- `isAllowEmpty` (optional): Set to true if the response can be empty. Defaults to `false`.
Example of usage:
```typescript
import { ResponseModel } from '@hodfords/nestjs-response';
import { Get } from '@nestjs/common';
import { IsNotEmpty, IsString } from 'class-validator';
class UserResponse {
@IsNotEmpty()
@IsString()
name: string;
}
export class UserController {
@Get()
@ResponseModel(UserResponse, true)
getAllUser() {
return [{ name: 'John' }];
}
}
```
`@ResponseModels()`
Use the @ResponseModels decorator when an API might return multiple response types.
Parameter:
- `...responseClasses`: A list of response classes or arrays of response classes.
Example of usage:
```typescript
import { ResponseModels } from '@hodfords/nestjs-response';
import { Controller, Get, Param } from '@nestjs/common';
import { UserResponse } from './responses/user.response';
import { UserPaginationResponse } from './responses/user-pagination.response';
@Controller()
export class AppController {
@Get('list-models/:type')
@ResponseModels(Number, [Number], UserPaginationResponse, [UserResponse], undefined, null)
getModels(@Param('type') type: string) {
if (type == 'undefined') {
return undefined;
}
if (type == 'pagination') {
return {
items: [{ name: 'John' }, { name: 'Daniel' }],
total: 2,
lastPage: 1,
perPage: 10,
currentPage: 1
};
}
if (type == 'multiple') {
return [{ name: 'John' }, { name: 'Daniel' }];
}
if (type == 'list-number') {
return [123, 456];
}
if (type == 'number') {
return 456;
}
return null;
}
}
```
### Exception Handling
When 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.
Example Case: If a property is expected to be a string, but a number is returned, a validation error will occur.
```typescript
import { ResponseModel } from '@hodfords/nestjs-response';
import { Get } from '@nestjs/common';
import { IsString } from 'class-validator';
class UserResponse {
@IsString()
name: string;
}
export class UserController {
@Get()
@ResponseModel(UserResponse)
getUser() {
return { name: 123 }; // Error: name must be a number ...
}
}
```
## License
This project is licensed under the MIT License