feat(server): disable validation (#1678)

Author: dinwwwh

apps/content/.vitepress/config.ts

@@ -224,7 +224,7 @@ export default withMermaid(defineConfig({
             { text: 'Publish Client to NPM', link: '/docs/advanced/publish-client-to-npm' },
             { text: 'Scaling Large Projects', link: '/docs/advanced/scaling-large-projects' },
             { text: 'Testing and Mocking', link: '/docs/advanced/testing-and-mocking' },
-            { text: 'Validation Errors', link: '/docs/advanced/validation-errors' },
+            { text: 'Validation Customization', link: '/docs/advanced/validation-customization' },
           ],
         },
         {

…ntent/docs/advanced/validation-errors.md …ocs/advanced/validation-customization.mdapps/content/docs/advanced/validation-errors.md renamed to apps/content/docs/advanced/validation-customization.md apps/content/docs/advanced/validation-errors.md renamed to apps/content/docs/advanced/validation-customization.md

@@ -1,10 +1,53 @@
-# Validation Errors
+# Validation Customization
+
+This guide explains how to customize validation in oRPC, including how to disable runtime validation and how to customize validation errors.
+
+## Disable Validation
+
+You can disable runtime validation with the `.$config`.
+
+```ts
+const base = os.$config({
+  /**
+   * When enabled, input schemas are not validated at runtime.
+   * Schemas are still used for type inference and OpenAPI generation.
+   *
+   * @warning Do not disable validation for schemas that transform values.
+   *
+   * @default false
+   */
+  disableInputValidation: true,
+
+  /**
+   * When enabled, output schemas are not validated at runtime.
+   * Schemas are still used for type inference and OpenAPI generation.
+   *
+   * Useful when output schemas exist only for specification generation.
+   *
+   * @warning Do not disable validation for schemas that transform values.
+   *
+   * @default false
+   */
+  disableOutputValidation: true
+})
+```
+
+::: warning
+Do not disable validation for schemas that transform values.
+For example, the following schema accepts a `number` but returns a `string`:
+
+```ts
+z.object({
+  value: z.number().transform(value => String(value)),
+})
+```
 
-oRPC includes built-in validation errors that work well for most cases. Customize them when you need a different message or error shape.
+If runtime validation is disabled, the transformation is skipped. As a result, the server returns a `number` while the client expects a `string`, leading to unexpected behavior.
+:::
 
-## Customizing
+## Custom Validation Errors
 
-You can catch validation errors with [interceptors](/docs/rpc/handler#interceptors), [client interceptors](/docs/rpc/handler#client-interceptors), or [middleware](/docs/middleware) applied before `.input` or `.output`.
+You can catch validation errors with [interceptors](/docs/rpc/handler#interceptors), [client interceptors](/docs/rpc/handler#client-interceptors), or [middleware](/docs/middleware) applied before `.input` or `.output` and then throw a custom error. This is useful if you want to change the error message or shape.
 
 ```ts twoslash
 import { RPCHandler } from '@orpc/server/fetch'
@@ -53,7 +96,7 @@ const handler = new RPCHandler(router, {
 })
 ```
 
-## Typesafe Validation Errors
+### Typesafe Validation Errors
 
 As explained in the [error handling guide](/docs/error-handling#orpcerror-compatibility), if you throw an `ORPCError` whose `code` and `data` match an error defined with `.errors`, oRPC treats it the same as `errors.[code]`.
 

apps/content/docs/helpers/form-data.md

@@ -55,7 +55,7 @@ const anyError = getIssueMessage('anything', 'path')
 ```
 
 ::: warning
-The `getIssueMessage` utility works with any data type but requires validation errors to follow the [standard schema issue format](https://standardschema.dev/#the-specifications). It looks for issues in the `data.issues` property. If you use custom [validation errors](/docs/advanced/validation-errors), store them elsewhere, or modify the issue format, `getIssueMessage` may not work as expected.
+The `getIssueMessage` utility works with any data type but requires validation errors to follow the [standard schema issue format](https://standardschema.dev/#the-specifications). It looks for issues in the `data.issues` property. If you [customize validation errors](/docs/advanced/validation-customization#custom-validation-errors), store them elsewhere, or modify the issue format, `getIssueMessage` may not work as expected.
 :::
 
 ## Usage Example

apps/content/docs/integrations/nest.md

@@ -126,7 +126,7 @@ export class PlanetController {
 By default, errors thrown in implemented procedures are caught and handled by oRPC, which then rethrows a generic `HttpException` to NestJS. If you want NestJS to catch the original error instead of `HttpException`, use the [Rethrow Plugin](/docs/plugins/rethrow) to bypass oRPC error handling and let NestJS handle the error directly.
 
 ::: tip
-Learn how to customize input and output validation errors in [Validation Errors](/docs/advanced/validation-errors) and the [ORPCModule](#configuration) section.
+Learn how to customize input and output validation errors in [Validation Errors](/docs/advanced/validation-customization#custom-validation-errors) and the [ORPCModule](#configuration) section.
 :::
 
 ## Body Parser

apps/content/docs/plugins/request-validation.md

@@ -36,7 +36,7 @@ const link = new RPCLink({
 
 ## Custom Validation Errors
 
-If you have already [customized validation errors on the server](/docs/advanced/validation-errors), you can use interceptors to catch and map the validation errors thrown by this plugin so they match your server-side errors.
+If you have already [customized validation errors on the server](/docs/advanced/validation-customization#custom-validation-errors), you can use interceptors to catch and map the validation errors thrown by this plugin so they match your server-side errors.
 
 ```ts
 import { ORPCError } from '@orpc/client'

apps/content/docs/plugins/response-validation.md

@@ -38,7 +38,7 @@ This plugin reconciles ORPC errors from other interceptors and plugins, allowing
 
 ## Custom Validation Errors
 
-If you have already [customized validation errors on the server](/docs/advanced/validation-errors), you can use interceptors to catch and map the validation errors thrown by this plugin so they match your server-side errors.
+If you have already [customized validation errors on the server](/docs/advanced/validation-customization#custom-validation-errors), you can use interceptors to catch and map the validation errors thrown by this plugin so they match your server-side errors.
 
 ```ts
 import { ORPCError } from '@orpc/client'

packages/server/src/builder.test-d.ts

@@ -39,6 +39,15 @@ describe('Builder', () => {
     builder.$context<'invalid'>()
   })
 
+  it('$config', () => {
+    expectTypeOf(builder.$config({ disableInputValidation: true, disableOutputValidation: true })).toEqualTypeOf<
+      typeof builder
+    >()
+
+    // @ts-expect-error - invalid setting
+    builder.$config('invalid')
+  })
+
   it('.errors', () => {
     expectTypeOf(builder.errors({ INVALID: { message: 'invalid' }, OVERRIDE: { message: 'override' } })).toEqualTypeOf<
       Builder<

packages/server/src/builder.test.ts

@@ -43,6 +43,8 @@ describe('builder', () => {
     orderedMiddlewares: [
       { middleware: vi.fn() as AnyFunction, inputSchemasLengthAtUse: 0, outputSchemasLengthAtUse: 0 },
     ],
+    disableInputValidation: false,
+    disableOutputValidation: false,
   }
 
   const metaPlugin: AnyMetaPlugin = {
@@ -63,6 +65,20 @@ describe('builder', () => {
     expect(builder.$context()).toBe(builder)
   })
 
+  it('$config', () => {
+    const applied = builder.$config({
+      disableOutputValidation: undefined,
+    })
+
+    expect(applied).toBeInstanceOf(Builder)
+    expect(applied).not.toBe(builder)
+
+    expect(applied['~orpc']).toEqual({
+      ...builder['~orpc'],
+      disableOutputValidation: undefined,
+    })
+  })
+
   it('.meta', () => {
     const applied = builder.meta(metaPlugin)
     expect(applied).toBeInstanceOf(Builder)
@@ -374,10 +390,8 @@ describe('builder', () => {
     expect(applied).toBe(augmentRouterSpy.mock.results[0]?.value)
     expect(augmentRouterSpy).toHaveBeenCalledOnce()
     expect(augmentRouterSpy).toHaveBeenCalledWith(router, {
+      ...builder['~orpc'],
       middlewares: builder['~orpc'].orderedMiddlewares.map((m: any) => m.middleware),
-      meta: builder['~orpc'].meta,
-      metaPlugins: builder['~orpc'].metaPlugins,
-      errorMap: builder['~orpc'].errorMap,
     })
   })
 
@@ -394,10 +408,8 @@ describe('builder', () => {
     expect(unlazied.default).toBe(augmentRouterSpy.mock.results[0]?.value)
     expect(augmentRouterSpy).toHaveBeenCalledOnce()
     expect(augmentRouterSpy).toHaveBeenCalledWith(router, {
+      ...builder['~orpc'],
       middlewares: builder['~orpc'].orderedMiddlewares.map((m: any) => m.middleware),
-      meta: builder['~orpc'].meta,
-      metaPlugins: builder['~orpc'].metaPlugins,
-      errorMap: builder['~orpc'].errorMap,
     })
   })
 })

packages/server/src/builder.ts

@@ -6,7 +6,7 @@ import type { Context, MergedInitialContext } from './context'
 import type { ORPCErrorConstructorMap } from './error'
 import type { Middleware } from './middleware'
 import type { DecoratedMiddleware } from './middleware-decorated'
-import type { OrderedMiddleware, ProcedureHandler } from './procedure'
+import type { OrderedMiddleware, ProcedureConfig, ProcedureHandler } from './procedure'
 import type { AnyRouter } from './router'
 import type { AugmentedRouter } from './router-utils'
 import { getHiddenMetaPlugins, mergeErrorMap, resolveMetaPlugins } from '@orpc/contract'
@@ -17,14 +17,13 @@ import { DecoratedProcedure } from './procedure-decorated'
 import { augmentRouter } from './router-utils'
 
 export interface DefaultInitialContext {
-
 }
 
 export interface BuilderDefinition<
   TInputSchema extends AnySchema,
   TInjectedContext extends AnySchema,
   TErrorMap extends ErrorMap,
->extends ProcedureContractDefinition<TInputSchema, TInjectedContext, TErrorMap> {
+>extends ProcedureContractDefinition<TInputSchema, TInjectedContext, TErrorMap>, ProcedureConfig {
   orderedMiddlewares: OrderedMiddleware[]
 }
 
@@ -57,6 +56,13 @@ export class Builder<
     return this as any
   }
 
+  $config(config: ProcedureConfig): Builder<TInitialContext, TErrorMap> {
+    return new Builder({
+      ...this['~orpc'],
+      ...config,
+    })
+  }
+
   meta(
     ...plugins: MetaPlugin<InitialInputSchema, InitialOutputSchema, TErrorMap>[]
   ): Builder<TInitialContext, TErrorMap> {
@@ -208,10 +214,8 @@ export class Builder<
     router: T,
   ): AugmentedRouter<T, TErrorMap> {
     return augmentRouter(router, {
+      ...this['~orpc'],
       middlewares: this['~orpc'].orderedMiddlewares.map(({ middleware }) => middleware),
-      meta: this['~orpc'].meta,
-      metaPlugins: this['~orpc'].metaPlugins,
-      errorMap: this['~orpc'].errorMap,
     }) as any
   }
 

packages/server/src/implementer-procedure.test.ts

@@ -13,6 +13,7 @@ describe('procedureImplementer', () => {
     outputSchemas: [z.number()],
     meta: { meta: true },
     metaPlugins: [{ name: 'plugin', init: vi.fn() }],
+    disableInputValidation: true,
   }
 
   const implementer = new ProcedureImplementer(definition)