feat: add explicit response map success helper

Add ctx.success(status, body) for handlers that need to select among multiple declared success statuses. Route both ctx.success and ctx.error through the shared response-map encoder so undeclared statuses fail at runtime and plugin-backed success responses keep their per-status encoding.

Author: aleclarson

src/client/index.ts

@@ -5,7 +5,6 @@ import type { HttpAction, HttpResource, HttpRouteTree } from '../http.js'
 import {
   createResponsePluginMap,
   getResponsePluginMarkerId,
-  responsePluginMarker,
   type ClientResponsePlugin,
   type ResponsePluginMarker,
 } from '../response.js'
@@ -17,7 +16,7 @@ import {
 import type { RouteArgs } from '../types/args.js'
 import type { RouteRequest } from '../types/request.js'
 import type { InferRouteResponse } from '../types/response.js'
-import type { RouteResponseMap, RouteSchema } from '../types/schema.js'
+import type { RouteSchema } from '../types/schema.js'
 
 /** Client type inferred from an HTTP route tree passed to `createClient`. */
 export type RouzerClient<
@@ -151,10 +150,8 @@ export function createClient<
     // Handle status-keyed response maps
     if (isResponseMap(responseSchema)) {
       const status = httpResponse.status
-      const statusKey = status as keyof typeof responseSchema
-      if (statusKey in responseSchema) {
-        const marker = responseSchema[statusKey]
-        const body = await httpResponse.json()
+      if (status in responseSchema) {
+        const marker = responseSchema[status]
         if (isErrorMarker(marker)) {
           return [await httpResponse.json(), null, status] as T['$result']
         }
@@ -173,7 +170,7 @@ export function createClient<
             status,
           ] as T['$result']
         }
-        return [null, body, status] as T['$result']
+        return [null, await httpResponse.json(), status] as T['$result']
       }
       // Undeclared status — reject
       return handleResponseError(httpResponse, props)
@@ -324,17 +321,3 @@ function joinPaths(left: string, right: string) {
   return [left, right].filter(Boolean).join('/').replace(/\/+/g, '/')
 }
 
-/** Return true when the response schema is a status-keyed response map. */
-function isResponseMap(
-  response: RouteSchema['response']
-): response is RouteResponseMap {
-  return (
-    typeof response === 'object' &&
-    response !== null &&
-    !(responsePluginMarker in response)
-  )
-}
-
-function isErrorMarker(marker: unknown): boolean {
-  return marker === $error.symbol
-}

src/server/router.ts

@@ -222,7 +222,18 @@ class RouterObject extends MiddlewareChain {
         }
 
         if (isResponseMap(schema.response)) {
-          ;(context as any).error = createErrorHelper()
+          ;(context as any).error = createResponseHelper(
+            schema.response,
+            request,
+            responsePlugins,
+            true
+          )
+          ;(context as any).success = createResponseHelper(
+            schema.response,
+            request,
+            responsePlugins,
+            false
+          )
         }
 
         const result = await handler(context)
@@ -242,9 +253,14 @@ class RouterObject extends MiddlewareChain {
           })
         }
         if (isResponseMap(schema.response)) {
-          // Success response from a response map — find the success status
-          const status = getSuccessStatus(schema.response)
-          return Response.json(result, { status })
+          const status = getDefaultSuccessStatus(schema.response)
+          return encodeResponseMapResult(
+            schema.response,
+            status,
+            result,
+            request,
+            responsePlugins
+          )
         }
         return Response.json(result)
       }
@@ -350,9 +366,15 @@ function validateRouterResponsePlugins(
   plugins: Map<string, RouterResponsePlugin>
 ) {
   for (const route of routes) {
-    const pluginId = getResponsePluginMarkerId(route.schema.response)
-    if (pluginId && !plugins.has(pluginId)) {
-      throw missingRouterResponsePlugin(pluginId)
+    const pluginIds = isResponseMap(route.schema.response)
+      ? getResponseMapPluginIds(route.schema.response)
+      : [getResponsePluginMarkerId(route.schema.response)].filter(
+          pluginId => pluginId !== undefined
+        )
+    for (const pluginId of pluginIds) {
+      if (!plugins.has(pluginId)) {
+        throw missingRouterResponsePlugin(pluginId)
+      }
     }
   }
 }
@@ -497,39 +519,28 @@ function createOriginPattern(origin: string) {
   return new ExactPattern(origin)
 }
 
-/** Return true when the response schema is a status-keyed response map. */
-function isResponseMap(
-  response: RouteSchema['response']
-): response is RouteResponseMap {
-  return (
-    typeof response === 'object' &&
-    response !== null &&
-    !(responsePluginMarker in response)
-  )
-}
-
-import { responsePluginMarker } from '../response.js'
-
-/** Create the `ctx.error(status, body)` helper for route handlers. */
-function createErrorHelper() {
-  return (status: number, body: unknown): Response => {
-    return Response.json(body, { status })
-  }
-}
-
-/**
- * Find the first success status in a response map (a status whose marker is
- * `$type<T>()` or a plugin marker, not `$error<T>()`).
- */
-function getSuccessStatus(responseMap: RouteResponseMap): number {
-  for (const key of Object.keys(responseMap)) {
-    const status = Number(key)
-    const marker = (responseMap as any)[status]
-    if (!isErrorMarker(marker)) {
-      return status
+/** Create `ctx.error(status, body)` or `ctx.success(status, body)`. */
+function createResponseHelper(
+  responseMap: RouteResponseMap,
+  request: Request,
+  responsePlugins: Map<string, RouterResponsePlugin>,
+  error: boolean
+) {
+  return (status: number, body: unknown): Promise<Response> | Response => {
+    const marker = responseMap[status]
+    if (!marker || isErrorMarker(marker) !== error) {
+      throw new Error(
+        `Undeclared ${error ? 'error' : 'success'} response status: ${status}`
+      )
     }
+    return encodeResponseMapResult(
+      responseMap,
+      status,
+      body,
+      request,
+      responsePlugins
+    )
   }
-  return 200
 }
 
 async function encodeResponseMapResult(

src/types/handler.ts

@@ -6,6 +6,7 @@ import type { HttpAction } from '../http.js'
 import type {
   InferRouteHandlerResult,
   InferResponseMapErrors,
+  InferResponseMapSuccesses,
 } from './response.js'
 import type { RouteResponseMap, RouteSchema } from './schema.js'
 
@@ -20,11 +21,15 @@ type RequestContext<TMiddleware extends AnyMiddlewareChain> =
  */
 export type RouteErrorResponse = Response & { __routeError__: true }
 
+/** Response returned by `ctx.success(status, body)` in route handlers. */
+export type RouteSuccessResponse = Response & { __routeSuccess__: true }
+
 export type RouteRequestHandler<
   TMiddleware extends AnyMiddlewareChain,
   TArgs extends object,
   TResult,
   TErrors = never,
+  TSuccesses = never,
 > = (
   context: RequestContext<TMiddleware> &
     TArgs &
@@ -42,6 +47,20 @@ export type RouteRequestHandler<
               ? [status: S, body: B]
               : never
           ) => RouteErrorResponse
+        }) &
+    ([TSuccesses] extends [never]
+      ? {}
+      : {
+          /**
+           * Return a declared success response with an explicit status.
+           *
+           * @remarks Useful when a response map declares multiple 2xx statuses.
+           */
+          success: <TEntry extends TSuccesses>(
+            ...args: TEntry extends [infer S extends number, infer B]
+              ? [status: S, body: B]
+              : never
+          ) => RouteSuccessResponse
         })
 ) => Promisable<TResult | Response>
 
@@ -65,7 +84,8 @@ export type InferActionHandler<
             : undefined
         },
         InferRouteHandlerResult<Extract<TAction['schema'], RouteSchema>>,
-        InferResponseMapErrors<R>
+        InferResponseMapErrors<R>,
+        InferResponseMapSuccesses<R>
       >
     : RouteRequestHandler<
         TMiddleware,
@@ -81,7 +101,8 @@ export type InferActionHandler<
             : undefined
         },
         InferRouteHandlerResult<Extract<TAction['schema'], RouteSchema>>,
-        InferResponseMapErrors<R>
+        InferResponseMapErrors<R>,
+        InferResponseMapSuccesses<R>
       >
   : TAction['method'] extends 'GET'
     ? RouteRequestHandler<

src/types/response.ts

@@ -72,3 +72,12 @@ export type InferResponseMapErrors<T extends RouteResponseMap> = {
     ? [K, TError]
     : never
 }[keyof T & number]
+
+/** Extract success entries as a union of `[status, body]` pairs. */
+export type InferResponseMapSuccesses<T extends RouteResponseMap> = {
+  [K in keyof T & number]: T[K] extends Unchecked<infer TSuccess>
+    ? [K, TSuccess]
+    : T[K] extends ResponsePluginMarker<any, infer TRouter>
+      ? [K, TRouter]
+      : never
+}[keyof T & number]

src/types/schema.ts

@@ -9,9 +9,7 @@ import type { ResponsePluginMarker } from '../response.js'
  * @remarks Application code should usually call `$type<T>()` instead of naming
  * this marker directly.
  */
-export type { Unchecked }
-export type { UncheckedError }
-export type { ResponsePluginMarker }
+export type { ResponsePluginMarker, Unchecked, UncheckedError }
 
 /** Single response marker accepted by status-keyed response maps. */
 export type RouteResponseMarker =

test/error-responses.test-d.ts

@@ -17,6 +17,7 @@ type AuthError = { code: 'UNAUTHORIZED'; message: string }
 const getUser = http.get('users/:id', {
   response: {
     200: $type<User>(),
+    201: $type<User>(),
     401: $error<AuthError>(),
     404: $error<NotFoundError>(),
   },
@@ -35,7 +36,10 @@ type GetUserResult = Awaited<ReturnType<typeof client.getUser>>
 type _ClientReturnsDiscriminatedTuple = Assert<
   Equal<
     GetUserResult,
-    [null, User, 200] | [AuthError, null, 401] | [NotFoundError, null, 404]
+    | [null, User, 200]
+    | [null, User, 201]
+    | [AuthError, null, 401]
+    | [NotFoundError, null, 404]
   >
 >
 
@@ -48,6 +52,23 @@ createRouter().use(routes, {
     if (ctx.path.id === 'unauthorized') {
       return ctx.error(401, { code: 'UNAUTHORIZED', message: 'no auth' })
     }
+    if (ctx.path.id === 'created') {
+      return ctx.success(201, { id: ctx.path.id, name: 'Ada' })
+    }
+    return { id: ctx.path.id, name: 'Ada' }
+  },
+})
+
+createRouter().use(routes, {
+  getUser(ctx) {
+    // @ts-expect-error 500 is not a declared error status.
+    ctx.error(500, { code: 'NOT_FOUND', message: 'nope' })
+    // @ts-expect-error Error body must match the selected status.
+    ctx.error(404, { code: 'UNAUTHORIZED', message: 'nope' })
+    // @ts-expect-error 404 is not a declared success status.
+    ctx.success(404, { code: 'NOT_FOUND', message: 'nope' })
+    // @ts-expect-error Success body must match the selected status.
+    ctx.success(201, { id: 123, name: 'Ada' })
     return { id: ctx.path.id, name: 'Ada' }
   },
 })

test/fixtures/error-responses/handler.ts

@@ -13,6 +13,13 @@ export default createRouter({ plugins: [ndjson.routerPlugin] }).use(routes, {
       })
     }
 
+    if (id === 'created') {
+      return ctx.success(201, {
+        id,
+        name: 'Grace',
+      })
+    }
+
     if (id === 'missing') {
       return ctx.error(404, {
         code: 'NOT_FOUND',

test/fixtures/error-responses/routes.ts

@@ -20,6 +20,7 @@ export type AuthError = {
 export const getUser = http.get('users/:id', {
   response: {
     200: $type<User>(),
+    201: $type<User>(),
     401: $error<AuthError>(),
     404: $error<NotFoundError>(),
   },

test/fixtures/error-responses/test.ts

@@ -7,6 +7,7 @@ export default createTest({
   name: 'typed error responses ($error<T> with status-keyed response map)',
   routes,
   handler,
+  clientPlugins: [ndjson.clientPlugin],
   test: async client => {
     // Success case: returns tuple [null, User, 200]
     const [error1, result1, status1] = await client.getUser({