tRPC v10 Zod‑auto‑inference: Uncertain Handling of Optional Fields in Auto‑Inferred Outputs

Behavior of Auto-Inferred Output Types

In tRPC v10, Zod-auto-inference preserves all keys defined in the Zod schema within the resulting TypeScript type, regardless of whether those keys are present in the actual runtime response. If a field is marked as .optional(), the inferred type will include that key as optional (e.g., key?: T | undefined). This remains true even if the server-side procedure omits the key entirely from the return object.

Default Values vs. Inferred Types

There is a critical distinction between Zod's .default() behavior and TypeScript's type inference:

• Type Level: Default values do not change the inferred TypeScript type. A field with a default value is treated as required in the type definition because Zod assumes the value will be present after validation.
• Runtime Level: Default values are only applied during the Zod parsing/validation process. If the procedure returns a raw object that bypasses a final Zod parse on the output, the default value will not be injected into the response sent to the client.

Ensuring Full Shape in React Query v5

Because tRPC's auto-inference only provides type-level hints and does not transform the runtime JSON payload, the client may receive an object missing keys that the type says are present. To guarantee the client receives the full shape, use one of the following patterns:

1. Explicit Returns: Ensure the procedure return statement explicitly includes all optional keys, assigning undefined to those that are absent.
2. Output Validation: Pass the return value through the Zod schema's .parse() method before returning it from the procedure. This forces Zod to apply default values and structure the object according to the schema.
3. Client-Side Defaults: Use optional chaining or nullish coalescing in your React components to handle the absence of these keys at runtime.

Verification Steps

You can verify this behavior by defining a schema and inspecting the output:

const schema = z.object({
  required: z.string(),
  optionalField: z.string().optional(),
  defaultField: z.number().default(5),
});

• Check Type: Hover over the inferred output type. You will see optionalField?: string | undefined and defaultField: number.
• Check Network: Call the procedure and inspect the Network tab in DevTools. If the server returns { required: "val" }, the defaultField will be missing from the JSON, despite the type claiming it is a required number.

Diagnostic Note: Are you using a custom transformer (like superjson)? Transformers can affect how undefined and null are serialized, which may change how missing keys are handled during the transport layer.