From 7ec7357356c67a3e5536ad722d555fab338141d2 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 16 Oct 2026 13:45:31 +0000
Subject: [PATCH 1/3] fix(effect): close type holes in catchORPCErrorCode and
 catchORPCErrorCodes

- Keep `ORPCError<any, any>` and wide-coded errors (e.g. `ORPCError<ORPCErrorCode, unknown>`,
  `ORPCError<string, unknown>`, union codes) in the result error channel, since catching one
  code does not catch the others.
- Narrow the handler error to the caught code instead of `never` for wide and union codes.
- Only exclude a member when every possible code is caught: `catchORPCErrorCode` requires a
  single literal code, and `catchORPCErrorCodes` only counts required keys whose value is a
  function, matching the runtime check.
- Merge success, error and services of handlers that may be `undefined` into the result.
- Import `ORPCError` from `@orpc/client` so client-only bundles do not pull in `@orpc/server`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lg5QRphdQBu6PCo88vV51o
---
 packages/effect/src/error.test-d.ts | 182 +++++++++++++++++++++++++++-
 packages/effect/src/error.test.ts   |   2 +-
 packages/effect/src/error.ts        | 113 +++++++++++------
 3 files changed, 257 insertions(+), 40 deletions(-)

diff --git a/packages/effect/src/error.test-d.ts b/packages/effect/src/error.test-d.ts
index 65cd32dce7..05c96d8680 100644
--- a/packages/effect/src/error.test-d.ts
+++ b/packages/effect/src/error.test-d.ts
@@ -1,4 +1,5 @@
-import type { ORPCError, ORPCErrorCode } from '@orpc/server'
+import type { AnyORPCError, ORPCErrorCode } from '@orpc/client'
+import { ORPCError } from '@orpc/client'
 import { Effect } from 'effect'
 import { catchORPCError, catchORPCErrorCode, catchORPCErrorCodes } from './error'
 
@@ -22,6 +23,14 @@ const effectWithHidden = {} as Effect.Effect<
   Service1
 >
 
+const effectWithAny = Effect.fail(new Error('boom') as unknown).pipe(
+  Effect.mapError(error => error instanceof ORPCError ? error : new ORPCError('INTERNAL_SERVER_ERROR')),
+)
+
+const effectWithWide = {} as Effect.Effect<'output', ORPCError<ORPCErrorCode, unknown>>
+const effectWithString = {} as Effect.Effect<'output', ORPCError<string, unknown>>
+const effectWithUnion = {} as Effect.Effect<'output', ORPCError<'NOT_FOUND' | 'CONFLICT', { id: string }>>
+
 describe('catchORPCError', () => {
   it('catches every ORPCError and excludes them from the error channel (data-last)', () => {
     const recovered = effect.pipe(catchORPCError((error) => {
@@ -180,6 +189,81 @@ describe('catchORPCErrorCode', () => {
     // @ts-expect-error - BAD_GATEWAY is not present and the channel cannot hold hidden ORPCErrors
     void withString.pipe(catchORPCErrorCode('BAD_GATEWAY', () => Effect.succeed('recovered')))
   })
+
+  it('keeps AnyORPCError in the error channel and narrows the handler to the caught code', () => {
+    expectTypeOf(effectWithAny).toEqualTypeOf<Effect.Effect<never, AnyORPCError>>()
+
+    const recovered = effectWithAny.pipe(catchORPCErrorCode('NOT_FOUND', (error) => {
+      expectTypeOf(error).toEqualTypeOf<ORPCError<'NOT_FOUND', any>>()
+      return Effect.succeed(error.code)
+    }))
+
+    expectTypeOf(recovered).toEqualTypeOf<Effect.Effect<'NOT_FOUND', AnyORPCError>>()
+  })
+
+  it('narrows wide codes to the caught code and keeps them in the error channel', () => {
+    const recoveredWide = effectWithWide.pipe(catchORPCErrorCode('NOT_FOUND', (error) => {
+      expectTypeOf(error).toEqualTypeOf<ORPCError<'NOT_FOUND', unknown>>()
+      return Effect.succeed(error.code)
+    }))
+
+    expectTypeOf(recoveredWide).toEqualTypeOf<Effect.Effect<'output' | 'NOT_FOUND', ORPCError<ORPCErrorCode, unknown>>>()
+
+    const recoveredString = catchORPCErrorCode(effectWithString, 'NOT_FOUND', (error) => {
+      expectTypeOf(error).toEqualTypeOf<ORPCError<'NOT_FOUND', unknown>>()
+      return Effect.succeed(error.code)
+    })
+
+    expectTypeOf(recoveredString).toEqualTypeOf<Effect.Effect<'output' | 'NOT_FOUND', ORPCError<string, unknown>>>()
+  })
+
+  it('narrows union codes to the caught code and keeps them in the error channel', () => {
+    const recovered = effectWithUnion.pipe(catchORPCErrorCode('NOT_FOUND', (error) => {
+      expectTypeOf(error).toEqualTypeOf<ORPCError<'NOT_FOUND', { id: string }>>()
+      return Effect.succeed(error.data.id)
+    }))
+
+    expectTypeOf(recovered).toEqualTypeOf<
+      Effect.Effect<'output' | string, ORPCError<'NOT_FOUND' | 'CONFLICT', { id: string }>>
+    >()
+  })
+
+  it('keeps errors in the error channel when the code is not a single literal', () => {
+    const code = {} as 'NOT_FOUND' | 'CONFLICT'
+
+    const recoveredUnion = effect.pipe(catchORPCErrorCode(code, (error) => {
+      expectTypeOf(error).toEqualTypeOf<ORPCError<'NOT_FOUND', { id: string }> | ORPCError<'CONFLICT', number>>()
+      return Effect.succeed('recovered' as const)
+    }))
+
+    expectTypeOf(recoveredUnion).toEqualTypeOf<
+      Effect.Effect<'output' | 'recovered', ORPCError<'NOT_FOUND', { id: string }> | ORPCError<'CONFLICT', number>, Service1>
+    >()
+
+    const recoveredString = effectWithHidden.pipe(catchORPCErrorCode({} as string, (error) => {
+      expectTypeOf(error).toEqualTypeOf<ORPCError<'NOT_FOUND', { id: string }> | ORPCError<string, unknown>>()
+      return Effect.succeed('recovered' as const)
+    }))
+
+    expectTypeOf(recoveredString).toEqualTypeOf<
+      Effect.Effect<'output' | 'recovered', ORPCError<'NOT_FOUND', { id: string }> | Error, Service1>
+    >()
+  })
+
+  it('keeps ORPCError subclasses', () => {
+    class NotFoundError extends ORPCError<'NOT_FOUND', { id: string }> {
+      declare readonly extra: 'extra'
+    }
+
+    const withSubclass = {} as Effect.Effect<'output', NotFoundError | ORPCError<'CONFLICT', number>>
+
+    const recovered = withSubclass.pipe(catchORPCErrorCode('NOT_FOUND', (error) => {
+      expectTypeOf(error).toEqualTypeOf<NotFoundError>()
+      return Effect.succeed(error.extra)
+    }))
+
+    expectTypeOf(recovered).toEqualTypeOf<Effect.Effect<'output' | 'extra', ORPCError<'CONFLICT', number>>>()
+  })
 })
 
 describe('catchORPCErrorCodes', () => {
@@ -246,4 +330,100 @@ describe('catchORPCErrorCodes', () => {
     // @ts-expect-error - BAD_GATEWAY is not present and the channel cannot hold hidden ORPCErrors
     void withString.pipe(catchORPCErrorCodes({ BAD_GATEWAY: () => Effect.succeed('recovered') }))
   })
+
+  it('keeps AnyORPCError in the error channel', () => {
+    const recovered = effectWithAny.pipe(catchORPCErrorCodes({
+      NOT_FOUND: (error) => {
+        expectTypeOf(error).toEqualTypeOf<AnyORPCError>()
+        return Effect.succeed('nf' as const)
+      },
+    }))
+
+    expectTypeOf(recovered).toEqualTypeOf<Effect.Effect<'nf', AnyORPCError>>()
+  })
+
+  it('types handlers of wide codes and keeps them in the error channel', () => {
+    const recoveredWide = effectWithWide.pipe(catchORPCErrorCodes({
+      NOT_FOUND: (error) => {
+        expectTypeOf(error).toEqualTypeOf<ORPCError<'NOT_FOUND', unknown>>()
+        return Effect.succeed('nf' as const)
+      },
+    }))
+
+    expectTypeOf(recoveredWide).toEqualTypeOf<Effect.Effect<'output' | 'nf', ORPCError<ORPCErrorCode, unknown>>>()
+
+    const recoveredString = catchORPCErrorCodes(effectWithString, {
+      NOT_FOUND: (error) => {
+        expectTypeOf(error).toEqualTypeOf<ORPCError<string, unknown>>()
+        return Effect.succeed('nf' as const)
+      },
+    })
+
+    expectTypeOf(recoveredString).toEqualTypeOf<Effect.Effect<'output' | 'nf', ORPCError<string, unknown>>>()
+  })
+
+  it('types handlers of undeclared keys when the channel can hold hidden ORPCErrors', () => {
+    void effectWithHidden.pipe(catchORPCErrorCodes({
+      __CUSTOM__: (error) => {
+        expectTypeOf(error).toExtend<AnyORPCError>()
+        expectTypeOf(error.code).toExtend<string>()
+        expectTypeOf(error.data).toEqualTypeOf<unknown>()
+        return Effect.succeed('recovered' as const)
+      },
+    }))
+  })
+
+  it('narrows union codes and excludes them only once every code is handled', () => {
+    const recoveredOne = effectWithUnion.pipe(catchORPCErrorCodes({
+      NOT_FOUND: (error) => {
+        expectTypeOf(error).toEqualTypeOf<ORPCError<'NOT_FOUND', { id: string }>>()
+        return Effect.succeed('nf' as const)
+      },
+    }))
+
+    expectTypeOf(recoveredOne).toEqualTypeOf<
+      Effect.Effect<'output' | 'nf', ORPCError<'NOT_FOUND' | 'CONFLICT', { id: string }>>
+    >()
+
+    const recoveredAll = effectWithUnion.pipe(catchORPCErrorCodes({
+      NOT_FOUND: () => Effect.succeed('nf' as const),
+      CONFLICT: (error) => {
+        expectTypeOf(error).toEqualTypeOf<ORPCError<'CONFLICT', { id: string }>>()
+        return Effect.succeed('cf' as const)
+      },
+    }))
+
+    expectTypeOf(recoveredAll).toEqualTypeOf<Effect.Effect<'output' | 'nf' | 'cf', never>>()
+  })
+
+  it('keeps codes whose handler can be undefined in the error channel', () => {
+    const recoveredUndefined = effect.pipe(catchORPCErrorCodes({
+      NOT_FOUND: undefined,
+      CONFLICT: () => Effect.succeed('cf' as const),
+    }))
+
+    expectTypeOf(recoveredUndefined).toEqualTypeOf<
+      Effect.Effect<'output' | 'cf', ORPCError<'NOT_FOUND', { id: string }>, Service1>
+    >()
+
+    const maybeHandler = {} as ((error: ORPCError<'NOT_FOUND', { id: string }>) => Effect.Effect<'nf', RangeError, Service2>) | undefined
+
+    const recoveredMaybe = effect.pipe(catchORPCErrorCodes({ NOT_FOUND: maybeHandler }))
+
+    expectTypeOf(recoveredMaybe).toEqualTypeOf<
+      Effect.Effect<
+        'output' | 'nf',
+        ORPCError<'NOT_FOUND', { id: string }> | ORPCError<'CONFLICT', number> | RangeError,
+        Service1 | Service2
+      >
+    >()
+
+    const optionalCases = {} as { NOT_FOUND?: (error: ORPCError<'NOT_FOUND', { id: string }>) => Effect.Effect<'nf'> }
+
+    const recoveredOptional = effect.pipe(catchORPCErrorCodes(optionalCases))
+
+    expectTypeOf(recoveredOptional).toEqualTypeOf<
+      Effect.Effect<'output' | 'nf', ORPCError<'NOT_FOUND', { id: string }> | ORPCError<'CONFLICT', number>, Service1>
+    >()
+  })
 })
diff --git a/packages/effect/src/error.test.ts b/packages/effect/src/error.test.ts
index fe6addf3bf..8b3f6ea415 100644
--- a/packages/effect/src/error.test.ts
+++ b/packages/effect/src/error.test.ts
@@ -1,4 +1,4 @@
-import { ORPCError } from '@orpc/server'
+import { ORPCError } from '@orpc/client'
 import { Cause, Effect, Exit } from 'effect'
 import { catchORPCError, catchORPCErrorCode, catchORPCErrorCodes } from './error'
 
diff --git a/packages/effect/src/error.ts b/packages/effect/src/error.ts
index 320c49a28b..e9805ba815 100644
--- a/packages/effect/src/error.ts
+++ b/packages/effect/src/error.ts
@@ -1,8 +1,67 @@
-import type { AnyORPCError, ORPCErrorCode } from '@orpc/server'
-import { ORPCError } from '@orpc/server'
+import type { AnyORPCError, ORPCErrorCode } from '@orpc/client'
+import { ORPCError } from '@orpc/client'
 import { getOwn } from '@orpc/shared'
 import { Effect, Function } from 'effect'
 
+type AnyEffect = Effect.Effect<any, any, any>
+
+/**
+ * Codes an `ORPCError` in `E` can have. Any code is possible when `E`
+ * can hold hidden `ORPCError` instances.
+ */
+type ORPCErrorCodeOf<E> = E extends ORPCError<infer TCode, any> ? TCode : AnyORPCError extends E ? ORPCErrorCode : never
+
+/**
+ * The `ORPCError`s in `E` whose code can be `TCode`, narrowed to `TCode`.
+ * Hidden `ORPCError` instances have unknown data.
+ */
+type ORPCErrorWithCode<E, TCode extends ORPCErrorCode> = E extends AnyORPCError
+  ? E extends ORPCError<infer UCode, infer UData>
+    ? 0 extends (1 & UCode)
+      ? ORPCError<TCode, UData>
+      : [UCode] extends [TCode]
+          ? E
+          : [UCode & TCode] extends [never] ? never : ORPCError<UCode & TCode, UData>
+    : never
+  : AnyORPCError extends E ? ORPCError<TCode, unknown> : never
+
+/**
+ * `E` without the `ORPCError`s whose every possible code is in `TCode`.
+ */
+type ExcludeORPCErrorCode<E, TCode extends string> = E extends ORPCError<infer UCode, any>
+  ? 0 extends (1 & UCode) ? E : [UCode] extends [TCode] ? never : E
+  : E
+
+/**
+ * `TCode` if it is a single literal code, `never` otherwise.
+ */
+type LiteralORPCErrorCode<TCode extends string, UCode extends string = TCode> = UCode extends string
+  ? [TCode] extends [UCode] ? Record<never, never> extends Record<UCode, unknown> ? never : UCode : never
+  : never
+
+/**
+ * The codes `TCases` handles: required, literal keys with a function value.
+ */
+type HandledORPCErrorCodes<TCases> = {
+  [K in keyof TCases]-?: Record<never, never> extends Pick<TCases, K> ? never : TCases[K] extends (...args: any[]) => any ? K : never
+}[keyof TCases] & string
+
+/**
+ * The handlers `catchORPCErrorCodes` accepts, keyed by the codes in `E`.
+ * Non-literal codes (e.g. hidden `ORPCError` instances) become an index
+ * signature, whose handler is bivariant so it accepts every literal handler.
+ */
+type ORPCErrorCodeCases<E> = {
+  [K in ORPCErrorCodeOf<E>]?: Record<never, never> extends Record<K, unknown>
+    ? { bivarianceHack(error: ORPCErrorWithCode<E, K>): AnyEffect }['bivarianceHack']
+    : (error: ORPCErrorWithCode<E, K>) => AnyEffect
+}
+
+/**
+ * The effects the handlers in `TCases` can return.
+ */
+type ORPCErrorCodeCasesEffect<TCases, TCase = TCases[keyof TCases]> = TCase extends (...args: any[]) => infer U ? U : never
+
 /**
  * Recovers from `ORPCError` failures in the error channel of an effect.
  * Other failures re-fail with their original cause. Because failure types
@@ -66,15 +125,15 @@ export const catchORPCError: {
  * @see {@link https://orpc.dev/docs/integrations/effect#catching-orpcerrors | Effect Integration - Catching ORPCErrors}
  */
 export const catchORPCErrorCode: {
-  <const TCode extends E extends ORPCError<infer TCode, any> ? TCode : AnyORPCError extends E ? ORPCErrorCode : never, E, A2, E2, R2>(
+  <const TCode extends ORPCErrorCodeOf<E>, E, A2, E2, R2>(
     code: TCode,
-    f: (error: E extends AnyORPCError ? Extract<E, ORPCError<TCode, any>> : AnyORPCError extends E ? ORPCError<TCode, unknown> : never) => Effect.Effect<A2, E2, R2>,
-  ): <A, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A | A2, E2 | Exclude<E, ORPCError<TCode, any>>, R | R2>
-  <A, E, R, const TCode extends E extends ORPCError<infer TCode, any> ? TCode : AnyORPCError extends E ? ORPCErrorCode : never, A2, E2, R2>(
+    f: (error: ORPCErrorWithCode<E, TCode>) => Effect.Effect<A2, E2, R2>,
+  ): <A, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A | A2, E2 | ExcludeORPCErrorCode<E, LiteralORPCErrorCode<TCode>>, R | R2>
+  <A, E, R, const TCode extends ORPCErrorCodeOf<E>, A2, E2, R2>(
     self: Effect.Effect<A, E, R>,
     code: TCode,
-    f: (error: E extends AnyORPCError ? Extract<E, ORPCError<TCode, any>> : AnyORPCError extends E ? ORPCError<TCode, unknown> : never) => Effect.Effect<A2, E2, R2>,
-  ): Effect.Effect<A | A2, E2 | Exclude<E, ORPCError<TCode, any>>, R | R2>
+    f: (error: ORPCErrorWithCode<E, TCode>) => Effect.Effect<A2, E2, R2>,
+  ): Effect.Effect<A | A2, E2 | ExcludeORPCErrorCode<E, LiteralORPCErrorCode<TCode>>, R | R2>
 } = Function.dual(
   3,
   (
@@ -114,42 +173,20 @@ export const catchORPCErrorCode: {
  * @see {@link https://orpc.dev/docs/integrations/effect#catching-orpcerrors | Effect Integration - Catching ORPCErrors}
  */
 export const catchORPCErrorCodes: {
-  <
-    E,
-    Cases extends
-    & { [K in E extends ORPCError<infer TCode, any> ? TCode : AnyORPCError extends E ? ORPCErrorCode : never]?: string extends K
-      ? (error: never) => Effect.Effect<any, any, any>
-      : K extends infer C extends ORPCErrorCode
-        ? (error: E extends AnyORPCError ? Extract<E, ORPCError<C, any>> : AnyORPCError extends E ? ORPCError<C, unknown> : never) => Effect.Effect<any, any, any>
-        : never }
-        & { [K in Exclude<keyof Cases, E extends ORPCError<infer TCode, any> ? TCode : AnyORPCError extends E ? ORPCErrorCode : never>]: never },
-  >(
+  <E, Cases extends ORPCErrorCodeCases<E> & { [K in Exclude<keyof Cases, ORPCErrorCodeOf<E>>]: never }>(
     cases: Cases,
   ): <A, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<
-    A | { [K in keyof Cases]: Cases[K] extends (...args: any[]) => Effect.Effect<infer A2, any, any> ? A2 : never }[keyof Cases],
-    | Exclude<E, ORPCError<keyof Cases & ORPCErrorCode, any>>
-    | { [K in keyof Cases]: Cases[K] extends (...args: any[]) => Effect.Effect<any, infer E2, any> ? E2 : never }[keyof Cases],
-    R | { [K in keyof Cases]: Cases[K] extends (...args: any[]) => Effect.Effect<any, any, infer R2> ? R2 : never }[keyof Cases]
+    A | Effect.Success<ORPCErrorCodeCasesEffect<Cases>>,
+    ExcludeORPCErrorCode<E, HandledORPCErrorCodes<Cases>> | Effect.Error<ORPCErrorCodeCasesEffect<Cases>>,
+    R | Effect.Services<ORPCErrorCodeCasesEffect<Cases>>
   >
-  <
-    A,
-    E,
-    R,
-    Cases extends
-    & { [K in E extends ORPCError<infer TCode, any> ? TCode : AnyORPCError extends E ? ORPCErrorCode : never]?: string extends K
-      ? (error: never) => Effect.Effect<any, any, any>
-      : K extends infer C extends ORPCErrorCode
-        ? (error: E extends AnyORPCError ? Extract<E, ORPCError<C, any>> : AnyORPCError extends E ? ORPCError<C, unknown> : never) => Effect.Effect<any, any, any>
-        : never }
-        & { [K in Exclude<keyof Cases, E extends ORPCError<infer TCode, any> ? TCode : AnyORPCError extends E ? ORPCErrorCode : never>]: never },
-  >(
+  <A, E, R, Cases extends ORPCErrorCodeCases<E> & { [K in Exclude<keyof Cases, ORPCErrorCodeOf<E>>]: never }>(
     self: Effect.Effect<A, E, R>,
     cases: Cases,
   ): Effect.Effect<
-    A | { [K in keyof Cases]: Cases[K] extends (...args: any[]) => Effect.Effect<infer A2, any, any> ? A2 : never }[keyof Cases],
-    | Exclude<E, ORPCError<keyof Cases & ORPCErrorCode, any>>
-    | { [K in keyof Cases]: Cases[K] extends (...args: any[]) => Effect.Effect<any, infer E2, any> ? E2 : never }[keyof Cases],
-    R | { [K in keyof Cases]: Cases[K] extends (...args: any[]) => Effect.Effect<any, any, infer R2> ? R2 : never }[keyof Cases]
+    A | Effect.Success<ORPCErrorCodeCasesEffect<Cases>>,
+    ExcludeORPCErrorCode<E, HandledORPCErrorCodes<Cases>> | Effect.Error<ORPCErrorCodeCasesEffect<Cases>>,
+    R | Effect.Services<ORPCErrorCodeCasesEffect<Cases>>
   >
 } = Function.dual(
   2,

From 12ac20c8bf77b301c23d91bf5dcec9fedeb654d0 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 17 Oct 2026 02:26:29 +0000
Subject: [PATCH 2/3] refactor(effect): simplify catchORPCErrorCode(s) type
 helpers

- Define the "which ORPCErrors can a handler receive" rule once (`ORPCErrorsOf`)
  and reuse it in `catchORPCError` and for the code suggestions.
- Flatten `ORPCErrorWithCode` to a single inference check, and test code
  coverage with `Exclude` so `any` codes need no special-case guard.
- Reuse effect's `Types.IsUnion`, `Types.RequiredKeys`, `Types.NoExcessProperties`
  and the built-in `ReturnType` instead of hand-written equivalents.
- Share the `catchORPCErrorCodes` result type between both overloads, and use
  `AnyEffect` in the runtime signatures.

No type or runtime behavior change; per-call type instantiations drop by 16-27%.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lg5QRphdQBu6PCo88vV51o
---
 packages/effect/src/error.ts | 97 +++++++++++++++++++-----------------
 1 file changed, 50 insertions(+), 47 deletions(-)

diff --git a/packages/effect/src/error.ts b/packages/effect/src/error.ts
index e9805ba815..bbc8de12fb 100644
--- a/packages/effect/src/error.ts
+++ b/packages/effect/src/error.ts
@@ -1,4 +1,5 @@
 import type { AnyORPCError, ORPCErrorCode } from '@orpc/client'
+import type { Types } from 'effect'
 import { ORPCError } from '@orpc/client'
 import { getOwn } from '@orpc/shared'
 import { Effect, Function } from 'effect'
@@ -6,61 +7,71 @@ import { Effect, Function } from 'effect'
 type AnyEffect = Effect.Effect<any, any, any>
 
 /**
- * Codes an `ORPCError` in `E` can have. Any code is possible when `E`
- * can hold hidden `ORPCError` instances.
+ * The `ORPCError`s a handler can receive from `E`. Failure types like `Error`
+ * can also hold hidden `ORPCError` instances, whose code and data are unknown.
  */
-type ORPCErrorCodeOf<E> = E extends ORPCError<infer TCode, any> ? TCode : AnyORPCError extends E ? ORPCErrorCode : never
+type ORPCErrorsOf<E> = E extends AnyORPCError ? E : AnyORPCError extends E ? ORPCError<ORPCErrorCode, unknown> : never
 
 /**
- * The `ORPCError`s in `E` whose code can be `TCode`, narrowed to `TCode`.
- * Hidden `ORPCError` instances have unknown data.
+ * The codes of the `ORPCError`s a handler can receive from `E`.
  */
-type ORPCErrorWithCode<E, TCode extends ORPCErrorCode> = E extends AnyORPCError
-  ? E extends ORPCError<infer UCode, infer UData>
-    ? 0 extends (1 & UCode)
-      ? ORPCError<TCode, UData>
-      : [UCode] extends [TCode]
-          ? E
-          : [UCode & TCode] extends [never] ? never : ORPCError<UCode & TCode, UData>
-    : never
+type ORPCErrorCodeOf<E> = ORPCErrorsOf<E>['code']
+
+/**
+ * The `ORPCError`s a handler for `TCode` can receive from `E`, narrowed to
+ * `TCode`. Errors whose every possible code is in `TCode` are kept as is.
+ */
+type ORPCErrorWithCode<E, TCode extends ORPCErrorCode> = E extends ORPCError<infer UCode, infer UData>
+  ? [Exclude<UCode, TCode>] extends [never]
+      ? E
+      : [UCode & TCode] extends [never] ? never : ORPCError<TCode extends UCode ? TCode : TCode & UCode, UData>
   : AnyORPCError extends E ? ORPCError<TCode, unknown> : never
 
 /**
  * `E` without the `ORPCError`s whose every possible code is in `TCode`.
  */
 type ExcludeORPCErrorCode<E, TCode extends string> = E extends ORPCError<infer UCode, any>
-  ? 0 extends (1 & UCode) ? E : [UCode] extends [TCode] ? never : E
+  ? [Exclude<UCode, TCode>] extends [never] ? never : E
   : E
 
 /**
  * `TCode` if it is a single literal code, `never` otherwise.
  */
-type LiteralORPCErrorCode<TCode extends string, UCode extends string = TCode> = UCode extends string
-  ? [TCode] extends [UCode] ? Record<never, never> extends Record<UCode, unknown> ? never : UCode : never
-  : never
-
-/**
- * The codes `TCases` handles: required, literal keys with a function value.
- */
-type HandledORPCErrorCodes<TCases> = {
-  [K in keyof TCases]-?: Record<never, never> extends Pick<TCases, K> ? never : TCases[K] extends (...args: any[]) => any ? K : never
-}[keyof TCases] & string
+type LiteralORPCErrorCode<TCode extends string> = Types.IsUnion<TCode> extends true
+  ? never
+  : Record<never, never> extends Record<TCode, unknown> ? never : TCode
 
 /**
  * The handlers `catchORPCErrorCodes` accepts, keyed by the codes in `E`.
  * Non-literal codes (e.g. hidden `ORPCError` instances) become an index
  * signature, whose handler is bivariant so it accepts every literal handler.
  */
-type ORPCErrorCodeCases<E> = {
+type ORPCErrorCodeCases<E, TCases> = Types.NoExcessProperties<{
   [K in ORPCErrorCodeOf<E>]?: Record<never, never> extends Record<K, unknown>
     ? { bivarianceHack(error: ORPCErrorWithCode<E, K>): AnyEffect }['bivarianceHack']
     : (error: ORPCErrorWithCode<E, K>) => AnyEffect
-}
+}, TCases>
+
+/**
+ * The codes `TCases` surely handles: required keys with a function value.
+ */
+type HandledORPCErrorCodes<TCases> = {
+  [K in keyof TCases]-?: TCases[K] extends (...args: any[]) => any ? K : never
+}[Types.RequiredKeys<TCases>] & string
 
 /**
  * The effects the handlers in `TCases` can return.
  */
-type ORPCErrorCodeCasesEffect<TCases, TCase = TCases[keyof TCases]> = TCase extends (...args: any[]) => infer U ? U : never
+type ORPCErrorCodeCasesEffect<TCases> = ReturnType<Extract<TCases[keyof TCases], (...args: any[]) => any>>
+
+/**
+ * `self` with the codes `TCases` handles caught by its handlers.
+ */
+type CatchORPCErrorCodesEffect<A, E, R, TCases> = Effect.Effect<
+  A | Effect.Success<ORPCErrorCodeCasesEffect<TCases>>,
+  ExcludeORPCErrorCode<E, HandledORPCErrorCodes<TCases>> | Effect.Error<ORPCErrorCodeCasesEffect<TCases>>,
+  R | Effect.Services<ORPCErrorCodeCasesEffect<TCases>>
+>
 
 /**
  * Recovers from `ORPCError` failures in the error channel of an effect.
@@ -84,17 +95,17 @@ type ORPCErrorCodeCasesEffect<TCases, TCase = TCases[keyof TCases]> = TCase exte
  */
 export const catchORPCError: {
   <E, A2, E2, R2>(
-    f: (error: E extends AnyORPCError ? E : AnyORPCError extends E ? ORPCError<ORPCErrorCode, unknown> : never) => Effect.Effect<A2, E2, R2>,
+    f: (error: ORPCErrorsOf<E>) => Effect.Effect<A2, E2, R2>,
   ): <A, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A | A2, E2 | Exclude<E, AnyORPCError>, R | R2>
   <A, E, R, A2, E2, R2>(
     self: Effect.Effect<A, E, R>,
-    f: (error: E extends AnyORPCError ? E : AnyORPCError extends E ? ORPCError<ORPCErrorCode, unknown> : never) => Effect.Effect<A2, E2, R2>,
+    f: (error: ORPCErrorsOf<E>) => Effect.Effect<A2, E2, R2>,
   ): Effect.Effect<A | A2, E2 | Exclude<E, AnyORPCError>, R | R2>
 } = Function.dual(
   2,
   (
-    self: Effect.Effect<any, any, any>,
-    f: (error: AnyORPCError) => Effect.Effect<any, any, any>,
+    self: AnyEffect,
+    f: (error: AnyORPCError) => AnyEffect,
   ) => self.pipe(
     Effect.catchIf((error): error is AnyORPCError => error instanceof ORPCError, f),
   ),
@@ -137,9 +148,9 @@ export const catchORPCErrorCode: {
 } = Function.dual(
   3,
   (
-    self: Effect.Effect<any, any, any>,
+    self: AnyEffect,
     code: ORPCErrorCode,
-    f: (error: AnyORPCError) => Effect.Effect<any, any, any>,
+    f: (error: AnyORPCError) => AnyEffect,
   ) => self.pipe(
     Effect.catchIf((error): error is AnyORPCError => error instanceof ORPCError && error.code === code, f),
   ),
@@ -173,26 +184,18 @@ export const catchORPCErrorCode: {
  * @see {@link https://orpc.dev/docs/integrations/effect#catching-orpcerrors | Effect Integration - Catching ORPCErrors}
  */
 export const catchORPCErrorCodes: {
-  <E, Cases extends ORPCErrorCodeCases<E> & { [K in Exclude<keyof Cases, ORPCErrorCodeOf<E>>]: never }>(
+  <E, Cases extends ORPCErrorCodeCases<E, Cases>>(
     cases: Cases,
-  ): <A, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<
-    A | Effect.Success<ORPCErrorCodeCasesEffect<Cases>>,
-    ExcludeORPCErrorCode<E, HandledORPCErrorCodes<Cases>> | Effect.Error<ORPCErrorCodeCasesEffect<Cases>>,
-    R | Effect.Services<ORPCErrorCodeCasesEffect<Cases>>
-  >
-  <A, E, R, Cases extends ORPCErrorCodeCases<E> & { [K in Exclude<keyof Cases, ORPCErrorCodeOf<E>>]: never }>(
+  ): <A, R>(self: Effect.Effect<A, E, R>) => CatchORPCErrorCodesEffect<A, E, R, Cases>
+  <A, E, R, Cases extends ORPCErrorCodeCases<E, Cases>>(
     self: Effect.Effect<A, E, R>,
     cases: Cases,
-  ): Effect.Effect<
-    A | Effect.Success<ORPCErrorCodeCasesEffect<Cases>>,
-    ExcludeORPCErrorCode<E, HandledORPCErrorCodes<Cases>> | Effect.Error<ORPCErrorCodeCasesEffect<Cases>>,
-    R | Effect.Services<ORPCErrorCodeCasesEffect<Cases>>
-  >
+  ): CatchORPCErrorCodesEffect<A, E, R, Cases>
 } = Function.dual(
   2,
   (
-    self: Effect.Effect<any, any, any>,
-    cases: Record<string, ((error: AnyORPCError) => Effect.Effect<any, any, any>) | undefined>,
+    self: AnyEffect,
+    cases: Record<string, ((error: AnyORPCError) => AnyEffect) | undefined>,
   ) => self.pipe(
     Effect.catchIf(
       (error): error is AnyORPCError => error instanceof ORPCError && typeof getOwn(cases, error.code) === 'function',

From 14845a6d472f205841752ff1bea25c9e3abe5363 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 17 Oct 2026 02:45:58 +0000
Subject: [PATCH 3/3] refactor(effect): drop helper comments covered by type
 tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lg5QRphdQBu6PCo88vV51o
---
 packages/effect/src/error.ts | 28 ----------------------------
 1 file changed, 28 deletions(-)

diff --git a/packages/effect/src/error.ts b/packages/effect/src/error.ts
index bbc8de12fb..989d03ae09 100644
--- a/packages/effect/src/error.ts
+++ b/packages/effect/src/error.ts
@@ -6,46 +6,24 @@ import { Effect, Function } from 'effect'
 
 type AnyEffect = Effect.Effect<any, any, any>
 
-/**
- * The `ORPCError`s a handler can receive from `E`. Failure types like `Error`
- * can also hold hidden `ORPCError` instances, whose code and data are unknown.
- */
 type ORPCErrorsOf<E> = E extends AnyORPCError ? E : AnyORPCError extends E ? ORPCError<ORPCErrorCode, unknown> : never
 
-/**
- * The codes of the `ORPCError`s a handler can receive from `E`.
- */
 type ORPCErrorCodeOf<E> = ORPCErrorsOf<E>['code']
 
-/**
- * The `ORPCError`s a handler for `TCode` can receive from `E`, narrowed to
- * `TCode`. Errors whose every possible code is in `TCode` are kept as is.
- */
 type ORPCErrorWithCode<E, TCode extends ORPCErrorCode> = E extends ORPCError<infer UCode, infer UData>
   ? [Exclude<UCode, TCode>] extends [never]
       ? E
       : [UCode & TCode] extends [never] ? never : ORPCError<TCode extends UCode ? TCode : TCode & UCode, UData>
   : AnyORPCError extends E ? ORPCError<TCode, unknown> : never
 
-/**
- * `E` without the `ORPCError`s whose every possible code is in `TCode`.
- */
 type ExcludeORPCErrorCode<E, TCode extends string> = E extends ORPCError<infer UCode, any>
   ? [Exclude<UCode, TCode>] extends [never] ? never : E
   : E
 
-/**
- * `TCode` if it is a single literal code, `never` otherwise.
- */
 type LiteralORPCErrorCode<TCode extends string> = Types.IsUnion<TCode> extends true
   ? never
   : Record<never, never> extends Record<TCode, unknown> ? never : TCode
 
-/**
- * The handlers `catchORPCErrorCodes` accepts, keyed by the codes in `E`.
- * Non-literal codes (e.g. hidden `ORPCError` instances) become an index
- * signature, whose handler is bivariant so it accepts every literal handler.
- */
 type ORPCErrorCodeCases<E, TCases> = Types.NoExcessProperties<{
   [K in ORPCErrorCodeOf<E>]?: Record<never, never> extends Record<K, unknown>
     ? { bivarianceHack(error: ORPCErrorWithCode<E, K>): AnyEffect }['bivarianceHack']
@@ -59,14 +37,8 @@ type HandledORPCErrorCodes<TCases> = {
   [K in keyof TCases]-?: TCases[K] extends (...args: any[]) => any ? K : never
 }[Types.RequiredKeys<TCases>] & string
 
-/**
- * The effects the handlers in `TCases` can return.
- */
 type ORPCErrorCodeCasesEffect<TCases> = ReturnType<Extract<TCases[keyof TCases], (...args: any[]) => any>>
 
-/**
- * `self` with the codes `TCases` handles caught by its handlers.
- */
 type CatchORPCErrorCodesEffect<A, E, R, TCases> = Effect.Effect<
   A | Effect.Success<ORPCErrorCodeCasesEffect<TCases>>,
   ExcludeORPCErrorCode<E, HandledORPCErrorCodes<TCases>> | Effect.Error<ORPCErrorCodeCasesEffect<TCases>>,