@hz-9/a5-crud-zod/README.md

Zod validation and CRUD utilities for the @hz-9/a5-* series of repositories.

# @hz-9/a5-crud-zod

Zod validation and CRUD utilities module for the @hz-9/a5-* series of repositories.

## Features

- 🛡️ **Zod Validation Exception Filter**: Automatically catch and format Zod validation errors
- 📝 **Schema Helpers**: Pre-built schema creators for common use cases (pagination, sorting, search)
- ✅ **Type-Safe Validation**: Fully typed validation utilities
- 🔧 **Utility Functions**: Helper functions for schema merging and validation

## Installation

```bash
rush update
```

## Usage

### Basic Module Setup

```typescript
import { Module } from '@nestjs/common'
import { A5CrudZodModule } from '@hz-9/a5-crud-zod'

@Module({
  imports: [
    A5CrudZodModule.forRoot({
      enableGlobalFilter: true, // Optional: enable global Zod exception filter
    }),
  ],
})
export class AppModule {}
```

### Using Validation Helpers

```typescript
import { z } from 'zod'
import { 
  createPaginationSchema, 
  createSortSchema, 
  createSearchSchema,
  mergeSchemas 
} from '@hz-9/a5-crud-zod'

// Create a pagination schema
const paginationSchema = createPaginationSchema(1, 20)

// Create a sort schema
const sortSchema = createSortSchema(['name', 'createdAt', 'updatedAt'])

// Create a search schema
const searchSchema = createSearchSchema()

// Merge multiple schemas
const querySchema = mergeSchemas(
  paginationSchema,
  sortSchema,
  searchSchema,
  z.object({
    status: z.enum(['active', 'inactive']).optional(),
  })
)
```

### Using ZodValidator

```typescript
import { ZodValidator } from '@hz-9/a5-crud-zod'
import { z } from 'zod'

const userSchema = z.object({
  name: z.string(),
  email: z.string().email(),
  age: z.number().positive(),
})

// Validate data (throws on error)
try {
  const validData = ZodValidator.validate(userSchema, inputData)
  console.log(validData)
} catch (error) {
  console.error('Validation failed:', error)
}

// Safe parse (returns result object)
const result = ZodValidator.safeParse(userSchema, inputData)
if (result.success) {
  console.log('Valid data:', result.data)
} else {
  console.error('Validation errors:', result.error)
}
```

### Using Exception Filter

```typescript
import { Controller, Post, Body } from '@nestjs/common'
import { z } from 'zod'
import { ZodValidator } from '@hz-9/a5-crud-zod'

const createUserSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
})

@Controller('users')
export class UserController {
  @Post()
  createUser(@Body() body: unknown) {
    // ZodValidationExceptionFilter will automatically catch and format errors
    const validData = ZodValidator.validate(createUserSchema, body)
    return { message: 'User created', data: validData }
  }
}
```

## API

### Schema Helpers

#### `createPaginationSchema(defaultPage?, defaultPageSize?)`

Creates a pagination schema with optional default values.

- `defaultPage`: Default page number (default: 1)
- `defaultPageSize`: Default page size (default: 10)

#### `createSortSchema(fields)`

Creates a sorting schema for specified fields.

- `fields`: Array of field names that can be sorted

#### `createSearchSchema()`

Creates a search schema with a keyword field.

#### `mergeSchemas(...schemas)`

Merges multiple Zod object schemas into one.

### Validators

#### `ZodValidator.validate<T>(schema, data)`

Validates data against a schema. Throws `ZodError` if validation fails.

#### `ZodValidator.safeParse<T>(schema, data)`

Safely validates data. Returns an object with `success` boolean and either `data` or `error`.

### Exception Filter

#### `ZodValidationExceptionFilter`

Automatically catches `ZodError` exceptions and returns formatted error responses:

```json
{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    {
      "path": "email",
      "message": "Invalid email",
      "code": "invalid_string"
    }
  ]
}
```

## License

MIT