orpc output type safety

[CaoKha]

Environment

• @orpc/server: 1.13.14
• TypeScript: 7.0.0-dev (tsgo)
• Node.js: 24.13.0
• OS: macOS (Darwin 25.4.0)

Reproduction

import { oc } from '@orpc/contract'
import { z } from 'zod'
import { os } from '@orpc/server'

const contract = oc.output(z.object({ name: z.string() }))

const procedure = os.contract(contract).handler(async () => {
  // No TS error here, even though `age` is not in the output schema
  return { name: 'Alice', age: 30 }
})

The handler returns { name: 'Alice', age: 30 } but the contract only defines { name: string }. TypeScript does not flag age as an excess property. At runtime, Zod strips age from the response, so the client never receives it.

Describe the bug

Handler return types are not strictly checked against the contract output schema at compile time. When a handler returns extra properties not defined in the output schema, TypeScript does not report an error. The extra fields are silently stripped at runtime by Zod's .strip() behavior, which can lead to subtle bugs that are hard to catch.

Additional context

This is fundamentally a TypeScript limitation (structural typing allows supersets), but frameworks like oRPC could enforce stricter types using utility types like Exact<T> or StrictOmit patterns to catch this at compile time.

Logs

[dosubot]

Hi @CaoKha! I'm Dosu and I’m helping the orpc team.

This is indeed a TypeScript structural typing limitation, as you noted. oRPC currently types the handler return as InferSchemaInput<TOutputSchema> [1], which means TypeScript will accept any object that is a superset of the required shape — so { name: 'Alice', age: 30 } satisfies { name: string } structurally.

There's no Exact<T> or similar utility type used in the codebase for handler return types [2]. The framework relies on runtime schema validation to enforce the output contract. This was a deliberate architectural choice when oRPC moved to schema-first type inference, removing explicit THandlerOutput type parameters in favor of schema-based inference [3].

In the meantime, a couple of workarounds:

• Explicit return type annotation — this triggers TypeScript's excess property checking:

  .handler(async (): Promise<{ name: string }> => {
    return { name: 'Alice', age: 30 } // TS error ✅
  })

• satisfies on the return value:

  .handler(async () => {
    return { name: 'Alice', age: 30 } satisfies { name: string } // TS error ✅
  })

• z.object().strict() on the output schema to make Zod throw at runtime instead of silently stripping.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[CaoKha]

@dosu I tried both solution 1 and 2 and it does not work since we used zod type and not primitive type as you mentioned. The third solution doesn't force typescript to throw error in compile time.

[dosubot]

You're right, I apologize for the misleading workarounds. Since the type comes from Zod's inference (not a manually written type), and TypeScript's satisfies and explicit return annotations both use structural typing under the hood, they won't catch excess properties either.

This is a genuine limitation — TypeScript's structural type system treats { name: string, age: number } as assignable to { name: string }, and there's no way around that with standard type annotations. The satisfies operator has the same structural compatibility rules.

The only way to get compile-time exact checking would be for oRPC to change how the handler return type is constrained internally — for example, by using a utility type like:

type Exact<T, U> = T & Record<Exclude<keyof U, keyof T>, never>

This would make excess properties resolve to never, causing a type error. But this is not currently implemented in oRPC [1]. The handler return type is simply InferSchemaInput<TOutputSchema> [2], which uses plain structural assignability.

So to summarize: there's no compile-time workaround available today on the user side. This would need to be addressed in oRPC's core type definitions by wrapping the handler's expected return type with an exact-match utility type. That said, Exact<T> patterns can have edge cases with optional properties, unions, and generics, so it's a non-trivial change.

For now, the best you can do is use .strict() on the Zod schema to at least get a runtime error instead of silent stripping — it won't give you a red squiggly in your editor, but it'll fail fast in tests or development.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[dinwwwh]

This is expected due to TS limitations. However, you don’t need to worry by default, z.object will remove any properties that are not defined.

[CaoKha]

@dinwwwh My point is that without strict validation, mistakes can easily happen when adding new code to a service. For example, in my case, I thought I had added some new fields to the service called by the handler and expected them to be returned, but they weren’t. TypeScript didn’t show any errors, so I had to manually check all the output schemas to ensure those new fields were included. In some codebases, ORPC contracts (where input and output schemas are defined) and handlers are placed in separate packages, which makes refactoring even more difficult. It would be helpful to have something that warns developers when there is an inconsistency between the output schema and the handler’s return value.

[dinwwwh]

I completely agree, but this is how TS works, and I don’t have a way to address it right now.

[CaoKha]

I will try to open a PR when I have the time. No promise though.