oRPC Zod Smart Coercion

Refined alternative to z.coerce — automatically coerces inputs to the expected type without modifying the schema.

SKILL.md

GitHub

Zod Smart Coercion

A plugin alternative to z.coerce that automatically converts inputs to the expected type without modifying the input schema.

In Zod v4, this plugin only supports discriminated unions. Regular unions are not coerced.

Installation

npm install @orpc/zod@latest

Setup

import { OpenAPIHandler } from '@orpc/openapi/fetch'
import { ZodSmartCoercionPlugin } from '@orpc/zod' // Zod v3
import { experimental_ZodSmartCoercionPlugin as ZodSmartCoercionPlugin } from '@orpc/zod/zod4' // Zod v4

const handler = new OpenAPIHandler(router, {
  plugins: [new ZodSmartCoercionPlugin()],
})

Do not use with RPCHandler — it may negatively impact performance.

Safe and Predictable Conversion

Coercion only happens when:

  1. The schema expects a specific type and the input can be converted.
  2. The input does not already match the schema.

For example:

  • If input is 'true' but the schema does not expect a boolean — no conversion.
  • If the schema accepts both boolean and string — 'true' is not coerced to a boolean.

Conversion Rules

Source Target Examples
'true', 'on', 't' true Boolean
'false', 'off', 'f' false Boolean
'42' 42 Number
'12345678901234567890' BigInt BigInt
'2024-11-27T00:00:00.000Z' Date ISO date/datetime
'/^abc$/i' RegExp Regular expression
'https://example.com' URL URL object
['a', 'b', 'a'] Set Deduped Set
[['k1', 'v1'], ['k2', 'v2']] Map Map from key/value pairs