fix(effect): close type holes in catchORPCErrorCode and catchORPCErrorCodes

[dinwwwh]

Migrates the Effect integration from @orpc/server to @orpc/client and significantly improves type inference and narrowing for error handling utilities.

Changes

• Import migration: Updated imports from @orpc/server to @orpc/client for ORPCError and related types
• Enhanced type inference: Introduced comprehensive type helpers (ORPCErrorsOf, ORPCErrorWithCode, ExcludeORPCErrorCode, LiteralORPCErrorCode, ORPCErrorCodeCases, etc.) to provide better type narrowing and error channel management
• Improved catchORPCErrorCode: Now properly narrows error types based on the caught code, keeping unhandled errors in the error channel with correct type information
• Improved catchORPCErrorCodes: Refactored type signatures to:
  • Support optional handlers (undefined values)
  • Properly track which error codes have been handled
  • Only exclude errors from the error channel when all codes in a union are handled
  • Better support for wide error types (string codes, ORPCErrorCode, etc.)
  • Preserve ORPCError subclasses with their custom properties
• Expanded test coverage: Added comprehensive type tests for:
  • AnyORPCError handling
  • Wide error codes (string, ORPCErrorCode)
  • Union code narrowing
  • Non-literal code parameters
  • ORPCError subclasses
  • Optional/undefined handlers
  • Partial handler coverage

The changes maintain backward compatibility while providing more precise type safety for error handling workflows.

https://claude.ai/code/session_01Lg5QRphdQBu6PCo88vV51o

[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	14845a6	Commit Preview URL Branch Preview URL	Oct 17 2026, 02:48 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@2261

@orpc/arktype

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

@orpc/bun

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

@orpc/client

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

@orpc/cloudflare

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

@orpc/contract

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

@orpc/experimental-effect

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

@orpc/evlog

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

@orpc/hibernation

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

@orpc/json-schema

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

@orpc/experimental-lock

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

@orpc/experimental-msw

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

@orpc/nest

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

@orpc/next

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

@orpc/node

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

@orpc/openapi

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

@orpc/opentelemetry

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

@orpc/pinia-colada

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

@orpc/pino

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

@orpc/publisher

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

@orpc/ratelimit

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

@orpc/server

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

@orpc/shared

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

@orpc/swr

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

@orpc/tanstack-query

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

@orpc/trpc

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

@orpc/valibot

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

@orpc/zod

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

commit: 14845a6

[codspeed]

Merging this PR will not alter performance

⚠️ 5 benchmarks spent significant time in system calls

System calls cannot be consistently instrumented, so they are not included in the measure, which understates the real cost. Please switch to the Walltime instrument to accurately measure system calls.

Measurement and system calls

• serve file
• range request
• not modified (304)
• not found fall through
• serve deeply nested encoded path

✅ 28 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing claude/vibrant-babbage-vz48bm (14845a6) with main (05f7ef3)}

Footnotes

1. 2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[pullfrog]

✅ No new issues found.

Reviewed changes — the type-level rewrite of the Effect error helpers in packages/effect/src/error.ts, the import migration to @orpc/client, and the expanded type/runtime tests. I verified the types against the runtime predicates and ran the checks below.

• Import migration: error.ts and its tests now import ORPCError, AnyORPCError, and ORPCErrorCode from @orpc/client. @orpc/server re-exports all three from @orpc/client (packages/server/src/index.ts:26-55), so class identity and the runtime instanceof ORPCError check are unchanged, and @orpc/client is already a dependency of packages/effect.
• Extracted type helpers: ORPCErrorsOf, ORPCErrorCodeOf, ORPCErrorWithCode, ExcludeORPCErrorCode, LiteralORPCErrorCode, ORPCErrorCodeCases, HandledORPCErrorCodes, ORPCErrorCodeCasesEffect, and CatchORPCErrorCodesEffect replace the previous inline conditionals.
• catchORPCErrorCode narrowing: the error channel drops a member only when the caught code is a single literal (LiteralORPCErrorCode returns never for unions, string, and ORPCErrorCode) and that member's whole code union is contained in it; wide/union codes, ORPCError<string>, ORPCError<ORPCErrorCode>, AnyORPCError, and hidden-Error channels all keep the error in the channel.
• catchORPCErrorCodes handling: only required keys with a function value enter HandledORPCErrorCodes — undefined and optional handlers keep their code in the error channel, which fixes prior unsoundness where keyof Cases excluded those codes even though the getOwn runtime predicate skips them.
• Test coverage: added type tests for wide codes, union narrowing, ORPCError subclasses, AnyORPCError, undeclared keys on hidden channels, and optional/undefined handlers, plus the runtime import update.

Verification: tsc -b packages/effect --force, root tsc --noEmit -p tsconfig.json (covers *.test-d.ts), vitest run packages/effect/src/error.test.ts (20/20), and eslint on the three changed files all pass.

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