89 lines
2.9 KiB
Markdown
89 lines
2.9 KiB
Markdown
---
|
|
title: Use Coercion for Form and Query Data
|
|
impact: CRITICAL
|
|
impactDescription: Form data and query params are always strings; without coercion, z.number() rejects "42" and z.boolean() rejects "true"
|
|
tags: schema, coerce, forms, query-params
|
|
---
|
|
|
|
## Use Coercion for Form and Query Data
|
|
|
|
HTML forms and URL query parameters always transmit data as strings. Using `z.number()` on form data will fail because `"42"` is not a number. Use `z.coerce.number()` to automatically convert strings to the correct type.
|
|
|
|
**Incorrect (no coercion for form data):**
|
|
|
|
```typescript
|
|
import { z } from 'zod'
|
|
|
|
const searchSchema = z.object({
|
|
query: z.string(),
|
|
page: z.number(), // Expects actual number
|
|
limit: z.number(),
|
|
showDeleted: z.boolean(), // Expects actual boolean
|
|
})
|
|
|
|
// Form data / query params are strings
|
|
const formData = new URLSearchParams('query=test&page=1&limit=10&showDeleted=true')
|
|
const params = Object.fromEntries(formData)
|
|
// { query: 'test', page: '1', limit: '10', showDeleted: 'true' }
|
|
|
|
searchSchema.parse(params)
|
|
// ZodError: Expected number, received string at "page"
|
|
// ZodError: Expected number, received string at "limit"
|
|
// ZodError: Expected boolean, received string at "showDeleted"
|
|
```
|
|
|
|
**Correct (using coercion):**
|
|
|
|
```typescript
|
|
import { z } from 'zod'
|
|
|
|
const searchSchema = z.object({
|
|
query: z.string(),
|
|
page: z.coerce.number().int().positive().default(1),
|
|
limit: z.coerce.number().int().min(1).max(100).default(10),
|
|
showDeleted: z.coerce.boolean().default(false),
|
|
})
|
|
|
|
// Form data / query params are strings
|
|
const formData = new URLSearchParams('query=test&page=1&limit=10&showDeleted=true')
|
|
const params = Object.fromEntries(formData)
|
|
|
|
const result = searchSchema.parse(params)
|
|
// { query: 'test', page: 1, limit: 10, showDeleted: true }
|
|
// Types are correct: number, number, boolean
|
|
```
|
|
|
|
**Available coercion types:**
|
|
|
|
```typescript
|
|
z.coerce.string() // Converts anything to string via String(value)
|
|
z.coerce.number() // Converts via Number(value), NaN fails validation
|
|
z.coerce.boolean() // Truthy/falsy conversion
|
|
z.coerce.bigint() // Converts via BigInt(value)
|
|
z.coerce.date() // Converts via new Date(value)
|
|
```
|
|
|
|
**Coercion edge cases:**
|
|
|
|
```typescript
|
|
// z.coerce.number() behavior
|
|
z.coerce.number().parse("42") // 42
|
|
z.coerce.number().parse("") // 0 (empty string becomes 0!)
|
|
z.coerce.number().parse("abc") // ZodError (NaN fails)
|
|
|
|
// z.coerce.boolean() behavior
|
|
z.coerce.boolean().parse("true") // true
|
|
z.coerce.boolean().parse("false") // true! (non-empty string is truthy)
|
|
z.coerce.boolean().parse("") // false
|
|
z.coerce.boolean().parse("0") // true! (non-empty string)
|
|
|
|
// For strict boolean parsing from strings:
|
|
const strictBooleanSchema = z.enum(['true', 'false']).transform(v => v === 'true')
|
|
```
|
|
|
|
**When NOT to use this pattern:**
|
|
- When receiving JSON payloads (already typed correctly)
|
|
- When you want strict type checking without conversion
|
|
|
|
Reference: [Zod API - Coercion](https://zod.dev/api#coercion)
|