refactor(json-schema,openapi)!: make JsonSchemaConverter sync (#1716)

## Summary

`JsonSchemaConverter.condition`/`.convert` and
`DelegatingJsonSchemaConverter.convert` are now synchronous, so JSON
schema conversion can be used in sync contexts.

```ts
const converter = new DelegatingJsonSchemaConverter([new ZodToJsonSchemaConverter()])
const [jsonSchema, optional] = converter.convert(schema, 'input') // no await needed
```

- All built-in converters (zod, valibot, arktype, effect, standard) were
already sync — only the interface and delegating wrapper changed.
- Smart coercion plugins now coerce without an extra microtask per call.
- `OpenAPIGenerator.generate` stays async (lazy router walking) but
converts schemas synchronously.
- BREAKING: custom converters with async `condition`/`convert` are no
longer supported; schemas whose fallback `validate(undefined)` is async
are now treated as required.

Author: dinwwwh

packages/json-schema/src/convert.test.ts

@@ -5,53 +5,67 @@ import z from 'zod'
 import { DelegatingJsonSchemaConverter } from './convert'
 
 describe('delegatingJsonSchemaConverter', () => {
-  it('uses the first matching custom converter', async () => {
+  it('uses the first matching custom converter', () => {
     const schema = z.object({ value: z.string() })
 
     const firstConverter: JsonSchemaConverter = {
-      condition: vi.fn().mockResolvedValue(true),
-      convert: vi.fn().mockResolvedValue([{ type: 'string' }, false]),
+      condition: vi.fn().mockReturnValue(true),
+      convert: vi.fn().mockReturnValue([{ type: 'string' }, false]),
     }
 
     const secondConverter: JsonSchemaConverter = {
-      condition: vi.fn().mockResolvedValue(true),
-      convert: vi.fn().mockResolvedValue([{ type: 'number' }, true]),
+      condition: vi.fn().mockReturnValue(true),
+      convert: vi.fn().mockReturnValue([{ type: 'number' }, true]),
     }
 
     const converter = new DelegatingJsonSchemaConverter([firstConverter, secondConverter])
 
-    await expect(converter.convert(schema, 'input')).resolves.toEqual([{ type: 'string' }, false])
+    expect(converter.convert(schema, 'input')).toEqual([{ type: 'string' }, false])
     expect(firstConverter.condition).toHaveBeenCalledWith(schema, 'input')
     expect(firstConverter.convert).toHaveBeenCalledWith(schema, 'input')
     expect(secondConverter.condition).not.toHaveBeenCalled()
     expect(secondConverter.convert).not.toHaveBeenCalled()
   })
 
-  it('converts schemas using the standard json schema fallback behavior', async () => {
+  it('converts schemas using the standard json schema fallback behavior', () => {
     const converter = new DelegatingJsonSchemaConverter([])
 
     const schema = z.number().transform(String).pipe(z.string())
-    await expect(converter.convert(schema, 'input')).resolves.toEqual([
+    expect(converter.convert(schema, 'input')).toEqual([
       expect.objectContaining({ type: 'number' }),
       false,
     ])
-    await expect(converter.convert(schema, 'output')).resolves.toEqual([
+    expect(converter.convert(schema, 'output')).toEqual([
       expect.objectContaining({ type: 'string' }),
       false,
     ])
 
     const optionalSchema = v.optional(v.string())
-    await expect(converter.convert(optionalSchema, 'input')).resolves.toEqual([
+    expect(converter.convert(optionalSchema, 'input')).toEqual([
       expect.objectContaining({ }),
       true,
     ])
-    await expect(converter.convert(optionalSchema, 'output')).resolves.toEqual([
+    expect(converter.convert(optionalSchema, 'output')).toEqual([
       expect.objectContaining({ }),
       true,
     ])
   })
 
-  it('returns an empty schema when ~standard does not expose jsonSchema', async () => {
+  it('returns an empty schema when ~standard does not expose jsonSchema', () => {
+    const schema: AnySchema = {
+      '~standard': {
+        vendor: 'custom',
+        version: 1,
+        validate: vi.fn().mockReturnValue({}),
+      },
+    }
+
+    const converter = new DelegatingJsonSchemaConverter([])
+
+    expect(converter.convert(schema, 'input')).toEqual([{}, true])
+  })
+
+  it('treats schemas with async validation as required', () => {
     const schema: AnySchema = {
       '~standard': {
         vendor: 'custom',
@@ -62,6 +76,6 @@ describe('delegatingJsonSchemaConverter', () => {
 
     const converter = new DelegatingJsonSchemaConverter([])
 
-    await expect(converter.convert(schema, 'input')).resolves.toEqual([{}, true])
+    expect(converter.convert(schema, 'input')).toEqual([{}, false])
   })
 })

packages/json-schema/src/convert.ts

@@ -1,5 +1,4 @@
 import type { AnySchema } from '@orpc/contract'
-import type { Promisable } from '@orpc/shared'
 import type { JsonSchema } from './types'
 
 export type JsonSchemaConverterDirection = 'input' | 'output'
@@ -8,27 +7,28 @@ export interface JsonSchemaConverter {
   /**
    * Determines whether this converter can handle the given schema.
    */
-  condition(schema: AnySchema | undefined, direction: JsonSchemaConverterDirection): Promisable<boolean>
+  condition(schema: AnySchema | undefined, direction: JsonSchemaConverterDirection): boolean
 
   /**
    * Converts an ORPC schema to a JSON Schema representation.
    */
-  convert(schema: AnySchema | undefined, direction: JsonSchemaConverterDirection): Promisable<[jsonSchema: JsonSchema, optional: boolean]>
+  convert(schema: AnySchema | undefined, direction: JsonSchemaConverterDirection): [jsonSchema: JsonSchema, optional: boolean]
 }
 
 export class DelegatingJsonSchemaConverter implements Pick<JsonSchemaConverter, 'convert'> {
   constructor(
     private readonly converters: JsonSchemaConverter[] = [],
   ) {}
 
-  async convert(schema: AnySchema | undefined, direction: JsonSchemaConverterDirection): Promise<[jsonSchema: JsonSchema, optional: boolean]> {
+  convert(schema: AnySchema | undefined, direction: JsonSchemaConverterDirection): [jsonSchema: JsonSchema, optional: boolean] {
     for (const converter of this.converters) {
-      if (await converter.condition(schema, direction)) {
+      if (converter.condition(schema, direction)) {
         return converter.convert(schema, direction)
       }
     }
 
-    const optional = !(await schema?.['~standard'].validate(undefined))?.issues?.length
+    const result = schema?.['~standard'].validate(undefined)
+    const optional = result instanceof Promise ? false : !result?.issues?.length
 
     if (schema && 'jsonSchema' in schema['~standard'] && schema['~standard'].jsonSchema) {
       try {

packages/json-schema/src/smart-coercion-handler-plugin.ts

@@ -31,27 +31,27 @@ export class SmartCoercionHandlerPlugin<T extends Context> implements StandardHa
     return {
       ...options,
       clientInterceptors: [
-        async ({ next, input, ...interceptorOptions }) => {
+        ({ next, input, ...interceptorOptions }) => {
           const inputSchemas = interceptorOptions.procedure['~orpc'].inputSchemas
 
           if (!inputSchemas) {
             return next()
           }
 
-          const coercedInput = await this.coerceValue(inputSchemas, input)
+          const coercedInput = this.coerceValue(inputSchemas, input)
           return next({ ...interceptorOptions, input: coercedInput })
         },
         ...toArray(options.clientInterceptors),
       ],
     }
   }
 
-  private async coerceValue(schemas: AnySchema[], value: unknown): Promise<unknown> {
+  private coerceValue(schemas: AnySchema[], value: unknown): unknown {
     for (const schema of schemas) {
       let converted = this.cache.get(schema)
 
       if (!converted) {
-        converted = await this.converter.convert(schema, 'input')
+        converted = this.converter.convert(schema, 'input')
         this.cache.set(schema, converted)
       }
 

packages/json-schema/src/smart-coercion-link-plugin.ts

@@ -53,7 +53,7 @@ export class SmartCoercionLinkPlugin<T extends ClientContext> implements Standar
               return output
             }
 
-            const coercedOutput = await this.coerceValue(outputSchemas, output)
+            const coercedOutput = this.coerceValue(outputSchemas, output)
             return coercedOutput
           }
           catch (error) {
@@ -69,20 +69,20 @@ export class SmartCoercionLinkPlugin<T extends ClientContext> implements Standar
             }
 
             const cloned = cloneORPCError(error)
-            cloned.data = await this.coerceValue([dataSchema], cloned.data)
+            cloned.data = this.coerceValue([dataSchema], cloned.data)
             throw cloned
           }
         },
       ],
     }
   }
 
-  private async coerceValue(schemas: AnySchema[], value: unknown): Promise<unknown> {
+  private coerceValue(schemas: AnySchema[], value: unknown): unknown {
     for (const schema of schemas) {
       let converted = this.cache.get(schema)
 
       if (!converted) {
-        converted = await this.converter.convert(schema, 'output')
+        converted = this.converter.convert(schema, 'output')
         this.cache.set(schema, converted)
       }
 

packages/openapi/src/openapi-generator.test.ts

@@ -8,10 +8,10 @@ import { OpenAPIGenerator } from './openapi-generator'
 describe('openAPIGenerator', () => {
   const zodJsonSchemaConverter: JsonSchemaConverter = {
     condition: schema => schema?.['~standard'].vendor === 'zod',
-    async convert(schema, direction) {
+    convert(schema, direction) {
       const jsonSchema = z.toJSONSchema(schema as any, { io: direction })
-      const output = await schema?.['~standard'].validate(undefined)
-      return [jsonSchema as any, !output?.issues]
+      const output = schema?.['~standard'].validate(undefined)
+      return [jsonSchema as any, !(output instanceof Promise) && !output?.issues]
     },
   }
 
@@ -3086,7 +3086,7 @@ describe('openAPIGenerator', () => {
           converters: [
             {
               condition: schema => schema === planetSchema,
-              async convert(_schema, _direction) {
+              convert(_schema, _direction) {
                 return [{
                   type: 'object',
                   properties: {
@@ -3150,7 +3150,7 @@ describe('openAPIGenerator', () => {
           converters: [
             {
               condition: schema => schema === planetSchema,
-              async convert(_schema, _direction) {
+              convert(_schema, _direction) {
                 return [{
                   type: 'object',
                   properties: {

packages/openapi/src/openapi-generator.ts

@@ -111,7 +111,7 @@ export class OpenAPIGenerator {
 
     const errors: string[] = []
 
-    await walkProcedureContractsAsync(router, async (contract, path) => {
+    await walkProcedureContractsAsync(router, (contract, path) => {
       if (value(options.filter, contract, path) === false) {
         return
       }
@@ -140,9 +140,9 @@ export class OpenAPIGenerator {
             tags: meta?.tags?.map(tag => tag),
           }
 
-          await this.request(doc, operationRef, def, meta, dynamicPathParams, options, path)
-          await this.successResponse(doc, operationRef, def, meta, options, path)
-          await this.errorResponse(doc, operationRef, def, meta, options)
+          this.request(doc, operationRef, def, meta, dynamicPathParams, options, path)
+          this.successResponse(doc, operationRef, def, meta, options, path)
+          this.errorResponse(doc, operationRef, def, meta, options)
         }
 
         if (typeof meta?.spec === 'function') {
@@ -172,17 +172,17 @@ export class OpenAPIGenerator {
     return this.serializer.serialize(doc, { asFormData: false, useFormDataForBlobFields: false }) as OpenAPIDocument
   }
 
-  private async convertSchema(schema: AnySchema | undefined, direction: JsonSchemaConverterDirection): Promise<[JsonSchema, boolean]> {
-    const [jsonSchema, optional] = await this.converter.convert(schema as any, direction)
+  private convertSchema(schema: AnySchema | undefined, direction: JsonSchemaConverterDirection): [JsonSchema, boolean] {
+    const [jsonSchema, optional] = this.converter.convert(schema as any, direction)
     return [strip$schemaField(jsonSchema), optional]
   }
 
-  private async convertSchemas(schemas: AnySchema[] | undefined, direction: JsonSchemaConverterDirection): Promise<[JsonSchema, boolean]> {
+  private convertSchemas(schemas: AnySchema[] | undefined, direction: JsonSchemaConverterDirection): [JsonSchema, boolean] {
     if (!schemas || schemas.length <= 1) {
       return this.convertSchema(schemas?.[0], direction)
     }
 
-    const results = await Promise.all(schemas.map(s => this.convertSchema(s, direction)))
+    const results = schemas.map(s => this.convertSchema(s, direction))
     const allOfSchemas: JsonSchema[] = []
     let optional = true
 
@@ -196,15 +196,15 @@ export class OpenAPIGenerator {
     return [combineJsonSchemasWithComposition('allOf', allOfSchemas), optional]
   }
 
-  private async request(
+  private request(
     doc: OpenAPIDocument,
     ref: OpenAPIOperationObject,
     def: AnyProcedureContract['~orpc'],
     meta: OpenAPIMeta | undefined,
     dynamicPathParams: DynamicPathParam[] | undefined,
     options: OpenAPIGeneratorGenerateOptions,
     path: string[],
-  ): Promise<void> {
+  ): void {
     const method = meta?.method ?? DEFAULT_OPENAPI_METHOD
     const inputStructure = meta?.inputStructure ?? DEFAULT_OPENAPI_INPUT_STRUCTURE
     const inputSchemas = def.inputSchemas
@@ -214,8 +214,8 @@ export class OpenAPIGenerator {
 
       if (asyncIteratorObjectDetails) {
         const [yieldSchemas, returnSchemas] = asyncIteratorObjectDetails
-        const yieldResult = await this.convertSchemas(yieldSchemas, 'input')
-        const returnResult = await this.convertSchemas(returnSchemas, 'input')
+        const yieldResult = this.convertSchemas(yieldSchemas, 'input')
+        const returnResult = this.convertSchemas(returnSchemas, 'input')
 
         ref.requestBody = {
           required: true,
@@ -228,7 +228,7 @@ export class OpenAPIGenerator {
 
     const dynamicParams = dynamicPathParams?.map(v => v.parameterName)
 
-    const [schema, optional] = await this.convertSchemas(inputSchemas, 'input')
+    const [schema, optional] = this.convertSchemas(inputSchemas, 'input')
 
     if (isUnconstrainedSchema(schema) && !dynamicParams?.length) {
       return
@@ -374,14 +374,14 @@ export class OpenAPIGenerator {
     }
   }
 
-  private async successResponse(
+  private successResponse(
     doc: OpenAPIDocument,
     ref: OpenAPIOperationObject,
     def: AnyProcedureContract['~orpc'],
     meta: OpenAPIMeta | undefined,
     options: OpenAPIGeneratorGenerateOptions,
     path: string[],
-  ): Promise<void> {
+  ): void {
     const outputSchemas = def.outputSchemas
     const status = meta?.successStatus ?? DEFAULT_SUCCESS_STATUS
     const description = meta?.successDescription ?? DEFAULT_OPENAPI_SUCCESS_DESCRIPTION
@@ -392,8 +392,8 @@ export class OpenAPIGenerator {
 
       if (iteratorDetails) {
         const [yieldSchemas, returnSchemas] = iteratorDetails
-        const yieldResult = await this.convertSchemas(yieldSchemas, 'output')
-        const returnResult = await this.convertSchemas(returnSchemas, 'output')
+        const yieldResult = this.convertSchemas(yieldSchemas, 'output')
+        const returnResult = this.convertSchemas(returnSchemas, 'output')
 
         ref.responses ??= {}
         ref.responses[status] = {
@@ -405,7 +405,7 @@ export class OpenAPIGenerator {
       }
     }
 
-    const [schema] = await this.convertSchemas(outputSchemas, 'output')
+    const [schema] = this.convertSchemas(outputSchemas, 'output')
 
     if (isUnconstrainedSchema(schema) || outputStructure === 'compact') {
       ref.responses ??= {}
@@ -481,13 +481,13 @@ export class OpenAPIGenerator {
     }
   }
 
-  private async errorResponse(
+  private errorResponse(
     doc: OpenAPIDocument,
     ref: OpenAPIOperationObject,
     def: AnyProcedureContract['~orpc'],
     meta: OpenAPIMeta | undefined,
     options: OpenAPIGeneratorGenerateOptions,
-  ): Promise<void> {
+  ): void {
     const errorStatusMap: Record<string, number> = options.errorStatusMap ?? COMMON_ERROR_STATUS_MAP
     const errorMap: ErrorMap = def.errorMap
 
@@ -504,7 +504,7 @@ export class OpenAPIGenerator {
 
       const status = errorStatusMap[code] ?? DEFAULT_ERROR_STATUS
       const defaultMessage = config.message
-      const [dataJsonSchema, dataOptional] = await this.convertSchema(config.data, 'output')
+      const [dataJsonSchema, dataOptional] = this.convertSchema(config.data, 'output')
 
       const definitions = errorDefinitionsByStatus.get(status)
       if (definitions) {