Should we remove the ability to return a typesafe ORPCError from .handler?

[dinwwwh]

In v2, a handler can return new ORPCError(...) and oRPC treats it as a typesafe error. The client can then infer its shape:

const getUser = os
  .input(z.object({ id: z.string() }))
  .handler(async ({ input }) => {
    const user = await db.findUser(input.id)

    if (!user) {
      return new ORPCError('NOT_FOUND', { data: { id: input.id } })
    }

    return user
  })

const [error, data, inferableError] = await safe(client.getUser({ id: '1' }))

if (inferableError) {
  inferableError.data.id // typed as string
}

I am thinking about removing this and keeping only throw. Here is why.

1. return for an error is not the JS/TS way

In JavaScript, return means success and throw means failure. oRPC v1 followed this rule: you always throw an ORPCError. Many users like that, and it matches the rest of the ecosystem. Libraries like Effect have their own error channel, but oRPC was never designed that way.

v2 added a second way. Now return new ORPCError(...) and throw new ORPCError(...) mean the same thing. You have to remember this rule when reading code, and a return that is actually an error is easy to misread.

2. Types and runtime can disagree

TypeScript can only detect a returned ORPCError when the return type is precise. If the handler returns unknown, any, {}, or a wide object type, TypeScript sees a normal output. But at runtime oRPC still checks instanceof ORPCError, throws the value, and marks it as inferable.

const example = os.handler(async () => {
  const result: unknown = await doSomething() // may be an ORPCError at runtime
  return result
})

const [error, data] = await safe(client.example())

if (isInferableError(error)) {
  // Type-level: `error` is `never`, TypeScript thinks this branch cannot run.
  // Runtime: this branch runs and `error` is an ORPCError.
}

With throw only, the rule is simple: what you return is the output, what you throw is an error. No hidden check in between.

3. Every handler pays for it

Runtime: every handler result goes through an instanceof ORPCError check. When it matches, the error is cloned and re-thrown with new flags. This runs on every call, even if you never use the feature.

Type-level: every .handler must split its return type into "output" and "error" using Exclude<T, AnyORPCError> and Extract<T, AnyORPCError>. Every Procedure also carries an extra TReturnedError generic that spreads into call, createProcedureClient, links, and integrations.

Removing this makes type checking faster and the types easier to read.

4. Cleaner API

• One way to signal an error: throw.
• Autocomplete no longer suggests returning an ORPCError from a handler.
• Simpler return types. This also applies to the contract-first approach. There, a returned ORPCError never affects client types (it is just thrown under the hood), but the handler return type is still Output | AnyORPCError today. After this change it would be just Output.
• Nothing is lost. .errors and the error() factory stay as the typesafe way to define errors:

const getUser = os
  .input(z.object({ id: z.string() }))
  .errors({
    NOT_FOUND: { data: z.object({ id: z.string() }) },
  })
  .handler(async ({ input, errors }) => {
    const user = await db.findUser(input.id)

    if (!user) {
      throw errors.NOT_FOUND({ data: { id: input.id } })
    }

    return user
  })

Please vote below and share your thoughts, especially if you rely on returning ORPCError today.

[tetrogem]

I would recommend keeping return errors.NOT_FOUND({ data: { id: input.id } }) (instead of throw) as then the TS typechecker can confirm its a valid error type, if you use throw you lose the benefit of having strict output error type checking for handlers.

Ideally, you should only be able to return the successful output value or explicitly defined error values, which is especially nice for documentation of what's returned with each error status code. throw/an opaque ORPCError should be reserved for unexpected errors/non-strict error types on projects that don't mind having them (as thrown types can't be checked/verified by TypeScript anyway)

[dinwwwh]

Thanks for the input. Two things:

1. The strict "only return the output or a defined error" check does not fit the current builder design. oRPC lets you call .errors after .handler, for example os.handler(...).errors({ ... }) (contract-first does not have this problem, since the contract defines the errors first). Errors defined later are not available as errors.X inside the handler, so users end up writing return new ORPCError('NOT_FOUND') instead. That is exactly the path this proposal removes.

2. Even if we keep return errors.X(...), reasons 1, 3, and 4 above still apply: two ways to signal an error, a runtime and type-level cost on every handler, and a more complex return type.

[tetrogem]

Point 2 is more of an implementation detail, and I don't know the inner workings of this library too well to comment on it, so for now I'll just address my thoughts on Point 1:

This seems fine to me, even if errors is called after handler -- This would just make it so no errors can be returned from handler (only thrown without typechecking, which putting .errors() first would still allow anyway so there's no difference in functionality). If the user wants to return their custom errors, they can specify the errors before the handler for them to be available. Defining them after just lists them as possibilities for the client to handle, it would just be that none of them would ever actually occur due to not being returnable in the handler. Overall though the system would still be typesafe.

I feel the bigger issue would be that ORPCError can merge with specified contract errors, as then without the type info beforehand, ORPCError could give the incorrect shape for a specific error status code. This behavior seems a bit unintuitive anyway and I'd personally recommend just splitting them so this auto-merging behavior doesn't exist, and just treating opaque ORPCErrors and custom defined errors as completely separate types. This would likely require the status to be returned along with the value in handlers in order to still be able to tell what value is attempting to be returned, but this more explicit syntax would be worth it for the benefits of stricter error typing in my opinion. I do understand this would be a large breaking change though. Some example code to better illustrate my idea:

const getUser = os
  .input(z.object({ id: z.string() }))
  .errors({
    NOT_FOUND: { data: z.object({ id: z.string() }) },
  })
  .handler(async ({ input, errors, success }) => {
    const user = await db.findUser(input.id)

    if (!user) {
      return errors.NOT_FOUND({ data: { id: input.id } }) // returns for example: { status: NOT_FOUND, value: { data: { id: input.id } } }
    }

    return success(user) // returns for example: { status: OK, value: user }
  })

This status allows orpc to know how to handle the return type. Thrown values are always treated as unknown/opaque errors (ORPCError) and can be handled separately from well-known success/error types by the client.

[JoeIaquinto]

How does this interact with the effect integration?

One lesson from effect is that throw and promise.reject make understanding what a function actually does really difficult. For example, if I call a function within my procedure, and the pattern is to throw new OrpcError, I don't know that function throws it because it's not part of its type definition. Errors as values is becoming more and more prevalent in the TS community.

[dinwwwh]

.handler will not allow return/infer ORPCError type anymore - so you need use .errors or error() factory for typesafe error, effect integration keep working but error will be throw without inferable.

throw and promise.reject make understanding what a function actually does really difficult.

Keep using Effect or other integration to deal with this, oRPC keep native (throw) by default.

[PaulSenon]

I agree with removing the special treatment of returned ORPCErrors from ordinary handlers. My suggestion is to give integrations such as Effect an explicit API for their typed error channel, while keeping an ordinary return on the success path.

I prototyped two primitives for adapter authors:

Primitive	The library supplies	oRPC returns
createHandlerAdapter	A conversion receiving { options, fail }	A descriptor accepted by .handler(...)
createClientAdapter	A result-type mapping and a conversion receiving { call }	A function that wraps a native client

The library defines its own representation. oRPC owns the typed boundary. There is no shared Result format and no requirement to use the same library on both sides.

Server: turn the library's error channel into an oRPC failure

The server conversion receives ordinary handler options (input, context, error constructors, cancellation signal) and fail(error):

• Success channel channel: Return a value
• Typed Error channel: Call fail(error): a failure from the adapter's typed oRPC error channel.
• Defect channel: Throw or reject normally: keep the ordinary exception path.

For Better Result, betterResultHandler(handler) captures the application function. When oRPC executes the procedure, the wrapper calls that function, unwraps Ok, or passes Err to fail. The generics preserve input, context, success and error types.

Complete generic server wrapper, including the captured handler

import type { AdaptedHandler, AnyORPCError, Context, ORPCErrorConstructorMap, ProcedureHandlerOptions } from '@orpc/server'
import type { Promisable } from '@orpc/shared'
import type { InferErr, InferOk, Result } from 'better-result'
import { createHandlerAdapter } from '@orpc/server'

export function betterResultHandler<TContext extends Context, TInput, TErrorConstructorMap extends ORPCErrorConstructorMap<any>, TResult extends Result<unknown, AnyORPCError>>(
  handler: (options: ProcedureHandlerOptions<TContext, TInput, TErrorConstructorMap>, input: TInput) => Promisable<TResult>,
): AdaptedHandler<TContext, TInput, InferOk<TResult>, InferErr<TResult>, TErrorConstructorMap> {
  return createHandlerAdapter(async ({ options, fail }) => {
    // Infer the whole result union before separating success and error branches.
    const result = await handler(options, options.input)
    return result.isOk() ? result.value as InferOk<TResult> : fail(result.error as InferErr<TResult>)
  })
}

The application supplies handler(options, input). The inner callback closes over it; oRPC supplies options and fail when executing that callback. This version supports async work and custom context.

Here is a deterministic business function with both a success and a failure:

import { ORPCError } from '@orpc/server'
import { Result } from 'better-result'

export function half(n: number) {
  return n % 2 === 0
    ? Result.ok(n / 2)
    : Result.err(new ORPCError('ODD_NUMBER', { data: { n } }))
}

Then connect it to oRPC:

import { betterResultHandler } from '@orpc/experimental-better-result'
import { os } from '@orpc/server'
import { z } from 'zod'
import { half } from './half'

export const router = {
  half: os.input(z.number().int())
    .handler(betterResultHandler(({ input }) => half(input))),
}

Zod checks the integer input; half handles the domain rule. The callback forwards oRPC's input to half. The function determines the success and error types without predeclaring ODD_NUMBER.

half(4) → Ok(2)           → return 2    → RPC success
half(3) → Err(ODD_NUMBER) → fail(error) → RPC failure

Client: turn an ordinary RPC call into the chosen representation

The client primitive works in the other direction. createClientAdapter receives a conversion and returns a wrapping function. Each invocation gives the conversion call(signal?), which starts the original RPC with its input and options.

The generic ResultKind below maps each procedure's output and oRPC error types to a Promise of Better Result. The conversion uses the existing safe() helper: success becomes Ok, an inferable oRPC error becomes Err, and other failures reject.

Complete generic client adapter

import type { AdaptedClient, AnyNestedClient, AnyORPCError, ClientAdapterKind } from '@orpc/client'
import { createClientAdapter, safe } from '@orpc/client'
import { Result } from 'better-result'

interface ResultKind extends ClientAdapterKind {
  readonly result: Promise<Result<this['output'], Extract<this['error'], AnyORPCError>>>
}
export type ResultClient<T extends AnyNestedClient> = AdaptedClient<T, ResultKind>

export const createResultClient = createClientAdapter<ResultKind>(async ({ call }) => {
  const result = await safe(call())
  if (result.isSuccess) {
    return Result.ok(result.data)
  }
  if (result.inferableError) {
    return Result.err(result.inferableError)
  }
  throw result.error
})

Apply that wrapping function to the native client and call both paths:

import { createResultClient } from '@orpc/experimental-better-result/client'
import { createRouterClient } from '@orpc/server'
import { router } from './router'

const rpc = createRouterClient(router)
const client = createResultClient(rpc)

const good = await client.half(4) // Ok(2)
const bad = await client.half(3) // Err: ODD_NUMBER

if (bad.isErr()) {
  console.log(bad.error.code) // 'ODD_NUMBER'
  console.log(bad.error.data.n) // 3; typed as number
}

This uses a direct client to keep the example small. The same adapter can wrap a remote oRPC client. Better Result objects do not cross the wire: the server emits ordinary RPC data/errors, and the client reconstructs its representation. A transport failure does not automatically become a typed business error.

Neither side chooses the other's library

An Effect client can call this Better Result handler. A Better Result client can call an Effect handler. A router can mix native, Effect, Better Result and DIY handlers while each client keeps its chosen representation. Adaptation can also be applied to an individual procedure.

Clients                                  Handlers

Native ─────────┐                  ┌──── Native
Effect ─────────┤                  ├──── Effect
Better Result ──┼───── oRPC ───────┼──── Better Result
DIY ────────────┘                  └──── DIY

Every client can call every handler; the rows do not imply matching pairs.

Three ways to establish the error types

Mode	Guarantee for adapted handlers
No declaration	Infer E from the adapter's typed failures. (replaces the current return new ORPCError(...))
.errors(...) before .handler(...)	Constrain E to the declared codes and payloads; provide typed error constructors.
Separate contract	Check input, output and adapted errors against that contract.

With declarations, errors.ODD_NUMBER(...) and a compatible new ORPCError('ODD_NUMBER', ...) are both accepted. An undeclared code or incompatible payload is a type error. An implementation may use a subset of the declared errors; .errors({}) allows no adapted failures. Without declarations, E stays inferred.

These guarantees concern the adapter's explicit error channel. Native throws do not become inferred checked exceptions, and unexpected failures remain possible. Internally, fail uses a private AdaptedFailure signal handled by oRPC; it is not an Effect defect. Effect.die on the server does not infer a business error. The Effect client's error channel includes ordinary call rejections, without reconstructing the server's Effect cause.

I think this is the best of both worlds. This way we keep oRPC native js/ts error handling at core, without any notion of built-in result pattern. But we give easy extension system to make anyone map any result system to oRPC internal representation, with total decoupling between client/server.

[dinwwwh]

Actually, almost all of your suggestions are already possible. See the Effect Integration.

The only difference is that I don't want to infer errors from .handler anymore, as that would simplify everything. If you need type-safe errors, you can use .errors or the error() factory.

[PaulSenon]

I think I focused too much on the API semantics argument and underweighted the internal complexity point. I was exploring whether inference could remain opt-in through adapters, while ordinary handlers followed native throw semantics. But I see that retaining the inference machinery itself is part of the cost you want to remove.

[dinwwwh]

Thanks everyone for your votes and suggestions! With an 85/15 split, return error will be removed in the next version!