ts-procedures 8.2.1 → 8.4.0

package/src/implementations/http/error-taxonomy.test.ts

@@ -5,10 +5,14 @@ import {
   ProcedureYieldValidationError,
 } from '../../errors.js'
 import type { TProcedureRegistration } from '../../index.js'
+import * as AJV from 'ajv'
 import {
   defineErrorTaxonomy,
   resolveErrorResponse,
   defaultErrorTaxonomy,
+  taxonomyToErrorDocs,
+  defaultErrorSchema,
+  defaultErrorBody,
 } from './error-taxonomy.js'
 
 class UseCaseError extends Error {
@@ -436,3 +440,110 @@ describe('resolveErrorResponse', () => {
     expect(Object.keys(taxonomy)).toEqual(['B', 'A'])
   })
 })
+
+describe('taxonomyToErrorDocs', () => {
+  test('synthesizes a { name const, message } schema for class+statusCode-only entries', () => {
+    const taxonomy = defineErrorTaxonomy({
+      AuthError: { class: AuthError, statusCode: 401 },
+    })
+    const docs = taxonomyToErrorDocs(taxonomy)
+    const auth = docs.find((d) => d.name === 'AuthError')
+    expect(auth?.statusCode).toBe(401)
+    expect(auth?.schema).toEqual({
+      type: 'object',
+      properties: {
+        name: { type: 'string', const: 'AuthError' },
+        message: { type: 'string' },
+      },
+      required: ['name', 'message'],
+    })
+  })
+
+  test('does NOT synthesize a schema when a custom toResponse is present', () => {
+    const taxonomy = defineErrorTaxonomy({
+      UseCaseError: {
+        class: UseCaseError,
+        statusCode: 422,
+        toResponse: (err) => ({ name: 'UseCaseError', message: err.externalMsg }),
+      },
+    })
+    const docs = taxonomyToErrorDocs(taxonomy)
+    const useCase = docs.find((d) => d.name === 'UseCaseError')
+    expect(useCase?.schema).toBeUndefined()
+  })
+
+  test('preserves an explicit schema untouched', () => {
+    const explicitSchema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string', const: 'UseCaseError' },
+        reason: { type: 'string' },
+      },
+      required: ['name', 'reason'],
+    }
+    const taxonomy = defineErrorTaxonomy({
+      UseCaseError: {
+        class: UseCaseError,
+        statusCode: 422,
+        schema: explicitSchema,
+      },
+    })
+    const docs = taxonomyToErrorDocs(taxonomy)
+    const useCase = docs.find((d) => d.name === 'UseCaseError')
+    expect(useCase?.schema).toBe(explicitSchema)
+  })
+})
+
+describe('defaultErrorSchema', () => {
+  test('synthesizes the { name, message } envelope for a bare entry', () => {
+    expect(defaultErrorSchema('AuthError', { class: AuthError, statusCode: 401 })).toEqual({
+      type: 'object',
+      properties: {
+        name: { type: 'string', const: 'AuthError' },
+        message: { type: 'string' },
+      },
+      required: ['name', 'message'],
+    })
+  })
+
+  test('returns undefined when a custom toResponse is present (shape unknown)', () => {
+    expect(
+      defaultErrorSchema('UseCaseError', {
+        class: UseCaseError,
+        statusCode: 422,
+        toResponse: () => ({ name: 'UseCaseError' }),
+      })
+    ).toBeUndefined()
+  })
+
+  test('returns the explicit schema when one is set', () => {
+    const schema = { type: 'object', properties: {} }
+    expect(
+      defaultErrorSchema('UseCaseError', { class: UseCaseError, statusCode: 422, schema })
+    ).toBe(schema)
+  })
+})
+
+// The synthesized schema and the runtime body share one source (defaultErrorBody).
+// This locks the invariant: whatever the default branch serializes must validate
+// against the schema codegen turns into the client error class. If either side
+// changes shape, this fails before consumers see a mismatch.
+describe('defaultErrorBody / defaultErrorSchema invariant', () => {
+  const ajv = new AJV.Ajv()
+
+  test('default body validates against the synthesized schema', () => {
+    const schema = defaultErrorSchema('AuthError', { class: AuthError, statusCode: 401 })
+    const validate = ajv.compile(schema!)
+
+    expect(validate(defaultErrorBody('AuthError', new Error('nope')))).toBe(true)
+    // A non-Error throw stringifies to a message — still valid.
+    expect(validate(defaultErrorBody('AuthError', 'plain string'))).toBe(true)
+    // Wrong discriminator name is rejected by the `const` — proves the schema
+    // actually constrains the wire shape the client dispatcher keys on.
+    expect(validate({ name: 'SomethingElse', message: 'x' })).toBe(false)
+  })
+
+  test('default body carries exactly the schema-described keys', () => {
+    expect(Object.keys(defaultErrorBody('X', new Error('m'))).sort()).toEqual(['message', 'name'])
+  })
+})

package/src/implementations/http/error-taxonomy.ts

@@ -204,9 +204,67 @@ export const PROCEDURE_REGISTRATION_ERROR_DOC: ErrorDoc = {
   },
 }
 
+/**
+ * The default response body for an entry without a custom `toResponse`:
+ * `{ name: <key>, message }`. This is the single source of truth for the default
+ * wire shape — `resolveErrorResponse` serializes with it and
+ * {@link defaultErrorSchema} describes it. Keeping both derived from one place
+ * means the synthesized schema can never drift from what the runtime emits.
+ */
+export function defaultErrorBody(key: string, err: unknown): { name: string; message: string } {
+  return {
+    name: key,
+    message: err instanceof Error ? err.message : String(err),
+  }
+}
+
+/**
+ * Synthesizes the response-body JSON Schema for a taxonomy entry that ships
+ * neither an explicit `schema` nor a custom `toResponse`.
+ *
+ * The common case for `defineErrorTaxonomy` is `{ class, statusCode }` only.
+ * For those entries the default `toResponse` (see `resolveErrorResponse`) emits
+ * exactly `{ name: <key>, message }`. Without a schema, `taxonomyToErrorDocs`
+ * produced a schema-less `ErrorDoc`, and codegen (`emit-errors.ts`) only emits a
+ * typed client error class for docs that carry a schema — so these entries
+ * silently fell back to the untyped `ClientHttpError`, while framework errors
+ * (which ship schemas) worked. That mismatch was confusing.
+ *
+ * By describing the default envelope here, the entry becomes self-describing and
+ * codegen emits a typed client error class with zero ceremony from the consumer.
+ *
+ * Rules:
+ * - Entry has an explicit `schema` → caller keeps it (this is not consulted).
+ * - Entry has a custom `toResponse` but no `schema` → returns `undefined`; the
+ *   body shape is unknown and we never guess it.
+ * - Entry has neither → returns the `{ name: const <key>, message }` schema that
+ *   describes {@link defaultErrorBody} — the exact body the runtime serializes.
+ *   (An invariant test keeps the two from drifting.)
+ */
+export function defaultErrorSchema(
+  key: string,
+  entry: ErrorTaxonomyEntry
+): Record<string, unknown> | undefined {
+  if (entry.schema) return entry.schema
+  if (entry.toResponse) return undefined
+  return {
+    type: 'object',
+    properties: {
+      name: { type: 'string', const: key },
+      message: { type: 'string' },
+    },
+    required: ['name', 'message'],
+  }
+}
+
 /**
  * Converts a taxonomy into {@link ErrorDoc} objects suitable for a DocEnvelope.
  *
+ * For entries that supply neither a `schema` nor a custom `toResponse`, the
+ * schema of the default `{ name, message }` envelope is synthesized (see
+ * {@link defaultErrorSchema}) so client codegen emits a typed error class for
+ * them too — matching the behavior of the schema-carrying framework defaults.
+ *
  * @internal Used by `DocRegistry` to merge taxonomy entries into the envelope.
  *   Consumers should pass their taxonomy directly to `new DocRegistry({ errors: taxonomy })`
  *   rather than calling this helper — the constructor handles the conversion.
@@ -216,7 +274,7 @@ export function taxonomyToErrorDocs(taxonomy: ErrorTaxonomy): ErrorDoc[] {
     name: key,
     statusCode: entry.statusCode,
     description: entry.description ?? '',
-    schema: entry.schema,
+    schema: defaultErrorSchema(key, entry),
   }))
 }
 
@@ -314,10 +372,7 @@ export function resolveErrorResponse(params: {
 
         const rawBody = entry.toResponse
           ? entry.toResponse(candidate as any, { key })
-          : {
-              name: key,
-              message: candidate instanceof Error ? candidate.message : String(candidate),
-            }
+          : defaultErrorBody(key, candidate)
         const body = ensureName(rawBody, key)
 
         return {

package/src/implementations/http/hono/handlers/http.test.ts

@@ -120,11 +120,79 @@ describe('installHttpRoute', () => {
         path: '/q', method: 'get',
         schema: { req: { query: Type.Any() }, res: { body: Type.Any() } },
       },
-        async (_ctx, { query }) => ({ body: query }))
+        async (_ctx, { query }) => query)
     }, { api: { queryParser } })
 
     const res = await app.request('/q?a=1&b=2')
     expect(queryParser).toHaveBeenCalledWith('a=1&b=2')
     expect(await res.json()).toEqual({ parsed: true, raw: 'a=1&b=2' })
   })
+
+  test('domain object with a top-level "body" field serializes whole (no res.headers)', async () => {
+    const { app } = buildApp((P) => {
+      P.CreateHttp('GetMessage', {
+        path: '/msg', method: 'get',
+        schema: { res: { body: Type.Object({ id: Type.String(), body: Type.String() }) } },
+      }, async () => ({ id: '1', body: 'hello text' }))
+    })
+    const res = await app.request('/msg')
+    expect(res.status).toBe(200)
+    expect(await res.json()).toEqual({ id: '1', body: 'hello text' })
+  })
+
+  test('envelope unwraps when res.headers is declared', async () => {
+    const { app } = buildApp((P) => {
+      P.CreateHttp('Enveloped', {
+        path: '/env', method: 'get',
+        schema: { res: { body: Type.Object({ ok: Type.Boolean() }), headers: Type.Object({}) } },
+      }, async () => ({ body: { ok: true }, headers: { 'x-trace': 'z' } }))
+    })
+    const res = await app.request('/env')
+    expect(res.status).toBe(200)
+    expect(res.headers.get('x-trace')).toBe('z')
+    expect(await res.json()).toEqual({ ok: true })
+  })
+
+  // Headers-only response shape — `res: { headers }` with no `res.body`. The
+  // handler returns `{ headers }` (no body key). The response must be bodyless,
+  // not an empty `application/json` payload that a client can't parse.
+  test('headers-only res schema returns a clean bodyless response', async () => {
+    const { app } = buildApp((P) => {
+      P.CreateHttp('HeadOnly', {
+        path: '/ho', method: 'get',
+        schema: { res: { headers: Type.Object({}) } },
+      }, async () => ({ headers: { 'x-trace': 'h1' } }))
+    })
+    const res = await app.request('/ho')
+    expect(res.status).toBe(200)
+    expect(res.headers.get('x-trace')).toBe('h1')
+    expect(res.headers.get('content-type')).toBeNull()
+    expect(await res.text()).toBe('')
+  })
+
+  // A void handler on a non-204 status sends a clean bodyless response rather
+  // than an empty `application/json` payload — uniform with the headers-only and
+  // 204 paths (an undefined body is always bodyless).
+  test('void handler on a 200 status returns a clean bodyless response', async () => {
+    const { app } = buildApp((P) => {
+      P.CreateHttp('Void', { path: '/void', method: 'get', schema: {} }, async () => undefined)
+    })
+    const res = await app.request('/void')
+    expect(res.status).toBe(200)
+    expect(res.headers.get('content-type')).toBeNull()
+    expect(await res.text()).toBe('')
+  })
+
+  test('res.headers declared with a 204 status applies headers and no body', async () => {
+    const { app } = buildApp((P) => {
+      P.CreateHttp('NoContent', {
+        path: '/nc', method: 'delete',
+        schema: { res: { headers: Type.Object({}) } },
+      }, async () => ({ headers: { 'x-trace': 'd1' } }))
+    })
+    const res = await app.request('/nc', { method: 'DELETE' })
+    expect(res.status).toBe(204)
+    expect(res.headers.get('x-trace')).toBe('d1')
+    expect(await res.text()).toBe('')
+  })
 })

package/src/implementations/http/hono/handlers/http.ts

@@ -103,32 +103,30 @@ export function installHttpRoute(params: {
 
       cfg.api?.onSuccess?.(procedure, c)
 
-      // 204 No Content — no body, just optional headers
-      if (successStatus === 204) {
-        if (result && typeof result === 'object' && 'headers' in result && (result as any).headers) {
-          for (const [k, v] of Object.entries((result as any).headers as Record<string, string>)) {
-            c.header(k, v)
-          }
-        }
-        return c.body(null, 204)
+      // The `{ body, headers }` envelope is OPT-IN via `schema.res.headers`: when
+      // the route declares response headers, the handler returns `{ body, headers }`;
+      // otherwise its return value IS the body. Gating on the schema (rather than
+      // duck-typing the result for a `body`/`headers` key) lets a domain object
+      // safely carry its own `body`/`headers` field without being unwrapped.
+      // Normalize both shapes to a single `{ body, headers }` so the response
+      // decision below is uniform for every legal return shape.
+      const hasResHeaders = procedure.config.schema?.res?.headers != null
+      const { body, headers } = hasResHeaders
+        ? ((result ?? {}) as { body?: unknown; headers?: unknown })
+        : { body: result, headers: undefined }
+
+      if (headers && typeof headers === 'object') {
+        for (const [k, v] of Object.entries(headers as Record<string, string>)) c.header(k, v)
       }
 
-      let body: unknown = result
-      let headers: Record<string, string> | undefined
-
-      if (result && typeof result === 'object' && 'body' in result && 'headers' in result) {
-        body = (result as any).body
-        headers = (result as any).headers as Record<string, string>
-      } else if (result && typeof result === 'object' && 'headers' in result && !('body' in result)) {
-        for (const [k, v] of Object.entries((result as any).headers as Record<string, string>)) {
-          c.header(k, v)
-        }
+      // No body to send — a 204 status, or an `undefined` return (a `void`
+      // handler, or a headers-only `res: { headers }` envelope). Emit a clean
+      // bodyless response instead of `c.json(undefined)`, which would send an
+      // empty, unparseable body under an `application/json` content-type.
+      if (successStatus === 204 || body === undefined) {
         return c.body(null, successStatus as any)
-      } else if (result && typeof result === 'object' && 'body' in result && !('headers' in result)) {
-        body = (result as any).body
       }
 
-      if (headers) for (const [k, v] of Object.entries(headers)) c.header(k, v)
       return c.json(body, successStatus as any)
     } catch (error) {
       return dispatchPreStreamError({