ts-procedures 7.0.0 → 7.1.1

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>,