npm package: @rjavlonn/toolkit
Description: Nest js tool kit
Latest version: 1.0.0

# Nest toolkit

Nest utils library


----------------------------------------
## `@Output()` Decorator

`@Output({...})` allows you to customize data returned by the controller layer.  
It combines the usage of `@SerializeOptions({...})` and `@UseInterceptors(...)`.

> For a better understanding of how SerializeOptions and UseInterceptors work, 
> checkout the documentation on the official NestJS Website.


### Configuration
To configure the output you can provide 3 properties:  

| key | Type   | description  |   
|---|---|---|
| class  | Function  | The decorated DTO Class you want to use.  |
|   transform | TransformOptions?  | `class-transformer` transform options |
|   validate | ValidationOptions?   |  `class-validator`  validation options |



### Usage
`@Output({...})` decorator is a *method* decorator for controllers only:

```typescript
    @Get('/:id/endpoint')
    @Output({
        class: ResourceDTO,
        transform: {
            groups: [Groups.Public],
            excludeExtraneousValues: true
        },
        transform: {
            always: true
        }
    })
    public async method(
        @Param('id') id: string,
        @Criteria() criteria?: QueryCriteria<Resource>,
    ): Promise<Resource> {
        criteria = criteria || new QueryCriteria<Resource>({
            survey: { id }
        });

        return await this.resourceService.one(criteria);
    }
}
```

----------------------------------------
## `@Catch` Decorator

### Default use case

From your custom controller :

```typescript
class ControllerA {
    get() {
        try {
            // find data
        } catch (e) {
            throw new InternalServerErrorException(e);
        }
    }
}
```

You can now use the `Catch` decorator, by default it will map an `InternalServerErrorException` 

```typescript
class ControllerA {
    @Catch()
    get() {
        // find data
    }
}
```

### Classic use case

From your custom controller :

```typescript
class ControllerA {
    get() {
        try {
            // find data
        } catch (e) {
            if (e instanceof MyCustomErrorA)
                throw new ConflictException(e);
            if (e instanceof MyCustomErrorB)
                throw new NotFoundException(e);
            throw InternalServerErrorException(e);
        }
    }
}
```

You can now use the `Catch` decorator.
  

```typescript
class ControllerA {
    @Catch({
        [MyCustomErrorA.name]: ConflictException,
        [MyCustomErrorB.name]: NotFoundException
    })
    get() {
        // find data
    }
}
```

If `MyCustomErrorA` is throws, it will be mapped on `ConflictException`

If `MyCustomErrorB` is throws, it will be mapped on `NotFoundException`

Others will be mapped on `InternalServerErrorException`

### Advanced use case

From your custom controller :

```typescript
class ControllerA {
    get() {
        try {
            // find data
        } catch (e) {
            if (e instanceof MyCustomErrorA) {
                console.log('Show me what you got.');
                throw new ConflictException(e);            
            }
            if (e instanceof MyCustomErrorB)
                throw new NotFoundException(e);
            throw InternalServerErrorException(e);
        }
    }
}
```

You can now use the `Catch` decorator.

```typescript
class HTTPExceptionFactory implements IHttpExceptionFactory {
    public create(e) {
        console.log('Show me what you got.');
        return new ConflictException(e);
    }
}

class ControllerA {
    @Catch({
        [MyCustomErrorA.name]: HTTPExceptionFactory,
        [MyCustomErrorB.name]: NotFoundException
    })
    get() {
        // find data
    }
}
```

If `MyCustomErrorA` is throws, it will be mapped on `HTTPExceptionFactory` and then call the `create` method. Here you can customize your business rules related to the error.

If `MyCustomErrorB` is throws, it will be mapped on `NotFoundException`

Others will be mapped on `InternalServerErrorException`

### Configuration
The second parameter of the decorator takes a `CatchOption` configuration object with the following properties :


| key                      | Type       | Default | description                                                                                     |   
|--------------------------|------------|---------|-------------------------------------------------------------------------------------------------|
| reply                    | Boolean    | `true`  | Use an `ExceptionFilter` to reply to the incoming `HttpRequest` with the mapped `HttpException` |
| logClientErrorsAsWarning | Boolean    | `false` | Will use `logger.warn` event for errors mapped to _client errors_ HTTP codes                    |