Nestjs Joi

https://github.com/whefter/nestjs-joi
Admin
Nestjs Joi provides an easy-to-use JoiPipe as an interface between Joi and NestJS for...
Tokens:10,813
Snippets:66
Trust Score:6.3
License:MIT
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install nestjs-joi and peer dependencies

Source: https://github.com/whefter/nestjs-joi/blob/master/README.md

Installs the nestjs-joi package and its required peer dependencies, including specific versions of @nestjs/common, @nestjs/core, joi, and reflect-metadata.

```bash
npm install --save nestjs-joi
npm install --save @nestjs/common@^7 @nestjs/core@^7 joi@^17 reflect-metadata@^0.1
```

--------------------------------

### Install JoiPipe Globally with JoiPipeModule

Source: https://github.com/whefter/nestjs-joi/blob/master/README.md

Explains how to import `JoiPipeModule` to install `JoiPipe` as a global injection-enabled pipe. This is required for `JoiPipe` to determine the HTTP method and use built-in groups like CREATE and UPDATE.

```typescript
import { JoiPipeModule } from 'nestjs-joi';

@Module({
  controllers: [BookController],
  imports: [JoiPipeModule],
})
export class AppModule {}
```

```typescript
import { JoiPipe } from 'nestjs-joi';
import { APP_PIPE } from '@nestjs/core';

@Module({
  controllers: [BookController],
  providers: [
    {
      provide: APP_PIPE,
      useClass: JoiPipe,
    },
  ],
})
export class AppModule {}
```

--------------------------------

### Instantiating JoiPipe with Joi Schema and Group Option

Source: https://github.com/whefter/nestjs-joi/blob/master/README.md

This example shows how to instantiate JoiPipe by providing a Joi schema directly, along with group options. This method bypasses the metatype and any associated Joi schema derivation, validating against the explicit schema provided.

```typescript
import { Controller, Get, Param, Body } from '@nestjs/common';
import { JoiPipe } from 'nestjs-joi';
import * as Joi from 'joi';

@Controller('/books')
export class BookController {
  // Assuming bookService is injected
  constructor(private readonly bookService) {}

  @Get('/:bookId')
  async getBook(@Param('bookId', new JoiPipe(Joi.string().required())) bookId: string) {
      // bookId guaranteed to be a string and defined and non-empty
      return this.bookService.getBookById(bookId);
  }
}
```

--------------------------------

### Instantiating JoiPipe with Group Option

Source: https://github.com/whefter/nestjs-joi/blob/master/README.md

This example shows how to instantiate JoiPipe with specific options, including a 'group' property. This allows for selective application of validation rules defined for that group or the default group.

```typescript
import { Controller, Post, Body } from '@nestjs/common';
import { JoiPipe } from 'nestjs-joi';
import { BookDto } from './book.dto'; // Assuming BookDto is defined elsewhere

const CREATE = 'create'; // Example group identifier

@Controller('/books')
export class BookController {
  // Assuming bookService is injected
  constructor(private readonly bookService) {}

  @Post('/')
  async createBook(@Body(new JoiPipe({ group: CREATE })) createData: BookDto) {
    // Validated creation data!
    return await this.bookService.createBook(createData);
  }
}
```

--------------------------------

### Instantiating JoiPipe with Type and Group Option

Source: https://github.com/whefter/nestjs-joi/blob/master/README.md

This example demonstrates creating a JoiPipe instance by explicitly passing a type (e.g., BookDto) and an options object with a 'group'. This forces validation against the schema derived from the provided type, ignoring the request's metatype.

```typescript
import { Controller, Post, Body } from '@nestjs/common';
import { JoiPipe } from 'nestjs-joi';
import { BookDto } from './book.dto'; // Assuming BookDto is defined elsewhere

const CREATE = 'create'; // Example group identifier

@Controller('/books')
export class BookController {
  // Assuming bookService is injected
  constructor(private readonly bookService) {}

  @Post('/')
  async createBook(@Body(new JoiPipe(BookDto, { group: CREATE })) createData: unknown) {
    // Validated creation data!
    return await this.bookService.createBook(createData);
  }
}
```

--------------------------------

### NestJS Microservice Joi Validation with RpcExceptionFilter

Source: https://context7.com/whefter/nestjs-joi/llms.txt

Illustrates integrating `nestjs-joi` with NestJS microservices. It shows how to validate incoming messages using `JoiPipe` with specific schemas and dynamically defined Joi objects. The example includes setting up `JoiPipeValidationRpcExceptionFilter` to convert validation errors into `RpcExceptions` for microservice communication.

```typescript
import { Controller } from '@nestjs/common';
import { MessagePattern, Payload } from '@nestjs/microservices';
import { JoiPipe } from 'nestjs-joi';
import { JoiSchema } from 'nestjs-joi';
import * as Joi from 'joi';

export class CreateBookMessage {
  @JoiSchema(Joi.string().required())
  name!: string;

  @JoiSchema(Joi.string().required())
  author!: string;
}

@Controller()
export class BookMicroserviceController {
  @MessagePattern({ cmd: 'create_book' })
  async createBook(@Payload(new JoiPipe(CreateBookMessage)) data: CreateBookMessage) {
    // data is validated against CreateBookMessage schema
    return { success: true, bookId: '123' };
  }

  @MessagePattern({ cmd: 'update_book' })
  async updateBook(
    @Payload(
      new JoiPipe(
        Joi.object({
          id: Joi.string().uuid().required(),
          name: Joi.string().optional(),
          author: Joi.string().optional(),
        }).or('name', 'author'),
      ),
    )
    data: { id: string; name?: string; author?: string },
  ) {
    // At least one of name or author must be provided
    return { success: true };
  }
}

// Exception filter to convert JoiPipeValidationException to RpcException
import { Module } from '@nestjs/common';
import { APP_FILTER } from '@nestjs/core';
// Not exported from main package to avoid @nestjs/microservices dependency
import { JoiPipeValidationRpcExceptionFilter } from 'nestjs-joi/microservice';

@Module({
  controllers: [BookMicroserviceController],
  providers: [
    {
      provide: APP_FILTER,
      useClass: JoiPipeValidationRpcExceptionFilter,
    },
  ],
  imports: [
    JoiPipeModule.forRoot({
      pipeOpts: {
        usePipeValidationException: true, // Required for RpcExceptionFilter
      },
    }),
  ],
})
export class MicroserviceModule {}

```

--------------------------------

### Using JoiPipe with Request Decorators in NestJS

Source: https://github.com/whefter/nestjs-joi/blob/master/README.md

This example demonstrates how to use JoiPipe with NestJS request decorators like @Body() to validate incoming request data. The JoiPipe automatically determines the schema based on the provided metatype (e.g., BookDto).

```typescript
import { Controller, Post, Body } from '@nestjs/common';
import { JoiPipe } from 'nestjs-joi';
import { BookDto } from './book.dto'; // Assuming BookDto is defined elsewhere

@Controller('/books')
export class BookController {
  // Assuming bookService is injected
  constructor(private readonly bookService) {}

  @Post('/')
  async createBook(@Body(JoiPipe) createData: BookDto) {
    // Validated creation data!
    return await this.bookService.createBook(createData);
  }
}
```

--------------------------------

### Configure JoiPipeModule with Root Options

Source: https://github.com/whefter/nestjs-joi/blob/master/README.md

Demonstrates how to pass `pipeOpts` to `JoiPipeModule` using the `forRoot()` method. This allows for global configuration of `JoiPipe` options, such as `usePipeValidationException`.

```typescript
import { JoiPipeModule } from 'nestjs-joi';

@Module({
  controllers: [BookController],
  imports: [
    JoiPipeModule.forRoot({
      pipeOpts: {
        usePipeValidationException: true,
      },
    }),
  ],
})
export class AppModule {}
```

```typescript
import { JoiPipe } from 'nestjs-joi';
import { APP_PIPE } from '@nestjs/core';

@Module({
  controllers: [BookController],
  providers: [
    {
      provide: APP_PIPE,
      useClass: JoiPipe,
    },
    {
      provide: JOIPIPE_OPTIONS,
      useValue: {
        usePipeValidationException: true,
      },
    },
  ],
})
export class AppModule {}
```

--------------------------------

### Configure JoiPipe Options via DI Provider

Source: https://github.com/whefter/nestjs-joi/blob/master/README.md

Shows how to define `pipeOpts` for `JoiPipe` in injection-enabled mode by using a DI provider for `JOIPIPE_OPTIONS`. This is necessary because `JoiPipe` instances are created via the constructor in this mode.

```typescript
@Module({
  ...
  controllers: [ControllerUsingJoiPipe],
  providers: [
    {
      provide: JOIPIPE_OPTIONS,
      useValue: {
        usePipeValidationException: true,
      },
    },
  ],
  ...
})
export class AppModule {}
```

--------------------------------

### JoiPipe Options

Source: https://github.com/whefter/nestjs-joi/blob/master/README.md

Details the available options for configuring JoiPipe, such as 'group', 'usePipeValidationException', 'defaultValidationOptions', and 'skipErrorFormatting'.

```APIDOC
## JoiPipe Options

### `pipeOpts` Object

- **`group`** (`string | symbol`): Filters schema construction based on defined groups or the `DEFAULT` group. Defaults to `undefined`.
- **`usePipeValidationException`** (`boolean`): If `true`, throws `JoiPipeValidationException` on validation errors instead of `BadRequestException`. Defaults to `false`.
- **`defaultValidationOptions`** (`Joi.ValidationOptions`): Default Joi validation options passed to `.validate()`. Defaults to `{ abortEarly: false, allowUnknown: true }`. Options set directly on the schema using `.prefs()` or `.options()` take precedence.
- **`skipErrorFormatting`** (`boolean`): If `true`, returns the original Joi error instead of a formatted readable message. Defaults to `false`.
```

--------------------------------

### JoiPipe with Joi Schema

Source: https://github.com/whefter/nestjs-joi/blob/master/README.md

Illustrates using JoiPipe with a raw Joi schema for validation.

```APIDOC
## GET /books/:bookId

### Description
Validates the `bookId` path parameter using a Joi string schema.

### Method
GET

### Endpoint
/books/:bookId

### Parameters
#### Path Parameters
- **bookId** (string) - Required - The ID of the book to retrieve. Guaranteed to be a string and non-empty.

### Response
#### Success Response (200)
- **book** (object) - The requested book object.

#### Response Example
```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Example Book",
  "author": "John Doe"
}
```
```

--------------------------------

### NestJS Module with JoiPipeModule and DTO validation

Source: https://github.com/whefter/nestjs-joi/blob/master/README.md

Demonstrates how to set up a NestJS module to globally enable Joi validation using JoiPipeModule and defines a BookDto class with Joi schema decorators for validation rules, including support for CREATE and UPDATE validation groups.

```typescript
import { JoiPipeModule, JoiSchema, JoiSchemaOptions, CREATE, UPDATE } from 'nestjs-joi';
import * as Joi from 'joi';

@Module({
  controllers: [BookController],
  imports: [JoiPipeModule],
})
export class AppModule {}

@JoiSchemaOptions({
  allowUnknown: false,
})
export class BookDto {
  @JoiSchema(Joi.string().required())
  @JoiSchema([CREATE], Joi.string().required())
  @JoiSchema([UPDATE], Joi.string().optional())
  name!: string;

  @JoiSchema(Joi.string().required())
  @JoiSchema([CREATE], Joi.string().required())
  @JoiSchema([UPDATE], Joi.string().optional())
  author!: string;

  @JoiSchema(Joi.number().optional())
  publicationYear?: number;
}

@Controller('/books')
export class BookController {
  @Post('/')
  async createBook(@Body() createData: BookDto) {
    // Validated creation data!
    return await this.bookService.createBook(createData);
  }

  @Put('/')
  async createBook(@Body() createData: BookDto) {
    // Validated create data!
    return await this.bookService.createBook(createData);
  }

  @Patch('/')
  async createBook(@Body() updateData: BookDto) {
    // Validated update data!
    return await this.bookService.createBook(createData);
  }
}
```

--------------------------------

### JoiPipe with Explicit Schema Group

Source: https://github.com/whefter/nestjs-joi/blob/master/README.md

Shows how to instantiate JoiPipe with specific options, including a validation group.

```APIDOC
## POST /books

### Description
Validates the request body using `JoiPipe` with a specific validation group ('CREATE').

### Method
POST

### Endpoint
/books

### Parameters
#### Request Body
- **createData** (BookDto) - Required - The data to create a new book, validated against the 'CREATE' group schema.

### Request Example
```json
{
  "title": "Example Book",
  "author": "John Doe"
}
```

### Response
#### Success Response (201)
- **createdBook** (object) - The newly created book object.

#### Response Example
```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Example Book",
  "author": "John Doe"
}
```
```

--------------------------------

### NestJS Custom JoiPipe Options via DI

Source: https://context7.com/whefter/nestjs-joi/llms.txt

Shows how to configure JoiPipe options globally or at the module level using NestJS dependency injection. This allows for centralized management of validation settings like custom groups, exception handling, and default validation options.

```typescript
import { Module, Global } from '@nestjs/common';
import { JOIPIPE_OPTIONS } from 'nestjs-joi';

@Global()
@Module({
  providers: [
    {
      provide: JOIPIPE_OPTIONS,
      useValue: {
        group: 'CUSTOM_GROUP', // Use custom validation group
        usePipeValidationException: true, // Throw catchable exceptions
        defaultValidationOptions: {
          abortEarly: false, // Return all errors, not just first
          allowUnknown: false, // Strict validation
          stripUnknown: true, // Remove unknown properties
        },
        skipErrorFormatting: false, // Use formatted messages
      },
    },
  ],
  exports: [JOIPIPE_OPTIONS],
})
export class ValidationConfigModule {}

@Module({
  imports: [ValidationConfigModule],
  controllers: [BookController],
})
export class AppModule {}
```

--------------------------------

### Using JoiPipe Constructor with @Args() in NestJS GraphQL

Source: https://github.com/whefter/nestjs-joi/blob/master/README.md

Demonstrates how to pass the JoiPipe constructor directly to decorators like @Args() when using @nestjs/graphql. It notes that this approach does not automatically respect HTTP methods (POST, PUT) for validation groups due to limitations in how Apollo processes GraphQL queries.

```typescript
import { Args, Query, Resolver } from '@nestjs/graphql';
import { JoiPipe } from 'nestjs-joi';

@Resolver()
export class MyResolver {
  @Query(() => String)
  async myQuery(@Args({ type: () => String, name: 'myArg', pipe: new JoiPipe() }) myArg: string) {
    return `Received: ${myArg}`;
  }
}
```

--------------------------------

### NestJS JoiPipe Instance Validation in Controller Methods

Source: https://context7.com/whefter/nestjs-joi/llms.txt

Demonstrates using JoiPipe instances directly within controller method decorators for explicit validation control. This allows for fine-grained control over which validation groups are applied or using raw Joi schemas for specific parameters.

```typescript
import { Controller, Post, Body, Patch, Param, Get, Query } from '@nestjs/common';
import { JoiPipe, CREATE, UPDATE } from 'nestjs-joi';
import * as Joi from 'joi';

@Controller('/books')
export class BookController {
  // Method 1: Using explicit validation group
  @Post('/')
  async createBook(@Body(new JoiPipe({ group: CREATE })) createData: BookDto) {
    // createData is validated with CREATE group rules
    return await this.bookService.createBook(createData);
  }

  // Method 2: Using explicit type (ignores metatype)
  @Patch('/:id')
  async updateBook(
    @Param('id') id: string,
    @Body(new JoiPipe(BookDto, { group: UPDATE })) updateData: unknown,
  ) {
    // updateData validated with BookDto UPDATE group rules
    return await this.bookService.updateBook(id, updateData);
  }

  // Method 3: Using raw Joi schema for simple validation
  @Get('/:bookId')
  async getBook(
    @Param('bookId', new JoiPipe(Joi.string().uuid().required())) bookId: string,
  ) {
    // bookId guaranteed to be a valid UUID string
    return this.bookService.getBookById(bookId);
  }

  // Method 4: Query parameter validation
  @Get('/search')
  async searchBooks(
    @Query(
      new JoiPipe(
        Joi.object({
          title: Joi.string().optional(),
          author: Joi.string().optional(),
          minYear: Joi.number().integer().min(1000).optional(),
          maxYear: Joi.number().integer().max(9999).optional(),
        }).or('title', 'author'),
      ),
    )
    query: { title?: string; author?: string; minYear?: number; maxYear?: number },
  ) {
    // At least one of title or author must be provided
    return this.bookService.search(query);
  }
}
```

--------------------------------

### NestJS JoiPipe Automatic Group Selection in Controllers

Source: https://context7.com/whefter/nestjs-joi/llms.txt

Illustrates using JoiPipe's constructor reference for automatic validation group selection based on the incoming HTTP method. This simplifies validation configuration by leveraging predefined groups for common operations like POST (CREATE) and PATCH (UPDATE).

```typescript
import { Controller, Post, Put, Patch, Body } from '@nestjs/common';
import { JoiPipe } from 'nestjs-joi';

@Controller('/books')
export class BookController {
  // POST request - automatically uses CREATE group
  @Post('/')
  async createBook(@Body(JoiPipe) createData: BookDto) {
    // createData validated with CREATE group:
    // - name: required, 1-255 chars
    // - author: required
    // - publicationYear: optional number
    return await this.bookService.createBook(createData);
  }

  // PUT request - automatically uses CREATE group (full resource replacement)
  @Put('/:id')
  async replaceBook(@Param('id') id: string, @Body(JoiPipe) replaceData: BookDto) {
    // replaceData validated with CREATE group (all fields required)
    return await this.bookService.replaceBook(id, replaceData);
  }

  // PATCH request - automatically uses UPDATE group
  @Patch('/:id')
  async updateBook(@Param('id') id: string, @Body(JoiPipe) updateData: BookDto) {
    // updateData validated with UPDATE group:
    // - name: optional
    // - author: optional
    // - publicationYear: optional
    return await this.bookService.updateBook(id, updateData);
  }
}
```

--------------------------------

### JoiPipe Usage with Request Decorators

Source: https://github.com/whefter/nestjs-joi/blob/master/README.md

Demonstrates how to use JoiPipe with request decorators like @Body() for validating incoming data.

```APIDOC
## POST /books

### Description
Validates the request body using `JoiPipe` and a `BookDto`.

### Method
POST

### Endpoint
/books

### Parameters
#### Request Body
- **createData** (BookDto) - Required - The data to create a new book.

### Request Example
```json
{
  "title": "Example Book",
  "author": "John Doe"
}
```

### Response
#### Success Response (201)
- **createdBook** (object) - The newly created book object.

#### Response Example
```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Example Book",
  "author": "John Doe"
}
```
```

--------------------------------

### Handling Microservice Validation Exceptions with JoiPipe

Source: https://github.com/whefter/nestjs-joi/blob/master/README.md

Illustrates how to configure JoiPipe to throw a custom exception for microservice communication and how to catch it using an ExceptionFilter. This addresses the limitation where JoiPipe might otherwise throw a generic BadRequestException or JoiPipeValidationException instead of an RpcException.

```typescript
import {
  ArgumentsHost,
  Catch,
  ExceptionFilter,
  HttpException,
} from '@nestjs/common';
import { RpcException } from '@nestjs/microservices';

@Catch()
export class JoiPipeValidationRpcExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToRpc();
    const response = ctx.getData();

    // Check if the exception is a JoiPipeValidationException or BadRequestException
    // and convert it to an RpcException
    if (exception instanceof HttpException) {
      return new RpcException(exception.getResponse());
    }

    // Handle other exceptions if necessary
    return new RpcException('An unknown error occurred');
  }
}

// Example usage in a microservice setup:
// @Module({
//   imports: [
//     ClientsModule.register([
//       {
//         name: 'MY_SERVICE',
//         transport: Transport.TCP,
//         options: {
//           filters: [JoiPipeValidationRpcExceptionFilter],
//         },
//       },
//     ]),
//   ],
// })
// export class MyModule {}

// In your JoiPipe configuration:
// new JoiPipe({ usePipeValidationException: true })

```

--------------------------------

### Accessing and Validating Joi Schemas Programmatically with nestjs-joi (TypeScript)

Source: https://context7.com/whefter/nestjs-joi/llms.txt

Demonstrates how to retrieve Joi schemas for a DTO class using `getClassSchema()` and `getTypeSchema()` in TypeScript. It shows how to obtain the default schema, schemas for specific validation groups like CREATE and UPDATE, and how to use these schemas to validate data. This is useful for performing validation outside of NestJS pipes, such as within service methods.

```typescript
import { getClassSchema, getTypeSchema, JoiSchema, CREATE, UPDATE } from 'nestjs-joi';
import * as Joi from 'joi';

export class BookDto {
  @JoiSchema(Joi.string().required())
  @JoiSchema([CREATE], Joi.string().required().min(1))
  @JoiSchema([UPDATE], Joi.string().optional())
  name!: string;

  @JoiSchema(Joi.string().required())
  author!: string;
}

// Get default schema
const defaultSchema = getClassSchema(BookDto);
const result1 = defaultSchema.validate({ name: 'Book', author: 'Author' });
// result1.error is undefined, result1.value contains validated data

// Get CREATE group schema
const createSchema = getClassSchema(BookDto, { group: CREATE });
const result2 = createSchema.validate({ name: '', author: 'Author' });
// result2.error exists - name must be at least 1 character

// Get UPDATE group schema
const updateSchema = getTypeSchema(BookDto, { group: UPDATE });
const result3 = updateSchema.validate({ author: 'New Author' });
// result3.error is undefined - name is optional in UPDATE group

// Use in service layer for validation outside of pipes
export class BookService {
  async validateAndCreate(data: unknown) {
    const schema = getClassSchema(BookDto, { group: CREATE });
    const { error, value } = schema.validate(data);

    if (error) {
      throw new Error(`Validation failed: ${error.message}`);
    }

    return this.repository.create(value);
  }
}

// Dynamic schema generation with different groups
export class DynamicValidator {
  validateByContext(data: unknown, context: 'create' | 'update') {
    const group = context === 'create' ? CREATE : UPDATE;
    const schema = getClassSchema(BookDto, { group });

    return schema.validate(data, {
      abortEarly: false,
      allowUnknown: true,
      stripUnknown: true,
    });
  }
}

```

--------------------------------

### JoiPipe with Explicit Type

Source: https://github.com/whefter/nestjs-joi/blob/master/README.md

Demonstrates using JoiPipe with an explicit type to define the schema, ignoring the request metatype.

```APIDOC
## POST /books

### Description
Validates the request body using `JoiPipe` with an explicit `BookDto` type, ignoring the request metatype.

### Method
POST

### Endpoint
/books

### Parameters
#### Request Body
- **createData** (unknown) - Required - The data to create a new book, validated against the `BookDto` schema.

### Request Example
```json
{
  "title": "Example Book",
  "author": "John Doe"
}
```

### Response
#### Success Response (201)
- **createdBook** (object) - The newly created book object.

#### Response Example
```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Example Book",
  "author": "John Doe"
}
```
```

--------------------------------

### Define Book DTO with JoiSchema Decorators

Source: https://github.com/whefter/nestjs-joi/blob/master/README.md

Demonstrates defining a Book DTO using JoiSchema decorators for different validation groups (CREATE, UPDATE, DEFAULT). This allows for conditional validation based on the HTTP method or context.

```typescript
export class BookDto {
  @JoiSchema(Joi.string().required())
  @JoiSchema([JoiValidationGroups.CREATE], Joi.string().required())
  @JoiSchema([JoiValidationGroups.UPDATE], Joi.string().optional())
  name!: string;

  @JoiSchema(Joi.string().required())
  @JoiSchema([JoiValidationGroups.CREATE], Joi.string().required())
  @JoiSchema([JoiValidationGroups.UPDATE], Joi.string().optional())
  author!: string;

  @JoiSchema(Joi.number().optional())
  publicationYear?: number;
}

@Controller()
class BookController {
  // POST: this will implicitely use the group "CREATE" to construct the schema
  @Post('/')
  async createBook(@Body(JoiPipe) createData: BookDto) {
    return await this.bookService.createBook(createData);
  }
}
```

--------------------------------

### Global Pipe Registration with JoiPipeModule

Source: https://context7.com/whefter/nestjs-joi/llms.txt

Registers JoiPipe as a global validation pipe within a NestJS application. It supports basic usage and custom configuration options for validation behavior, such as error handling and allowing unknown properties. This module leverages NestJS's dependency injection.

```typescript
import { Module } from '@nestjs/common';
import { JoiPipeModule } from 'nestjs-joi';

// Basic usage - registers global pipe with default options
@Module({
  imports: [JoiPipeModule],
  controllers: [BookController],
})
export class AppModule {}

// With custom options - configure validation behavior
@Module({
  imports: [
    JoiPipeModule.forRoot({
      pipeOpts: {
        usePipeValidationException: true, // Throw JoiPipeValidationException instead of BadRequestException
        defaultValidationOptions: {
          abortEarly: false, // Show all validation errors
          allowUnknown: true, // Allow unknown properties
        },
        skipErrorFormatting: false, // Use formatted error messages
      },
    }),
  ],
  controllers: [BookController],
})
export class AppModule {}
```

--------------------------------

### Importing Joi Validation Groups in TypeScript

Source: https://github.com/whefter/nestjs-joi/blob/master/README.md

Shows two methods for importing the built-in validation groups (DEFAULT, CREATE, UPDATE) provided by 'nestjs-joi'. This allows for conditional validation based on the operation type (e.g., creating or updating a resource).

```typescript
import { JoiValidationGroups } from 'nestjs-joi';

// Accessing groups via the JoiValidationGroups object
const createGroup = JoiValidationGroups.CREATE;
const updateGroup = JoiValidationGroups.UPDATE;
const defaultGroup = JoiValidationGroups.DEFAULT;

console.log(createGroup);
console.log(updateGroup);
console.log(defaultGroup);

```

```typescript
import { DEFAULT, CREATE, UPDATE } from 'nestjs-joi';

// Direct import of individual groups
const createGroup = CREATE;
const updateGroup = UPDATE;
const defaultGroup = DEFAULT;

console.log(createGroup);
console.log(updateGroup);
console.log(defaultGroup);

// Example assertion
console.log(JoiValidationGroups.CREATE === CREATE); // true

```

--------------------------------

### Schema Post-processing with @JoiSchemaCustomization

Source: https://context7.com/whefter/nestjs-joi/llms.txt

The @JoiSchemaCustomization decorator allows for applying custom transformations or validations to the final constructed Joi schema. This is useful for implementing complex conditional logic or adding specific validation rules not directly supported by basic Joi types. It can also be applied conditionally for different groups.

```typescript
import { JoiSchema, JoiSchemaCustomization } from 'nestjs-joi';
import * as Joi from 'joi';

@JoiSchemaCustomization((schema: Joi.ObjectSchema) => {
  // Add conditional validation based on other fields
  return schema.custom((value, helpers) => {
    if (value.publicationYear && value.publicationYear > new Date().getFullYear()) {
      return helpers.error('any.invalid');
    }
    return value;
  });
})
export class BookDto {
  @JoiSchema(Joi.string().required())
  name!: string;

  @JoiSchema(Joi.number().optional())
  publicationYear?: number;
}

// Multiple customizations for different groups
@JoiSchemaCustomization((schema) => schema.and('firstName', 'lastName'))
@JoiSchemaCustomization([CREATE], (schema) =>
  schema.and('email', 'password').required(),
)
@JoiSchemaCustomization([UPDATE], (schema) => schema.or('firstName', 'lastName', 'email'))
export class UserDto {
  @JoiSchema([CREATE], Joi.string().required())
  @JoiSchema([UPDATE], Joi.string().optional())
  firstName?: string;

  @JoiSchema([CREATE], Joi.string().required())
  @JoiSchema([UPDATE], Joi.string().optional())
  lastName?: string;

  @JoiSchema([CREATE], Joi.string().email().required())
  @JoiSchema([UPDATE], Joi.string().email().optional())
  email?: string;

  @JoiSchema([CREATE], Joi.string().min(8).required())
  password?: string;
}

```

--------------------------------

### Class-level Joi Validation Options with @JoiSchemaOptions

Source: https://context7.com/whefter/nestjs-joi/llms.txt

The @JoiSchemaOptions decorator applies Joi validation configurations to an entire schema. It can be used to set options like 'allowUnknown', 'stripUnknown', and 'abortEarly'. This decorator supports applying different options for specific groups like CREATE or UPDATE.

```typescript
import { JoiSchema, JoiSchemaOptions } from 'nestjs-joi';
import * as Joi from 'joi';

@JoiSchemaOptions({
  allowUnknown: false, // Reject any properties not defined with @JoiSchema
  stripUnknown: true, // Remove unknown properties instead of rejecting
  abortEarly: true, // Stop validation on first error
})
export class StrictBookDto {
  @JoiSchema(Joi.string().required())
  name!: string;

  @JoiSchema(Joi.string().required())
  author!: string;

  // Any other properties will be rejected or stripped
}

// Different options for different groups
@JoiSchemaOptions({ allowUnknown: true })
@JoiSchemaOptions([CREATE], { allowUnknown: false, stripUnknown: true })
@JoiSchemaOptions([UPDATE], { allowUnknown: true, stripUnknown: false })
export class FlexibleBookDto {
  @JoiSchema([CREATE], Joi.string().required())
  @JoiSchema([UPDATE], Joi.string().optional())
  name!: string;

  // CREATE: unknown properties stripped
  // UPDATE: unknown properties allowed
}

```

--------------------------------

### Custom Joi Validation Error Handling in NestJS

Source: https://context7.com/whefter/nestjs-joi/llms.txt

Demonstrates how to define custom error messages for Joi schema validations in NestJS DTOs using the `error()` method and `messages` option. It also shows how to create a custom `JoiValidationExceptionFilter` to catch and format `JoiPipeValidationException` for HTTP responses.

```typescript
import { JoiSchema } from 'nestjs-joi';
import * as Joi from 'joi';

export class BookDto {
  // Custom error message using Joi's error() method
  @JoiSchema(
    Joi.string()
      .required()
      .alphanum()
      .error(new Error('Book name must contain only alphanumeric characters')),
  )
  name!: string;

  // Custom error using messages option
  @JoiSchema(
    Joi.string()
      .required()
      .email()
      .messages({
        'string.email': 'Please provide a valid email address',
        'any.required': 'Email is required for book contact',
      }),
  )
  contactEmail!: string;
}

// Exception filter for catching JoiPipeValidationException
import { Catch, ExceptionFilter, ArgumentsHost } from '@nestjs/common';
import { Response } from 'express';
import { JoiPipeValidationException } from 'nestjs-joi';

@Catch(JoiPipeValidationException)
export class JoiValidationExceptionFilter implements ExceptionFilter {
  catch(exception: JoiPipeValidationException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();

    // Access the original Joi validation error
    const joiError = exception.joiValidationError;

    response.status(400).json({
      statusCode: 400,
      message: 'Validation failed',
      errors: joiError.details.map((detail) => ({
        field: detail.path.join('.'),
        message: detail.message,
        type: detail.type,
      })),
    });
  }
}

// Apply the filter globally
import { Module } from '@nestjs/common';
import { APP_FILTER } from '@nestjs/core';

@Module({
  providers: [
    {
      provide: APP_FILTER,
      useClass: JoiValidationExceptionFilter,
    },
  ],
})
export class AppModule {}

```

--------------------------------

### JoiPipeValidationRpcExceptionFilter for NestJS Microservices

Source: https://github.com/whefter/nestjs-joi/blob/master/README.md

This exception filter handles JoiPipeValidationException in NestJS microservices. It re-throws these exceptions as RpcException to prevent them from being silently swallowed by NestJS, ensuring proper error handling. It is not exported from the main package to avoid a dependency on @nestjs/microservice.

```typescript
import { JoiPipeValidationRpcExceptionFilter } from 'nestjs-joi/microservice';
```

--------------------------------

### Property Validation with @JoiSchema() Decorator

Source: https://context7.com/whefter/nestjs-joi/llms.txt

Defines Joi validation schemas for class properties in TypeScript. This decorator allows for multiple schemas per property, enabling different validation rules based on validation groups like CREATE, UPDATE, or DEFAULT. It also supports nested object validation and custom validation options.

```typescript
import { JoiSchema, JoiSchemaOptions, CREATE, UPDATE, DEFAULT } from 'nestjs-joi';
import * as Joi from 'joi';

@JoiSchemaOptions({
  allowUnknown: false, // Reject unknown properties
})
export class BookDto {
  // Default validation - used when no specific group matches
  @JoiSchema(Joi.string().required())
  // CREATE group - used for POST and PUT requests
  @JoiSchema([CREATE], Joi.string().required().min(1).max(255))
  // UPDATE group - used for PATCH requests
  @JoiSchema([UPDATE], Joi.string().optional())
  name!: string;

  @JoiSchema(Joi.string().required())
  @JoiSchema([CREATE], Joi.string().required())
  @JoiSchema([UPDATE], Joi.string().optional())
  author!: string;

  @JoiSchema(Joi.number().optional().min(1000).max(9999))
  publicationYear?: number;

  // Nested validation
  @JoiSchema(
    Joi.object({
      street: Joi.string().required(),
      city: Joi.string().required(),
      zipCode: Joi.string().pattern(/^\d{5}$/),
    }).optional(),
  )
  publisherAddress?: {
    street: string;
    city: string;
    zipCode?: string;
  };
}
```

--------------------------------

### Define Custom Joi Schema Error

Source: https://github.com/whefter/nestjs-joi/blob/master/README.md

Illustrates how to define a custom error message for a Joi schema property using the `.error()` method. This custom error will be thrown when validation fails for the specified property.

```typescript
@JoiSchema(
  Joi.string()
    .required()
    .alphanum()
    .error(
      new Error(
        `prop must contain only alphanumeric characters`,
      ),
    ),
)
prop: string;
```

--------------------------------

### Schema Inheritance with @JoiSchemaExtends

Source: https://context7.com/whefter/nestjs-joi/llms.txt

The @JoiSchemaExtends decorator is used to define schema inheritance, especially when working with NestJS utility types like OmitType or PartialType. This ensures that Joi validation rules are correctly inherited. It is crucial for maintaining validation consistency across related DTOs.

```typescript
import { JoiSchema, JoiSchemaExtends } from 'nestjs-joi';
import { OmitType, PartialType } from '@nestjs/mapped-types';
import * as Joi from 'joi';

export class BaseBookDto {
  @JoiSchema(Joi.string().required())
  name!: string;

  @JoiSchema(Joi.string().required())
  author!: string;

  @JoiSchema(Joi.string().uuid().required())
  id!: string;

  @JoiSchema(Joi.date().required())
  createdAt!: Date;
}

// Without @JoiSchemaExtends, schema inheritance would break
@JoiSchemaExtends(BaseBookDto)
export class CreateBookDto extends OmitType(BaseBookDto, ['id', 'createdAt'] as const) {
  // Inherits name and author validation from BaseBookDto
  // Omits id and createdAt
}

@JoiSchemaExtends(BaseBookDto)
export class UpdateBookDto extends PartialType(BaseBookDto) {
  // All fields become optional
  // Inherits all validation rules from BaseBookDto but as optional
}

@JoiSchemaExtends(CreateBookDto)
export class ExtendedBookDto extends CreateBookDto {
  @JoiSchema(Joi.string().uri().required())
  coverImageUrl!: string;

  @JoiSchema(Joi.array().items(Joi.string()).optional())
  tags?: string[];
}

```
Tokens:
Raw