ts-procedures 5.16.0 → 6.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "5.16.0",
+  "version": "6.0.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",
@@ -12,7 +12,8 @@
   "scripts": {
     "build": "tsc",
     "lint": "npx eslint src/ --quiet",
-    "prepublishOnly": "npm run lint && npm run build",
+    "check-docs": "bash scripts/check-docs-consistency.sh",
+    "prepublishOnly": "npm run lint && npm run build && npm run check-docs",
     "postinstall": "node ./agent_config/bin/postinstall.mjs",
     "test": "vitest run"
   },
@@ -45,6 +46,10 @@
       "types": "./build/implementations/http/doc-registry.d.ts",
       "import": "./build/implementations/http/doc-registry.js"
     },
+    "./http-errors": {
+      "types": "./build/implementations/http/error-taxonomy.d.ts",
+      "import": "./build/implementations/http/error-taxonomy.js"
+    },
     "./client": {
       "types": "./build/client/index.d.ts",
       "import": "./build/client/index.js"

package/src/client/call.ts

@@ -2,10 +2,12 @@ import { buildAdapterRequest } from './request-builder.js'
 import { runBeforeRequest, runAfterResponse, runOnError } from './hooks.js'
 import { applyRequestOptions, resolveBasePath } from './resolve-options.js'
 import { ClientRequestError } from './errors.js'
+import { dispatchTypedError } from './error-dispatch.js'
 import type {
   ClientAdapter,
   ClientHooks,
   CallDescriptor,
+  ErrorRegistry,
   ProcedureCallDefaults,
   ProcedureCallOptions,
 } from './types.js'
@@ -17,6 +19,7 @@ export interface ExecuteCallConfig {
   hooks: ClientHooks
   defaults?: ProcedureCallDefaults
   options?: ProcedureCallOptions
+  errorRegistry?: ErrorRegistry
 }
 
 /**
@@ -33,7 +36,7 @@ export interface ExecuteCallConfig {
  * 8. Return response.body as TResponse
  */
 export async function executeCall<TResponse>(config: ExecuteCallConfig): Promise<TResponse> {
-  const { descriptor, basePath, adapter, hooks, defaults, options } = config
+  const { descriptor, basePath, adapter, hooks, defaults, options, errorRegistry } = config
 
   // 1. Build the initial request (path/query/body from descriptor)
   const resolvedBasePath = resolveBasePath(defaults, options, basePath)
@@ -73,6 +76,12 @@ export async function executeCall<TResponse>(config: ExecuteCallConfig): Promise
 
   // 7. Check status AFTER hooks (hooks may have swallowed the error by mutating status)
   if (response.status < 200 || response.status >= 300) {
+    const typed = dispatchTypedError(errorRegistry, response.body, {
+      status: response.status,
+      procedureName: descriptor.name,
+      scope: descriptor.scope,
+    })
+    if (typed) throw typed
     throw new ClientRequestError({
       status: response.status,
       headers: response.headers,

package/src/client/error-dispatch.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from 'vitest'
+import { dispatchTypedError } from './error-dispatch.js'
+import type { ErrorRegistry, ErrorResponseMeta } from './types.js'
+
+class SyntheticError extends Error {
+  constructor(
+    message: string,
+    readonly props: string[]
+  ) {
+    super(message)
+    this.name = 'SyntheticError'
+    Object.setPrototypeOf(this, SyntheticError.prototype)
+  }
+}
+
+const meta: ErrorResponseMeta = { status: 422, procedureName: 'Test', scope: 'users' }
+
+function makeRegistry(): ErrorRegistry {
+  return {
+    SyntheticError: {
+      fromResponse(body, m) {
+        const b = body as { message: string; props: string[] }
+        return new SyntheticError(b.message, b.props)
+      },
+    },
+  }
+}
+
+describe('dispatchTypedError', () => {
+  test('returns a typed error when body.name matches a registry key', () => {
+    const err = dispatchTypedError(
+      makeRegistry(),
+      { name: 'SyntheticError', message: 'bad', props: ['x'] },
+      meta
+    )
+    expect(err).toBeInstanceOf(SyntheticError)
+    expect(err).toBeInstanceOf(Error)
+    expect((err as SyntheticError).props).toEqual(['x'])
+  })
+
+  test('returns null when no registry is provided', () => {
+    const err = dispatchTypedError(undefined, { name: 'SyntheticError' }, meta)
+    expect(err).toBeNull()
+  })
+
+  test('returns null when body is not an object', () => {
+    expect(dispatchTypedError(makeRegistry(), 'oops', meta)).toBeNull()
+    expect(dispatchTypedError(makeRegistry(), null, meta)).toBeNull()
+    expect(dispatchTypedError(makeRegistry(), 42, meta)).toBeNull()
+  })
+
+  test('returns null when body.name is missing or not a string', () => {
+    expect(dispatchTypedError(makeRegistry(), {}, meta)).toBeNull()
+    expect(dispatchTypedError(makeRegistry(), { name: 123 }, meta)).toBeNull()
+  })
+
+  test('returns null when body.name does not match any registry key', () => {
+    expect(
+      dispatchTypedError(makeRegistry(), { name: 'UnregisteredError' }, meta)
+    ).toBeNull()
+  })
+
+  test('returns null when fromResponse returns a non-Error value', () => {
+    const registry: ErrorRegistry = {
+      Broken: {
+        // Intentionally returns a non-Error — defensive guard in dispatch.
+        fromResponse: () => 'not an error' as unknown as Error,
+      },
+    }
+    expect(dispatchTypedError(registry, { name: 'Broken' }, meta)).toBeNull()
+  })
+})

package/src/client/error-dispatch.ts

@@ -0,0 +1,27 @@
+import type { ErrorRegistry, ErrorResponseMeta } from './types.js'
+
+/**
+ * Attempts to construct a typed error from the response body using the
+ * registry. Returns `null` when:
+ *   - no registry is configured,
+ *   - the body is not a plain object with a `name` string,
+ *   - no registry key matches the body's `name`, or
+ *   - `fromResponse` returns a non-Error value (defensive — registry entries
+ *     are expected to return `Error` subclasses).
+ *
+ * Callers fall back to `ClientRequestError` when this returns `null`.
+ */
+export function dispatchTypedError(
+  registry: ErrorRegistry | undefined,
+  body: unknown,
+  meta: ErrorResponseMeta
+): Error | null {
+  if (!registry) return null
+  if (!body || typeof body !== 'object') return null
+  const name = (body as { name?: unknown }).name
+  if (typeof name !== 'string') return null
+  const factory = registry[name]
+  if (!factory?.fromResponse) return null
+  const result = factory.fromResponse(body, meta)
+  return result instanceof Error ? result : null
+}

package/src/client/fetch-adapter.ts

@@ -174,17 +174,23 @@ export function createFetchAdapter(config?: FetchAdapterConfig): ClientAdapter {
       })
 
       const headers = extractHeaders(response)
+      const emptyBody: AsyncIterable<unknown> = {
+        [Symbol.asyncIterator]: async function* () {},
+      }
+
+      // Non-2xx responses on a stream endpoint are JSON, not SSE. Parse the
+      // body eagerly and surface it via errorBody so the client can dispatch
+      // a typed error (or fall back to ClientRequestError with a real body).
+      if (response.status < 200 || response.status >= 300) {
+        const errorBody = await parseResponseBody(response)
+        return { status: response.status, headers, body: emptyBody, errorBody }
+      }
 
       if (!response.body) {
-        // No body — return an empty async iterable
-        const emptyBody: AsyncIterable<unknown> = {
-          [Symbol.asyncIterator]: async function* () {},
-        }
         return { status: response.status, headers, body: emptyBody }
       }
 
       const body = parseSseStream(response.body as ReadableStream<Uint8Array>)
-
       return { status: response.status, headers, body }
     },
   }

package/src/client/index.ts

@@ -30,6 +30,7 @@ export function createClient<TScopes>(config: CreateClientConfig<TScopes>): TSco
     basePath,
     hooks: globalHooks = {},
     defaults: globalDefaults = {},
+    errorRegistry,
     scopes,
   } = config
 
@@ -38,6 +39,7 @@ export function createClient<TScopes>(config: CreateClientConfig<TScopes>): TSco
     adapter,
     hooks: globalHooks,
     defaults: globalDefaults,
+    errorRegistry,
 
     call<TResponse>(
       descriptor: CallDescriptor,
@@ -50,6 +52,7 @@ export function createClient<TScopes>(config: CreateClientConfig<TScopes>): TSco
         hooks: globalHooks,
         defaults: globalDefaults,
         options,
+        errorRegistry,
       })
     },
 
@@ -79,6 +82,7 @@ export function createClient<TScopes>(config: CreateClientConfig<TScopes>): TSco
             hooks: globalHooks,
             defaults: globalDefaults,
             options,
+            errorRegistry,
           })
         } catch (err) {
           rejectResult(err)
@@ -126,8 +130,13 @@ export type {
   ProcedureCallOptions,
   CreateClientConfig,
   RequestMeta,
+  ErrorRegistry,
+  ErrorFactory,
+  ErrorResponseMeta,
 } from './types.js'
 
+export { dispatchTypedError } from './error-dispatch.js'
+
 export { ClientRequestError, ClientPathParamError, ClientStreamError } from './errors.js'
 
 export { createTypedStream } from './stream.js'

package/src/client/stream.ts

@@ -2,9 +2,11 @@ import { buildAdapterRequest } from './request-builder.js'
 import { runBeforeRequest, runAfterResponse, runOnError } from './hooks.js'
 import { applyRequestOptions, resolveBasePath } from './resolve-options.js'
 import { ClientRequestError } from './errors.js'
+import { dispatchTypedError } from './error-dispatch.js'
 import type {
   ClientAdapter,
   ClientHooks,
+  ErrorRegistry,
   StreamDescriptor,
   TypedStream,
   AdapterResponse,
@@ -100,6 +102,7 @@ export interface ExecuteStreamConfig {
   hooks: ClientHooks
   defaults?: ProcedureCallDefaults
   options?: ProcedureCallOptions
+  errorRegistry?: ErrorRegistry
 }
 
 /**
@@ -118,7 +121,7 @@ export interface ExecuteStreamConfig {
 export async function executeStream<TYield, TReturn = void>(
   config: ExecuteStreamConfig,
 ): Promise<TypedStream<TYield, TReturn>> {
-  const { descriptor, basePath, adapter, hooks, defaults, options } = config
+  const { descriptor, basePath, adapter, hooks, defaults, options, errorRegistry } = config
 
   // 1. Build the initial request
   const resolvedBasePath = resolveBasePath(defaults, options, basePath)
@@ -149,11 +152,13 @@ export async function executeStream<TYield, TReturn = void>(
     throw err
   }
 
-  // Build an AdapterResponse shape for the hooks (body is null for streams at this point)
+  // Build an AdapterResponse shape for the hooks. For success the body is null
+  // (the actual data flows through the async iterable); for non-2xx the adapter
+  // eagerly parses the JSON response body and surfaces it via `errorBody`.
   const responseForHooks: AdapterResponse = {
     status: streamResponse.status,
     headers: streamResponse.headers,
-    body: null,
+    body: streamResponse.errorBody ?? null,
   }
 
   // 6. Run after-response hooks immediately (before iteration)
@@ -165,6 +170,12 @@ export async function executeStream<TYield, TReturn = void>(
 
   // 7. Check status after hooks (hooks may mutate responseForHooks.status)
   if (responseForHooks.status < 200 || responseForHooks.status >= 300) {
+    const typed = dispatchTypedError(errorRegistry, responseForHooks.body, {
+      status: responseForHooks.status,
+      procedureName: descriptor.name,
+      scope: descriptor.scope,
+    })
+    if (typed) throw typed
     throw new ClientRequestError({
       status: responseForHooks.status,
       headers: responseForHooks.headers,

package/src/client/typed-error-dispatch.test.ts

@@ -0,0 +1,211 @@
+/* eslint-disable @typescript-eslint/no-empty-object-type */
+import { describe, expect, test } from 'vitest'
+import { Type } from 'typebox'
+import { Procedures } from '../index.js'
+import { APIConfig } from '../implementations/types.js'
+import { HonoAPIAppBuilder, defineErrorTaxonomy } from '../implementations/http/hono-api/index.js'
+import { createClient } from './index.js'
+import { ClientRequestError } from './errors.js'
+import type { ClientAdapter, ErrorRegistry } from './types.js'
+
+// ---------------------------------------------------------------------------
+// Error taxonomy + simulated generated error classes
+// ---------------------------------------------------------------------------
+
+class UseCaseError extends Error {
+  constructor(
+    readonly externalMsg: string,
+    readonly internalMsg: string
+  ) {
+    super(externalMsg)
+    this.name = 'UseCaseError'
+    Object.setPrototypeOf(this, UseCaseError.prototype)
+  }
+}
+
+const appErrors = defineErrorTaxonomy({
+  UseCaseError: {
+    class: UseCaseError,
+    statusCode: 422,
+    toResponse: (err) => ({ message: err.externalMsg }),
+  },
+})
+
+// Simulates what the codegen emits: a runtime class + a registry entry the
+// client uses for dispatch. In real usage this comes from the generated
+// `_errors.ts`; here we inline it to test the client-side dispatch path end
+// to end without invoking the codegen pipeline.
+class ApiUseCaseError extends Error {
+  readonly status: number
+  readonly procedureName: string
+  readonly scope: string
+  readonly body: { name: 'UseCaseError'; message: string }
+  constructor(args: {
+    message: string
+    status: number
+    procedureName: string
+    scope: string
+    body: { name: 'UseCaseError'; message: string }
+  }) {
+    super(args.message)
+    this.name = 'UseCaseError'
+    this.status = args.status
+    this.procedureName = args.procedureName
+    this.scope = args.scope
+    this.body = args.body
+    Object.setPrototypeOf(this, ApiUseCaseError.prototype)
+  }
+
+  static fromResponse(
+    body: unknown,
+    meta: { status: number; procedureName: string; scope: string }
+  ): ApiUseCaseError {
+    const b = body as { name: 'UseCaseError'; message: string }
+    return new ApiUseCaseError({
+      message: b.message,
+      status: meta.status,
+      procedureName: meta.procedureName,
+      scope: meta.scope,
+      body: b,
+    })
+  }
+}
+
+const errorRegistry: ErrorRegistry = { UseCaseError: ApiUseCaseError }
+
+// ---------------------------------------------------------------------------
+// Tiny adapter that routes through the in-memory Hono app (no real network)
+// ---------------------------------------------------------------------------
+
+interface HonoAppLike {
+  request(
+    url: string,
+    init: { method?: string; headers?: Record<string, string>; body?: string }
+  ): Response | Promise<Response>
+}
+
+function honoAdapter(app: HonoAppLike): ClientAdapter {
+  return {
+    async request(req) {
+      const res = await Promise.resolve(
+        app.request(req.url, {
+          method: req.method,
+          headers: req.headers,
+          body: req.body !== undefined ? JSON.stringify(req.body) : undefined,
+        })
+      )
+      const headers: Record<string, string> = {}
+      res.headers.forEach((v, k) => (headers[k] = v))
+      const body = await res.json().catch(() => null)
+      return { status: res.status, headers, body }
+    },
+    async stream() {
+      throw new Error('not used')
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('typed error dispatch — end-to-end', () => {
+  function buildApp() {
+    const API = Procedures<{}, APIConfig>()
+    API.Create(
+      'GetUser',
+      {
+        path: '/users/:id',
+        method: 'get',
+        schema: {
+          input: { pathParams: Type.Object({ id: Type.String() }) },
+          returnType: Type.Object({ id: Type.String() }),
+        },
+      },
+      async (_ctx, { pathParams }) => {
+        if (pathParams.id === 'missing') {
+          throw new UseCaseError('User not found', `no user with id=${pathParams.id}`)
+        }
+        return { id: pathParams.id }
+      }
+    )
+    return new HonoAPIAppBuilder({ errors: appErrors }).register(API, () => ({})).build()
+  }
+
+  test('server-thrown UseCaseError arrives on client as a typed class instance', async () => {
+    const app = buildApp()
+    const api = createClient({
+      adapter: honoAdapter(app),
+      basePath: '',
+      errorRegistry,
+      scopes: (client) => ({
+        getUser: (id: string) =>
+          client.call<{ id: string }>({
+            name: 'GetUser',
+            scope: 'users',
+            path: '/users/:id',
+            method: 'get',
+            kind: 'api',
+            params: { pathParams: { id } },
+          }),
+      }),
+    })
+
+    await expect(api.getUser('missing')).rejects.toBeInstanceOf(ApiUseCaseError)
+    try {
+      await api.getUser('missing')
+    } catch (err) {
+      expect(err).toBeInstanceOf(ApiUseCaseError)
+      expect(err).toBeInstanceOf(Error)
+      expect((err as ApiUseCaseError).status).toBe(422)
+      expect((err as ApiUseCaseError).procedureName).toBe('GetUser')
+      expect((err as ApiUseCaseError).message).toBe('User not found')
+      expect((err as ApiUseCaseError).body.name).toBe('UseCaseError')
+    }
+  })
+
+  test('unregistered error body falls back to ClientRequestError', async () => {
+    const app = buildApp()
+    // Omit the registry so dispatch can't match; client sees the raw
+    // transport error instead of a typed class.
+    const api = createClient({
+      adapter: honoAdapter(app),
+      basePath: '',
+      scopes: (client) => ({
+        getUser: (id: string) =>
+          client.call<{ id: string }>({
+            name: 'GetUser',
+            scope: 'users',
+            path: '/users/:id',
+            method: 'get',
+            kind: 'api',
+            params: { pathParams: { id } },
+          }),
+      }),
+    })
+
+    await expect(api.getUser('missing')).rejects.toBeInstanceOf(ClientRequestError)
+  })
+
+  test('success responses are not disturbed by dispatch logic', async () => {
+    const app = buildApp()
+    const api = createClient({
+      adapter: honoAdapter(app),
+      basePath: '',
+      errorRegistry,
+      scopes: (client) => ({
+        getUser: (id: string) =>
+          client.call<{ id: string }>({
+            name: 'GetUser',
+            scope: 'users',
+            path: '/users/:id',
+            method: 'get',
+            kind: 'api',
+            params: { pathParams: { id } },
+          }),
+      }),
+    })
+
+    await expect(api.getUser('u_42')).resolves.toEqual({ id: 'u_42' })
+  })
+})

package/src/client/types.ts

@@ -60,6 +60,12 @@ export interface AdapterStreamResponse {
   status: number
   headers: Record<string, string>
   body: AsyncIterable<unknown>
+  /**
+   * Populated when `status` is non-2xx — the parsed response body. Surfaced so
+   * `executeStream` can dispatch typed errors via the error registry instead
+   * of always falling back to `ClientRequestError` with `body: null`.
+   */
+  errorBody?: unknown
 }
 
 // ── Hooks ────────────────────────────────────────────────
@@ -148,6 +154,33 @@ export interface ProcedureCallDefaults {
  */
 export interface ProcedureCallOptions extends ProcedureCallDefaults, ClientHooks {}
 
+// ── Error Registry ───────────────────────────────────────
+
+/**
+ * Metadata attached to a typed error at construction. Supplies the transport
+ * context (status, procedure, scope) that isn't part of the response body.
+ */
+export interface ErrorResponseMeta {
+  status: number
+  procedureName: string
+  scope: string
+}
+
+/**
+ * A factory for a typed error class — constructed from the response body plus
+ * transport metadata. Generated error classes expose this as a static method.
+ */
+export interface ErrorFactory {
+  fromResponse(body: unknown, meta: ErrorResponseMeta): Error
+}
+
+/**
+ * Maps `body.name` values (taxonomy keys) to error class factories. When the
+ * client sees a non-2xx response whose body has a `name` matching a registry
+ * entry, it throws the typed error instead of a generic `ClientRequestError`.
+ */
+export type ErrorRegistry = Record<string, ErrorFactory>
+
 // ── Client Instance ──────────────────────────────────────
 
 export interface ClientInstance {
@@ -155,6 +188,8 @@ export interface ClientInstance {
   adapter: ClientAdapter
   hooks: ClientHooks
   defaults: ProcedureCallDefaults
+  /** Optional registry for runtime dispatch of typed errors by `body.name`. */
+  errorRegistry?: ErrorRegistry
   call<TResponse>(descriptor: CallDescriptor, options?: ProcedureCallOptions): Promise<TResponse>
   stream<TYield, TReturn>(descriptor: StreamDescriptor, options?: ProcedureCallOptions): TypedStream<TYield, TReturn>
 }
@@ -172,4 +207,11 @@ export interface CreateClientConfig<TScopes> {
    * fires first cancels the request).
    */
   defaults?: ProcedureCallDefaults
+  /**
+   * Optional error-dispatch registry. When a non-2xx response body has a
+   * `name` field matching a registry key, the client throws the typed error
+   * constructed via that entry's `fromResponse`. When absent or when no key
+   * matches, falls back to `ClientRequestError` (transport error shape).
+   */
+  errorRegistry?: ErrorRegistry
 }

package/src/codegen/e2e.test.ts

@@ -339,12 +339,13 @@ describe('E2E: generateClient full pipeline', () => {
     expect(existsSync(join(tmpDir, '_errors.ts'))).toBe(true)
   })
 
-  it('_errors.ts contains ProcedureError type', async () => {
+  it('_errors.ts contains a runtime class for ProcedureError', async () => {
     tmpDir = makeTmpDir()
     await generateClient({ envelope, outDir: tmpDir })
 
     const content = readFileSync(join(tmpDir, '_errors.ts'), 'utf-8')
-    expect(content).toContain('export type ProcedureError =')
+    expect(content).toContain('export class ProcedureError')
+    expect(content).toContain('static fromResponse(')
   })
 
   it('_errors.ts contains the service-prefixed ProcedureErrorUnion', async () => {
@@ -357,12 +358,16 @@ describe('E2E: generateClient full pipeline', () => {
     expect(content).toContain('ProcedureValidationError')
   })
 
-  it('index.ts does not import _errors when namespaceTypes is off', async () => {
+  it('index.ts imports the _errors registry as a runtime value when errors are present', async () => {
+    // PR 3 change: the error registry is imported as a value (not `import
+    // type`) so `createApiClient` can wire it into `createClient` regardless
+    // of `namespaceTypes`.
     tmpDir = makeTmpDir()
     await generateClient({ envelope, outDir: tmpDir })
 
     const content = readFileSync(join(tmpDir, 'index.ts'), 'utf-8')
-    expect(content).not.toContain("from './_errors'")
+    expect(content).toContain("import * as _errorsModule from './_errors'")
+    expect(content).toContain('errorRegistry: _errorsModule.ApiErrorRegistry')
   })
 
   it('index.ts folds errors into the service namespace when namespaceTypes is on', async () => {

package/src/codegen/emit-client-runtime.ts

@@ -20,6 +20,9 @@ const TYPES_IMPORT = `import type {
   ProcedureCallOptions,
   CreateClientConfig,
   RequestMeta,
+  ErrorRegistry,
+  ErrorFactory,
+  ErrorResponseMeta,
 } from './_types'`
 
 /**
@@ -28,6 +31,7 @@ const TYPES_IMPORT = `import type {
  */
 const SOURCE_FILES = [
   'errors.ts',
+  'error-dispatch.ts',
   'request-builder.ts',
   'resolve-options.ts',
   'hooks.ts',