feat(effect): add catchORPCError, catchORPCErrorCode and catchORPCErrorCodes utils

[dinwwwh]

Adds catchORPCError, catchORPCErrorCode and catchORPCErrorCodes to @orpc/experimental-effect for recovering from ORPCError failures in an effect's error channel. Recovered errors are excluded from the resulting effect's error channel, and non-matching failures re-fail with their original cause.

Details

• All utilities support data-first and data-last (.pipe) styles, following Effect's dual convention.
• Handlers receive the matching errors narrowed from the error channel, with per-code data types preserved.
• catchORPCErrorCode and catchORPCErrorCodes mirror Effect's catchTag/catchTags naming and suggest/restrict codes to those present in the error channel.
• Defects and interruptions are not caught.

Testing

• Logic tests cover all call styles, code matching/mismatch, partial and undefined handler maps, non-ORPCError passthrough, defects, successes, and re-failing handlers — 100% statement/branch/function/line coverage on the new module.
• Type tests verify handler narrowing, error-channel exclusion, requirement merging, custom codes, and rejection of out-of-channel codes and map keys.
• Docs: new "Catching ORPCErrors" section on the Effect integration page.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
orpc	Ready	Preview	Aug 2, 2026 2:51pm

[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@1766

@orpc/arktype

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

@orpc/bun

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

@orpc/client

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

@orpc/cloudflare

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

@orpc/contract

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

@orpc/experimental-effect

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

@orpc/evlog

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

@orpc/json-schema

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

@orpc/nest

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

@orpc/next

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

@orpc/openapi

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

@orpc/opentelemetry

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

@orpc/pinia-colada

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

@orpc/pino

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

@orpc/publisher

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

@orpc/ratelimit

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

@orpc/server

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

@orpc/shared

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

@orpc/swr

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

@orpc/tanstack-query

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

@orpc/trpc

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

@orpc/valibot

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

@orpc/zod

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

commit: 8edc5b3

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codspeed-hq]

Merging this PR will not alter performance

✅ 25 untouched benchmarks

---

_{Comparing dinwwwh:claude/catch-orpc-error-utils-2e8418 (8edc5b3) with main (240215c)}

[pullfrog]

✅ No new issues found.

Reviewed changes — adds catchORPCError and catchORPCErrorByCode to @orpc/experimental-effect for recovering from ORPCError failures in an effect's error channel.

• catchORPCError / catchORPCErrorByCode (error.ts) — two Function.dual utilities wrapping Effect.catchIf with an instanceof ORPCError type guard, following the same pattern as the existing succeedOnORPCError in handler.ts. catchORPCError handles every ORPCError code; catchORPCErrorByCode narrows by code and constrains the code argument to the codes present in the error channel.
• Runtime tests (error.test.ts) — 12 tests covering data-first/data-last call styles, code matching and mismatch, non-ORPCError passthrough, defects, successes, and re-failing handlers. 100% statement/branch/function/line coverage.
• Type tests (error.test-d.ts) — verifies handler narrowing, error-channel exclusion, requirement merging, never handler for ORPCError-free channels, custom codes, and rejection of out-of-channel codes.
• Barrel re-export (index.ts) — adds export * from './error'; export test updated.
• Docs (effect.md) — new "Catching ORPCErrors" section with import and usage examples.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes — renames catchORPCErrorByCode to catchORPCErrorCode and adds catchORPCErrorCodes for multi-code recovery.

• Renamed catchORPCErrorByCode → catchORPCErrorCode — aligns with Effect's catchTag naming convention, dropping the By prefix. All call sites, tests, type tests, and docs updated.
• Added catchORPCErrorCodes — accepts a map of code-to-handler entries, catching each ORPCError with the matching handler and excluding handled codes from the resulting error channel. Supports undefined handlers (treated as no-op for that code). Both data-first and data-last styles via Function.dual(2, ...).
• New tests — 7 runtime tests covering matching/mismatching codes, undefined handlers, non-ORPCError passthrough, successes, and re-failing handlers. 4 type tests covering narrowing, channel exclusion, and code-key restriction.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}