@hodfords/nestjs-response 10.2.0 → 10.2.2

package/README.md

@@ -0,0 +1,151 @@
+<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
+@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';
+
+class UserResponse {
+    @ApiProperty()
+    @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 { ResponseModel } from '@hodfords/nestjs-response';
+
+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
+class UserResponse {
+    @ApiProperty()
+    @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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hodfords/nestjs-response",
-  "version": "10.2.0",
+  "version": "10.2.2",
   "description": "Standardizes and validates API responses in NestJS for consistent and reliable communication",
   "author": "",
   "license": "UNLICENSED",