Api

Builder Chain

Schema validation, transforms, metadata, and typed middleware builder reference.

Builder chain

Every configuration method returns a new builder. .action() is terminal.

MethodBehavior
.schema(schema)Standard Schema v1 or supported legacy Zod input validation
.errors({ CODE: 'Public message' })Declare expected business failure codes and messages
.outputSchema(schema)Validates and transforms the handler result
.use(middleware)Appends typed middleware
.metadata(meta)Merges server-defined metadata
.action(handler)Creates the default-exportable action

Schema types

A Standard Schema v1 object provides ~standard.version: 1 and ~standard.validate. Validation may return synchronously or asynchronously. Legacy Zod schemas expose safeParseAsync; supported Zod 3.20+ schemas remain accepted.

The client input type is the input schema's input. The handler's parsedInput type is its output. When output validation is configured, the client receives the output schema's parsed output, including transforms. Invalid output becomes a server error.

import { z } from 'zod'

export default actionClient
  .schema(z.object({ count: z.string().transform(Number) }))
  .outputSchema(z.object({ count: z.number() }).transform(value => ({ label: String(value.count) })))
  .action(({ parsedInput }) => ({ count: parsedInput.count }))
// Client sends { count: string }, handler receives { count: number },
// client result.data is { label: string }.

Choose refinements that reject non-finite or otherwise invalid numbers for real numeric input. Validator examples and async refinements.

Middleware

.use(async ({ ctx, next, fail, event, metadata, clientInput }) => {
  return next({ ctx: { ...ctx, requestLabel: 'example' } })
})

ctx is the preceding context; next({ ctx }) replaces it. event is the H3 request. clientInput is raw unvalidated input, while metadata is server configuration. Middleware runs before schema parsing and must call next() exactly once to continue. Throw to stop, or return fail(code) with a business error declared by .errors() earlier in the chain (0.8.1+). See middleware.

Handler

.action(({ parsedInput, ctx, event }) => ({ greeting: `Hello, ${parsedInput.name}!` }))

Handlers can return synchronously or asynchronously. Without .schema(), an action takes no typed input: call the client with undefined. Without .outputSchema(), output inference comes from the handler's return type. JSON transport still applies: send and return serializable data, and explicitly encode Dates as ISO strings rather than expecting a Date instance in the browser.

Business errors

Inside the terminal handler or a middleware, fail(code, { validationErrors? }) stops execution with a declared public business error. Write return fail(...) so TypeScript narrows the code that follows. Codes are limited to .errors() declarations, and field-error paths follow the action input. The generated result carries inferred businessError.code and businessError.message. See error handling.

Copyright © 2026