Smart Coercion Plugin

Automatically converts values to match your schema types without requiring manual coercion logic.

Installation

npm install @orpc/json-schema@beta

pnpm add @orpc/json-schema@beta

yarn add @orpc/json-schema@beta

bun add @orpc/json-schema@beta

Setup

Use SmartCoercionHandlerPlugin in your handler to coerce incoming request data to the expected .input schema:

import { SmartCoercionHandlerPlugin } from '@orpc/json-schema'

const handler = new OpenAPIHandler(router, {
  plugins: [
    new SmartCoercionHandlerPlugin({
      converters: [
        new ZodToJsonSchemaConverter(),
        // Add other schema converters as needed
      ],
    })
  ]
})

Use SmartCoercionLinkPlugin in your link to coerce server responses to the expected .output or .errors schemas:

import { SmartCoercionLinkPlugin } from '@orpc/json-schema'

const link = new OpenAPILink(contract, {
  plugins: [
    new SmartCoercionLinkPlugin(contract, {
      converters: [
        new ZodToJsonSchemaConverter(),
        // Add other schema converters as needed
      ],
    }),
  ]
})

How It Works

The plugin coerces values safely by following these rules:

Schema-driven: Converts only when the schema defines the target type
Safe only: Converts only values with an unambiguous, lossless representation, such as '123' to 123
Preserve original values: Leaves the original value unchanged when conversion would be unsafe
Union-aware: Tries to determine the best union branch to use for conversion
Deep conversion: Applies recursively inside nested objects and arrays

Conversion Rules

String → Boolean

Supports these specific string values, case-insensitively:

'true', 'on' → true
'false', 'off' → false

String → Number

Supports valid numeric strings:

'123' → 123
'3.14' → 3.14

String/Number → BigInt

Supports integer strings and whole numbers:

'12345678901234567890' → 12345678901234567890n
123 → 123n

String → Date

Supports ISO 8601 date and datetime strings:

'2023-10-01' → new Date('2023-10-01')
'2020-01-01T06:15' → new Date('2020-01-01T06:15')
'2020-01-01T06:15Z' → new Date('2020-01-01T06:15Z')
'2020-01-01T06:15:00Z' → new Date('2020-01-01T06:15:00Z')
'2020-01-01T06:15:00.123Z' → new Date('2020-01-01T06:15:00.123Z')
'2020-01-01T06:15:00-07:00' → new Date('2020-01-01T06:15:00-07:00')

String → RegExp

Supports valid regular expression strings:

'/^\\d+$/i' → new RegExp('^\\d+$', 'i')
'/abc/' → new RegExp('abc')

String → URL

Supports valid URL strings:

'https://example.com' → new URL('https://example.com')

Array → Set

Supports arrays of unique values:

['apple', 'banana'] → new Set(['apple', 'banana'])

Array → Object

Converts arrays into objects with numeric keys:

['apple', 'banana'] → { 0: 'apple', 1: 'banana' }

Array → Map

Supports arrays of key-value pairs with unique keys:

[['key1', 'value1'], ['key2', 'value2']] → new Map([['key1', 'value1'], ['key2', 'value2']])

Advanced Usage

You can also use this plugin in guides such as Expanding Type Support for OpenAPI Link.

Learn More

For implementation details, see the SmartCoercionHandlerPlugin source code, the SmartCoercionLinkPlugin source code, or the coercer source code.