feat(effect): improve JSON Schema converter with caching and options

[dinwwwh]

Refactors EffectSchemaToJsonSchemaConverter to directly use Effect's Schema.toJsonSchemaDocument API instead of wrapping the standard JSON schema converter, enabling better support for Effect-specific features and improved test coverage.

Key Changes

• Direct Effect integration: Now calls Schema.toJsonSchemaDocument directly, which properly handles Effect schemas with identifiers, class definitions, and recursive schemas by preserving them in $defs
• Options forwarding: Accepts and forwards Schema.ToJsonSchemaOptions (e.g., onExcessProperty, generateDescriptions, includeAnnotationKey, referencePolicy) to Effect's converter
• Caching support: Added optional cache parameter to reuse conversion results per schema instance and direction via WeakMap, improving performance for repeated conversions
• Improved optionality detection: Uses isStandardSchemaOptional helper for consistent optional field detection across input/output directions
• Enhanced test coverage: Expanded test suite with 40+ test cases covering:
  • Condition matching for various schema types
  • Input/output direction handling
  • Schema mutation safety
  • Options forwarding (onExcessProperty, includeAnnotationKey, referencePolicy, generateDescriptions)
  • Class definitions and recursive schema handling
  • Optionality detection for defaulted, undefined-producing, and unknown schemas
  • Error propagation from Effect
  • Cache behavior (enabled and disabled)

Documentation Updates

Updated integration docs to reflect the new converter capabilities, including examples of using options and guidance on the cache option for performance optimization.

https://claude.ai/code/session_016FEE7vGy6NSSU3yy1GLtMR

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	orpc	affa9da	Commit Preview URL Branch Preview URL	Oct 04 2026, 07:43 AM

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[pkg-pr-new]

More templates

• @orpc/bun-playground
• @orpc/cloudflare-playground
• @orpc/nest-playground
• @orpc/next-playground

@orpc/ai-sdk

npm i https://pkg.pr.new/@orpc/ai-sdk@2175

@orpc/arktype

npm i https://pkg.pr.new/@orpc/arktype@2175

@orpc/bun

npm i https://pkg.pr.new/@orpc/bun@2175

@orpc/client

npm i https://pkg.pr.new/@orpc/client@2175

@orpc/cloudflare

npm i https://pkg.pr.new/@orpc/cloudflare@2175

@orpc/contract

npm i https://pkg.pr.new/@orpc/contract@2175

@orpc/experimental-effect

npm i https://pkg.pr.new/@orpc/experimental-effect@2175

@orpc/evlog

npm i https://pkg.pr.new/@orpc/evlog@2175

@orpc/hibernation

npm i https://pkg.pr.new/@orpc/hibernation@2175

@orpc/json-schema

npm i https://pkg.pr.new/@orpc/json-schema@2175

@orpc/experimental-lock

npm i https://pkg.pr.new/@orpc/experimental-lock@2175

@orpc/experimental-msw

npm i https://pkg.pr.new/@orpc/experimental-msw@2175

@orpc/nest

npm i https://pkg.pr.new/@orpc/nest@2175

@orpc/next

npm i https://pkg.pr.new/@orpc/next@2175

@orpc/node

npm i https://pkg.pr.new/@orpc/node@2175

@orpc/openapi

npm i https://pkg.pr.new/@orpc/openapi@2175

@orpc/opentelemetry

npm i https://pkg.pr.new/@orpc/opentelemetry@2175

@orpc/pinia-colada

npm i https://pkg.pr.new/@orpc/pinia-colada@2175

@orpc/pino

npm i https://pkg.pr.new/@orpc/pino@2175

@orpc/publisher

npm i https://pkg.pr.new/@orpc/publisher@2175

@orpc/ratelimit

npm i https://pkg.pr.new/@orpc/ratelimit@2175

@orpc/server

npm i https://pkg.pr.new/@orpc/server@2175

@orpc/shared

npm i https://pkg.pr.new/@orpc/shared@2175

@orpc/swr

npm i https://pkg.pr.new/@orpc/swr@2175

@orpc/tanstack-query

npm i https://pkg.pr.new/@orpc/tanstack-query@2175

@orpc/trpc

npm i https://pkg.pr.new/@orpc/trpc@2175

@orpc/valibot

npm i https://pkg.pr.new/@orpc/valibot@2175

@orpc/zod

npm i https://pkg.pr.new/@orpc/zod@2175

commit: affa9da

[codspeed]

Merging this PR will not alter performance

✅ 30 untouched benchmarks

---

_{Comparing claude/relaxed-lamport-cfcequ (affa9da) with main (f7c1ee4)}

[pullfrog]

✅ No new issues found.

Reviewed changes — reimplementation of EffectSchemaToJsonSchemaConverter against Effect 4's Schema.toJsonSchemaDocument, plus expanded tests and docs.

• Direct Effect conversion — convert now calls Schema.toJsonSchemaDocument, using Schema.toType(schema) for the output direction and merging returned definitions into the root as $defs.
• Optionality — now computed via isStandardSchemaOptional on the standard-schema wrapper; condition additionally requires EffectSchema.isSchema(schema).
• Options forwarding — EffectSchemaToJsonSchemaConverterOptions extends Schema.ToJsonSchemaOptions (onExcessProperty, generateDescriptions, includeAnnotationKey, referencePolicy) and adds an opt-in cache (per-direction WeakMaps).
• Error propagation — Effect conversion errors now surface instead of being swallowed to {}.
• Tests + docs — 24 tests and effect.mdx updates for options, $defs, and cache.

I compared the new output against the base implementation for a spread of schemas (transforms like NumberFromString/Date/Trim, structs, classes, optionals, NullOr, recursive Category, record, union, tuple) in both directions: JSON Schema is byte-identical. The only behavioral delta is that Schema.UndefinedOr(Schema.String) on input is now optional: true (base said false) — a correctness fix, since UndefinedOr accepts undefined and the new path validates the real Effect standard schema. $defs output matches what OpenAPIComponentRegistry.hoistDefs expects, and cache is off by default so there is no default-path regression. type:check and eslint pass, and converter.test.ts is green (24/24).

  ^{｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}