feat(json-schema): stable SmartCoercionPlugin (#1285)

unnoq · web-flow · commit f01f7b13ddc0 · 2025-12-18T15:15:53.000+07:00
&lt;!-- This is an auto-generated comment: release notes by coderabbit.ai
--&gt;

## Summary by CodeRabbit

## Release Notes

* **API Updates**
* SmartCoercionPlugin and JsonSchemaCoercer are now available as stable
public APIs.
* SmartCoercionPluginOptions and JsonSchemaCoerceOptions are now stable
configuration interfaces.
* Update your project imports to reference the new stable API exports
for continued compatibility.

&lt;sub&gt;✏️ Tip: You can customize this high-level summary in your review
settings.&lt;/sub&gt;

&lt;!-- end of auto-generated comment: release notes by coderabbit.ai --&gt;
diff --git a/apps/content/docs/openapi/plugins/smart-coercion.md b/apps/content/docs/openapi/plugins/smart-coercion.md
@@ -43,9 +43,7 @@ Configure the plugin with [JSON Schema Converters](/docs/openapi/openapi-specifi
 
 ```ts
 import { OpenAPIHandler } from '@orpc/openapi/fetch'
-import {
-  experimental_SmartCoercionPlugin as SmartCoercionPlugin
-} from '@orpc/json-schema'
+import { SmartCoercionPlugin } from '@orpc/json-schema'
 
 const handler = new OpenAPIHandler(router, {
   plugins: [
diff --git a/packages/json-schema/src/coercer.test.ts b/packages/json-schema/src/coercer.test.ts
@@ -1,5 +1,5 @@
 /* eslint-disable prefer-regex-literals */
-import { experimental_JsonSchemaCoercer as JsonSchemaCoercer } from './coercer'
+import { JsonSchemaCoercer } from './coercer'
 
 describe('jsonSchemaCoercer', () => {
   const coercer = new JsonSchemaCoercer()
diff --git a/packages/json-schema/src/coercer.ts b/packages/json-schema/src/coercer.ts
@@ -4,17 +4,17 @@ import { JsonSchemaXNativeType } from './types'
 
 const FLEXIBLE_DATE_FORMAT_REGEX = /^[^-]+-[^-]+-[^-]+$/
 
-export interface experimental_JsonSchemaCoerceOptions {
+export interface JsonSchemaCoerceOptions {
   components?: Record<string, JsonSchema>
 }
 
-export class experimental_JsonSchemaCoercer {
-  coerce(schema: JsonSchema, value: unknown, options: experimental_JsonSchemaCoerceOptions = {}): unknown {
+export class JsonSchemaCoercer {
+  coerce(schema: JsonSchema, value: unknown, options: JsonSchemaCoerceOptions = {}): unknown {
     const [, coerced] = this.#coerce(schema, value, options)
     return coerced
   }
 
-  #coerce(schema: JsonSchema, originalValue: unknown, options: experimental_JsonSchemaCoerceOptions): [satisfied: boolean, coerced: unknown] {
+  #coerce(schema: JsonSchema, originalValue: unknown, options: JsonSchemaCoerceOptions): [satisfied: boolean, coerced: unknown] {
     if (typeof schema === 'boolean') {
       return [schema, originalValue]
     }
diff --git a/packages/json-schema/src/smart-coercion-plugin.test.ts b/packages/json-schema/src/smart-coercion-plugin.test.ts
@@ -1,6 +1,6 @@
 import * as z from 'zod'
 import { ZodToJsonSchemaConverter } from '../../zod/src/zod4'
-import { experimental_SmartCoercionPlugin as SmartCoercionPlugin } from './smart-coercion-plugin'
+import { SmartCoercionPlugin } from './smart-coercion-plugin'
 
 describe('smartCoercionPlugin', () => {
   it('should coerce input based on schema', async () => {
diff --git a/packages/json-schema/src/smart-coercion-plugin.ts b/packages/json-schema/src/smart-coercion-plugin.ts
@@ -6,19 +6,19 @@ import type { JsonSchema } from './types'
 import { CompositeSchemaConverter } from '@orpc/openapi'
 import { toArray } from '@orpc/shared'
 import {
-  experimental_JsonSchemaCoercer as JsonSchemaCoercer,
+  JsonSchemaCoercer,
 } from './coercer'
 
-export interface experimental_SmartCoercionPluginOptions {
+export interface SmartCoercionPluginOptions {
   schemaConverters?: readonly ConditionalSchemaConverter[]
 }
 
-export class experimental_SmartCoercionPlugin<T extends Context> implements StandardHandlerPlugin<T> {
+export class SmartCoercionPlugin<T extends Context> implements StandardHandlerPlugin<T> {
   private readonly converter: SchemaConverter
   private readonly coercer: JsonSchemaCoercer
   private readonly cache: WeakMap<AnySchema, JsonSchema> = new WeakMap()
 
-  constructor(options: experimental_SmartCoercionPluginOptions = {}) {
+  constructor(options: SmartCoercionPluginOptions = {}) {
     this.converter = new CompositeSchemaConverter(toArray(options.schemaConverters))
     this.coercer = new JsonSchemaCoercer()
   }
diff --git a/playgrounds/astro/src/pages/api/[...rest].ts b/playgrounds/astro/src/pages/api/[...rest].ts
@@ -2,7 +2,7 @@ import '../../polyfill'
 import { OpenAPIHandler } from '@orpc/openapi/fetch'
 import { onError } from '@orpc/server'
 import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
-import { experimental_SmartCoercionPlugin as SmartCoercionPlugin } from '@orpc/json-schema'
+import { SmartCoercionPlugin } from '@orpc/json-schema'
 import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
 import { router } from '../../routers'
 import type { APIRoute } from 'astro'
diff --git a/playgrounds/cloudflare-worker/worker/index.ts b/playgrounds/cloudflare-worker/worker/index.ts
@@ -1,7 +1,7 @@
 import { RPCHandler } from '@orpc/server/fetch'
 import { OpenAPIHandler } from '@orpc/openapi/fetch'
 import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
-import { experimental_SmartCoercionPlugin as SmartCoercionPlugin } from '@orpc/json-schema'
+import { SmartCoercionPlugin } from '@orpc/json-schema'
 import { upgradeDurableIteratorRequest } from '@orpc/experimental-durable-iterator/durable-object'
 import { BatchHandlerPlugin } from '@orpc/server/plugins'
 import { router } from './routers'
diff --git a/playgrounds/contract-first/src/main.ts b/playgrounds/contract-first/src/main.ts
@@ -3,7 +3,7 @@ import { OpenAPIHandler } from '@orpc/openapi/node'
 import { onError } from '@orpc/server'
 import { RPCHandler } from '@orpc/server/node'
 import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
-import { experimental_SmartCoercionPlugin as SmartCoercionPlugin } from '@orpc/json-schema'
+import { SmartCoercionPlugin } from '@orpc/json-schema'
 import { router } from './routers'
 import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
 import './polyfill'
diff --git a/playgrounds/nest/src/app.module.ts b/playgrounds/nest/src/app.module.ts
@@ -7,7 +7,7 @@ import { ReferenceController } from './reference/reference.controller'
 import { ReferenceService } from './reference/reference.service'
 import { onError, ORPCModule } from '@orpc/nest'
 import { REQUEST } from '@nestjs/core'
-import { experimental_SmartCoercionPlugin as SmartCoercionPlugin } from '@orpc/json-schema'
+import { SmartCoercionPlugin } from '@orpc/json-schema'
 import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
 import { Request } from 'express'
 
diff --git a/playgrounds/next/src/app/api/[[...rest]]/route.ts b/playgrounds/next/src/app/api/[[...rest]]/route.ts
@@ -2,7 +2,7 @@ import { router } from '@/routers'
 import { OpenAPIHandler } from '@orpc/openapi/fetch'
 import { onError } from '@orpc/server'
 import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
-import { experimental_SmartCoercionPlugin as SmartCoercionPlugin } from '@orpc/json-schema'
+import { SmartCoercionPlugin } from '@orpc/json-schema'
 import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
 import '../../../polyfill'
 import { NewUserSchema, UserSchema } from '@/schemas/user'
diff --git a/playgrounds/nuxt/server/routes/api/[...].ts b/playgrounds/nuxt/server/routes/api/[...].ts
@@ -1,7 +1,7 @@
 import { OpenAPIHandler } from '@orpc/openapi/fetch'
 import { onError } from '@orpc/server'
 import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
-import { experimental_SmartCoercionPlugin as SmartCoercionPlugin } from '@orpc/json-schema'
+import { SmartCoercionPlugin } from '@orpc/json-schema'
 import { router } from '../../routers'
 import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
 import { NewUserSchema, UserSchema } from '../../schemas/user'
diff --git a/playgrounds/solid-start/src/routes/api/[...rest].ts b/playgrounds/solid-start/src/routes/api/[...rest].ts
@@ -2,7 +2,7 @@ import type { APIEvent } from '@solidjs/start/server'
 import { OpenAPIHandler } from '@orpc/openapi/fetch'
 import { router } from '~/routers'
 import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
-import { experimental_SmartCoercionPlugin as SmartCoercionPlugin } from '@orpc/json-schema'
+import { SmartCoercionPlugin } from '@orpc/json-schema'
 import { onError } from '@orpc/server'
 import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
 import '~/polyfill'
diff --git a/playgrounds/svelte-kit/src/routes/api/[...rest]/+server.ts b/playgrounds/svelte-kit/src/routes/api/[...rest]/+server.ts
@@ -3,7 +3,7 @@ import { router } from '../../../routers'
 import { onError } from '@orpc/server'
 import type { RequestHandler } from '@sveltejs/kit'
 import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
-import { experimental_SmartCoercionPlugin as SmartCoercionPlugin } from '@orpc/json-schema'
+import { SmartCoercionPlugin } from '@orpc/json-schema'
 import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
 import '../../../polyfill'
 import { NewUserSchema, UserSchema } from '../../../schemas/user'
diff --git a/playgrounds/tanstack-start/src/routes/api/$.ts b/playgrounds/tanstack-start/src/routes/api/$.ts
@@ -2,7 +2,7 @@ import '~/polyfill'
 
 import { OpenAPIHandler } from '@orpc/openapi/fetch'
 import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
-import { experimental_SmartCoercionPlugin as SmartCoercionPlugin } from '@orpc/json-schema'
+import { SmartCoercionPlugin } from '@orpc/json-schema'
 import { createFileRoute } from '@tanstack/react-router'
 import { router } from '~/routers'
 import { onError } from '@orpc/server'

Original file line number	Diff line number	Diff line change
`@@ -4,17 +4,17 @@ import { JsonSchemaXNativeType } from './types'`
`4`	`4`
`5`	`5`	`const FLEXIBLE_DATE_FORMAT_REGEX = /^[^-]+-[^-]+-[^-]+$/`
`6`	`6`
`7`		`-export interface experimental_JsonSchemaCoerceOptions {`
	`7`	`+export interface JsonSchemaCoerceOptions {`
`8`	`8`	`components?: Record<string, JsonSchema>`
`9`	`9`	`}`
`10`	`10`
`11`		`-export class experimental_JsonSchemaCoercer {`
`12`		`- coerce(schema: JsonSchema, value: unknown, options: experimental_JsonSchemaCoerceOptions = {}): unknown {`
	`11`	`+export class JsonSchemaCoercer {`
	`12`	`+ coerce(schema: JsonSchema, value: unknown, options: JsonSchemaCoerceOptions = {}): unknown {`
`13`	`13`	`const [, coerced] = this.#coerce(schema, value, options)`
`14`	`14`	`return coerced`
`15`	`15`	`}`
`16`	`16`
`17`		`- #coerce(schema: JsonSchema, originalValue: unknown, options: experimental_JsonSchemaCoerceOptions): [satisfied: boolean, coerced: unknown] {`
	`17`	`+ #coerce(schema: JsonSchema, originalValue: unknown, options: JsonSchemaCoerceOptions): [satisfied: boolean, coerced: unknown] {`
`18`	`18`	`if (typeof schema === 'boolean') {`
`19`	`19`	`return [schema, originalValue]`
`20`	`20`	`}`