132 lines
3.6 KiB
Markdown
132 lines
3.6 KiB
Markdown
---
|
|
title: Use default() for Optional Fields with Defaults
|
|
impact: MEDIUM
|
|
impactDescription: Manual default handling spreads logic across codebase; .default() centralizes defaults in schema
|
|
tags: refine, default, optional, configuration
|
|
---
|
|
|
|
## Use default() for Optional Fields with Defaults
|
|
|
|
When a field is optional but should have a default value when missing, use `.default()` instead of handling defaults in business logic. This keeps default values centralized in the schema and ensures consistent behavior.
|
|
|
|
**Incorrect (defaults spread across codebase):**
|
|
|
|
```typescript
|
|
import { z } from 'zod'
|
|
|
|
const configSchema = z.object({
|
|
timeout: z.number().optional(),
|
|
retries: z.number().optional(),
|
|
debug: z.boolean().optional(),
|
|
})
|
|
|
|
type Config = z.infer<typeof configSchema>
|
|
|
|
function createClient(config: Config) {
|
|
// Defaults handled in business logic - duplicated everywhere
|
|
const timeout = config.timeout ?? 5000
|
|
const retries = config.retries ?? 3
|
|
const debug = config.debug ?? false
|
|
|
|
// ...
|
|
}
|
|
|
|
function createOtherClient(config: Config) {
|
|
// Same defaults duplicated - risk of inconsistency
|
|
const timeout = config.timeout ?? 5000
|
|
const retries = config.retries ?? 3 // What if someone uses 2 here?
|
|
const debug = config.debug ?? false
|
|
|
|
// ...
|
|
}
|
|
```
|
|
|
|
**Correct (defaults in schema):**
|
|
|
|
```typescript
|
|
import { z } from 'zod'
|
|
|
|
const configSchema = z.object({
|
|
timeout: z.number().default(5000),
|
|
retries: z.number().default(3),
|
|
debug: z.boolean().default(false),
|
|
})
|
|
|
|
type Config = z.infer<typeof configSchema>
|
|
// { timeout: number; retries: number; debug: boolean }
|
|
// No optional - defaults fill in missing values
|
|
|
|
function createClient(config: Config) {
|
|
// config.timeout is guaranteed to exist
|
|
console.log(config.timeout) // 5000 if not provided
|
|
console.log(config.retries) // 3 if not provided
|
|
console.log(config.debug) // false if not provided
|
|
}
|
|
|
|
// Parse fills in defaults
|
|
configSchema.parse({})
|
|
// { timeout: 5000, retries: 3, debug: false }
|
|
|
|
configSchema.parse({ timeout: 10000 })
|
|
// { timeout: 10000, retries: 3, debug: false }
|
|
```
|
|
|
|
**Input type vs Output type with defaults:**
|
|
|
|
```typescript
|
|
const schema = z.object({
|
|
name: z.string(),
|
|
role: z.enum(['admin', 'user']).default('user'),
|
|
})
|
|
|
|
type SchemaInput = z.input<typeof schema>
|
|
// { name: string; role?: 'admin' | 'user' }
|
|
|
|
type SchemaOutput = z.output<typeof schema>
|
|
// { name: string; role: 'admin' | 'user' }
|
|
|
|
// Input type is optional, output type is required
|
|
```
|
|
|
|
**Default with factory function:**
|
|
|
|
```typescript
|
|
// Static default
|
|
const schema1 = z.object({
|
|
id: z.string().default('temp-id'),
|
|
})
|
|
|
|
// Factory function for dynamic defaults
|
|
const schema2 = z.object({
|
|
id: z.string().default(() => crypto.randomUUID()),
|
|
createdAt: z.date().default(() => new Date()),
|
|
})
|
|
|
|
// Each parse creates new values
|
|
schema2.parse({}) // { id: 'abc-123...', createdAt: 2024-01-15... }
|
|
schema2.parse({}) // { id: 'def-456...', createdAt: 2024-01-15... }
|
|
```
|
|
|
|
**Combining with optional/nullable:**
|
|
|
|
```typescript
|
|
// .optional().default() - if undefined, use default
|
|
z.string().optional().default('fallback')
|
|
|
|
// .nullable().default() - null stays null, only undefined gets default
|
|
z.string().nullable().default('fallback')
|
|
// null -> null
|
|
// undefined -> 'fallback'
|
|
|
|
// .nullish().default() - both null and undefined get default
|
|
z.string().nullish().default('fallback')
|
|
// null -> 'fallback'
|
|
// undefined -> 'fallback'
|
|
```
|
|
|
|
**When NOT to use this pattern:**
|
|
- When absence of value has different meaning than default
|
|
- When defaults depend on other fields (use transform)
|
|
|
|
Reference: [Zod API - default](https://zod.dev/api#default)
|