ts-procedures 5.16.0 → 6.0.0

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

@@ -0,0 +1,183 @@
+/**
+ * Verifies the generated error classes actually work at runtime — instantiated,
+ * thrown, and `instanceof`-checkable. We do this by generating a client from a
+ * synthetic DocEnvelope, writing it to a temp dir, dynamically importing the
+ * generated `_errors.ts`, and exercising the classes.
+ */
+import { describe, expect, it } from 'vitest'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { execSync } from 'node:child_process'
+import { generateClient } from './index.js'
+import type { DocEnvelope } from '../implementations/types.js'
+
+describe('generated _errors.ts — runtime behavior', () => {
+  const envelope: DocEnvelope = {
+    basePath: '/api',
+    headers: [],
+    errors: [
+      {
+        name: 'UseCaseError',
+        statusCode: 422,
+        description: 'Business rule violation.',
+        schema: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', const: 'UseCaseError' },
+            message: { type: 'string' },
+          },
+          required: ['name', 'message'],
+        },
+      },
+      {
+        name: 'AuthError',
+        statusCode: 401,
+        description: 'Authentication required.',
+        schema: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', const: 'AuthError' },
+            message: { type: 'string' },
+          },
+          required: ['name', 'message'],
+        },
+      },
+    ],
+    routes: [
+      {
+        kind: 'api',
+        name: 'Ping',
+        scope: 'default',
+        path: '/ping',
+        fullPath: '/api/ping',
+        method: 'get',
+        jsonSchema: { response: { type: 'object', properties: {} } },
+      },
+    ],
+  }
+
+  function makeTmp(): string {
+    return mkdtempSync(join(tmpdir(), 'ts-proc-errors-'))
+  }
+
+  it('emits classes that extend a shared base and are instanceof-checkable', async () => {
+    const outDir = makeTmp()
+    try {
+      await generateClient({ envelope, outDir, namespaceTypes: false, selfContained: true })
+
+      // Compile the generated files with tsc so the classes become runnable JS.
+      const tsconfig = {
+        compilerOptions: {
+          target: 'ES2022',
+          module: 'ESNext',
+          moduleResolution: 'bundler',
+          strict: true,
+          outDir: './out',
+        },
+        include: ['_types.ts', '_client.ts', '_errors.ts', 'index.ts', 'default.ts'],
+      }
+      writeFileSync(join(outDir, 'tsconfig.json'), JSON.stringify(tsconfig, null, 2))
+
+      const tscPath = join(process.cwd(), 'node_modules/.bin/tsc')
+      try {
+        execSync(`${tscPath} --project ${join(outDir, 'tsconfig.json')}`, { stdio: 'pipe' })
+      } catch (e) {
+        const err = e as { stdout?: Buffer; stderr?: Buffer }
+        const stdout = err.stdout?.toString() ?? ''
+        const stderr = err.stderr?.toString() ?? ''
+        throw new Error(`tsc failed in ${outDir}:\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`)
+      }
+
+      // Dynamic import of the compiled output.
+      const errorsUrl = `file://${join(outDir, 'out', '_errors.js')}`
+      const mod = await import(errorsUrl)
+
+      // Default serviceName is 'Api' so base class is ApiProcedureError and
+      // registry is ApiErrorRegistry.
+      expect(typeof mod.ApiProcedureError).toBe('function')
+      expect(typeof mod.UseCaseError).toBe('function')
+      expect(typeof mod.AuthError).toBe('function')
+
+      // Classes extend the base — `instanceof` works in both directions.
+      const useCase = mod.UseCaseError.fromResponse(
+        { name: 'UseCaseError', message: 'boom' },
+        { status: 422, procedureName: 'DoThing', scope: 'things' }
+      )
+      expect(useCase).toBeInstanceOf(mod.UseCaseError)
+      expect(useCase).toBeInstanceOf(mod.ApiProcedureError)
+      expect(useCase).toBeInstanceOf(Error)
+      expect(useCase.status).toBe(422)
+      expect(useCase.procedureName).toBe('DoThing')
+      expect(useCase.scope).toBe('things')
+      expect(useCase.message).toBe('boom')
+      expect(useCase.body.message).toBe('boom')
+
+      // Registry is a plain object keyed by class name.
+      expect(mod.ApiErrorRegistry.UseCaseError).toBe(mod.UseCaseError)
+      expect(mod.ApiErrorRegistry.AuthError).toBe(mod.AuthError)
+
+      // Subclasses don't accidentally share identity (distinct constructors).
+      const auth = mod.AuthError.fromResponse(
+        { name: 'AuthError', message: 'nope' },
+        { status: 401, procedureName: 'Secret', scope: 'auth' }
+      )
+      expect(auth).toBeInstanceOf(mod.AuthError)
+      expect(auth).not.toBeInstanceOf(mod.UseCaseError)
+    } finally {
+      rmSync(outDir, { recursive: true, force: true })
+    }
+  }, 30000)
+
+  it('namespaceTypes: true wraps classes in a namespace and registry is reachable via qualified name', async () => {
+    const outDir = makeTmp()
+    try {
+      await generateClient({
+        envelope,
+        outDir,
+        namespaceTypes: true,
+        selfContained: true,
+        serviceName: 'Demo',
+      })
+
+      const tsconfig = {
+        compilerOptions: {
+          target: 'ES2022',
+          module: 'ESNext',
+          moduleResolution: 'bundler',
+          strict: true,
+          outDir: './out',
+        },
+        include: ['_types.ts', '_client.ts', '_errors.ts', 'index.ts', 'default.ts'],
+      }
+      writeFileSync(join(outDir, 'tsconfig.json'), JSON.stringify(tsconfig, null, 2))
+
+      const tscPath = join(process.cwd(), 'node_modules/.bin/tsc')
+      try {
+        execSync(`${tscPath} --project ${join(outDir, 'tsconfig.json')}`, { stdio: 'pipe' })
+      } catch (e) {
+        const err = e as { stdout?: Buffer; stderr?: Buffer }
+        const stdout = err.stdout?.toString() ?? ''
+        const stderr = err.stderr?.toString() ?? ''
+        throw new Error(`tsc failed in ${outDir}:\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`)
+      }
+
+      const errorsUrl = `file://${join(outDir, 'out', '_errors.js')}`
+      const mod = await import(errorsUrl)
+
+      const ns = mod.DemoErrors
+      expect(typeof ns.UseCaseError).toBe('function')
+      expect(typeof ns.DemoErrorRegistry).toBe('object')
+      expect(ns.DemoErrorRegistry.UseCaseError).toBe(ns.UseCaseError)
+
+      const useCase = ns.UseCaseError.fromResponse(
+        { name: 'UseCaseError', message: 'x' },
+        { status: 422, procedureName: 'P', scope: 's' }
+      )
+      expect(useCase).toBeInstanceOf(ns.UseCaseError)
+      expect(useCase).toBeInstanceOf(ns.DemoProcedureError)
+    } finally {
+      rmSync(outDir, { recursive: true, force: true })
+    }
+  }, 30000)
+})

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

@@ -49,36 +49,66 @@ const errorDocWithoutSchema: ErrorDoc = {
 // ---------------------------------------------------------------------------
 
 describe('emitErrorsFile', () => {
-  it('generates types for errors with schemas', async () => {
+  it('generates a runtime class per error with schema', async () => {
     const result = await emitErrorsFile([procedureErrorDoc, validationErrorDoc])
     expect(result).toBeDefined()
-    expect(result).toContain('export type ProcedureError =')
-    expect(result).toContain('export type ProcedureValidationError =')
+    expect(result).toContain('export class ProcedureError')
+    expect(result).toContain('export class ProcedureValidationError')
   })
 
-  it('generates ProcedureErrorUnion discriminated union', async () => {
-    const result = await emitErrorsFile([procedureErrorDoc, validationErrorDoc])
+  it('emits a body type for each class', async () => {
+    const result = await emitErrorsFile([procedureErrorDoc])
+    expect(result).toContain('export type ProcedureErrorBody =')
+  })
+
+  it('each class has a static fromResponse factory', async () => {
+    const result = await emitErrorsFile([procedureErrorDoc])
+    expect(result).toContain('static fromResponse(')
+    expect(result).toContain("name: 'ProcedureError'")
+  })
+
+  it('emits a shared base class the errors extend', async () => {
+    const result = await emitErrorsFile([procedureErrorDoc])
     expect(result).toBeDefined()
-    expect(result).toContain('export type ProcedureErrorUnion = ProcedureError | ProcedureValidationError')
+    expect(result).toMatch(/export class ProcedureErrorBase<TBody = unknown> extends Error/)
+    expect(result).toContain('extends ProcedureErrorBase<ProcedureErrorBody>')
+  })
+
+  it('emits a discriminated union type', async () => {
+    const result = await emitErrorsFile([procedureErrorDoc, validationErrorDoc])
+    expect(result).toContain(
+      'export type ProcedureErrorUnion = ProcedureError | ProcedureValidationError'
+    )
+  })
+
+  it('emits a runtime registry keyed by class name', async () => {
+    const result = await emitErrorsFile([procedureErrorDoc, validationErrorDoc])
+    expect(result).toContain('export const ErrorRegistry = {')
+    expect(result).toMatch(/ProcedureError,/)
+    expect(result).toMatch(/ProcedureValidationError,/)
   })
 
   it('includes JSDoc with statusCode and description', async () => {
     const result = await emitErrorsFile([procedureErrorDoc])
-    expect(result).toBeDefined()
-    expect(result).toContain('/** An error thrown from within a procedure handler via ctx.error(). (HTTP 500) */')
+    expect(result).toContain(
+      '/** An error thrown from within a procedure handler via ctx.error(). (HTTP 500) */'
+    )
   })
 
-  it('includes JSDoc before the type declaration', async () => {
+  it('includes JSDoc before the concrete class declaration', async () => {
     const result = await emitErrorsFile([procedureErrorDoc])
-    expect(result).toBeDefined()
-    const jsdocIdx = result!.indexOf('/** An error thrown from within a procedure handler via ctx.error().')
-    const typeIdx = result!.indexOf('export type ProcedureError =')
-    expect(jsdocIdx).toBeLessThan(typeIdx)
+    const jsdocIdx = result!.indexOf(
+      '/** An error thrown from within a procedure handler via ctx.error().'
+    )
+    // Match only the concrete class (ProcedureError), not the base class
+    // (ProcedureErrorBase which is a prefix-collision).
+    const concreteClassIdx = result!.indexOf('export class ProcedureError extends')
+    expect(jsdocIdx).toBeGreaterThan(-1)
+    expect(concreteClassIdx).toBeGreaterThan(jsdocIdx)
   })
 
   it('includes the auto-generated header comment', async () => {
     const result = await emitErrorsFile([procedureErrorDoc])
-    expect(result).toBeDefined()
     expect(result).toContain('// Auto-generated by ts-procedures-codegen — do not edit')
   })
 
@@ -87,116 +117,90 @@ describe('emitErrorsFile', () => {
     expect(result).toBeUndefined()
   })
 
-  it('returns undefined for empty errors array', async () => {
+  it('returns undefined for an empty errors array', async () => {
     const result = await emitErrorsFile([])
     expect(result).toBeUndefined()
   })
 
-  it('skips errors without schema, includes those with schema', async () => {
-    const result = await emitErrorsFile([procedureErrorDoc, errorDocWithoutSchema, validationErrorDoc])
-    expect(result).toBeDefined()
-    expect(result).toContain('export type ProcedureError =')
-    expect(result).toContain('export type ProcedureValidationError =')
-    // UnknownError has no schema, so it should not appear as a type
-    expect(result).not.toContain('export type UnknownError =')
-    // But the union should only include the ones with schemas
-    expect(result).toContain('ProcedureError | ProcedureValidationError')
-    expect(result).not.toContain('UnknownError')
-  })
-
-  it('union type has single type when only one error has schema', async () => {
-    const result = await emitErrorsFile([procedureErrorDoc])
-    expect(result).toBeDefined()
-    expect(result).toContain('export type ProcedureErrorUnion = ProcedureError')
-  })
-
-  it('union type does not include errros without schemas', async () => {
-    const result = await emitErrorsFile([procedureErrorDoc, errorDocWithoutSchema])
-    expect(result).toBeDefined()
+  it('skips errors without schema, emits classes for the rest', async () => {
+    const result = await emitErrorsFile([
+      procedureErrorDoc,
+      errorDocWithoutSchema,
+      validationErrorDoc,
+    ])
+    expect(result).toContain('export class ProcedureError')
+    expect(result).toContain('export class ProcedureValidationError')
+    expect(result).not.toContain('export class UnknownError')
     expect(result).not.toContain('UnknownError')
-    expect(result).toContain('export type ProcedureErrorUnion = ProcedureError')
   })
 
-  it('respects ajscOpts passed to jsonSchemaToTypeString', async () => {
-    // Just verify it does not crash when options are passed — behavior is tested in emit-types.test.ts
+  it('accepts ajsc options without crashing', async () => {
     const result = await emitErrorsFile([procedureErrorDoc], { ajsc: { enumStyle: 'union' } })
     expect(result).toBeDefined()
-    expect(result).toContain('export type ProcedureError =')
+    expect(result).toContain('export class ProcedureError')
   })
 
   describe('serviceName', () => {
-    it('uses Errors namespace by default', async () => {
-      const result = await emitErrorsFile([procedureErrorDoc, validationErrorDoc], { namespaceTypes: true })
+    it('uses Errors namespace by default in namespace mode', async () => {
+      const result = await emitErrorsFile([procedureErrorDoc], { namespaceTypes: true })
       expect(result).toContain('export namespace Errors {')
     })
 
-    it('prefixes namespace with serviceName when provided', async () => {
-      const result = await emitErrorsFile([procedureErrorDoc, validationErrorDoc], { namespaceTypes: true, serviceName: 'Auth' })
+    it('prefixes namespace with serviceName', async () => {
+      const result = await emitErrorsFile([procedureErrorDoc], {
+        namespaceTypes: true,
+        serviceName: 'Auth',
+      })
       expect(result).toContain('export namespace AuthErrors {')
       expect(result).not.toContain('export namespace Errors {')
     })
 
-    it('PascalCases a kebab-case serviceName for namespace', async () => {
-      const result = await emitErrorsFile([procedureErrorDoc], { namespaceTypes: true, serviceName: 'user-service' })
+    it('PascalCases a kebab-case serviceName', async () => {
+      const result = await emitErrorsFile([procedureErrorDoc], {
+        namespaceTypes: true,
+        serviceName: 'user-service',
+      })
       expect(result).toContain('export namespace UserServiceErrors {')
     })
 
-    it('does not affect namespace when namespaceTypes is false', async () => {
-      const result = await emitErrorsFile([procedureErrorDoc], { namespaceTypes: false, serviceName: 'Auth' })
-      expect(result).toBeDefined()
-      expect(result).not.toContain('namespace')
-    })
-
-    it('prefixes ProcedureErrorUnion in flat mode when serviceName is set', async () => {
-      const result = await emitErrorsFile([procedureErrorDoc, validationErrorDoc], { namespaceTypes: false, serviceName: 'Auth' })
-      expect(result).toBeDefined()
-      expect(result).toContain('export type AuthProcedureErrorUnion = ProcedureError | ProcedureValidationError')
-      expect(result).not.toContain('export type ProcedureErrorUnion =')
-    })
-
-    it('prefixes ProcedureErrorUnion inside namespace when serviceName is set', async () => {
-      const result = await emitErrorsFile([procedureErrorDoc], { namespaceTypes: true, serviceName: 'Auth' })
-      expect(result).toBeDefined()
-      expect(result).toContain('AuthProcedureErrorUnion')
-      expect(result).not.toMatch(/\bexport type ProcedureErrorUnion\b/)
+    it('prefixes base class, union, and registry when serviceName is set', async () => {
+      const result = await emitErrorsFile([procedureErrorDoc, validationErrorDoc], {
+        serviceName: 'Auth',
+      })
+      expect(result).toMatch(/export class AuthProcedureError<TBody = unknown> extends Error/)
+      expect(result).toContain(
+        'export type AuthProcedureErrorUnion = ProcedureError | ProcedureValidationError'
+      )
+      expect(result).toContain('export const AuthErrorRegistry = {')
     })
 
-    it('leaves ProcedureErrorUnion unprefixed when no serviceName', async () => {
-      const result = await emitErrorsFile([procedureErrorDoc], { namespaceTypes: false })
-      expect(result).toBeDefined()
+    it('leaves names unprefixed when no serviceName', async () => {
+      const result = await emitErrorsFile([procedureErrorDoc])
+      expect(result).toMatch(/export class ProcedureErrorBase<TBody = unknown> extends Error/)
       expect(result).toContain('export type ProcedureErrorUnion = ProcedureError')
+      expect(result).toContain('export const ErrorRegistry = {')
     })
   })
 
   describe('namespaceTypes', () => {
-    it('wraps error types in export namespace Errors', async () => {
-      const result = await emitErrorsFile([procedureErrorDoc, validationErrorDoc], { namespaceTypes: true })
-      expect(result).toBeDefined()
+    it('wraps classes and registry in export namespace', async () => {
+      const result = await emitErrorsFile([procedureErrorDoc, validationErrorDoc], {
+        namespaceTypes: true,
+      })
       expect(result).toContain('export namespace Errors {')
-      expect(result).toContain('export type ProcedureError =')
-      expect(result).toContain('export type ProcedureValidationError =')
-    })
-
-    it('places union inside the namespace', async () => {
-      const result = await emitErrorsFile([procedureErrorDoc, validationErrorDoc], { namespaceTypes: true })
-      expect(result).toBeDefined()
-      expect(result).toContain('export type ProcedureErrorUnion = ProcedureError | ProcedureValidationError')
-      // Union should be inside the namespace (indented)
-      const lines = result!.split('\n')
-      const unionLine = lines.find((l) => l.includes('ProcedureErrorUnion'))
-      expect(unionLine).toMatch(/^\s+export type ProcedureErrorUnion/)
+      expect(result).toContain('export class ProcedureError')
+      expect(result).toContain('export const ErrorRegistry = {')
     })
 
-    it('includes JSDoc inside namespace', async () => {
+    it('contents are indented inside the namespace block', async () => {
       const result = await emitErrorsFile([procedureErrorDoc], { namespaceTypes: true })
-      expect(result).toBeDefined()
-      expect(result).toContain('(HTTP 500)')
+      const classLine = result!.split('\n').find((l) => l.includes('export class ProcedureError'))
+      expect(classLine).toMatch(/^\s{2}export class ProcedureError/)
     })
 
     it('flat mode does not wrap in namespace', async () => {
       const result = await emitErrorsFile([procedureErrorDoc], { namespaceTypes: false })
-      expect(result).toBeDefined()
-      expect(result).not.toContain('export namespace Errors')
+      expect(result).not.toContain('export namespace')
     })
   })
 })

package/src/codegen/emit-errors.ts

@@ -1,4 +1,4 @@
-import { jsonSchemaToTypeString, jsonSchemaToExtractedTypes, type AjscOptions } from './emit-types.js'
+import { jsonSchemaToTypeBody, type AjscOptions } from './emit-types.js'
 import type { ErrorDoc } from '../implementations/types.js'
 import { CODEGEN_HEADER } from './constants.js'
 import { toPascalCase } from './naming.js'
@@ -11,14 +11,25 @@ export interface EmitErrorsOptions {
 }
 
 /**
- * Generates a TypeScript file with error type declarations from the DocEnvelope.errors array.
+ * Generates a TypeScript file with runtime error classes (plus a registry
+ * object for dispatch) derived from `DocEnvelope.errors`.
  *
- * Only errors with a `schema` property are included. If no errors have schemas,
- * returns `undefined` (no file generated).
+ * For each error with a schema, emits:
+ *   - `interface <Name>Body { ... }` — typed response body
+ *   - `class <Name> extends <ServiceName>ProcedureError<<Name>Body>` with
+ *     constructor + static `fromResponse(body, meta)`
  *
- * When `namespaceTypes` is true, wraps in `export namespace Errors { ... }`
- * (or `${ServiceName}Errors` with `serviceName`). The union type is similarly
- * prefixed: `ProcedureErrorUnion` → `${ServiceName}ProcedureErrorUnion`.
+ * The shared base `<ServiceName>ProcedureError` is emitted so consumers can
+ * `catch (e) { if (e instanceof ApiErrors.ApiProcedureError) ... }` to handle
+ * any service error in one block. `instanceof` works across bundler boundaries
+ * because the generated file holds the sole class definition at runtime.
+ *
+ * The registry `<ServiceName>ErrorRegistry` maps body `name` values to
+ * classes, consumed by the client's `dispatchTypedError` to produce typed
+ * errors instead of generic `ClientRequestError` instances.
+ *
+ * When `namespaceTypes` is on, everything is wrapped in `export namespace
+ * <ServiceName>Errors { ... }`. Returns `undefined` if no errors have schemas.
  */
 export async function emitErrorsFile(
   errors: ErrorDoc[],
@@ -27,54 +38,125 @@ export async function emitErrorsFile(
   const { ajsc: ajscOpts, namespaceTypes = false, serviceName } = options ?? {}
   const servicePrefix = serviceName ? toPascalCase(serviceName) : ''
   const namespaceName = servicePrefix ? `${servicePrefix}Errors` : 'Errors'
+  const baseClassName = servicePrefix ? `${servicePrefix}ProcedureError` : 'ProcedureErrorBase'
   const unionName = servicePrefix ? `${servicePrefix}ProcedureErrorUnion` : 'ProcedureErrorUnion'
+  const registryName = servicePrefix ? `${servicePrefix}ErrorRegistry` : 'ErrorRegistry'
 
-  // Filter to only errors that have a schema
-  const errorsWithSchema = errors.filter((e): e is ErrorDoc & { schema: Record<string, unknown> } =>
-    e.schema != null
+  const errorsWithSchema = errors.filter(
+    (e): e is ErrorDoc & { schema: Record<string, unknown> } => e.schema != null
   )
 
   if (errorsWithSchema.length === 0) {
     return undefined
   }
 
-  const typeLines: string[] = []
+  // Compute the typed body for each error by converting its schema to a TS type.
+  const entries: Array<{
+    doc: (typeof errorsWithSchema)[number]
+    bodyType: string
+  }> = []
+  for (const doc of errorsWithSchema) {
+    const bodyType = await jsonSchemaToTypeBody(doc.schema, ajscOpts)
+    entries.push({ doc, bodyType: bodyType ?? 'unknown' })
+  }
+
+  const lines: string[] = []
+  const indent = namespaceTypes ? '  ' : ''
 
   if (namespaceTypes) {
-    typeLines.push(`export namespace ${namespaceName} {`)
+    lines.push(`export namespace ${namespaceName} {`)
+  }
+
+  // Shared base class — lets consumers catch any service error with one check.
+  lines.push(
+    `${indent}/** Base class for every generated error in this service. Catch with \`instanceof\`. */`,
+    `${indent}export class ${baseClassName}<TBody = unknown> extends Error {`,
+    `${indent}  readonly status: number`,
+    `${indent}  readonly procedureName: string`,
+    `${indent}  readonly scope: string`,
+    `${indent}  readonly body: TBody`,
+    `${indent}  constructor(args: {`,
+    `${indent}    name: string`,
+    `${indent}    message: string`,
+    `${indent}    status: number`,
+    `${indent}    procedureName: string`,
+    `${indent}    scope: string`,
+    `${indent}    body: TBody`,
+    `${indent}  }) {`,
+    `${indent}    super(args.message)`,
+    `${indent}    this.name = args.name`,
+    `${indent}    this.status = args.status`,
+    `${indent}    this.procedureName = args.procedureName`,
+    `${indent}    this.scope = args.scope`,
+    `${indent}    this.body = args.body`,
+    `${indent}    Object.setPrototypeOf(this, new.target.prototype)`,
+    `${indent}  }`,
+    `${indent}}`,
+    ''
+  )
 
-    for (const error of errorsWithSchema) {
-      const result = await jsonSchemaToExtractedTypes(error.schema, ajscOpts)
-      if (result != null) {
-        typeLines.push(`  /** ${error.description} (HTTP ${error.statusCode}) */`)
-        for (const decl of result.declarations) {
-          typeLines.push(`  ${decl}`)
-        }
-        typeLines.push(`  export type ${error.name} = ${result.body}`)
-        typeLines.push('')
-      }
-    }
+  // Per-error body interface + class with fromResponse static factory.
+  for (const { doc, bodyType } of entries) {
+    const bodyInterfaceName = `${doc.name}Body`
+    lines.push(
+      `${indent}/** Response body for ${doc.name}. */`,
+      `${indent}export type ${bodyInterfaceName} = ${bodyType}`,
+      ''
+    )
 
-    const unionMembers = errorsWithSchema.map((e) => e.name).join(' | ')
-    typeLines.push(`  export type ${unionName} = ${unionMembers}`)
-    typeLines.push('}')
-    typeLines.push('')
-  } else {
-    for (const error of errorsWithSchema) {
-      const typeDecl = await jsonSchemaToTypeString(error.name, error.schema, ajscOpts)
-      if (typeDecl != null) {
-        typeLines.push(`/** ${error.description} (HTTP ${error.statusCode}) */`)
-        typeLines.push(typeDecl)
-        typeLines.push('')
-      }
-    }
+    const statusLiteral = doc.statusCode
+    const descLine = doc.description
+      ? `${indent}/** ${doc.description} (HTTP ${statusLiteral}) */`
+      : `${indent}/** HTTP ${statusLiteral} */`
 
-    const unionMembers = errorsWithSchema.map((e) => e.name).join(' | ')
-    typeLines.push(`export type ${unionName} = ${unionMembers}`)
-    typeLines.push('')
+    lines.push(
+      descLine,
+      `${indent}export class ${doc.name} extends ${baseClassName}<${bodyInterfaceName}> {`,
+      `${indent}  static readonly errorName = '${doc.name}' as const`,
+      `${indent}  static readonly statusCode = ${statusLiteral}`,
+      `${indent}  static fromResponse(`,
+      `${indent}    body: ${bodyInterfaceName},`,
+      `${indent}    meta: { status: number; procedureName: string; scope: string }`,
+      `${indent}  ): ${doc.name} {`,
+      `${indent}    const message =`,
+      `${indent}      body && typeof (body as { message?: unknown }).message === 'string'`,
+      `${indent}        ? (body as { message: string }).message`,
+      `${indent}        : '${doc.name}'`,
+      `${indent}    return new ${doc.name}({`,
+      `${indent}      name: '${doc.name}',`,
+      `${indent}      message,`,
+      `${indent}      status: meta.status,`,
+      `${indent}      procedureName: meta.procedureName,`,
+      `${indent}      scope: meta.scope,`,
+      `${indent}      body,`,
+      `${indent}    })`,
+      `${indent}  }`,
+      `${indent}}`,
+      ''
+    )
   }
 
-  const body = typeLines.join('\n')
+  // Union type — every generated error class instance.
+  const unionMembers = entries.map((e) => e.doc.name).join(' | ')
+  lines.push(
+    `${indent}/** Union of every generated error in this service. */`,
+    `${indent}export type ${unionName} = ${unionMembers}`,
+    ''
+  )
+
+  // Registry for runtime dispatch — keyed by body.name.
+  lines.push(
+    `${indent}/** Runtime registry consumed by the client to dispatch by \`body.name\`. */`,
+    `${indent}export const ${registryName} = {`,
+    ...entries.map((e) => `${indent}  ${e.doc.name},`),
+    `${indent}} as const`,
+    ''
+  )
+
+  if (namespaceTypes) {
+    lines.push('}')
+    lines.push('')
+  }
 
-  return [CODEGEN_HEADER, '', body].join('\n')
+  return [CODEGEN_HEADER, '', lines.join('\n')].join('\n')
 }