@mpen/routekit 0.1.0 → 0.1.2

package/src/router/routes/zod/zod.ts

@@ -1,1318 +0,0 @@
-import { HttpStatus } from '@mpen/http'
-import type { Router } from '../../router'
-import {
-    defineMiddleware,
-    type DeclaredMiddleware,
-    type DefineMiddlewareOptions,
-    type MiddlewareResponseDeclaration,
-} from '../../middleware/define'
-import type {
-    AddedContextFromMiddlewareInput,
-    AnyContext,
-    ContextFromMiddlewareInput,
-    ContextMiddleware,
-    Handler,
-    HandlerContext,
-    HandlerResult,
-    JsonObjectSchema,
-    JsonSchema,
-    MiddlewareInput,
-    Route,
-    RouteOptions,
-    RouteSchema,
-} from '../../types'
-import { isJsonContentType } from '../../lib/media-type'
-import { RequestBodyError } from '../../request'
-import { isRoutekitBody, isRoutekitResponse, response, type RoutekitResponse } from '../../response'
-import { z } from 'zod'
-
-/**
- * Validation error component identifiers for Zod-backed routes.
- */
-export const enum ValidationError {
-    REQUEST_BODY,
-    URL_PATH,
-    QUERY_PARAMETERS,
-}
-
-type ErrorTree = ReturnType<typeof z.treeifyError>
-type ZodSchema = z.ZodTypeAny | undefined
-type AnyZodResponseBodySchemas = Partial<Record<number | 'default', z.ZodTypeAny>>
-type ZodResponseBodySchemas = AnyZodResponseBodySchemas | undefined
-type ResponseValidationMode = false | 'strict' | 'parse'
-type ResponseValidationOption = boolean | ResponseValidationMode
-
-type ZodRouteContext<Ctx extends object, BuilderMiddleware, RouteMiddleware> = Ctx &
-    AddedContextFromMiddlewareInput<BuilderMiddleware> &
-    AddedContextFromMiddlewareInput<RouteMiddleware>
-
-type ZodBuilderMiddlewareInput<
-    Ctx extends object,
-    BuilderMiddleware extends MiddlewareInput<Ctx>,
-    RouteMiddleware extends MiddlewareInput<Ctx>,
-> = [BuilderMiddleware] extends [undefined]
-    ? RouteMiddleware
-    : [RouteMiddleware] extends [undefined]
-      ? BuilderMiddleware
-      : MiddlewareInput<Ctx>
-
-/**
- * Default validation error payload returned by Zod-backed routes.
- */
-export type ZodValidationErrorBody = {
-    component: 'request_body' | 'url_path' | 'query_parameters'
-    errorTree: ErrorTree
-    message: string
-}
-
-/**
- * Zod schema input that mirrors the core route `schema` shape.
- */
-export type ZodRouteSchemaInput<
-    BodySchema extends ZodSchema = undefined,
-    PathSchema extends ZodSchema = undefined,
-    QuerySchema extends ZodSchema = undefined,
-    ResponseBodySchemas extends ZodResponseBodySchemas = undefined,
-> = {
-    request?: {
-        query?: QuerySchema
-        path?: PathSchema
-        body?: BodySchema
-    }
-    response?: {
-        body?: ResponseBodySchemas
-    }
-}
-
-type InferSchema<Schema extends ZodSchema> = Schema extends z.ZodTypeAny ? z.infer<Schema> : unknown
-
-type InferResponseBodySchemaUnion<ResponseBodySchemas extends AnyZodResponseBodySchemas> = [
-    keyof ResponseBodySchemas,
-] extends [never]
-    ? unknown
-    : {
-          [Status in keyof ResponseBodySchemas]: NonNullable<
-              ResponseBodySchemas[Status]
-          > extends z.ZodTypeAny
-              ? z.infer<NonNullable<ResponseBodySchemas[Status]>>
-              : never
-      }[keyof ResponseBodySchemas]
-
-type InferResponseBody<ResponseBodySchemas extends ZodResponseBodySchemas> =
-    ResponseBodySchemas extends AnyZodResponseBodySchemas
-        ? 200 extends keyof ResponseBodySchemas
-            ? InferResponseBodySchemaUnion<ResponseBodySchemas>
-            : 'default' extends keyof ResponseBodySchemas
-              ? InferResponseBodySchemaUnion<ResponseBodySchemas>
-              : unknown
-        : unknown
-
-type NormalizeSchema<Schema> =
-    Schema extends ZodRouteSchemaInput<any, any, any, any>
-        ? Schema
-        : ZodRouteSchemaInput<undefined, undefined, undefined, undefined>
-
-type ExtractBodySchema<Schema extends ZodRouteSchemaInput<any, any, any, any> | undefined> =
-    NormalizeSchema<Schema> extends ZodRouteSchemaInput<infer BodySchema, any, any, any>
-        ? BodySchema
-        : undefined
-
-type ExtractPathSchema<Schema extends ZodRouteSchemaInput<any, any, any, any> | undefined> =
-    NormalizeSchema<Schema> extends ZodRouteSchemaInput<any, infer PathSchema, any, any>
-        ? PathSchema
-        : undefined
-
-type ExtractQuerySchema<Schema extends ZodRouteSchemaInput<any, any, any, any> | undefined> =
-    NormalizeSchema<Schema> extends ZodRouteSchemaInput<any, any, infer QuerySchema, any>
-        ? QuerySchema
-        : undefined
-
-type ExtractResponseBodySchemas<
-    Schema extends ZodRouteSchemaInput<any, any, any, any> | undefined,
-> =
-    NormalizeSchema<Schema> extends ZodRouteSchemaInput<any, any, any, infer ResponseBodySchemas>
-        ? ResponseBodySchemas
-        : undefined
-
-type ZodMiddlewareDeclarations<Schemas extends AnyZodResponseBodySchemas> = {
-    [Status in keyof Schemas]: NonNullable<Schemas[Status]> extends z.ZodTypeAny
-        ? MiddlewareResponseDeclaration<z.infer<NonNullable<Schemas[Status]>>>
-        : never
-}
-
-type ZodDeclaredResponse<Schemas extends AnyZodResponseBodySchemas> = {
-    [Status in keyof Schemas]-?: NonNullable<Schemas[Status]> extends z.ZodTypeAny
-        ? RoutekitResponse<
-              z.infer<NonNullable<Schemas[Status]>>,
-              Status extends number ? Status : number
-          >
-        : never
-}[keyof Schemas]
-
-type ZodSchemaMiddlewareContext<
-    Schema extends ZodRouteSchemaInput<any, any, any, any> | undefined,
-> = {
-    params: ZodHandlerParams<
-        ExtractBodySchema<Schema>,
-        ExtractPathSchema<Schema>,
-        ExtractQuerySchema<Schema>
-    >
-}
-
-/**
- * Validated request inputs exposed to a Zod-backed handler.
- */
-export type ZodHandlerParams<
-    BodySchema extends ZodSchema,
-    PathSchema extends ZodSchema,
-    QuerySchema extends ZodSchema,
-> = {
-    path: InferSchema<PathSchema>
-    query: InferSchema<QuerySchema>
-    body: InferSchema<BodySchema>
-}
-
-/**
- * Context object exposed to a Zod-backed handler.
- */
-export type ZodHandlerContext<
-    BodySchema extends ZodSchema,
-    PathSchema extends ZodSchema,
-    QuerySchema extends ZodSchema,
-    Ctx extends object,
-> = Omit<HandlerContext<Ctx>, 'path'> & {
-    params: ZodHandlerParams<BodySchema, PathSchema, QuerySchema>
-}
-
-/**
- * Validation error handler used when request parsing fails.
- *
- * @param component - Request component that failed validation.
- * @param error - The Zod validation error.
- * @returns A handler result that should be returned to the client.
- */
-export type ValidationErrorHandler<
-    Responses extends AnyZodResponseBodySchemas = AnyZodResponseBodySchemas,
-> = (component: ValidationError, error: z.ZodError) => ZodDeclaredResponse<Responses>
-
-/**
- * Shared defaults that can be applied to Zod handler helpers.
- */
-type ZodHandlerDefaults = {
-    /**
-     * Route schema fragments that should be merged into every factory-built route.
-     * Route-level schemas override matching request fields and response status codes.
-     */
-    schema?: ZodRouteSchemaInput<any, any, any, any>
-    /**
-     * Whether and how to apply `schema.response.body` to handler responses.
-     * `false` disables response validation, `true` and `'strict'` validate without changing the
-     * response body, and `'parse'` returns the parsed response body. Defaults to `'parse'`.
-     */
-    validateResponse?: ResponseValidationOption
-} & (
-    | {
-          onRequestValidationError?: undefined
-          validationResponses?: undefined
-      }
-    | {
-          /**
-           * Override the default request validation error response.
-           */
-          onRequestValidationError: ValidationErrorHandler
-          /**
-           * Response schemas returned by `onRequestValidationError`.
-           */
-          validationResponses: AnyZodResponseBodySchemas
-      }
-)
-
-/**
- * Shared defaults that can be applied to Zod route helpers.
- */
-export type ZodRouteHelperDefaults<
-    BuilderCtx extends object = AnyContext,
-    BuilderMiddleware extends MiddlewareInput<BuilderCtx> = undefined,
-> = ZodHandlerDefaults & {
-    /**
-     * Middleware applied to every route built by the helper.
-     */
-    middleware?: BuilderMiddleware
-}
-
-/**
- * Handler signature used by Zod schema boundaries and route builders.
- */
-export type ZodRouteHandler<
-    BodySchema extends ZodSchema,
-    PathSchema extends ZodSchema,
-    QuerySchema extends ZodSchema,
-    ResponseBodySchemas extends ZodResponseBodySchemas,
-    Ctx extends object = AnyContext,
-> = (
-    this: Router<any>,
-    ctx: ZodHandlerContext<BodySchema, PathSchema, QuerySchema, Ctx>,
-) => HandlerResult<InferResponseBody<ResponseBodySchemas>>
-
-/**
- * Shared options used by Zod route builders.
- */
-export type ZodHandlerOptions<
-    Schema extends ZodRouteSchemaInput<any, any, any, any> | undefined,
-    Ctx extends object = AnyContext,
-> = ZodHandlerDefaults & {
-    schema?: Schema
-    handler: ZodRouteHandler<
-        ExtractBodySchema<Schema>,
-        ExtractPathSchema<Schema>,
-        ExtractQuerySchema<Schema>,
-        ExtractResponseBodySchemas<Schema>,
-        Ctx
-    >
-}
-
-/**
- * Full route options used by Zod route builders.
- */
-export type ZodRouteOptions<
-    Schema extends ZodRouteSchemaInput<any, any, any, any> | undefined,
-    Ctx extends object = AnyContext,
-    BuilderMiddleware extends MiddlewareInput<Ctx> = undefined,
-    RouteMiddleware extends MiddlewareInput<Ctx> = undefined,
-> = Omit<
-    Route<Ctx, RouteMiddleware, ZodRouteContext<Ctx, BuilderMiddleware, RouteMiddleware>>,
-    'handler' | 'schema' | 'middleware'
-> &
-    ZodHandlerOptions<Schema, ZodRouteContext<Ctx, BuilderMiddleware, RouteMiddleware>> & {
-        middleware?: RouteMiddleware
-    }
-
-/**
- * Method-specific route options used by Zod route builders.
- */
-export type WithZodOptions<
-    Schema extends ZodRouteSchemaInput<any, any, any, any> | undefined,
-    Ctx extends object = AnyContext,
-    BuilderMiddleware extends MiddlewareInput<Ctx> = undefined,
-    RouteMiddleware extends MiddlewareInput<Ctx> = undefined,
-> = Omit<
-    RouteOptions<Ctx, RouteMiddleware, ZodRouteContext<Ctx, BuilderMiddleware, RouteMiddleware>>,
-    'handler' | 'schema' | 'middleware'
-> &
-    ZodHandlerOptions<Schema, ZodRouteContext<Ctx, BuilderMiddleware, RouteMiddleware>> & {
-        middleware?: RouteMiddleware
-    }
-
-/**
- * Zod route builder created by [`createZodRouteBuilder`]{@link createZodRouteBuilder}.
- *
- * @example
- * ```ts
- * const route = createZodRouteBuilder()
- *
- * router.get('/users/:id', route({
- *   schema: {
- *     request: {
- *       path: z.object({id: z.string()}),
- *     },
- *   },
- *   handler: ({params}) => ({id: params.path.id}),
- * }))
- *
- * router.add(route({
- *   method: HttpMethod.GET,
- *   path: '/health',
- *   handler: () => ({ok: true}),
- * }))
- * ```
- */
-export type ZodRouteBuilder<
-    BuilderCtx extends object = AnyContext,
-    BuilderMiddleware extends MiddlewareInput<BuilderCtx> = undefined,
-> = {
-    /**
-     * Build a full route definition that includes its own path.
-     *
-     * @param options - Full route options including `path`.
-     * @returns A full route definition compatible with [`Router.add`]{@link Router#add}.
-     */
-    <
-        Schema extends ZodRouteSchemaInput<any, any, any, any> | undefined,
-        RouteMiddleware extends MiddlewareInput<BuilderCtx> = undefined,
-    >(
-        options: ZodRouteOptions<Schema, BuilderCtx, BuilderMiddleware, RouteMiddleware>,
-    ): Route<
-        BuilderCtx,
-        ZodBuilderMiddlewareInput<BuilderCtx, BuilderMiddleware, RouteMiddleware>,
-        ZodRouteContext<BuilderCtx, BuilderMiddleware, RouteMiddleware>
-    >
-    /**
-     * Build method-specific route options that leave the path to the registering router.
-     *
-     * @param options - Method route options without a route path.
-     * @returns Route options compatible with helpers like [`Router.get`]{@link Router#get}.
-     */
-    <
-        Schema extends ZodRouteSchemaInput<any, any, any, any> | undefined,
-        RouteMiddleware extends MiddlewareInput<BuilderCtx> = undefined,
-    >(
-        options: WithZodOptions<Schema, BuilderCtx, BuilderMiddleware, RouteMiddleware>,
-    ): RouteOptions<
-        BuilderCtx,
-        ZodBuilderMiddlewareInput<BuilderCtx, BuilderMiddleware, RouteMiddleware>,
-        ZodRouteContext<BuilderCtx, BuilderMiddleware, RouteMiddleware>
-    >
-}
-
-type ResolvedZodHandlerOptions<
-    Schema extends ZodRouteSchemaInput<any, any, any, any> | undefined,
-    Ctx extends object,
-> = {
-    schema: Schema | undefined
-    handler: ZodRouteHandler<
-        ExtractBodySchema<Schema>,
-        ExtractPathSchema<Schema>,
-        ExtractQuerySchema<Schema>,
-        ExtractResponseBodySchemas<Schema>,
-        Ctx
-    >
-    validateResponse: ResponseValidationMode
-    onRequestValidationError: ValidationErrorHandler
-}
-
-type ResponseBodyForValidation = {
-    value: unknown
-    writableJson: boolean
-}
-
-const validationErrorComponentName = new Map<ValidationError, ZodValidationErrorBody['component']>([
-    [ValidationError.REQUEST_BODY, 'request_body'],
-    [ValidationError.URL_PATH, 'url_path'],
-    [ValidationError.QUERY_PARAMETERS, 'query_parameters'],
-])
-
-class ZodResponseValidationError extends Error {
-    readonly status: number
-    readonly error: z.ZodError
-
-    constructor(status: number, error: z.ZodError) {
-        super(`Response validation failed for status ${status}: ${z.prettifyError(error)}`)
-        this.name = 'ZodResponseValidationError'
-        this.status = status
-        this.error = error
-    }
-}
-
-function createValidationResponse(
-    component: ValidationError,
-    error: z.ZodError,
-): RoutekitResponse<ZodValidationErrorBody, HttpStatus.BAD_REQUEST> {
-    const payload: ZodValidationErrorBody = {
-        component: validationErrorComponentName.get(component) ?? 'request_body',
-        errorTree: z.treeifyError(error),
-        message: z.prettifyError(error),
-    }
-    return response(payload, { status: HttpStatus.BAD_REQUEST })
-}
-
-function normalizeResponseValidationMode(
-    option: ResponseValidationOption | undefined,
-): ResponseValidationMode | undefined {
-    if (option === true) return 'strict'
-    return option
-}
-
-function resolveDefaults<
-    Schema extends ZodRouteSchemaInput<any, any, any, any> | undefined,
-    Ctx extends object,
->(
-    options: ZodHandlerOptions<Schema, Ctx>,
-    defaults?: ZodHandlerDefaults,
-): ResolvedZodHandlerOptions<Schema, Ctx> {
-    return {
-        schema: options.schema,
-        handler: options.handler,
-        validateResponse:
-            normalizeResponseValidationMode(options.validateResponse) ??
-            normalizeResponseValidationMode(defaults?.validateResponse) ??
-            'parse',
-        onRequestValidationError:
-            options.onRequestValidationError ??
-            defaults?.onRequestValidationError ??
-            createValidationResponse,
-    }
-}
-
-function readQueryParams(searchParams: URLSearchParams): Record<string, string | string[]> {
-    const query: Record<string, string | string[]> = {}
-    for (const [key, value] of searchParams.entries()) {
-        const existing = query[key]
-        if (existing === undefined) {
-            query[key] = value
-            continue
-        }
-        if (Array.isArray(existing)) {
-            existing.push(value)
-        } else {
-            query[key] = [existing, value]
-        }
-    }
-    return query
-}
-
-function zodErrorFromThrowable(error: unknown): z.ZodError {
-    return new z.ZodError([
-        {
-            code: z.ZodIssueCode.custom,
-            path: [],
-            message: error instanceof Error ? error.message : String(error),
-        },
-    ])
-}
-
-function sanitizeJsonSchema(schema: JsonSchema): JsonSchema {
-    if (Array.isArray(schema)) {
-        return schema.map((entry) =>
-            sanitizeJsonSchema(entry as JsonSchema),
-        ) as unknown as JsonSchema
-    }
-    if (!schema || typeof schema !== 'object') {
-        return schema
-    }
-
-    const sanitizedEntries = Object.entries(schema)
-        .filter(([key]) => key !== '$schema' && key !== '~standard')
-        .map(([key, value]) => [key, sanitizeJsonSchema(value as JsonSchema)])
-    return Object.fromEntries(sanitizedEntries)
-}
-
-function toJsonSchema(schema: z.ZodTypeAny): JsonSchema {
-    return sanitizeJsonSchema(z.toJSONSchema(schema) as JsonSchema)
-}
-
-function buildRouteSchema(
-    schema?: ZodRouteSchemaInput<any, any, any, any>,
-): RouteSchema | undefined {
-    if (!schema) return undefined
-
-    const request = schema.request
-        ? {
-              ...(schema.request.query
-                  ? { query: toJsonSchema(schema.request.query) as JsonObjectSchema }
-                  : {}),
-              ...(schema.request.path
-                  ? { path: toJsonSchema(schema.request.path) as JsonObjectSchema }
-                  : {}),
-              ...(schema.request.body ? { body: toJsonSchema(schema.request.body) } : {}),
-          }
-        : undefined
-
-    const responseBody = schema.response?.body
-        ? Object.fromEntries(
-              Object.entries(schema.response.body).map(([status, responseSchema]) => {
-                  const normalizedStatus = status === 'default' ? status : Number(status)
-                  return [normalizedStatus, toJsonSchema(responseSchema as z.ZodTypeAny)]
-              }),
-          )
-        : undefined
-
-    const response =
-        responseBody && Object.keys(responseBody).length > 0 ? { body: responseBody } : undefined
-
-    if ((!request || Object.keys(request).length === 0) && !response) {
-        return undefined
-    }
-
-    return {
-        ...(request && Object.keys(request).length > 0 ? { request } : {}),
-        ...(response ? { response } : {}),
-    }
-}
-
-function buildZodMiddlewareDeclarations<Schemas extends AnyZodResponseBodySchemas>(
-    schemas: Schemas,
-): ZodMiddlewareDeclarations<Schemas> {
-    return Object.fromEntries(
-        Object.entries(schemas).flatMap(([status, schema]) =>
-            schema
-                ? [
-                      [
-                          status,
-                          {
-                              schema: toJsonSchema(schema as z.ZodTypeAny),
-                              parse: (value: unknown) => (schema as z.ZodTypeAny).parse(value),
-                          },
-                      ],
-                  ]
-                : [],
-        ),
-    ) as ZodMiddlewareDeclarations<Schemas>
-}
-
-/**
- * Options for [`defineZodMiddleware`]{@link defineZodMiddleware}.
- *
- * @typeParam AddedCtx - Context made available to downstream handlers.
- * @typeParam Ctx - Context required by the middleware.
- * @typeParam Responses - Status-keyed Zod schemas for locally originated responses.
- */
-export type DefineZodMiddlewareOptions<
-    AddedCtx extends object,
-    Ctx extends object,
-    Responses extends AnyZodResponseBodySchemas,
-> = {
-    responses: Responses
-    run: DefineMiddlewareOptions<AddedCtx, Ctx, ZodMiddlewareDeclarations<Responses>>['run']
-}
-
-/**
- * Create response-declaring middleware backed by Zod response schemas.
- *
- * @example
- * ```ts
- * const requireAuth = defineZodMiddleware({
- *     responses: { 401: z.object({ message: z.string() }) },
- *     run: (_ctx, { respond }) => respond(response({ message: 'Sign in' }, { status: 401 })),
- * })
- * ```
- *
- * @param options - Locally originated response schemas and middleware implementation.
- * @returns Declared middleware with inferred, runtime-validated terminal responses.
- * @typeParam AddedCtx - Context made available to downstream handlers.
- * @typeParam Ctx - Context required by the middleware.
- * @typeParam Responses - Status-keyed Zod schemas for locally originated responses.
- */
-export function defineZodMiddleware<
-    AddedCtx extends object = {},
-    Ctx extends object = AnyContext,
-    const Responses extends AnyZodResponseBodySchemas = {},
->(options: DefineZodMiddlewareOptions<AddedCtx, Ctx, Responses>): DeclaredMiddleware<AddedCtx, Ctx>
-export function defineZodMiddleware<
-    AddedCtx extends object = {},
-    Ctx extends object = AnyContext,
-    const Responses extends AnyZodResponseBodySchemas = {},
->(
-    options: DefineZodMiddlewareOptions<AddedCtx, Ctx, Responses>,
-): DeclaredMiddleware<AddedCtx, Ctx> {
-    return defineMiddleware<AddedCtx, Ctx, ZodMiddlewareDeclarations<Responses>>({
-        responses: buildZodMiddlewareDeclarations(options.responses),
-        run: options.run,
-    })
-}
-
-function mergeRouteSchema(
-    defaults: ZodHandlerDefaults,
-    schema: ZodRouteSchemaInput<any, any, any, any> | undefined,
-): ZodRouteSchemaInput<any, any, any, any> | undefined {
-    const defaultSchema = defaults.schema
-    if (!defaultSchema) return schema
-    if (!schema) return defaultSchema
-
-    const request =
-        !defaultSchema.request && !schema.request
-            ? undefined
-            : {
-                  ...defaultSchema.request,
-                  ...schema.request,
-              }
-
-    const defaultBody = defaultSchema.response?.body ?? {}
-    const routeBody = schema.response?.body ?? {}
-    const responseBody: AnyZodResponseBodySchemas = {}
-
-    const statuses = new Set([...Object.keys(defaultBody), ...Object.keys(routeBody)])
-    for (const status of statuses) {
-        const s = status === 'default' ? status : Number(status)
-        const defaultStatusSchema = defaultBody[s as keyof typeof defaultBody]
-        const routeStatusSchema = routeBody[s as keyof typeof routeBody]
-        if (defaultStatusSchema && routeStatusSchema) {
-            responseBody[s as keyof typeof responseBody] = z.union([
-                defaultStatusSchema,
-                routeStatusSchema,
-            ])
-        } else if (defaultStatusSchema) {
-            responseBody[s as keyof typeof responseBody] = defaultStatusSchema
-        } else if (routeStatusSchema) {
-            responseBody[s as keyof typeof responseBody] = routeStatusSchema
-        }
-    }
-
-    const response = Object.keys(responseBody).length > 0 ? { body: responseBody } : undefined
-
-    return {
-        ...(request ? { request } : {}),
-        ...(response ? { response } : {}),
-    }
-}
-
-function normalizeMiddlewareInput<Ctx extends object>(
-    middleware: MiddlewareInput<Ctx>,
-): ContextMiddleware<any, Ctx>[] {
-    if (!middleware) return []
-    if (Array.isArray(middleware)) {
-        return middleware.filter(Boolean) as ContextMiddleware<any, Ctx>[]
-    }
-    return [middleware as ContextMiddleware<any, Ctx>]
-}
-
-function mergeMiddleware<Ctx extends object>(
-    defaultMiddleware: MiddlewareInput<Ctx>,
-    routeMiddleware: MiddlewareInput<Ctx>,
-): MiddlewareInput<Ctx> {
-    const list = [
-        ...normalizeMiddlewareInput(defaultMiddleware),
-        ...normalizeMiddlewareInput(routeMiddleware),
-    ]
-    return list.length ? list : undefined
-}
-
-function mergeZodOptions<
-    Ctx extends object,
-    BuilderMiddleware extends MiddlewareInput<Ctx>,
-    RouteMiddleware extends MiddlewareInput<Ctx>,
-    Options extends {
-        schema?: ZodRouteSchemaInput<any, any, any, any> | undefined
-        middleware?: RouteMiddleware
-    },
->(
-    defaults: ZodRouteHelperDefaults<Ctx, BuilderMiddleware>,
-    options: Options,
-): Omit<Options, 'middleware'> & { middleware?: MiddlewareInput<Ctx> } {
-    const { middleware: defaultMiddleware, ...defaultOptions } = defaults
-    const schema = mergeRouteSchema(defaults, options.schema)
-    const middleware = mergeMiddleware(defaultMiddleware, options.middleware)
-    return {
-        ...defaultOptions,
-        ...options,
-        ...(schema === undefined ? {} : { schema }),
-        ...(middleware === undefined ? {} : { middleware }),
-    } as Omit<Options, 'middleware'> & { middleware?: MiddlewareInput<Ctx> }
-}
-
-function hasRoutePath(options: unknown): options is { path: unknown } {
-    return (options as { path?: unknown }).path !== undefined
-}
-
-function isSkippableResponseValidationValue(value: unknown): boolean {
-    return (
-        value instanceof ReadableStream ||
-        value instanceof Uint8Array ||
-        (typeof Buffer !== 'undefined' && value instanceof Buffer) ||
-        (!!value && typeof value === 'object' && Symbol.asyncIterator in value)
-    )
-}
-
-function jsonValuesEqual(left: unknown, right: unknown): boolean {
-    if (Object.is(left, right)) return true
-    if (typeof left !== typeof right) return false
-    if (!left || !right || typeof left !== 'object') return false
-    if (Array.isArray(left) || Array.isArray(right)) {
-        return (
-            Array.isArray(left) &&
-            Array.isArray(right) &&
-            left.length === right.length &&
-            left.every((value, index) => jsonValuesEqual(value, right[index]))
-        )
-    }
-
-    const leftEntries = Object.entries(left)
-    const rightRecord = right as Record<string, unknown>
-    const rightKeys = new Set(Object.keys(rightRecord))
-    return (
-        leftEntries.length === rightKeys.size &&
-        leftEntries.every(
-            ([key, value]) => rightKeys.has(key) && jsonValuesEqual(value, rightRecord[key]),
-        )
-    )
-}
-
-function getResponseSchemaForStatus(
-    schema: ZodRouteSchemaInput<any, any, any, any> | undefined,
-    status: number,
-): z.ZodTypeAny | undefined {
-    return schema?.response?.body?.[status] ?? schema?.response?.body?.default
-}
-
-async function readResponseBodyForValidation(
-    response: Response,
-): Promise<ResponseBodyForValidation | undefined> {
-    if (!response.body) return undefined
-    const contentType = response.headers.get('content-type') ?? ''
-    const clone = response.clone()
-    if (isJsonContentType(contentType)) {
-        return {
-            value: await clone.json(),
-            writableJson: true,
-        }
-    }
-    return {
-        value: await clone.text(),
-        writableJson: false,
-    }
-}
-
-function responseWithJsonBody(response: Response, value: unknown): Response {
-    const headers = new Headers(response.headers)
-    headers.delete('content-length')
-    if (!headers.has('content-type')) {
-        headers.set('content-type', 'application/json')
-    }
-    return new Response(value === undefined ? undefined : JSON.stringify(value), {
-        status: response.status,
-        statusText: response.statusText,
-        headers,
-    })
-}
-
-function parseResponseSchema(
-    schema: ZodRouteSchemaInput<any, any, any, any> | undefined,
-    status: number,
-    value: unknown,
-    mode: ResponseValidationMode,
-): unknown {
-    const responseSchema = getResponseSchemaForStatus(schema, status)
-    if (!responseSchema) return value
-    const result = responseSchema.safeParse(value)
-    if (!result.success) {
-        throw new ZodResponseValidationError(status, result.error)
-    }
-    if (mode === 'strict' && !jsonValuesEqual(value, result.data)) {
-        throw new ZodResponseValidationError(
-            status,
-            new z.ZodError([
-                {
-                    code: z.ZodIssueCode.custom,
-                    path: [],
-                    message: 'Response body does not match the parsed schema output.',
-                },
-            ]),
-        )
-    }
-    return mode === 'parse' ? result.data : value
-}
-
-async function validateHandlerResult(
-    schema: ZodRouteSchemaInput<any, any, any, any> | undefined,
-    result: unknown,
-    mode: ResponseValidationMode,
-): Promise<unknown> {
-    if (result instanceof Response) {
-        const body = await readResponseBodyForValidation(result)
-        if (!body) return result
-        const parsed = parseResponseSchema(schema, result.status, body.value, mode)
-        return mode === 'parse' && body.writableJson ? responseWithJsonBody(result, parsed) : result
-    }
-    if (isRoutekitResponse(result)) {
-        const parsed = parseResponseSchema(schema, result.status, result.body, mode)
-        return mode === 'parse'
-            ? response(parsed, { status: result.status, headers: result.headers })
-            : result
-    }
-    if (isRoutekitBody(result)) {
-        const parsed = parseResponseSchema(schema, HttpStatus.OK, result.value, mode)
-        return mode === 'parse' ? parsed : result
-    }
-    if (isSkippableResponseValidationValue(result)) {
-        return result
-    }
-    return parseResponseSchema(schema, HttpStatus.OK, result, mode)
-}
-
-const defaultValidationErrorSchema = z.object({
-    component: z.enum(['request_body', 'url_path', 'query_parameters']),
-    errorTree: z.unknown(),
-    message: z.string(),
-})
-
-/**
- * Options for [`zodSchemaMiddleware`]{@link zodSchemaMiddleware}.
- *
- * @typeParam Schema - Zod request and downstream response schema declaration.
- */
-type ZodSchemaMiddlewareBaseOptions<
-    Schema extends ZodRouteSchemaInput<any, any, any, any> | undefined,
-> = {
-    schema?: Schema
-    validateResponse?: ResponseValidationOption
-}
-
-/**
- * Options for a Zod request/response schema boundary.
- *
- * A custom request-validation callback must declare the response schemas it can originate.
- *
- * @typeParam Schema - Zod request and downstream response schema declaration.
- * @typeParam ValidationResponses - Schemas owned by a custom validation-error callback.
- */
-export type ZodSchemaMiddlewareOptions<
-    Schema extends ZodRouteSchemaInput<any, any, any, any> | undefined,
-    ValidationResponses extends AnyZodResponseBodySchemas | undefined = undefined,
-> = ZodSchemaMiddlewareBaseOptions<Schema> &
-    ([ValidationResponses] extends [undefined]
-        ? {
-              onRequestValidationError?: undefined
-              validationResponses?: undefined
-          }
-        : {
-              onRequestValidationError: ValidationErrorHandler<
-                  Extract<ValidationResponses, AnyZodResponseBodySchemas>
-              >
-              validationResponses: ValidationResponses
-          })
-
-/**
- * Create Zod middleware that parses request inputs and validates downstream responses.
- *
- * @example
- * ```ts
- * const parseUserId = zodSchemaMiddleware({
- *     schema: { request: { path: z.object({ id: z.string() }) } },
- * })
- * ```
- *
- * @param options - Request, response, and validation-error schema behavior.
- * @returns Declared middleware exposing parsed request values to downstream handlers.
- * @typeParam Schema - Zod request and downstream response schema declaration.
- * @typeParam Ctx - Context required before this middleware executes.
- */
-export function zodSchemaMiddleware<
-    Schema extends ZodRouteSchemaInput<any, any, any, any> | undefined,
-    const ValidationResponses extends AnyZodResponseBodySchemas | undefined = undefined,
-    Ctx extends object = AnyContext,
->(
-    options: ZodSchemaMiddlewareOptions<Schema, ValidationResponses>,
-): DeclaredMiddleware<ZodSchemaMiddlewareContext<Schema>, Ctx> {
-    const validateResponse = normalizeResponseValidationMode(options.validateResponse) ?? 'parse'
-    const parsesRequest = options.schema?.request !== undefined
-    const validationResponses =
-        options.validationResponses ??
-        (parsesRequest
-            ? ({
-                  [HttpStatus.BAD_REQUEST]: defaultValidationErrorSchema,
-              } satisfies AnyZodResponseBodySchemas)
-            : {})
-    const declarations = buildZodMiddlewareDeclarations(validationResponses)
-    const onRequestValidationError = options.onRequestValidationError ?? createValidationResponse
-
-    return defineMiddleware<ZodSchemaMiddlewareContext<Schema>, Ctx, typeof declarations>({
-        schema: buildRouteSchema(options.schema),
-        responses: declarations,
-        async run(ctx, { next, forward, respond }) {
-            const bodySchema = options.schema?.request?.body
-            const pathSchema = options.schema?.request?.path
-            const querySchema = options.schema?.request?.query
-            const queryParams = readQueryParams(ctx.url.searchParams)
-            const handlerContext = ctx as HandlerContext<Ctx> & ZodSchemaMiddlewareContext<Schema>
-            const params = {
-                path: ctx.path as InferSchema<ExtractPathSchema<Schema>>,
-                query: undefined as InferSchema<ExtractQuerySchema<Schema>>,
-                body: undefined as InferSchema<ExtractBodySchema<Schema>>,
-            }
-            handlerContext.params = params
-
-            if (querySchema) {
-                const parsed = querySchema.safeParse(queryParams)
-                if (!parsed.success) {
-                    return respond(
-                        onRequestValidationError(
-                            ValidationError.QUERY_PARAMETERS,
-                            parsed.error,
-                        ) as never,
-                    )
-                }
-                params.query = parsed.data as InferSchema<ExtractQuerySchema<Schema>>
-            }
-
-            if (pathSchema) {
-                const parsed = pathSchema.safeParse(ctx.path)
-                if (!parsed.success) {
-                    return respond(
-                        onRequestValidationError(ValidationError.URL_PATH, parsed.error) as never,
-                    )
-                }
-                params.path = parsed.data as InferSchema<ExtractPathSchema<Schema>>
-            }
-
-            if (bodySchema) {
-                let rawBody: unknown
-                try {
-                    rawBody = await ctx.request.body.parse()
-                } catch (err) {
-                    if (err instanceof RequestBodyError) throw err
-                    return respond(
-                        onRequestValidationError(
-                            ValidationError.REQUEST_BODY,
-                            zodErrorFromThrowable(err),
-                        ) as never,
-                    )
-                }
-                const parsed = bodySchema.safeParse(rawBody)
-                if (!parsed.success) {
-                    return respond(
-                        onRequestValidationError(
-                            ValidationError.REQUEST_BODY,
-                            parsed.error,
-                        ) as never,
-                    )
-                }
-                params.body = parsed.data as InferSchema<ExtractBodySchema<Schema>>
-            }
-
-            const result = await next()
-            return forward(
-                validateResponse === false
-                    ? result
-                    : ((await validateHandlerResult(
-                          options.schema,
-                          result,
-                          validateResponse,
-                      )) as HandlerResult),
-            )
-        },
-    })
-}
-
-/**
- * Build a route handler that parses request inputs with Zod and optionally validates responses.
- *
- * @example
- * ```ts
- * const handler = zodHandler({
- *   schema: {
- *     request: {
- *       path: z.object({id: z.string()}),
- *     },
- *     response: {
- *       body: {
- *         200: z.object({id: z.string()}),
- *       },
- *     },
- *   },
- *   handler: ({params}) => ({id: params.path.id}),
- * })
- * ```
- *
- * @param options - Handler definition extended with request and response Zod schemas.
- * @returns A handler that validates request inputs before invoking the provided handler.
- */
-export function zodHandler<
-    Schema extends ZodRouteSchemaInput<any, any, any, any> | undefined,
-    Ctx extends object = AnyContext,
->(
-    options: ZodHandlerOptions<Schema, Ctx>,
-): Handler<InferResponseBody<ExtractResponseBodySchemas<Schema>>, Ctx> {
-    const resolved = resolveDefaults(options)
-
-    return async function (this: Router<any>, ctx: HandlerContext<Ctx>) {
-        const run = async (): Promise<
-            HandlerResult<InferResponseBody<ExtractResponseBodySchemas<Schema>>>
-        > => {
-            const validateAndReturn = async (
-                result: HandlerResult<InferResponseBody<ExtractResponseBodySchemas<Schema>>>,
-            ): Promise<HandlerResult<InferResponseBody<ExtractResponseBodySchemas<Schema>>>> => {
-                if (resolved.validateResponse !== false) {
-                    return (await validateHandlerResult(
-                        resolved.schema,
-                        result,
-                        resolved.validateResponse,
-                    )) as HandlerResult<InferResponseBody<ExtractResponseBodySchemas<Schema>>>
-                }
-                return result
-            }
-            const bodySchema = resolved.schema?.request?.body
-            const pathSchema = resolved.schema?.request?.path
-            const querySchema = resolved.schema?.request?.query
-            const queryParams = readQueryParams(ctx.url.searchParams)
-
-            const handlerContext = {
-                ...ctx,
-                params: {
-                    path: ctx.path as InferSchema<ExtractPathSchema<Schema>>,
-                    query: undefined as InferSchema<ExtractQuerySchema<Schema>>,
-                    body: undefined as InferSchema<ExtractBodySchema<Schema>>,
-                },
-            } as ZodHandlerContext<
-                ExtractBodySchema<Schema>,
-                ExtractPathSchema<Schema>,
-                ExtractQuerySchema<Schema>,
-                Ctx
-            >
-
-            if (querySchema) {
-                const queryResult = querySchema.safeParse(queryParams)
-                if (!queryResult.success) {
-                    return await validateAndReturn(
-                        resolved.onRequestValidationError(
-                            ValidationError.QUERY_PARAMETERS,
-                            queryResult.error,
-                        ) as HandlerResult<InferResponseBody<ExtractResponseBodySchemas<Schema>>>,
-                    )
-                }
-                handlerContext.params.query = queryResult.data as InferSchema<
-                    ExtractQuerySchema<Schema>
-                >
-            }
-
-            if (pathSchema) {
-                const pathResult = pathSchema.safeParse(ctx.path)
-                if (!pathResult.success) {
-                    return await validateAndReturn(
-                        resolved.onRequestValidationError(
-                            ValidationError.URL_PATH,
-                            pathResult.error,
-                        ) as HandlerResult<InferResponseBody<ExtractResponseBodySchemas<Schema>>>,
-                    )
-                }
-                handlerContext.params.path = pathResult.data as InferSchema<
-                    ExtractPathSchema<Schema>
-                >
-            }
-
-            if (bodySchema) {
-                let rawBody: unknown
-                try {
-                    rawBody = await ctx.request.body.parse()
-                } catch (err) {
-                    if (err instanceof RequestBodyError) throw err
-                    return await validateAndReturn(
-                        resolved.onRequestValidationError(
-                            ValidationError.REQUEST_BODY,
-                            zodErrorFromThrowable(err),
-                        ) as HandlerResult<InferResponseBody<ExtractResponseBodySchemas<Schema>>>,
-                    )
-                }
-                const bodyResult = bodySchema.safeParse(rawBody)
-                if (!bodyResult.success) {
-                    return await validateAndReturn(
-                        resolved.onRequestValidationError(
-                            ValidationError.REQUEST_BODY,
-                            bodyResult.error,
-                        ) as HandlerResult<InferResponseBody<ExtractResponseBodySchemas<Schema>>>,
-                    )
-                }
-                handlerContext.params.body = bodyResult.data as InferSchema<
-                    ExtractBodySchema<Schema>
-                >
-            }
-
-            const result = await resolved.handler.call(this, handlerContext)
-            return await validateAndReturn(result)
-        }
-
-        return await run()
-    }
-}
-
-/**
- * Build a validated handler plus the matching JSON Schema route metadata.
- *
- * @param options - Zod-backed handler definition with optional request and response schemas.
- * @returns The validated handler and generated route `schema`.
- */
-export function zodPartial<
-    Schema extends ZodRouteSchemaInput<any, any, any, any> | undefined,
-    Ctx extends object = AnyContext,
->(
-    options: ZodHandlerOptions<Schema, Ctx>,
-): {
-    handler: Handler<InferResponseBody<ExtractResponseBodySchemas<Schema>>, Ctx>
-    schema?: RouteSchema
-} {
-    const schema = buildRouteSchema(options.schema)
-    return {
-        handler: zodHandler(options),
-        ...(schema ? { schema } : {}),
-    }
-}
-
-/**
- * Build method-specific route options that validate inputs with Zod and expose JSON Schema metadata.
- *
- * @example
- * ```ts
- * router.post('/users/:id', withZod({
- *   name: 'user.update',
- *   schema: {
- *     request: {
- *       path: z.object({id: z.string()}),
- *       body: z.object({name: z.string()}),
- *     },
- *   },
- *   handler: ({params}) => ({id: params.path.id, name: params.body.name}),
- * }))
- * ```
- *
- * @param options - Method route options extended with Zod request and response schemas.
- * @returns Route options compatible with method-specific router helpers.
- */
-export function withZod<
-    Schema extends ZodRouteSchemaInput<any, any, any, any> | undefined,
-    Ctx extends object = AnyContext,
-    RouteMiddleware extends MiddlewareInput<Ctx> = undefined,
->(
-    options: WithZodOptions<Schema, Ctx, undefined, RouteMiddleware>,
-): RouteOptions<Ctx, RouteMiddleware, ZodRouteContext<Ctx, undefined, RouteMiddleware>> {
-    const {
-        schema,
-        handler,
-        onRequestValidationError,
-        validateResponse,
-        validationResponses,
-        ...routeOptions
-    } = options
-    const partial = zodPartial<Schema, ZodRouteContext<Ctx, undefined, RouteMiddleware>>({
-        ...(schema ? { schema } : {}),
-        handler,
-        ...(onRequestValidationError ? { onRequestValidationError } : {}),
-        ...(validationResponses ? { validationResponses } : {}),
-        ...(validateResponse === undefined ? {} : { validateResponse }),
-    } as ZodHandlerOptions<Schema, ZodRouteContext<Ctx, undefined, RouteMiddleware>>)
-    return {
-        ...routeOptions,
-        handler: partial.handler,
-        ...(partial.schema ? { schema: partial.schema } : {}),
-    }
-}
-
-/**
- * Create a Zod route builder with shared defaults.
- *
- * @example
- * ```ts
- * const route = createZodRouteBuilder({
- *   validateResponse: false,
- *   schema: {
- *     response: {
- *       body: {
- *         400: z.object({message: z.string()}),
- *       },
- *     },
- *   },
- * })
- *
- * router.post('/users/:id', route({
- *   name: 'user.update',
- *   schema: {
- *     request: {
- *       path: z.object({id: z.string()}),
- *     },
- *   },
- *   handler: ({params}) => ({id: params.path.id}),
- * }))
- * ```
- *
- * @param defaults - Default schema fragments, response validation, and request validation error handling.
- * @returns A route builder compatible with method-specific router helpers and full route definitions.
- */
-export function createZodRouteBuilder<
-    BuilderMiddleware extends MiddlewareInput<any>,
-    BuilderCtx extends object = ContextFromMiddlewareInput<BuilderMiddleware>,
->(
-    defaults: ZodRouteHelperDefaults<BuilderCtx, BuilderMiddleware> & {
-        middleware: BuilderMiddleware
-    },
-): ZodRouteBuilder<BuilderCtx, BuilderMiddleware>
-export function createZodRouteBuilder<
-    BuilderCtx extends object = AnyContext,
-    BuilderMiddleware extends MiddlewareInput<BuilderCtx> = undefined,
->(
-    defaults?: ZodRouteHelperDefaults<BuilderCtx, BuilderMiddleware>,
-): ZodRouteBuilder<BuilderCtx, BuilderMiddleware>
-export function createZodRouteBuilder<
-    BuilderCtx extends object = AnyContext,
-    BuilderMiddleware extends MiddlewareInput<BuilderCtx> = undefined,
->(
-    defaults: ZodRouteHelperDefaults<BuilderCtx, BuilderMiddleware> = {},
-): ZodRouteBuilder<BuilderCtx, BuilderMiddleware> {
-    return (<
-        Schema extends ZodRouteSchemaInput<any, any, any, any> | undefined,
-        RouteMiddleware extends MiddlewareInput<BuilderCtx> = undefined,
-    >(
-        options:
-            | ZodRouteOptions<Schema, BuilderCtx, BuilderMiddleware, RouteMiddleware>
-            | WithZodOptions<Schema, BuilderCtx, BuilderMiddleware, RouteMiddleware>,
-    ):
-        | Route<
-              BuilderCtx,
-              ZodBuilderMiddlewareInput<BuilderCtx, BuilderMiddleware, RouteMiddleware>,
-              ZodRouteContext<BuilderCtx, BuilderMiddleware, RouteMiddleware>
-          >
-        | RouteOptions<
-              BuilderCtx,
-              ZodBuilderMiddlewareInput<BuilderCtx, BuilderMiddleware, RouteMiddleware>,
-              ZodRouteContext<BuilderCtx, BuilderMiddleware, RouteMiddleware>
-          > => {
-        const merged = mergeZodOptions(defaults, options)
-        const {
-            schema,
-            handler,
-            onRequestValidationError,
-            validateResponse,
-            validationResponses,
-            middleware,
-            ...routeOptions
-        } = merged
-        const boundary = zodSchemaMiddleware({
-            ...(schema ? { schema } : {}),
-            ...(onRequestValidationError ? { onRequestValidationError } : {}),
-            ...(validateResponse === undefined ? {} : { validateResponse }),
-            ...(validationResponses === undefined ? {} : { validationResponses }),
-        } as any)
-        const routeMiddleware = mergeMiddleware(
-            middleware as MiddlewareInput<BuilderCtx>,
-            boundary as unknown as MiddlewareInput<BuilderCtx>,
-        )
-        const built = {
-            ...routeOptions,
-            handler,
-            middleware: routeMiddleware,
-        }
-        if (hasRoutePath(built)) {
-            return built as unknown as Route<
-                BuilderCtx,
-                ZodBuilderMiddlewareInput<BuilderCtx, BuilderMiddleware, RouteMiddleware>,
-                ZodRouteContext<BuilderCtx, BuilderMiddleware, RouteMiddleware>
-            >
-        }
-        return built as unknown as RouteOptions<
-            BuilderCtx,
-            ZodBuilderMiddlewareInput<BuilderCtx, BuilderMiddleware, RouteMiddleware>,
-            ZodRouteContext<BuilderCtx, BuilderMiddleware, RouteMiddleware>
-        >
-    }) as ZodRouteBuilder<BuilderCtx, BuilderMiddleware>
-}
-
-/**
- * Build a full route definition that validates inputs with Zod and exposes JSON Schema metadata.
- *
- * @param options - Route definition extended with Zod request and response schemas.
- * @returns A route compatible with the core router.
- */
-export function zodRoute<
-    Schema extends ZodRouteSchemaInput<any, any, any, any> | undefined,
-    Ctx extends object = AnyContext,
-    RouteMiddleware extends MiddlewareInput<Ctx> = undefined,
->(
-    options: ZodRouteOptions<Schema, Ctx, undefined, RouteMiddleware>,
-): Route<Ctx, RouteMiddleware, ZodRouteContext<Ctx, undefined, RouteMiddleware>> {
-    const {
-        schema,
-        handler,
-        onRequestValidationError,
-        validateResponse,
-        validationResponses,
-        ...route
-    } = options
-    const partial = zodPartial<Schema, ZodRouteContext<Ctx, undefined, RouteMiddleware>>({
-        ...(schema ? { schema } : {}),
-        handler,
-        ...(onRequestValidationError ? { onRequestValidationError } : {}),
-        ...(validationResponses ? { validationResponses } : {}),
-        ...(validateResponse === undefined ? {} : { validateResponse }),
-    } as ZodHandlerOptions<Schema, ZodRouteContext<Ctx, undefined, RouteMiddleware>>)
-    return {
-        ...route,
-        handler: partial.handler,
-        ...(partial.schema ? { schema: partial.schema } : {}),
-    }
-}