feat(zod,valibot,arktype): add option to cache generated JSON schemas (#1753)

Adds an opt-in `cache` option to `ZodToJsonSchemaConverter`,
`ValibotToJsonSchemaConverter`, and `ArkTypeToJsonSchemaConverter` that
memoizes conversion results in per-direction WeakMaps keyed by the
schema instance. Converting the same schema repeatedly — e.g.
regenerating an OpenAPI spec or sharing a converter across plugins — no
longer re-runs the underlying JSON schema conversion.

## Performance
- Repeat conversions of the same schema instance return the cached
`[jsonSchema, optional]` tuple with no conversion work.
- `input` and `output` directions are cached independently, and WeakMap
keys keep schemas garbage-collectable.

## Notes
- Disabled by default: cached results are shared objects, so they must
be treated as immutable when the option is enabled.
- The `cache` flag is stripped before options are forwarded to the
underlying `toJsonSchema` implementations.

## Testing
- New tests in all three packages verify results are reused per schema
and direction, the underlying conversion runs only once, and behavior is
unchanged when disabled.
- Docs for the zod, valibot, and arktype integrations mention the new
option.

Author: dinwwwh

apps/content/docs/integrations/arktype.md

@@ -41,6 +41,15 @@ const generator = new OpenAPIGenerator({
 })
 ```
 
+::: tip
+Enable the `cache` option to reuse conversion results when the same schema instance is converted repeatedly. When enabled, repeated conversions return the same JSON schema object, so treat the results as immutable.
+
+```ts
+const converter = new ArkTypeToJsonSchemaConverter({ cache: true })
+```
+
+:::
+
 ### Reusable Types
 
 A common pattern is defining reusable or recursive types using scopes. The converter preserves them in `$defs`, which `OpenAPIGenerator` can then [hoist](/docs/openapi/specification#hoisting-defs) into `components.schemas`.

apps/content/docs/integrations/valibot.md

@@ -41,6 +41,15 @@ const generator = new OpenAPIGenerator({
 })
 ```
 
+::: tip
+Enable the `cache` option to reuse conversion results when the same schema instance is converted repeatedly. When enabled, repeated conversions return the same JSON schema object, so treat the results as immutable.
+
+```ts
+const converter = new ValibotToJsonSchemaConverter({ cache: true })
+```
+
+:::
+
 ### Reusable Schemas
 
 A common pattern is defining reusable or recursive schemas via definitions. The converter preserves them in `$defs`, which `OpenAPIGenerator` can then [hoist](/docs/openapi/specification#hoisting-defs) into `components.schemas`. For more on how definitions work in Valibot, see [Valibot JSON Schema Definitions](https://github.com/open-circle/valibot/blob/main/packages/to-json-schema/README.md#definitions).

apps/content/docs/integrations/zod.md

@@ -45,6 +45,15 @@ const generator = new OpenAPIGenerator({
 })
 ```
 
+::: tip
+Enable the `cache` option to reuse conversion results when the same schema instance is converted repeatedly. When enabled, repeated conversions return the same JSON schema object, so treat the results as immutable.
+
+```ts
+const converter = new ZodToJsonSchemaConverter({ cache: true })
+```
+
+:::
+
 ### Reusable Schemas
 
 A common pattern is defining reusable schemas with `id` metadata. The converter places them in `$defs`, which `OpenAPIGenerator` then [hoists](/docs/openapi/specification#hoisting-defs) into `components.schemas`. For more on `id` and `$ref` in Zod, see [Zod JSON Schema Registries](https://zod.dev/json-schema?id=registries#registries).

packages/arktype/src/converter.test.ts

@@ -127,4 +127,38 @@ describe('arkTypeToJsonSchemaConverter', () => {
       false,
     ])
   })
+
+  describe('cache option', () => {
+    it('reuses conversion results per schema and direction when enabled', () => {
+      const converter = new ArkTypeToJsonSchemaConverter({ cache: true })
+      const schema = type('string')
+      // arktype interns types, so the same definition returns the same instance/spy across tests
+      const toJsonSchema = vi.spyOn(schema, 'toJsonSchema')
+      toJsonSchema.mockClear()
+
+      const input = converter.convert(schema, 'input')
+      expect(input).toEqual([{ type: 'string' }, false])
+      expect(converter.convert(schema, 'input')).toBe(input)
+      expect(toJsonSchema).toHaveBeenCalledTimes(1)
+
+      const output = converter.convert(schema, 'output')
+      expect(output).toEqual([{ type: 'string' }, false])
+      expect(output).not.toBe(input)
+      expect(converter.convert(schema, 'output')).toBe(output)
+      expect(toJsonSchema).toHaveBeenCalledTimes(2)
+    })
+
+    it('converts on every call when disabled', () => {
+      const schema = type('string')
+      const toJsonSchema = vi.spyOn(schema, 'toJsonSchema')
+      toJsonSchema.mockClear()
+
+      const first = converter.convert(schema, 'input')
+      const second = converter.convert(schema, 'input')
+
+      expect(second).toEqual(first)
+      expect(second).not.toBe(first)
+      expect(toJsonSchema).toHaveBeenCalledTimes(2)
+    })
+  })
 })

packages/arktype/src/converter.ts

@@ -3,12 +3,28 @@ import type { AnySchema, JsonSchema, JsonSchemaConverter, JsonSchemaConverterDir
 import type { Type } from 'arktype'
 import { JsonSchemaFormat, JsonSchemaXNativeType } from '@orpc/json-schema'
 
-export interface ArkTypeToJsonSchemaConverterOptions extends Omit<ToJsonSchema.Options, 'dialect' | 'target'> {}
+export interface ArkTypeToJsonSchemaConverterOptions extends Omit<ToJsonSchema.Options, 'dialect' | 'target'> {
+  /**
+   * Caches conversion results in a WeakMap keyed by the ArkType schema instance,
+   * so converting the same schema again is free.
+   *
+   * When enabled, repeated conversions return the same JSON schema object,
+   * so treat returned schemas as immutable.
+   *
+   * @default false
+   */
+  cache?: boolean
+}
 
 export class ArkTypeToJsonSchemaConverter implements JsonSchemaConverter {
   private readonly toJsonSchemaOptions: ToJsonSchema.Options
+  private readonly cache: undefined | { [d in JsonSchemaConverterDirection]: WeakMap<Type, [jsonSchema: JsonSchema, optional: boolean]> }
+
+  constructor({ cache, ...options }: ArkTypeToJsonSchemaConverterOptions = {}) {
+    if (cache) {
+      this.cache = { input: new WeakMap(), output: new WeakMap() }
+    }
 
-  constructor(options: ArkTypeToJsonSchemaConverterOptions = {}) {
     this.toJsonSchemaOptions = {
       ...options,
       target: 'draft-2020-12',
@@ -49,6 +65,23 @@ export class ArkTypeToJsonSchemaConverter implements JsonSchemaConverter {
   convert(schema: AnySchema | undefined, direction: JsonSchemaConverterDirection): [jsonSchema: JsonSchema, optional: boolean] {
     const arkTypeSchema = schema as Type
 
+    if (this.cache) {
+      const cached = this.cache[direction].get(arkTypeSchema)
+      if (cached) {
+        return cached
+      }
+    }
+
+    const result = this.convertUncached(arkTypeSchema, direction)
+
+    if (this.cache) {
+      this.cache[direction].set(arkTypeSchema, result)
+    }
+
+    return result
+  }
+
+  private convertUncached(arkTypeSchema: Type, direction: JsonSchemaConverterDirection): [jsonSchema: JsonSchema, optional: boolean] {
     const jsonSchema = this.convertArkType(arkTypeSchema, direction)
 
     let optional = false

packages/valibot/src/converter.test.ts

@@ -1,7 +1,16 @@
+import { toJsonSchema } from '@valibot/to-json-schema'
 import * as v from 'valibot'
 import * as z from 'zod'
 import { ValibotToJsonSchemaConverter } from './converter'
 
+vi.mock('@valibot/to-json-schema', async (original) => {
+  const mod = await original<typeof import('@valibot/to-json-schema')>()
+  return {
+    ...mod,
+    toJsonSchema: vi.fn((...args: [any]) => mod.toJsonSchema(...args)),
+  }
+})
+
 describe('valibotToJsonSchemaConverter', () => {
   const converter = new ValibotToJsonSchemaConverter()
 
@@ -114,4 +123,39 @@ describe('valibotToJsonSchemaConverter', () => {
       expect(converter.convert(schema, 'input')).toEqual([jsonSchema, false])
     })
   })
+
+  describe('cache option', () => {
+    const schema = v.pipe(v.number(), v.transform(n => n.toString()), v.string())
+
+    it('reuses conversion results per schema and direction when enabled', () => {
+      const converter = new ValibotToJsonSchemaConverter({ cache: true })
+
+      vi.mocked(toJsonSchema).mockClear()
+
+      const input = converter.convert(schema, 'input')
+      expect(input).toEqual([{ type: 'number' }, false])
+      expect(converter.convert(schema, 'input')).toBe(input)
+      expect(toJsonSchema).toHaveBeenCalledTimes(1)
+
+      const output = converter.convert(schema, 'output')
+      expect(output).toEqual([{ type: 'string' }, false])
+      expect(output).not.toBe(input)
+      expect(converter.convert(schema, 'output')).toBe(output)
+      expect(toJsonSchema).toHaveBeenCalledTimes(2)
+
+      converter.convert(v.string(), 'input')
+      expect(toJsonSchema).toHaveBeenCalledTimes(3)
+    })
+
+    it('converts on every call when disabled', () => {
+      vi.mocked(toJsonSchema).mockClear()
+
+      const first = converter.convert(schema, 'input')
+      const second = converter.convert(schema, 'input')
+
+      expect(second).toEqual(first)
+      expect(second).not.toBe(first)
+      expect(toJsonSchema).toHaveBeenCalledTimes(2)
+    })
+  })
 })

packages/valibot/src/converter.ts

@@ -4,10 +4,31 @@ import type { BaseSchema, MapSchema, SetSchema } from 'valibot'
 import { JsonSchemaFormat, JsonSchemaXNativeType } from '@orpc/json-schema'
 import { toJsonSchema } from '@valibot/to-json-schema'
 
-export interface ValibotToJsonSchemaConverterOptions extends Omit<ConversionConfig, 'target' | 'typeMode' | 'overrideRef'> {}
+export interface ValibotToJsonSchemaConverterOptions extends Omit<ConversionConfig, 'target' | 'typeMode' | 'overrideRef'> {
+  /**
+   * Caches conversion results in a WeakMap keyed by the Valibot schema instance,
+   * so converting the same schema again is free.
+   *
+   * When enabled, repeated conversions return the same JSON schema object,
+   * so treat returned schemas as immutable.
+   *
+   * @default false
+   */
+  cache?: boolean
+}
 
 export class ValibotToJsonSchemaConverter implements JsonSchemaConverter {
-  constructor(private readonly options: ValibotToJsonSchemaConverterOptions = {}) {
+  private readonly conversionConfig: ConversionConfig
+  private readonly cache: undefined | { [d in JsonSchemaConverterDirection]: WeakMap<BaseSchema<any, any, any>, [jsonSchema: JsonSchema, optional: boolean]> }
+
+  constructor(
+    { cache, ...conversionConfig }: ValibotToJsonSchemaConverterOptions = {},
+  ) {
+    this.conversionConfig = conversionConfig
+
+    if (cache) {
+      this.cache = { input: new WeakMap(), output: new WeakMap() }
+    }
   }
 
   condition(schema: AnySchema | undefined, _direction: JsonSchemaConverterDirection): boolean {
@@ -16,6 +37,24 @@ export class ValibotToJsonSchemaConverter implements JsonSchemaConverter {
 
   convert(schema: AnySchema | undefined, direction: JsonSchemaConverterDirection): [jsonSchema: JsonSchema, optional: boolean] {
     const valibotSchema = schema as BaseSchema<any, any, any>
+
+    if (this.cache) {
+      const cached = this.cache[direction].get(valibotSchema)
+      if (cached) {
+        return cached
+      }
+    }
+
+    const result = this.convertUncached(valibotSchema, direction)
+
+    if (this.cache) {
+      this.cache[direction].set(valibotSchema, result)
+    }
+
+    return result
+  }
+
+  private convertUncached(valibotSchema: BaseSchema<any, any, any>, direction: JsonSchemaConverterDirection): [jsonSchema: JsonSchema, optional: boolean] {
     const jsonSchema = this.convertValibot(valibotSchema, direction)
 
     let optional = false
@@ -33,7 +72,7 @@ export class ValibotToJsonSchemaConverter implements JsonSchemaConverter {
   private convertValibot(schema: BaseSchema<any, any, any>, direction: JsonSchemaConverterDirection): ValibotJsonSchema {
     const jsonSchema = toJsonSchema(schema, {
       errorMode: 'ignore',
-      ...this.options,
+      ...this.conversionConfig,
       target: 'draft-2020-12',
       typeMode: direction,
       overrideSchema: (context) => {
@@ -70,8 +109,8 @@ export class ValibotToJsonSchemaConverter implements JsonSchemaConverter {
           ;(context.jsonSchema as any)['x-native-type'] = JsonSchemaXNativeType.Map
         }
 
-        if (this.options.overrideSchema) {
-          return this.options.overrideSchema(context)
+        if (this.conversionConfig.overrideSchema) {
+          return this.conversionConfig.overrideSchema(context)
         }
       },
     })

packages/zod/src/converter.test.ts

@@ -288,4 +288,37 @@ describe('zodToJsonSchemaConverter', () => {
       }, false])
     })
   })
+
+  describe('cache option', () => {
+    it('reuses conversion results per schema and direction when enabled', () => {
+      const converter = new ZodToJsonSchemaConverter({ cache: true })
+
+      vi.mocked(toJSONSchema).mockClear()
+
+      const input = converter.convert(codecSchema, 'input')
+      expect(input).toEqual([{ type: 'string' }, false])
+      expect(converter.convert(codecSchema, 'input')).toBe(input)
+      expect(toJSONSchema).toHaveBeenCalledTimes(1)
+
+      const output = converter.convert(codecSchema, 'output')
+      expect(output).toEqual([{ type: 'number' }, false])
+      expect(output).not.toBe(input)
+      expect(converter.convert(codecSchema, 'output')).toBe(output)
+      expect(toJSONSchema).toHaveBeenCalledTimes(2)
+
+      converter.convert(z.string(), 'input')
+      expect(toJSONSchema).toHaveBeenCalledTimes(3)
+    })
+
+    it('converts on every call when disabled', () => {
+      vi.mocked(toJSONSchema).mockClear()
+
+      const first = converter.convert(codecSchema, 'input')
+      const second = converter.convert(codecSchema, 'input')
+
+      expect(second).toEqual(first)
+      expect(second).not.toBe(first)
+      expect(toJSONSchema).toHaveBeenCalledTimes(2)
+    })
+  })
 })