ts-procedures 8.5.0 → 9.0.0

package/src/implementations/http/README.md

@@ -1,390 +0,0 @@
-# HTTP Implementations
-
-HTTP implementation builders for `ts-procedures` that create type-safe, versioned endpoints with automatic path generation, schema-based validation, and route documentation.
-
-## Available Implementations
-
-| Framework | Subpath | Description |
-|-----------|---------|-------------|
-| HonoAppBuilder | `ts-procedures/hono` | Unified Hono builder — dispatches RPC, RPC streams, REST, and REST streams from one `register()` call. Works on Bun, Deno, Cloudflare Workers, and Node.js. |
-
-`HonoAppBuilder` is a unified builder: one builder, one `app`, one set of cross-cutting hooks. The procedure kind drives behavior — pick the creator that matches the shape you need.
-
-### Procedure kinds and which creator to use
-
-| Procedure kind | Created with | Config shape | Handler return | HTTP methods | Use case |
-|----------------|--------------|--------------|----------------|--------------|----------|
-| `rpc` | `Create()` | `RPCConfig` (`scope`, `version`) | `Promise<T>` | POST | Standard request/response |
-| `rpc-stream` | `CreateStream()` | `RPCConfig` | `AsyncGenerator<T>` | GET, POST | RPC-style streaming (SSE / text) |
-| `http` | `CreateHttp()` | `APIConfig` (`path`, `method`) | `Promise<T>` | GET, POST, PUT, DELETE, PATCH, HEAD | REST-style endpoint with `schema.req` channels |
-| `http-stream` | `CreateHttpStream()` | `APIConfig` | `AsyncGenerator<T>` | GET, POST | REST-style streaming endpoint |
-
-`HonoAppBuilder` accepts all four kinds from the same factory.
-
-## Core Concepts
-
-### Config Interfaces
-
-RPC and RPC-stream procedures share `RPCConfig`:
-
-```typescript
-interface RPCConfig {
-  scope: string | string[]  // Route path segment(s)
-  version: number           // API version number
-  errors?: string[]         // Optional taxonomy keys for typed-client narrowing
-}
-```
-
-REST-style procedures (`CreateHttp` / `CreateHttpStream`) use `APIConfig`:
-
-```typescript
-interface APIConfig {
-  path: string              // Route path with Hono params (e.g., '/users/:id')
-  method: HttpMethod        // 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head'
-  successStatus?: number    // Default: POST→201, DELETE→204, others→200
-  scope?: string            // Optional grouping for codegen file emission
-  errors?: string[]
-}
-```
-
-API routes use developer-defined paths — no auto-generation from scope/version.
-
-### Path Generation
-
-Routes are generated using kebab-case conversion:
-
-```
-/{pathPrefix}/{scope...}/{procedureName}/{version}
-```
-
-**Examples:**
-
-| Scope | Procedure Name | Version | Generated Path |
-|-------|----------------|---------|----------------|
-| `'users'` | `'Create'` | `1` | `/users/create/1` |
-| `'users'` | `'GetById'` | `1` | `/users/get-by-id/1` |
-| `['users', 'admin']` | `'List'` | `1` | `/users/admin/list/1` |
-| `['UserModule', 'permissions']` | `'Update'` | `2` | `/user-module/permissions/update/2` |
-
-**With pathPrefix `/api/v1`:**
-
-| Scope | Procedure Name | Version | Generated Path |
-|-------|----------------|---------|----------------|
-| `'users'` | `'Create'` | `1` | `/api/v1/users/create/1` |
-| `['users', 'admin']` | `'Delete'` | `2` | `/api/v1/users/admin/delete/2` |
-
-### Context Resolution
-
-The `factoryContext` parameter supports three patterns:
-
-```typescript
-// 1. Static object
-builder.register(Factory, { userId: 'static-123' })
-
-// 2. Sync function
-builder.register(Factory, (c) => ({
-  userId: c.req.header('x-user-id')
-}))
-
-// 3. Async function
-builder.register(Factory, async (c) => {
-  const user = await validateToken(c.req.header('authorization'))
-  return { userId: user.id }
-})
-```
-
-### Abort Signal
-
-All HTTP implementations automatically inject an `AbortSignal` into the handler context as `ctx.signal`. This signal aborts when the client disconnects, enabling handlers to cancel in-flight work (fetch calls, database queries, etc.).
-
-| Framework | Procedure kind | Signal source | Behavior |
-|-----------|---------------|---------------|----------|
-| HonoAppBuilder | `rpc`, `http` | `c.req.raw.signal` | Web standard Request signal |
-| HonoAppBuilder | `rpc-stream`, `http-stream` | `c.req.raw.signal` | Combined with internal stream AbortController via `AbortSignal.any()` |
-
-For streaming procedures, `signal.reason` is `'stream-completed'` on normal completion, allowing handlers to distinguish from client disconnection.
-
-### Error Handling
-
-Both builders support two peer error-handling modes — **declarative** (`errors` taxonomy + `unknownError`) and **imperative** (`onError` callback) — plus a cross-cutting `onRequestError` observer for logging, tracing, and metrics.
-
-Full spec (taxonomy shape, `toResponse`/`onCatch`/`match`, per-route narrowing, mid-stream caveats): **[docs/http-integrations.md § Error Handling](../../../docs/http-integrations.md#error-handling)**.
-
-### Lifecycle Hooks
-
-`HonoAppBuilder`'s config is **stratified**: cross-cutting hooks live at the top level, kind-specific hooks live inside `rpc:`, `api:`, and `stream:` blocks.
-
-```typescript
-new HonoAppBuilder({
-  // Cross-cutting (every kind)
-  onRequestStart, onRequestEnd, onRequestError,
-  errors, unknownError, onError,
-
-  // Kind-specific blocks
-  rpc:    { onSuccess },
-  api:    { queryParser, onSuccess },
-  stream: { defaultStreamMode, onStreamStart, onStreamEnd, onMidStreamError },
-})
-```
-
-**Non-streaming flow (`rpc`, `http`):**
-
-```
-onRequestStart → handler → onSuccess → onRequestEnd
-                    ↓
-              (on error)
-                    ↓
-            onRequestError (observer)
-                    ↓
-        errors taxonomy / onError fallback
-                    ↓
-              onRequestEnd
-```
-
-**Streaming flow (`rpc-stream`, `http-stream`):**
-
-```
-onRequestStart → onStreamStart → [yields...] → onStreamEnd → onRequestEnd
-                      ↓
-                 (on error)
-                      ↓
-   ┌──────────────────┴──────────────────┐
-   ↓ (pre-stream — before onStreamStart) ↓ (mid-stream — after first yield)
-errors taxonomy / onError → onRequestEnd  onMidStreamError → onStreamEnd → onRequestEnd
-```
-
-Pre-stream errors short-circuit before `onStreamStart` fires, so `onStreamEnd` does **not** run on that path. Mid-stream errors run `onMidStreamError` and then still fire `onStreamEnd` because the stream had already started.
-
-| Hook | Config block | Triggers on |
-|------|--------------|-------------|
-| `onRequestStart` | top-level | Before route handler (every kind) |
-| `onRequestEnd` | top-level | After response sent (every kind) |
-| `onRequestError` | top-level | Cross-cutting observer — fires for every caught error before dispatch |
-| `onError` | top-level | Imperative pre-stream error callback — peer of `errors` taxonomy |
-| `errors` / `unknownError` | top-level | Declarative taxonomy dispatch |
-| `rpc.onSuccess` | `rpc:` | After successful RPC handler |
-| `api.onSuccess` | `api:` | After successful HTTP handler |
-| `api.queryParser` | `api:` | Custom query-string parser for HTTP routes |
-| `stream.defaultStreamMode` | `stream:` | Default mode (`'sse'` \| `'text'`) for both stream kinds |
-| `stream.onStreamStart` | `stream:` | Before first yield |
-| `stream.onStreamEnd` | `stream:` | After stream completes |
-| `stream.onMidStreamError` | `stream:` | On mid-stream error (generator throws after first yield) |
-
-### Route Documentation
-
-Each registered procedure generates documentation accessible via `builder.docs`. Every doc carries a `kind` discriminant for reliable narrowing.
-
-**RPC (`RPCHttpRouteDoc`, `kind: 'rpc'`):**
-
-```typescript
-interface RPCHttpRouteDoc {
-  kind: 'rpc'
-  name: string
-  path: string
-  method: 'post'
-  scope: string | string[]
-  version: number
-  errors?: string[]
-  jsonSchema: {
-    body?: object      // From schema.params
-    response?: object  // From schema.returnType
-  }
-}
-```
-
-**RPC stream (`StreamHttpRouteDoc`, `kind: 'stream'`):**
-
-```typescript
-interface StreamHttpRouteDoc {
-  kind: 'stream'
-  name: string
-  path: string
-  methods: ('get' | 'post')[]
-  streamMode: 'sse' | 'text'
-  scope: string | string[]
-  version: number
-  errors?: string[]
-  jsonSchema: {
-    params?: object     // From schema.params
-    yieldType?: object  // From schema.yieldType
-    returnType?: object // From schema.returnType
-  }
-}
-```
-
-**REST (`APIHttpRouteDoc`, `kind: 'api'`):**
-
-```typescript
-interface APIHttpRouteDoc {
-  kind: 'api'
-  name: string
-  scope?: string
-  path: string
-  method: HttpMethod
-  fullPath: string           // Includes pathPrefix
-  successStatus?: number
-  errors?: string[]
-  jsonSchema: {
-    req?: {
-      pathParams?: object    // From schema.req.pathParams
-      query?: object         // From schema.req.query
-      body?: object          // From schema.req.body
-      headers?: object       // From schema.req.headers
-    }
-    res?: {
-      body?: object           // From schema.res.body
-      headers?: object        // From schema.res.headers
-    }
-  }
-}
-```
-
-**REST stream (`HttpStreamRouteDoc`, `kind: 'http-stream'`):**
-
-```typescript
-interface HttpStreamRouteDoc {
-  kind: 'http-stream'
-  name: string
-  scope?: string
-  path: string
-  method: HttpMethod
-  fullPath: string
-  streamMode: 'sse' | 'text'
-  errors?: string[]
-  jsonSchema: {
-    req?: {
-      pathParams?: object
-      query?: object
-      body?: object
-      headers?: object
-    }
-    res?: { headers?: object }
-    yield?: object
-    returnType?: object
-  }
-}
-```
-
-### Builder Pattern
-
-Both builders follow the same pattern:
-
-```typescript
-const builder = new HonoAppBuilder(config)
-  .register(PublicFactory, publicContextResolver)
-  .register(ProtectedFactory, protectedContextResolver)
-
-const app = builder.build()
-const docs = builder.docs
-```
-
-`build()` is synchronous — it returns the framework app instance directly. Don't `await` the call.
-
-A single `HonoAppBuilder` registers procedures of every kind from the same factory and mounts them on one Hono `app`. The optional `app?: Hono` config lets you mount onto an existing Hono instance that already has custom middleware, health checks, or static routes; if omitted, the builder constructs its own.
-
-**Key methods:**
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `register(factory, context, options?)` | `this` | Register a procedure factory |
-| `build()` | Framework app | Create routes and return the application |
-
-**Properties:**
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `app` | Framework app | The underlying framework application |
-| `docs` | Route doc array | Route documentation, lazily computed on first read; `build()` also populates it. |
-
-### DocRegistry
-
-For single-builder apps, prefer `builder.toDocEnvelope({ basePath, errors })` — it wraps `DocRegistry` for the common case and produces an envelope identical to the multi-app aggregator.
-
-For multi-app aggregation (e.g., two `HonoAppBuilder` instances mounted on different prefixes), `DocRegistry` composes route documentation from every source into one typed envelope:
-
-```typescript
-import { DocRegistry } from 'ts-procedures/http-docs'
-
-const docs = new DocRegistry({
-  basePath: '/api',
-  errors: appErrors,  // your ErrorTaxonomy — framework defaults auto-merged and deduped
-})
-  .from(builderA)
-  .from(builderB)
-
-app.get('/docs', (c) => c.json(docs.toJSON()))
-```
-
-- `from()` stores a reference — routes are read lazily at `toJSON()` time
-- `toJSON()` supports optional `filter` and `transform` options
-- `errors` accepts an `ErrorTaxonomy` or raw `ErrorDoc[]`; framework defaults are auto-merged (opt out via `includeDefaults: false`)
-- Every builder satisfies the `DocSource` interface (`{ readonly docs: AnyHttpRouteDoc[] }`)
-
-### Client Code Generation
-
-Generate type-safe client SDKs from your DocRegistry output. The codegen reads the `DocEnvelope` JSON and produces per-scope TypeScript files with typed params, response types, and callable functions.
-
-**Requirements:** every route needs a `scope` field for file grouping. RPC and stream routes carry `scope` via `RPCConfig`. REST routes (`CreateHttp` / `CreateHttpStream`) carry an optional `scope` directly on the procedure config:
-
-```typescript
-procs.CreateHttp('GetUser', {
-  path: '/users/:id',
-  method: 'get',
-  scope: 'users', // Used for codegen file grouping
-  schema: { req: { pathParams: Type.Object({ id: Type.String() }) } },
-}, async (_, { pathParams }) => /* ... */)
-```
-
-**Route-doc kinds and how the codegen consumes them:**
-
-| Doc kind | Source procedure | Params shape in generated callable | Generated callable |
-|----------|------------------|------------------------------------|--------------------|
-| `rpc` | `Create()` | `jsonSchema.body` → flat params | `client.call()` |
-| `api` | `CreateHttp()` | `jsonSchema.req.{pathParams,query,body,headers}` → structured params | `client.call()` |
-| `stream` | `CreateStream()` | `jsonSchema.params` → flat params | `client.stream()` |
-| `http-stream` | `CreateHttpStream()` | `jsonSchema.req.{pathParams,query,body,headers}` → structured params | `client.stream()` |
-
-**SSE return values:** Stream procedures that return a value have it sent as `event: 'return'` SSE message. The client's `TypedStream.result` promise resolves with this value.
-
-**SSE yieldType unwrapping:** Codegen detects the SSE envelope in `yieldType` and uses the inner `data` schema for the generated `Yield` type.
-
-**Kind discriminant:** All route docs include a `kind` field (`'rpc' | 'api' | 'stream' | 'http-stream'`) for reliable type narrowing in the codegen pipeline and consumer code.
-
-**Namespace types:** Use `--namespace-types` to wrap generated types in nested TS namespaces (`Scope.Route.Params`) instead of flat prefixed exports (`RouteParams`).
-
-**ajsc options:** `--enum-style`, `--depluralize`, `--array-item-naming`, `--uncountable-words` are passed through to the ajsc TypescriptConverter for JSON Schema → TypeScript conversion.
-
-**Self-contained mode:** Use `--self-contained` to emit `_types.ts` (all client type definitions) and `_client.ts` (runtime: `createClient`, `createFetchAdapter`, hooks, errors) into the output directory. All scope files and `index.ts` will import from `./_types` instead of `ts-procedures/client`, so consumers have no runtime dependency on `ts-procedures`. With this flag, `ts-procedures` can be a devDependency only.
-
-**Clean output directory:** Use `--clean-out-dir` (or `cleanOutDir: true` in the programmatic API) to recursively remove the output directory before writing, so scope files left over from deleted or renamed scopes are pruned. Skipped under `--dry-run`.
-
-## TypeScript Types
-
-```typescript
-import type {
-  RPCConfig,
-  RPCHttpRouteDoc,
-  StreamHttpRouteDoc,
-  HttpStreamRouteDoc,
-  StreamMode,
-  APIConfig,
-  APIHttpRouteDoc,
-  APIInput,
-  HttpMethod,
-} from 'ts-procedures/http'
-
-// Client Runtime
-import { createClient, createFetchAdapter } from 'ts-procedures/client'
-import type {
-  ClientAdapter,
-  ClientHooks,
-  TypedStream,
-  ClientInstance,
-  ProcedureCallDefaults,
-  ProcedureCallOptions,
-  RequestMeta,
-} from 'ts-procedures/client'
-
-// Code Generation (build-time only)
-import { generateClient } from 'ts-procedures/codegen'
-```

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

@@ -1,283 +0,0 @@
-import { describe, expect, test, vi } from 'vitest'
-import { Hono } from 'hono'
-import { dispatchMidStreamError, dispatchPreStreamError } from './error-dispatch.js'
-import { defineErrorTaxonomy } from './error-taxonomy.js'
-import { ProcedureValidationError } from '../../errors.js'
-
-function makeContext() {
-  return new Promise<import('hono').Context>((resolve) => {
-    const app = new Hono()
-    app.get('/', (c) => {
-      resolve(c)
-      return c.text('ok')
-    })
-    app.request('/')
-  })
-}
-
-const dummyProcedure = {
-  name: 'Test',
-  kind: 'rpc',
-  config: { scope: 'test', version: 1 },
-  handler: async () => undefined,
-} as any
-
-describe('dispatchPreStreamError', () => {
-  test('default taxonomy: ProcedureValidationError → 400', async () => {
-    const c = await makeContext()
-    const err = new ProcedureValidationError('Test', 'Validation error for Test', [
-      { instancePath: '/x', message: 'expected number' } as any,
-    ])
-
-    const res = await dispatchPreStreamError({
-      err,
-      procedure: dummyProcedure,
-      raw: c,
-      cfg: {},
-    })
-
-    expect(res.status).toBe(400)
-    const body = await res.json()
-    expect(body.name).toBe('ProcedureValidationError')
-    expect(body.procedureName).toBe('Test')
-  })
-
-  test('user taxonomy entry takes precedence', async () => {
-    const c = await makeContext()
-    class MyError extends Error {
-      constructor(public reason: string) { super(reason) }
-    }
-    const errors = defineErrorTaxonomy({
-      MyError: { class: MyError, statusCode: 422, toResponse: (e) => ({ name: 'MyError', reason: e.reason }) },
-    })
-
-    const res = await dispatchPreStreamError({
-      err: new MyError('boom'),
-      procedure: dummyProcedure,
-      raw: c,
-      cfg: { errors },
-    })
-
-    expect(res.status).toBe(422)
-    expect(await res.json()).toEqual({ name: 'MyError', reason: 'boom' })
-  })
-
-  test('falls back to onError imperative callback', async () => {
-    const c = await makeContext()
-    const onError = vi.fn().mockResolvedValue(c.json({ ok: false }, 503))
-
-    const res = await dispatchPreStreamError({
-      err: new Error('unmatched'),
-      procedure: dummyProcedure,
-      raw: c,
-      cfg: { onError: (proc, raw, e) => onError(proc, raw, e) },
-    })
-
-    expect(onError).toHaveBeenCalled()
-    expect(res.status).toBe(503)
-  })
-
-  test('hard default 500 when nothing matches', async () => {
-    const c = await makeContext()
-    const res = await dispatchPreStreamError({
-      err: new Error('boom'),
-      procedure: dummyProcedure,
-      raw: c,
-      cfg: {},
-    })
-    expect(res.status).toBe(500)
-    expect(await res.json()).toEqual({ error: 'boom' })
-  })
-
-  test('onRequestError observer fires before dispatch and is awaited', async () => {
-    const c = await makeContext()
-    const calls: string[] = []
-    const onRequestError = vi.fn(async () => {
-      calls.push('observer')
-    })
-    const errors = defineErrorTaxonomy({
-      AnyError: {
-        match: (e): e is Error => e instanceof Error,
-        statusCode: 500,
-        toResponse: () => {
-          calls.push('toResponse')
-          return { name: 'AnyError' }
-        },
-      },
-    })
-
-    await dispatchPreStreamError({
-      err: new Error('x'),
-      procedure: dummyProcedure,
-      raw: c,
-      cfg: { errors, onRequestError },
-    })
-
-    expect(calls).toEqual(['observer', 'toResponse'])
-    expect(onRequestError).toHaveBeenCalledWith({ err: expect.any(Error), procedure: dummyProcedure, raw: c })
-  })
-
-  test('observer throw is swallowed and logged', async () => {
-    const c = await makeContext()
-    const consoleErr = vi.spyOn(console, 'error').mockImplementation(() => {})
-    const onRequestError = vi.fn(() => { throw new Error('observer broke') })
-
-    const res = await dispatchPreStreamError({
-      err: new Error('x'),
-      procedure: dummyProcedure,
-      raw: c,
-      cfg: { onRequestError },
-    })
-
-    expect(res.status).toBe(500)
-    expect(consoleErr).toHaveBeenCalled()
-    consoleErr.mockRestore()
-  })
-
-  test('taxonomy onCatch is fully awaited before the response body is written', async () => {
-    const c = await makeContext()
-    const calls: string[] = []
-    class HookedError extends Error {}
-    const errors = defineErrorTaxonomy({
-      HookedError: {
-        class: HookedError,
-        statusCode: 500,
-        toResponse: () => ({ name: 'HookedError' }),
-        onCatch: async () => {
-          // Awaiting an async setTimeout here means a non-awaiting dispatcher
-          // would write the response BEFORE this push runs. The order we capture
-          // in `calls` reveals which branch happened.
-          await new Promise<void>((resolve) => setTimeout(resolve, 5))
-          calls.push('oncatch-done')
-        },
-      },
-    })
-
-    // Spy on c.json: when the dispatcher writes the response, record where in
-    // the timeline it happened relative to onCatch's push.
-    const originalJson = c.json.bind(c) as (...args: any[]) => Response
-    const jsonSpy = vi.fn((...args: any[]) => {
-      calls.push('response-write')
-      return originalJson(...args)
-    })
-    ;(c as any).json = jsonSpy
-
-    const res = await dispatchPreStreamError({
-      err: new HookedError('boom'),
-      procedure: dummyProcedure,
-      raw: c,
-      cfg: { errors },
-    })
-
-    expect(res.status).toBe(500)
-    expect(jsonSpy).toHaveBeenCalledTimes(1)
-    // If the dispatcher awaits onCatch first, 'oncatch-done' precedes
-    // 'response-write'. Without the await, the order would be reversed
-    // (or 'oncatch-done' would land after the dispatcher returns).
-    expect(calls).toEqual(['oncatch-done', 'response-write'])
-  })
-})
-
-const streamProcedure = {
-  name: 'Tail',
-  kind: 'rpc-stream',
-  config: { scope: 'logs', version: 1 },
-  handler: async function* () {},
-} as any
-
-describe('dispatchMidStreamError', () => {
-  test('uses taxonomy body when configured', async () => {
-    const c = await makeContext()
-    class MidErr extends Error {}
-    const errors = defineErrorTaxonomy({
-      MidErr: { class: MidErr, statusCode: 500, toResponse: () => ({ name: 'MidErr', detail: 'x' }) },
-    })
-
-    const result = await dispatchMidStreamError({
-      err: new MidErr('mid'),
-      procedure: streamProcedure,
-      raw: c,
-      cfg: { errors },
-    })
-
-    expect(result.data).toEqual({ name: 'MidErr', detail: 'x' })
-    expect(result.sseEvent).toBe('error')
-    expect(result.runOnCatch).toBeTypeOf('function')
-  })
-
-  test('falls back to onMidStreamError', async () => {
-    const c = await makeContext()
-    const result = await dispatchMidStreamError({
-      err: new Error('boom'),
-      procedure: streamProcedure,
-      raw: c,
-      cfg: {
-        onMidStreamError: () => ({ data: { kind: 'fail', msg: 'boom' } }),
-      },
-    })
-
-    expect(result.data).toEqual({ kind: 'fail', msg: 'boom' })
-    expect(result.sseEvent).toBe('Tail') // procedure name override
-  })
-
-  test('hard default { error: msg } when nothing matches', async () => {
-    const c = await makeContext()
-    const result = await dispatchMidStreamError({
-      err: new Error('plain'),
-      procedure: streamProcedure,
-      raw: c,
-      cfg: {},
-    })
-
-    expect(result.data).toEqual({ error: 'plain' })
-    expect(result.sseEvent).toBe('error')
-  })
-
-  test('onRequestError observer fires before dispatch (mid-stream form)', async () => {
-    const c = await makeContext()
-    const onRequestError = vi.fn(async () => {})
-
-    await dispatchMidStreamError({
-      err: new Error('x'),
-      procedure: streamProcedure,
-      raw: c,
-      cfg: { onRequestError },
-    })
-
-    expect(onRequestError).toHaveBeenCalled()
-  })
-
-  test('returns a runOnCatch function that is invokable and awaits the taxonomy hook', async () => {
-    const c = await makeContext()
-    const calls: string[] = []
-    class StreamErr extends Error {}
-    const errors = defineErrorTaxonomy({
-      StreamErr: {
-        class: StreamErr,
-        statusCode: 500,
-        toResponse: () => ({ name: 'StreamErr' }),
-        onCatch: async () => {
-          await new Promise<void>((resolve) => setTimeout(resolve, 5))
-          calls.push('oncatch-done')
-        },
-      },
-    })
-
-    // Mid-stream contract: the dispatcher does NOT call runOnCatch itself —
-    // the caller (stream handler) decides when to invoke it. Verify the shape
-    // and that awaiting it actually awaits the hook.
-    const result = await dispatchMidStreamError({
-      err: new StreamErr('mid'),
-      procedure: streamProcedure,
-      raw: c,
-      cfg: { errors },
-    })
-
-    expect(result.runOnCatch).toBeTypeOf('function')
-    // Hook has not yet run — caller hasn't invoked it.
-    expect(calls).toEqual([])
-
-    await result.runOnCatch!()
-    expect(calls).toEqual(['oncatch-done'])
-  })
-})