ts-procedures 8.2.1 → 8.3.0

package/build/implementations/http/hono/handlers/http.js

@@ -68,33 +68,28 @@ export function installHttpRoute(params) {
                 : undefined;
             const result = await procedure.handler({ ...context, signal: c.req.raw.signal }, reqParams);
             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.headers) {
-                    for (const [k, v] of Object.entries(result.headers)) {
-                        c.header(k, v);
-                    }
-                }
-                return c.body(null, 204);
-            }
-            let body = result;
-            let headers;
-            if (result && typeof result === 'object' && 'body' in result && 'headers' in result) {
-                body = result.body;
-                headers = result.headers;
-            }
-            else if (result && typeof result === 'object' && 'headers' in result && !('body' in result)) {
-                for (const [k, v] of Object.entries(result.headers)) {
+            // 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 ?? {})
+                : { body: result, headers: undefined };
+            if (headers && typeof headers === 'object') {
+                for (const [k, v] of Object.entries(headers))
                     c.header(k, v);
-                }
-                return c.body(null, successStatus);
             }
-            else if (result && typeof result === 'object' && 'body' in result && !('headers' in result)) {
-                body = result.body;
+            // 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);
             }
-            if (headers)
-                for (const [k, v] of Object.entries(headers))
-                    c.header(k, v);
             return c.json(body, successStatus);
         }
         catch (error) {

package/build/implementations/http/hono/handlers/http.js.map

@@ -1 +1 @@
-{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../../../src/implementations/http/hono/handlers/http.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAA;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAGvD,MAAM,YAAY,GAAiB,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CAAA;AAE3D,SAAS,oBAAoB,CAAC,MAAkB;IAC9C,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,MAAM,CAAC,CAAG,OAAO,GAAG,CAAA;QACzB,KAAK,QAAQ,CAAC,CAAC,OAAO,GAAG,CAAA;QACzB,OAAO,CAAC,CAAO,OAAO,GAAG,CAAA;IAC3B,CAAC;AACH,CAAC;AAED,SAAS,gBAAgB,CAAC,WAAmB;IAC3C,MAAM,EAAE,GAAG,IAAI,eAAe,CAAC,WAAW,CAAC,CAAA;IAC3C,MAAM,MAAM,GAA4B,EAAE,CAAA;IAC1C,KAAK,MAAM,GAAG,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAC7B,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;IACtD,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED,SAAS,YAAY,CAAC,GAAW,EAAE,MAAmB;IACpD,MAAM,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAC1B,IAAI,CAAC,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,CAAA;IACvB,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;IAC5B,OAAO,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;AAC/B,CAAC;AAED,KAAK,UAAU,aAAa,CAC1B,CAAU,EACV,MAAkB,EAClB,SAAkC,EAClC,MAAmB;IAEnB,MAAM,MAAM,GAA4B,EAAE,CAAA;IAC1C,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7C,QAAQ,OAAO,EAAE,CAAC;YAChB,KAAK,YAAY;gBACf,MAAM,CAAC,UAAU,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,CAAA;gBACjC,MAAK;YACP,KAAK,OAAO;gBACV,MAAM,CAAC,KAAK,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;gBAC9C,MAAK;YACP,KAAK,MAAM;gBACT,IAAI,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;oBAClC,MAAM,CAAC,IAAI,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;gBACpD,CAAC;gBACD,MAAK;YACP,KAAK,SAAS,CAAC,CAAC,CAAC;gBACf,MAAM,GAAG,GAA2B,EAAE,CAAA;gBACtC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA,CAAC,CAAC,CAAC,CAAA;gBACnD,MAAM,CAAC,OAAO,GAAG,GAAG,CAAA;gBACpB,MAAK;YACP,CAAC;YACD;gBACE,MAAM,CAAC,OAAO,CAAC,GAAG,SAAS,CAAA;QAC/B,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAMhC;IACC,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,MAAM,CAAA;IACzD,MAAM,WAAW,GAAG,GAAG,CAAC,GAAG,EAAE,WAAW,IAAI,gBAAgB,CAAA;IAE5D,MAAM,KAAK,GAAG,iBAAiB,CAC7B,SAAS,EACT,GAAG,CAAC,UAAU,EACd,WAAW,CAAC,kBAAyB,CACtC,CAAA;IACD,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAEhB,MAAM,aAAa,GAAG,SAAS,CAAC,MAAM,CAAC,aAAa,IAAI,oBAAoB,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IACrG,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAA;IAE9C,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAU,EAAE,EAAE;QACjF,IAAI,CAAC;YACH,MAAM,OAAO,GACX,OAAO,WAAW,CAAC,cAAc,KAAK,UAAU;gBAC9C,CAAC,CAAC,MAAO,WAAW,CAAC,cAAsC,CAAC,CAAC,CAAC;gBAC9D,CAAC,CAAC,WAAW,CAAC,cAAc,CAAA;YAEhC,MAAM,SAAS,GAAG,SAAS;gBACzB,CAAC,CAAC,MAAM,aAAa,CAAC,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,CAAC;gBACzE,CAAC,CAAC,SAAS,CAAA;YAEb,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,OAAO,CACpC,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,EACxC,SAAS,CACV,CAAA;YAED,GAAG,CAAC,GAAG,EAAE,SAAS,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC,CAAA;YAElC,kDAAkD;YAClD,IAAI,aAAa,KAAK,GAAG,EAAE,CAAC;gBAC1B,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,SAAS,IAAI,MAAM,IAAK,MAAc,CAAC,OAAO,EAAE,CAAC;oBAC3F,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAE,MAAc,CAAC,OAAiC,CAAC,EAAE,CAAC;wBACvF,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;oBAChB,CAAC;gBACH,CAAC;gBACD,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;YAC1B,CAAC;YAED,IAAI,IAAI,GAAY,MAAM,CAAA;YAC1B,IAAI,OAA2C,CAAA;YAE/C,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,IAAI,MAAM,IAAI,SAAS,IAAI,MAAM,EAAE,CAAC;gBACpF,IAAI,GAAI,MAAc,CAAC,IAAI,CAAA;gBAC3B,OAAO,GAAI,MAAc,CAAC,OAAiC,CAAA;YAC7D,CAAC;iBAAM,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,SAAS,IAAI,MAAM,IAAI,CAAC,CAAC,MAAM,IAAI,MAAM,CAAC,EAAE,CAAC;gBAC9F,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAE,MAAc,CAAC,OAAiC,CAAC,EAAE,CAAC;oBACvF,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;gBAChB,CAAC;gBACD,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,aAAoB,CAAC,CAAA;YAC3C,CAAC;iBAAM,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,IAAI,MAAM,IAAI,CAAC,CAAC,SAAS,IAAI,MAAM,CAAC,EAAE,CAAC;gBAC9F,IAAI,GAAI,MAAc,CAAC,IAAI,CAAA;YAC7B,CAAC;YAED,IAAI,OAAO;gBAAE,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;oBAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;YACzE,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,aAAoB,CAAC,CAAA;QAC3C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,sBAAsB,CAAC;gBAC5B,GAAG,EAAE,KAAK;gBACV,SAAS;gBACT,GAAG,EAAE,CAAC;gBACN,GAAG,EAAE;oBACH,MAAM,EAAE,GAAG,CAAC,MAAM;oBAClB,YAAY,EAAE,GAAG,CAAC,YAAY;oBAC9B,OAAO,EAAE,GAAG,CAAC,OAAO;oBACpB,cAAc,EAAE,GAAG,CAAC,cAAc;iBACnC;aACF,CAAC,CAAA;QACJ,CAAC;IACH,CAAC,CAAC,CAAA;AACJ,CAAC"}
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../../../src/implementations/http/hono/handlers/http.ts"],"names":[],"mappings":"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"}

package/build/implementations/http/hono/handlers/http.test.js

@@ -108,11 +108,74 @@ describe('installHttpRoute', () => {
             P.CreateHttp('Q', {
                 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('');
+    });
 });
 //# sourceMappingURL=http.test.js.map

package/build/implementations/http/hono/handlers/http.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"http.test.js","sourceRoot":"","sources":["../../../../../src/implementations/http/hono/handlers/http.test.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"http.test.js","sourceRoot":"","sources":["../../../../../src/implementations/http/hono/handlers/http.test.ts"],"names":[],"mappings":"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"}

package/docs/client-and-codegen.md

@@ -4,6 +4,10 @@
 
 ts-procedures can generate type-safe client SDKs directly from your server's `DocRegistry` output. Generated files include TypeScript types and callable functions for every registered procedure, organized by scope — no manual type duplication required.
 
+## Setup / prerequisites
+
+> **ESM only.** ts-procedures and its generated output are ESM-only — a `tsconfig.json` with `"module": "commonjs"` fails immediately. In your consuming project set `"type": "module"` in `package.json`, and in `tsconfig.json` use `"module": "ESNext"` with `"moduleResolution": "Bundler"` (or `"NodeNext"`). Run scripts with [`tsx`](https://github.com/privatenumber/tsx) during development (e.g. `tsx src/index.ts`).
+
 ## Quick Start
 
 **Step 1 — Serve your docs endpoint** (see [DocRegistry](./http-integrations.md#docregistry--composing-docs-from-multiple-builders) for setup):
@@ -35,7 +39,11 @@ const api = createApiClient({
     },
   },
 })
+```
 
+> **Note:** `basePath` must be the **origin only** (e.g. `http://localhost:3000`), not `http://localhost:3000/api`. Generated client paths already include the server's `pathPrefix` (e.g. `/api/...`), so putting the prefix in `basePath` too doubles it up to `/api/api/...`.
+
+```typescript
 try {
   const user = await api.users.GetUser({ pathParams: { id: '123' } })
 } catch (err) {

package/docs/core.md

@@ -214,6 +214,8 @@ schema: { params: Type.Object({ title: Type.String() }) }
 
 TypeBox schemas are valid JSON Schema and work directly with AJV for runtime validation.
 
+> **Composing schemas:** the bundled typebox has no `Type.Composite`. Compose with a flat object spread instead — `Type.Object({ ...Base.properties, extra: Type.String() })` — which also keeps the emitted JSON Schema a single `object` rather than an `allOf`.
+
 ### Validation Behavior
 
 AJV is configured with:

package/docs/http-integrations.md

@@ -134,6 +134,10 @@ new HonoAppBuilder({
 
 For streaming procedures the taxonomy covers the pre-stream path only; mid-stream errors are handled via `stream.onMidStreamError`.
 
+> **Typed client classes — when you get them for free.** A taxonomy entry declared with just `{ class, statusCode }` is self-describing: its default body is `{ name, message }`, so codegen emits a typed client error class and registry entry automatically — `catch (e) { if (e instanceof ApiErrors.NotFound) ... }` works with zero extra ceremony. The framework can only do this when it knows the wire shape. Two cases where it can't, and the client falls back to the untyped `ClientHttpError` until you help it:
+> - **Custom `toResponse` without a `schema`.** Once you shape the body yourself, the framework won't guess it. Add an explicit `schema` matching your `toResponse` to restore the typed class.
+> - **Raw `ErrorDoc`s** added via `DocRegistry.documentError(...)` or a `config.errors` array (rather than a taxonomy). These carry no body contract — give them a `schema` to make them typed on the client.
+
 ### Imperative — the `onError` callback
 
 For apps that don't need typed client dispatch or declarative docs, configure `onError` directly and handle every error in one place:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "8.2.1",
+  "version": "8.3.0",
   "description": "A TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition. Define your procedures once and get full type inference, runtime validation, and framework integration hooks.",
   "main": "build/exports.js",
   "types": "build/exports.d.ts",

package/src/codegen/emit-errors.integration.test.ts

@@ -10,6 +10,11 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { execSync } from 'node:child_process'
 import { generateClient } from './index.js'
+import { emitErrorsFile } from './emit-errors.js'
+import {
+  defineErrorTaxonomy,
+  taxonomyToErrorDocs,
+} from '../implementations/http/error-taxonomy.js'
 import type { DocEnvelope } from '../implementations/types.js'
 
 describe('generated _errors.ts — runtime behavior', () => {
@@ -180,4 +185,25 @@ describe('generated _errors.ts — runtime behavior', () => {
       rmSync(outDir, { recursive: true, force: true })
     }
   }, 30000)
+
+  // ---------------------------------------------------------------------------
+  // Taxonomy-derived envelope: a class+statusCode-only entry must produce a
+  // typed client error class + registry entry (previously schema-less → skipped).
+  // ---------------------------------------------------------------------------
+  it('emits a typed class + registry entry for a class+statusCode-only taxonomy entry', async () => {
+    const taxonomy = defineErrorTaxonomy({
+      // Only { class, statusCode } — the common case. No schema, no toResponse.
+      AuthError: { class: class AuthError extends Error {}, statusCode: 401 },
+    })
+    const errorDocs = taxonomyToErrorDocs(taxonomy)
+
+    // The synthesized schema is what makes codegen emit a class for it.
+    const result = await emitErrorsFile(errorDocs)
+    expect(result).toBeDefined()
+    expect(result).toContain('export class AuthError')
+    expect(result).toContain('export const ErrorRegistry = {')
+    // Precise registry membership — `^\s*AuthError,$` avoids matching a
+    // substring like `MyAuthError,` or an occurrence in a comment.
+    expect(result).toMatch(/^\s*AuthError,$/m)
+  })
 })

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({