-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update docs for nestjs-response: Merge pull request #17 from hodfords…
…-solutions/chore/update-package-json chore: update package json
- Loading branch information
1 parent
5d90cae
commit 37394a3
Showing
1 changed file
with
163 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,3 +1,165 @@ | ||
--- | ||
displayed_sidebar: docs | ||
--- | ||
title: "@hodfords/nestjs-response" | ||
--- | ||
<p align="center"> | ||
<a href="http://opensource.hodfords.uk" target="blank"><img src="https://opensource.hodfords.uk/img/logo.svg" width="320" alt="Nest Logo" /></a> | ||
</p> | ||
|
||
<p align="center"> | ||
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. | ||
</p> | ||
|
||
## 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 |