ts-procedures 7.1.0 → 7.1.1

package/src/implementations/http/hono-stream/error-taxonomy.test.ts

@@ -96,3 +96,83 @@ describe('HonoStreamAppBuilder — error taxonomy (pre-stream)', () => {
     expect(await res.json()).toEqual({ name: 'ServiceUnavailable' })
   })
 })
+
+describe('HonoStreamAppBuilder — error taxonomy (mid-stream)', () => {
+  test('taxonomy resolves the body for a typed error thrown mid-stream (SSE)', async () => {
+    const errors = defineErrorTaxonomy({
+      AuthError: {
+        class: AuthError,
+        statusCode: 403,
+        toResponse: (err) => ({ name: 'AuthError', reason: err.reason }),
+      },
+    })
+    const RPC = Procedures<{}, RPCConfig>()
+    RPC.CreateStream('Stream', { scope: 'test', version: 1 }, async function* () {
+      yield { msg: 'first' }
+      throw new AuthError('forbidden')
+    })
+
+    const app = new HonoStreamAppBuilder({ errors })
+      .register(RPC, () => ({}))
+      .build()
+
+    const res = await app.request('/test/stream/1', { method: 'POST' })
+    expect(res.status).toBe(200) // status committed before error
+    const text = await res.text()
+    // Last event is the error event with the resolved body shape
+    expect(text).toContain('event: error')
+    expect(text).toContain('"name":"AuthError"')
+    expect(text).toContain('"reason":"forbidden"')
+  })
+
+  test('onMidStreamError still runs as fallback when taxonomy does not match', async () => {
+    const RPC = Procedures<{}, RPCConfig>()
+    RPC.CreateStream('Stream', { scope: 'test', version: 1 }, async function* () {
+      yield { msg: 'first' }
+      throw new TypeError('mid-stream boom')
+    })
+
+    const app = new HonoStreamAppBuilder({
+      errors: {
+        AuthError: {
+          class: AuthError,
+          statusCode: 403,
+          toResponse: () => ({ name: 'AuthError', reason: 'forbidden' }),
+        },
+      },
+      onMidStreamError: (_p, _c, err) => ({ data: { name: 'FallbackError', message: err.message } }),
+    })
+      .register(RPC, () => ({}))
+      .build()
+
+    const res = await app.request('/test/stream/1', { method: 'POST' })
+    const text = await res.text()
+    expect(text).toContain('"name":"FallbackError"')
+    expect(text).toContain('mid-stream boom')
+  })
+
+  test('mid-stream typed body falls through to text mode', async () => {
+    const RPC = Procedures<{}, RPCConfig>()
+    RPC.CreateStream('Stream', { scope: 'test', version: 1 }, async function* () {
+      yield { msg: 'first' }
+      throw new AuthError('forbidden')
+    })
+    const app = new HonoStreamAppBuilder({
+      defaultStreamMode: 'text',
+      errors: {
+        AuthError: {
+          class: AuthError,
+          statusCode: 403,
+          toResponse: () => ({ name: 'AuthError', reason: 'forbidden' }),
+        },
+      },
+    })
+      .register(RPC, () => ({}))
+      .build()
+
+    const res = await app.request('/test/stream/1', { method: 'POST' })
+    const text = await res.text()
+    expect(text).toContain('"name":"AuthError"')
+    expect(text).toContain('"reason":"forbidden"')
+  })
+})

package/src/implementations/http/hono-stream/index.test.ts

@@ -890,7 +890,7 @@ describe('HonoStreamAppBuilder', () => {
 
       const doc = builder.docs[0]!
       expect(doc.path).toBe('/messages/stream-messages/1')
-      expect(doc.methods).toEqual(['get', 'post'])
+      expect(doc.methods).toEqual(['post', 'get'])
       expect(doc.streamMode).toBe('sse')
       expect(doc.jsonSchema.params).toBeDefined()
       expect(doc.jsonSchema.returnType).toBeDefined()
@@ -1111,7 +1111,7 @@ describe('HonoStreamAppBuilder', () => {
       // Base properties should NOT be overridden
       expect(doc.name).toBe('Test')
       expect(doc.path).toBe('/test/test/1')
-      expect(doc.methods).toEqual(['get', 'post'])
+      expect(doc.methods).toEqual(['post', 'get'])
       // Custom field should be present
       expect(doc).toHaveProperty('customField', 'custom-value')
     })
@@ -1779,7 +1779,7 @@ describe('HonoStreamAppBuilder', () => {
       // Only streaming procedure should be registered
       expect(builder.docs).toHaveLength(1)
       expect(builder.docs[0]!.name).toBe('WatchNotifications')
-      expect(builder.docs[0]!.methods).toEqual(['get', 'post'])
+      expect(builder.docs[0]!.methods).toEqual(['post', 'get'])
 
       // Test streaming
       const res = await app.request('/user/notifications/watch-notifications/1?limit=2', {

package/src/implementations/http/hono-stream/index.ts

@@ -75,10 +75,13 @@ export type HonoStreamAppBuilderConfig<TErrorData = unknown> = {
   onStreamEnd?: (procedure: TStreamProcedureRegistration, c: Context, streamMode: StreamMode) => void
   /**
    * Declarative error-to-response mapping (one of the two peer error modes).
-   * Thrown error classes map to status codes + bodies declaratively. Mid-stream
-   * errors still go through `onMidStreamError` — the HTTP status is already
-   * committed once streaming starts. See hono-api for the full taxonomy
-   * contract.
+   * Thrown error classes map to status codes + bodies declaratively. The
+   * taxonomy applies to BOTH pre-stream errors (where the status code is
+   * honored) AND mid-stream errors (where only the body shape is honored —
+   * the HTTP status is already committed once streaming starts; the body is
+   * written as the SSE `event: 'error'` data, or a JSON line in text mode,
+   * for the client's error registry to dispatch). See hono-api for the full
+   * taxonomy contract.
    */
   errors?: ErrorTaxonomy
   /**
@@ -185,6 +188,7 @@ export class HonoStreamAppBuilder<TErrorData = unknown> {
 
   private _app: Hono = new Hono()
   private _docs: (StreamHttpRouteDoc & object)[] = []
+  private _skipped: { name: string; reason: string }[] = []
 
   get app(): Hono {
     return this._app
@@ -194,6 +198,16 @@ export class HonoStreamAppBuilder<TErrorData = unknown> {
     return this._docs
   }
 
+  /**
+   * Procedures that were skipped at `build()` time because they don't fit
+   * this builder (e.g. non-streaming procedures registered against the
+   * stream builder). Surfaced via `DocSource.skippedProcedures` so
+   * DocRegistry can warn about coverage gaps.
+   */
+  get skippedProcedures(): { name: string; reason: string }[] {
+    return this._skipped
+  }
+
   /**
    * Registers a procedure factory with its context.
    * Only streaming procedures (created with CreateStream) will be registered.
@@ -355,24 +369,61 @@ export class HonoStreamAppBuilder<TErrorData = unknown> {
           })
         }
       } catch (error) {
-        // Get error yield value from callback (onMidStreamError)
-        let errorResult: MidStreamErrorResult<TErrorData> | undefined
+        // Dispatch order mirrors hono-rpc: taxonomy → onMidStreamError → default.
+        // The HTTP status is already committed (200 OK headers were sent the
+        // moment streaming started), so the taxonomy here only drives the
+        // wire-protocol body shape — clients dispatch through the same error
+        // registry as RPC/API responses by reading `data.name`.
+        let errorData: unknown
+        let sseEventOverride: string | undefined
+        let sseIdOverride: string | undefined
+        let sseRetryOverride: number | undefined
+        let runOnCatch: (() => Promise<void>) | undefined
 
-        if (this.config?.onMidStreamError) {
-          errorResult = this.config.onMidStreamError(procedure, c, error as Error)
+        if (this.config?.errors || this.config?.unknownError) {
+          const resolved = resolveErrorResponse({
+            err: error,
+            userTaxonomy: this.config.errors,
+            unknownError: this.config.unknownError,
+            procedure,
+            raw: c,
+          })
+          if (resolved) {
+            errorData = resolved.body
+            sseEventOverride = 'error'
+            runOnCatch = resolved.runOnCatch
+          }
+        }
+
+        if (errorData === undefined && this.config?.onMidStreamError) {
+          const errorResult: MidStreamErrorResult<TErrorData> | undefined =
+            this.config.onMidStreamError(procedure, c, error as Error)
+          if (errorResult?.data !== undefined) {
+            errorData = errorResult.data
+            sseEventOverride = procedure.name
+          }
+        }
+
+        if (errorData === undefined) {
+          errorData = { error: (error as Error).message }
+          sseEventOverride = 'error'
         }
 
-        // Write error value to stream
-        const errorData = errorResult?.data ?? { error: (error as Error).message }
         const sseMeta = getSSEMeta(errorData)
 
         await stream.writeSSE({
           data: typeof errorData === 'string' ? errorData : JSON.stringify(errorData),
-          event: sseMeta?.event ?? (errorResult?.data !== undefined ? procedure.name : 'error'),
-          id: sseMeta?.id ?? String(eventId++),
-          ...(sseMeta?.retry !== undefined && { retry: sseMeta.retry }),
+          event: sseMeta?.event ?? sseEventOverride ?? 'error',
+          id: sseMeta?.id ?? sseIdOverride ?? String(eventId++),
+          ...((sseMeta?.retry ?? sseRetryOverride) !== undefined && {
+            retry: (sseMeta?.retry ?? sseRetryOverride) as number,
+          }),
         })
 
+        if (runOnCatch) {
+          await runOnCatch()
+        }
+
         // closeStream defaults to true if not specified
         // (stream closes naturally after this handler completes)
       } finally {
@@ -408,16 +459,43 @@ export class HonoStreamAppBuilder<TErrorData = unknown> {
           await stream.writeln(JSON.stringify(value))
         }
       } catch (error) {
-        // Get error yield value from callback (onMidStreamError)
-        let errorResult: MidStreamErrorResult<TErrorData> | undefined
+        // Same dispatch order as SSE — taxonomy first, onMidStreamError next,
+        // hard default last. Text streams have no event/id metadata, so we
+        // only forward the body bytes.
+        let errorData: unknown
+        let runOnCatch: (() => Promise<void>) | undefined
 
-        if (this.config?.onMidStreamError) {
-          errorResult = this.config.onMidStreamError(procedure, c, error as Error)
+        if (this.config?.errors || this.config?.unknownError) {
+          const resolved = resolveErrorResponse({
+            err: error,
+            userTaxonomy: this.config.errors,
+            unknownError: this.config.unknownError,
+            procedure,
+            raw: c,
+          })
+          if (resolved) {
+            errorData = resolved.body
+            runOnCatch = resolved.runOnCatch
+          }
+        }
+
+        if (errorData === undefined && this.config?.onMidStreamError) {
+          const errorResult: MidStreamErrorResult<TErrorData> | undefined =
+            this.config.onMidStreamError(procedure, c, error as Error)
+          if (errorResult?.data !== undefined) {
+            errorData = errorResult.data
+          }
+        }
+
+        if (errorData === undefined) {
+          errorData = { error: (error as Error).message }
         }
 
-        // Write error value to stream
-        const errorData = errorResult?.data ?? { error: (error as Error).message }
         await stream.writeln(JSON.stringify(errorData))
+
+        if (runOnCatch) {
+          await runOnCatch()
+        }
       } finally {
         if (this.config?.onStreamEnd) {
           this.config.onStreamEnd(procedure, c, 'text')
@@ -436,8 +514,23 @@ export class HonoStreamAppBuilder<TErrorData = unknown> {
     this.factories.forEach(({ factory, factoryContext, streamMode, extendProcedureDoc }) => {
       const mode = streamMode ?? this.config?.defaultStreamMode ?? 'sse'
 
-      factory
-        .getProcedures()
+      const procedures = factory.getProcedures()
+
+      // Track non-streaming procedures so DocRegistry can warn about coverage
+      // gaps (e.g. a regular procedure registered with this builder will get
+      // dropped here and needs to be registered with HonoRPCAppBuilder).
+      for (const p of procedures as { name: string; isStream?: boolean }[]) {
+        if (p.isStream !== true) {
+          const reason =
+            'Non-streaming procedure registered with HonoStreamAppBuilder — register it with HonoRPCAppBuilder (or HonoApiAppBuilder) instead.'
+          this._skipped.push({ name: p.name, reason })
+          console.warn(
+            `[ts-procedures hono-stream] Skipping procedure "${p.name}": ${reason}`
+          )
+        }
+      }
+
+      procedures
         .filter(
           (p: { isStream?: boolean }): p is TStreamProcedureRegistration => p.isStream === true
         )
@@ -471,7 +564,10 @@ export class HonoStreamAppBuilder<TErrorData = unknown> {
       config,
       prefix: this.config?.pathPrefix,
     })
-    const methods = ['get', 'post'] as const
+    // POST first so codegen (which uses `methods[0]`) defaults to POST. POST is
+    // the canonical method for streaming procedures because it can carry a body
+    // for params; GET is the supplementary method for query-string callers.
+    const methods = ['post', 'get'] as const
     const jsonSchema: { params?: Record<string, unknown>; yieldType?: Record<string, unknown>; returnType?: Record<string, unknown> } = {}
 
     if (config.schema?.params) {

package/src/implementations/types.ts

@@ -168,6 +168,13 @@ export type AnyHttpRouteDoc = RPCHttpRouteDoc | APIHttpRouteDoc | StreamHttpRout
 
 export interface DocSource<T = AnyHttpRouteDoc> {
   readonly docs: T[]
+  /**
+   * Optional list of procedures that were registered with this builder but
+   * couldn't be served by it (e.g. a streaming procedure registered with an
+   * RPC builder). DocRegistry aggregates these across sources and warns at
+   * `toJSON()` time so silently-dropped procedures don't slip through.
+   */
+  readonly skippedProcedures?: { name: string; reason: string }[]
 }
 
 export interface HeaderDoc {

package/src/index.test.ts

@@ -915,10 +915,19 @@ describe('Streaming Procedures - CreateStream', () => {
     expect(values).toEqual(['user-123'])
   })
 
-  test('CreateStream wrapped errors preserve cause', async () => {
+  test('CreateStream rethrows the original error preserving class identity', async () => {
+    // The streaming wrapper must NOT box user errors inside ProcedureError —
+    // doing so would defeat route-declared typed-error dispatch on the client
+    // (the HTTP builder's taxonomy would see `ProcedureError` instead of the
+    // user's class). Stack annotation is added in place; class identity and
+    // custom properties are preserved.
+    class MyDomainError extends Error {
+      readonly name = 'MyDomainError'
+      readonly code = 'STREAM_FAIL'
+    }
+
     const { CreateStream } = Procedures()
-    const originalError = new Error('Stream underlying error')
-    ;(originalError as any).code = 'STREAM_FAIL'
+    const originalError = new MyDomainError('Stream underlying error')
 
     const { StreamCause } = CreateStream(
       'StreamCause',
@@ -935,12 +944,40 @@ describe('Streaming Procedures - CreateStream', () => {
       }
       expect.fail('Should have thrown')
     } catch (e: any) {
-      expect(e).toBeInstanceOf(ProcedureError)
-      expect(e.cause).toBe(originalError)
-      expect(e.cause.code).toBe('STREAM_FAIL')
+      expect(e).toBe(originalError)
+      expect(e).toBeInstanceOf(MyDomainError)
+      expect(e.code).toBe('STREAM_FAIL')
     }
   })
 
+  test('CreateStream propagates .return() to the user generator', async () => {
+    // Consumers that close a stream early (via `iterator.return()` or breaking
+    // out of for-await) must trigger the user generator's `finally` block so
+    // cleanup (db handles, subscriptions, signal-driven teardown) runs.
+    const { CreateStream } = Procedures()
+    let finallyRan = false
+
+    const { EarlyClose } = CreateStream(
+      'EarlyClose',
+      {},
+      async function* () {
+        try {
+          yield 1
+          yield 2
+          yield 3
+        } finally {
+          finallyRan = true
+        }
+      }
+    )
+
+    const iter = EarlyClose({}, {})
+    const first = await iter.next()
+    expect(first.value).toBe(1)
+    await iter.return!(undefined)
+    expect(finallyRan).toBe(true)
+  })
+
   test('CreateStream with extended config', () => {
     interface ExtConfig {
       scope: string

package/src/index.ts

@@ -383,8 +383,8 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
           params as any
         )
 
+        const userIterator = userGenerator[Symbol.asyncIterator]()
         try {
-          const userIterator = userGenerator[Symbol.asyncIterator]()
           let userIterResult = await userIterator.next()
 
           while (!userIterResult.done) {
@@ -411,27 +411,30 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
           // can send it as a special 'return' SSE event
           return userIterResult.value
         } catch (error: any) {
-          if (error instanceof ProcedureError) {
-            throw error
-          } else {
-            const err = new ProcedureError(
-              name,
-              `Error in streaming handler for ${name} - ${error?.message}`,
-              undefined,
-              definitionInfo
-            )
-            err.cause = error
-            if (error.stack && definitionInfo.definedAt) {
-              const { file, line, column } = definitionInfo.definedAt
-              err.stack =
-                error.stack +
-                `\n--- Procedure "${name}" defined at ---\n    at ${file}:${line}:${column}`
-            } else if (error.stack) {
-              err.stack = error.stack
-            }
-            throw err
+          // Preserve the original error class so HTTP builders' taxonomies and
+          // `onMidStreamError` callbacks see the actual thrown type — boxing
+          // user-defined errors inside ProcedureError defeats route-declared
+          // typed-error dispatch on the client. Augment the stack trace in
+          // place with the procedure's definition site when available.
+          if (
+            definitionInfo.definedAt &&
+            error &&
+            typeof error.stack === 'string'
+          ) {
+            const { file, line, column } = definitionInfo.definedAt
+            error.stack =
+              `${error.stack}\n--- Procedure "${name}" defined at ---\n    at ${file}:${line}:${column}`
           }
+          throw error
         } finally {
+          // Propagate `.return()` to the user generator so its `finally`
+          // blocks (and any `signal`-driven cleanup) run when the consumer
+          // closes the stream early. No-op when iteration already completed.
+          try {
+            await userIterator.return?.(undefined)
+          } catch {
+            // Swallow — cleanup must not mask the primary error path
+          }
           abortController.abort('stream-completed')
         }
       } as (ctx: TContext, params?: any) => AsyncGenerator<any, any, unknown>,