@horizon-apps/domain-schema-core/docs/json-to-zod-generator.md

Core domain schema utilities for Horizon Platform - Schema generators, data enrichers, converters and specifications

# JsonToZodGenerator

Gera schemas Zod a partir do formato Horizon Fields Metadata Pattern v2.2.0.

## Features

- ✅ **Inferência inteligente** - Gera validações automaticamente
- ✅ **Suporte completo v2.2.0** - `categories`, `precision`, `mask`, `Json[]`
- ✅ **Mask para dados limpos** - Validações realistas para backend
- ✅ **Performance otimizada** - Rápido e eficiente

## Quick Start

```typescript
import { JsonToZodGenerator } from '@horizon-integrations/dev-toolkit'

const fields = [
  {
    "key": "valor_venda",
    "type": "Number",
    "label": "Valor de Venda",
    "format": "currency",
    "validation": {"precision": 2, "min": 0},
    "origin": "hb:property"
  }
]

const zod = JsonToZodGenerator.generate(fields, {
  schemaName: 'Property',
  enablePrecisionValidation: true
})

console.log(zod)
// Output: valor_venda: z.number().min(0).multipleOf(0.01).optional()
```

## Tipos Suportados

| Tipo | Zod Gerado | Exemplo |
|------|------------|---------|
| `String` | `z.string()` | Texto simples |
| `String[]` | `z.array(z.string())` | Array de strings |
| `Number` | `z.number()` | Números |
| `Boolean` | `z.boolean()` | true/false |
| `Json` | `z.any()` | Objeto JSON |
| `Json[]` | `z.array(z.any())` | Array de objetos |

## Validações Automáticas

### Precision (Decimais)
```typescript
{
  "validation": {"precision": 2}
}
// → .multipleOf(0.01)
```

### Mask (Dados Limpos)
```typescript
{
  "mask": "cep"
}
// → .length(8, "CEP deve ter exatamente 8 dígitos")
```

### Enum Object Format
```typescript
{
  "enum": {"venda": "Venda", "locacao": "Locação"}
}
// → z.enum(["venda", "locacao"])
```

## Options

```typescript
interface JsonToZodOptions {
  schemaName: string
  addDescriptions?: boolean
  exportType?: boolean
  enablePrecisionValidation?: boolean
  enableMaskValidation?: boolean
  enableConditionalFields?: boolean
  logInference?: boolean
}
```

## API

### `generate(fields, options)`
Gera schema Zod a partir de array de campos.

### `generateFromFile(jsonPath, options)`
Gera schema a partir de arquivo JSON.

### `saveToFile(fields, options, outputPath)`
Gera e salva schema em arquivo.

### `analyzeSchema(fields)`
Retorna estatísticas do schema.

## Exemplo Completo

```typescript
const schema = JsonToZodGenerator.generate(fields, {
  schemaName: 'Property',
  addDescriptions: true,
  exportType: true,
  enablePrecisionValidation: true,
  enableMaskValidation: true,
  logInference: true
})

// Gera:
// - PropertyZod (schema)
// - PropertyType (tipo inferido)
// - validateProperty() (helper)
// - safeValidateProperty() (helper)
```

## Migration do V1

```typescript
// V1 (antigo)
import { JsonToZodGenerator } from '@horizon-integrations/dev-toolkit'

// V2 (novo)
import { JsonToZodGenerator } from '@horizon-integrations/dev-toolkit'
```

### Principais Diferenças

- `tags` → `categories`
- `enumValues/enumLabels` → `enum` (object)
- Suporte para `Json[]`
- Validação `precision` 
- Mask para dados limpos (sem regex complexa)