ts-procedures 5.15.0 → 6.0.0

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

@@ -1,3 +1,35 @@
+// ── Request Metadata ─────────────────────────────────────
+
+/**
+ * Per-request metadata visible to adapters and hooks. Defined as an empty
+ * interface so consumers can augment it via TypeScript declaration merging
+ * to get end-to-end type safety for their own metadata fields.
+ *
+ * @example With a non-self-contained client:
+ * ```ts
+ * declare module 'ts-procedures/client' {
+ *   interface RequestMeta {
+ *     traceId?: string
+ *     priority?: 'high' | 'low'
+ *   }
+ * }
+ * ```
+ *
+ * @example With a self-contained (code-generated) client:
+ * ```ts
+ * declare module './generated/_types' {
+ *   interface RequestMeta {
+ *     traceId?: string
+ *   }
+ * }
+ * ```
+ *
+ * After augmentation, `request.meta.traceId` is typed everywhere — per-call
+ * options, hooks, and adapters.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface RequestMeta {}
+
 // ── Adapter ──────────────────────────────────────────────
 
 export interface ClientAdapter {
@@ -11,6 +43,11 @@ export interface AdapterRequest {
   headers?: Record<string, string>
   body?: unknown
   signal?: AbortSignal
+  /**
+   * Per-request metadata. Augment `RequestMeta` via declaration merging to
+   * type your own fields. See {@link RequestMeta}.
+   */
+  meta?: RequestMeta
 }
 
 export interface AdapterResponse {
@@ -23,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 ────────────────────────────────────────────────
@@ -81,14 +124,72 @@ export interface TypedStream<TYield, TReturn = void> extends AsyncIterable<TYiel
   result: Promise<TReturn>
 }
 
-// ── Client Instance ──────────────────────────────────────
+// ── Request Options ──────────────────────────────────────
+
+/**
+ * Request-level configuration that can be set as client-level defaults
+ * (via `CreateClientConfig.defaults`) or per-call (via `ProcedureCallOptions`).
+ *
+ * - `signal`: AbortSignal for cancellation. When both a default and per-call
+ *   signal are provided, they're combined — whichever aborts first wins.
+ * - `timeout`: Timeout in milliseconds. Combined with `signal` the same way.
+ *   A per-call `timeout: 0` disables an inherited default timeout.
+ * - `headers`: Extra headers merged into the request. Per-call keys win over
+ *   default keys. Still subject to further mutation by `onBeforeRequest` hooks.
+ * - `basePath`: Override the base path for this call. Per-call > default > config.
+ * - `meta`: Per-request metadata typed via the {@link RequestMeta} interface.
+ *   Merged shallowly (per-call keys win over default keys).
+ */
+export interface ProcedureCallDefaults {
+  signal?: AbortSignal
+  timeout?: number
+  headers?: Record<string, string>
+  basePath?: string
+  meta?: RequestMeta
+}
+
+/**
+ * Per-call options. Extends both `ProcedureCallDefaults` (request config) and
+ * `ClientHooks` (hooks), so a single options bag covers both concerns.
+ */
+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
+}
 
-export type ProcedureCallOptions = ClientHooks
+/**
+ * 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 {
   basePath: string
   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>
 }
@@ -100,4 +201,17 @@ export interface CreateClientConfig<TScopes> {
   basePath: string
   scopes: (client: ClientInstance) => TScopes
   hooks?: ClientHooks
+  /**
+   * Default request options applied to every call. Per-call options override
+   * these (except `signal`, which combines via AbortSignal.any — whichever
+   * 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 () => {
@@ -481,6 +486,157 @@ describe('E2E: generateClient full pipeline', () => {
         execSync(`${tscPath} --noEmit --project ${join(tmpDir, 'tsconfig.json')}`, { stdio: 'pipe' })
       }).not.toThrow()
     })
+
+    it('_types.ts exports RequestMeta (empty interface ready for augmentation)', async () => {
+      tmpDir = makeTmpDir()
+      await generateClient({ envelope, outDir: tmpDir, selfContained: true })
+
+      const content = readFileSync(join(tmpDir, '_types.ts'), 'utf-8')
+      expect(content).toContain('export interface RequestMeta')
+      // meta on AdapterRequest and ProcedureCallDefaults should be typed as RequestMeta
+      expect(content).toContain('meta?: RequestMeta')
+    })
+
+    it('developers can augment RequestMeta for typed per-call meta + typed hook/adapter access', async () => {
+      tmpDir = makeTmpDir()
+      await generateClient({ envelope, outDir: tmpDir, selfContained: true })
+
+      // Write a consumer file that augments RequestMeta, then uses typed meta
+      // end-to-end: per-call options, createClient defaults, onBeforeRequest, and adapter.
+      const consumer = `
+import { createClient } from './_client'
+import type { ClientAdapter } from './_types'
+import { createApiBindings } from './index'
+
+declare module './_types' {
+  interface RequestMeta {
+    traceId: string
+    priority?: 'high' | 'low'
+  }
+}
+
+const typedAdapter: ClientAdapter = {
+  async request(req) {
+    // req.meta is now typed
+    const trace: string | undefined = req.meta?.traceId
+    const pri: 'high' | 'low' | undefined = req.meta?.priority
+    void trace; void pri
+    return { status: 200, headers: {}, body: {} }
+  },
+  async stream(req) {
+    const trace: string | undefined = req.meta?.traceId
+    void trace
+    return { status: 200, headers: {}, body: (async function*() {})() }
+  },
+}
+
+const client = createClient({
+  adapter: typedAdapter,
+  basePath: 'https://api.example.com',
+  scopes: createApiBindings,
+  defaults: {
+    meta: { traceId: 'default-trace' }, // typed
+  },
+  hooks: {
+    onBeforeRequest(ctx) {
+      // ctx.request.meta is typed via declaration merging
+      const trace: string | undefined = ctx.request.meta?.traceId
+      void trace
+      return ctx
+    },
+  },
+})
+
+async function run(): Promise<void> {
+  // Per-call meta is typed — traceId is required, priority is optional
+  await client.users.GetUser(
+    { id: '1' },
+    { meta: { traceId: 'per-call-trace', priority: 'high' } },
+  )
+  // Timeout + signal + headers typecheck
+  await client.users.GetUser(
+    { id: '2' },
+    { timeout: 5000, headers: { 'X-Request-Id': 'abc' }, basePath: 'https://other' },
+  )
+}
+void run
+`
+      const { writeFileSync } = await import('node:fs')
+      writeFileSync(join(tmpDir, 'consumer.ts'), consumer)
+
+      const tsconfig = {
+        compilerOptions: {
+          strict: true,
+          target: 'ES2022',
+          module: 'ES2022',
+          moduleResolution: 'bundler',
+          noEmit: true,
+          skipLibCheck: true,
+        },
+        include: ['_types.ts', '_client.ts', 'index.ts', 'users.ts', 'events.ts', '_errors.ts', 'consumer.ts'],
+      }
+      writeFileSync(join(tmpDir, 'tsconfig.json'), JSON.stringify(tsconfig))
+
+      const { execSync } = await import('node:child_process')
+      const tscPath = join(process.cwd(), 'node_modules', '.bin', 'tsc')
+      expect(() => {
+        execSync(`${tscPath} --noEmit --project ${join(tmpDir, 'tsconfig.json')}`, { stdio: 'pipe' })
+      }).not.toThrow()
+    })
+
+    it('augmented RequestMeta rejects wrong types (compile error)', async () => {
+      tmpDir = makeTmpDir()
+      await generateClient({ envelope, outDir: tmpDir, selfContained: true })
+
+      // Passing a number for `traceId` (declared as string) should fail tsc
+      const consumer = `
+import { createClient, createFetchAdapter } from './_client'
+import { createApiBindings } from './index'
+// RequestMeta is imported only for augmentation below
+import type {} from './_types'
+
+declare module './_types' {
+  interface RequestMeta {
+    traceId: string
+  }
+}
+
+const client = createClient({
+  adapter: createFetchAdapter(),
+  basePath: 'https://api.example.com',
+  scopes: createApiBindings,
+})
+
+async function run(): Promise<void> {
+  // @ts-expect-error traceId must be string, not number
+  await client.users.GetUser({ id: '1' }, { meta: { traceId: 42 } })
+}
+void run
+`
+      const { writeFileSync } = await import('node:fs')
+      writeFileSync(join(tmpDir, 'consumer.ts'), consumer)
+
+      const tsconfig = {
+        compilerOptions: {
+          strict: true,
+          target: 'ES2022',
+          module: 'ES2022',
+          moduleResolution: 'bundler',
+          noEmit: true,
+          skipLibCheck: true,
+        },
+        include: ['_types.ts', '_client.ts', 'index.ts', 'users.ts', 'events.ts', '_errors.ts', 'consumer.ts'],
+      }
+      writeFileSync(join(tmpDir, 'tsconfig.json'), JSON.stringify(tsconfig))
+
+      const { execSync } = await import('node:child_process')
+      const tscPath = join(process.cwd(), 'node_modules', '.bin', 'tsc')
+      // With @ts-expect-error in place, tsc should pass; if RequestMeta wasn't
+      // enforcing the type, @ts-expect-error would fail because there'd be no error.
+      expect(() => {
+        execSync(`${tscPath} --noEmit --project ${join(tmpDir, 'tsconfig.json')}`, { stdio: 'pipe' })
+      }).not.toThrow()
+    })
   })
 
   // ── namespaceTypes mode ───────────────────────────────────────────────────

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

@@ -16,8 +16,13 @@ const TYPES_IMPORT = `import type {
   StreamDescriptor,
   TypedStream,
   ClientInstance,
+  ProcedureCallDefaults,
   ProcedureCallOptions,
   CreateClientConfig,
+  RequestMeta,
+  ErrorRegistry,
+  ErrorFactory,
+  ErrorResponseMeta,
 } from './_types'`
 
 /**
@@ -26,7 +31,9 @@ const TYPES_IMPORT = `import type {
  */
 const SOURCE_FILES = [
   'errors.ts',
+  'error-dispatch.ts',
   'request-builder.ts',
+  'resolve-options.ts',
   'hooks.ts',
   'call.ts',
   'stream.ts',