ts-procedures 5.1.0 → 5.3.0

package/src/implementations/http/express-rpc/README.md

@@ -91,6 +91,33 @@ builder.register(RPC, async (req) => {
 })
 ```
 
+## Abort Signal
+
+`ExpressRPCAppBuilder` provides a lazy `AbortSignal` on `ctx.signal`. The underlying `AbortController` and `req.on('close')` listener are only created when `ctx.signal` is first accessed, so handlers that don't use it pay no overhead.
+
+The signal aborts when the client disconnects before the response finishes (premature close). Normal response completion does not trigger an abort.
+
+```typescript
+RPC.Create(
+  'SlowQuery',
+  { scope: 'data', version: 1 },
+  async (ctx, params) => {
+    // Automatically cancelled if client disconnects
+    const response = await fetch('https://slow-api.example.com/data', {
+      signal: ctx.signal,
+    })
+    return response.json()
+  }
+)
+```
+
+To use `ctx.signal` with type safety, include `signal: AbortSignal` in your context type:
+
+```typescript
+type AppContext = { userId: string; signal: AbortSignal }
+const RPC = Procedures<AppContext, RPCConfig>()
+```
+
 ## Error Handling
 
 Custom error handler receives the procedure, request, response, and error:

package/src/implementations/http/express-rpc/index.ts

@@ -179,7 +179,19 @@ export class ExpressRPCAppBuilder {
                 ? await factoryContext(req)
                 : (factoryContext as ExtractContext<typeof factory>)
 
-            res.json(await procedure.handler(context, req.body))
+            let ac: AbortController | undefined
+            const ctxWithSignal = Object.defineProperty({ ...context }, 'signal', {
+              get() {
+                if (!ac) {
+                  ac = new AbortController()
+                  req.on('close', () => { if (!res.writableFinished) ac!.abort() })
+                }
+                return ac.signal
+              },
+              enumerable: true,
+            })
+
+            res.json(await procedure.handler(ctxWithSignal, req.body))
             if (this.config?.onSuccess) {
               this.config.onSuccess(procedure, req, res)
             }

package/src/implementations/http/hono-rpc/README.md

@@ -135,6 +135,31 @@ The `extendProcedureDoc` callback receives:
 
 This allows you to derive documentation fields from procedure config or add static metadata per factory registration.
 
+## Abort Signal
+
+`HonoRPCAppBuilder` automatically injects the HTTP request's `AbortSignal` (`c.req.raw.signal`) into the handler context. When a client disconnects mid-request, `ctx.signal` aborts, cancelling any signal-aware operations:
+
+```typescript
+RPC.Create(
+  'SlowQuery',
+  { scope: 'data', version: 1 },
+  async (ctx, params) => {
+    // Automatically cancelled if client disconnects
+    const response = await fetch('https://slow-api.example.com/data', {
+      signal: ctx.signal,
+    })
+    return response.json()
+  }
+)
+```
+
+To use `ctx.signal` with type safety, include `signal: AbortSignal` in your context type:
+
+```typescript
+type AppContext = { userId: string; signal: AbortSignal }
+const RPC = Procedures<AppContext, RPCConfig>()
+```
+
 ## Error Handling
 
 Custom error handler receives the procedure, context, and error. **Must return a Response:**

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

@@ -169,7 +169,7 @@ export class HonoRPCAppBuilder {
 
             // Hono uses c.req.json() for body parsing
             const body = await c.req.json().catch(() => ({}))
-            const result = await procedure.handler(context, body)
+            const result = await procedure.handler({ ...context, signal: c.req.raw.signal }, body)
 
             if (this.config?.onSuccess) {
               this.config.onSuccess(procedure, c)

package/src/implementations/http/hono-stream/README.md

@@ -446,13 +446,26 @@ RPC.CreateStream('WatchUser', config, async function* (ctx) {
 
 ## Client Disconnect Handling
 
-When a client disconnects, the stream's `onAbort` handler is triggered, which calls `generator.return()` to clean up. The `ctx.signal` in your handler will be aborted:
+When a client disconnects, the stream's `onAbort` handler is triggered, which calls `generator.return()` to clean up. The `ctx.signal` in your handler will be aborted.
+
+`HonoStreamAppBuilder` injects the HTTP request's `AbortSignal` (`c.req.raw.signal`) into the handler context. This is combined with the stream's internal `AbortController` via `AbortSignal.any()`, so `ctx.signal` aborts on either client disconnect or normal stream completion.
+
+Use `signal.reason` to distinguish between the two:
 
 ```typescript
 RPC.CreateStream('LongStream', config, async function* (ctx) {
-  while (!ctx.signal.aborted) {
-    yield { tick: Date.now() }
-    await new Promise((r) => setTimeout(r, 1000))
+  try {
+    while (!ctx.signal.aborted) {
+      yield { tick: Date.now() }
+      await new Promise((r) => setTimeout(r, 1000))
+    }
+  } finally {
+    if (ctx.signal.reason === 'stream-completed') {
+      // Generator finished normally
+    } else {
+      // Client disconnected — clean up resources
+      await releaseResources()
+    }
   }
 })
 ```

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

@@ -242,7 +242,7 @@ export class HonoStreamAppBuilder<TErrorData = unknown> {
   ) {
     return streamSSE(c, async (stream) => {
       // Pass isPrevalidated: true since we already validated params in createStreamHandler
-      const generator = procedure.handler({ ...context, isPrevalidated: true }, params)
+      const generator = procedure.handler({ ...context, signal: c.req.raw.signal, isPrevalidated: true }, params)
 
       stream.onAbort(async () => {
         await generator.return(undefined)
@@ -311,7 +311,7 @@ export class HonoStreamAppBuilder<TErrorData = unknown> {
   ) {
     return streamText(c, async (stream) => {
       // Pass isPrevalidated: true since we already validated params in createStreamHandler
-      const generator = procedure.handler({ ...context, isPrevalidated: true }, params)
+      const generator = procedure.handler({ ...context, signal: c.req.raw.signal, isPrevalidated: true }, params)
 
       stream.onAbort(async () => {
         await generator.return(undefined)

package/src/index.test.ts

@@ -431,6 +431,61 @@ describe('Procedures', () => {
       expect(e.meta).toEqual({ code: 'ERR_001' })
     }
   })
+
+  test('Create passes through external signal from context', async () => {
+    const { Create } = Procedures<{ signal: AbortSignal }>()
+    const externalAc = new AbortController()
+    let capturedSignal: AbortSignal | null = null
+
+    const { WithSignal } = Create('WithSignal', {}, async (ctx) => {
+      capturedSignal = ctx.signal!
+      return 'done'
+    })
+
+    await WithSignal({ signal: externalAc.signal }, {})
+    expect(capturedSignal).toBe(externalAc.signal)
+    expect(capturedSignal!.aborted).toBe(false)
+  })
+
+  test('Create external signal reflects abort from caller', async () => {
+    const { Create } = Procedures<{ signal: AbortSignal }>()
+    const externalAc = new AbortController()
+    let capturedSignal: AbortSignal | null = null
+
+    const { AbortedSignal } = Create('AbortedSignal', {}, async (ctx) => {
+      capturedSignal = ctx.signal!
+      expect(ctx.signal!.aborted).toBe(true)
+      return 'done'
+    })
+
+    externalAc.abort()
+    await AbortedSignal({ signal: externalAc.signal }, {})
+    expect(capturedSignal!.aborted).toBe(true)
+  })
+
+  test('Create external signal cancels in-flight async work', async () => {
+    const { Create } = Procedures<{ signal: AbortSignal }>()
+    const externalAc = new AbortController()
+    let wasAbortedDuringWork = false
+    const ready = Promise.withResolvers<void>()
+
+    const { LongWork } = Create('LongWork', {}, async (ctx) => {
+      ready.resolve()
+      await new Promise<void>((resolve) => {
+        ctx.signal!.addEventListener('abort', () => {
+          wasAbortedDuringWork = true
+          resolve()
+        })
+      })
+      return 'done'
+    })
+
+    const p = LongWork({ signal: externalAc.signal }, {})
+    await ready.promise
+    externalAc.abort()
+    await p
+    expect(wasAbortedDuringWork).toBe(true)
+  })
 })
 
 describe('Procedures - Definition Location in Errors', () => {
@@ -930,6 +985,46 @@ describe('Streaming Procedures - CreateStream', () => {
     expect(capturedSignal).not.toBeNull()
     expect(capturedSignal!.aborted).toBe(true)
   })
+
+  test('CreateStream signal.reason is stream-completed after normal completion', async () => {
+    const { CreateStream } = Procedures()
+    let capturedSignal: AbortSignal | null = null
+
+    const { ReasonStream } = CreateStream('ReasonStream', {}, async function* (ctx) {
+      capturedSignal = ctx.signal
+      yield 'value'
+    })
+
+    for await (const _val of ReasonStream({}, {})) {
+      // consume
+    }
+
+    expect(capturedSignal!.reason).toBe('stream-completed')
+  })
+
+  test('CreateStream combines external signal with internal signal', async () => {
+    const { CreateStream } = Procedures<{ signal: AbortSignal }>()
+    const externalAc = new AbortController()
+    let capturedSignal: AbortSignal | null = null
+
+    const { CombinedStream } = CreateStream('CombinedStream', {}, async function* (ctx) {
+      capturedSignal = ctx.signal
+      // Combined signal is a new object, not the raw external signal
+      expect(ctx.signal).not.toBe(externalAc.signal)
+      yield 'value'
+    })
+
+    // Abort external before consuming — combined signal should reflect it
+    externalAc.abort('client-disconnected')
+
+    for await (const _val of CombinedStream({ signal: externalAc.signal }, {})) {
+      // consume
+    }
+
+    expect(capturedSignal!.aborted).toBe(true)
+    // Reason comes from external abort, not internal 'stream-completed'
+    expect(capturedSignal!.reason).toBe('client-disconnected')
+  })
 })
 
 describe('isPrevalidated context property', () => {

package/src/index.ts

@@ -11,6 +11,7 @@ export type TNoContextProvided = unknown
 
 export type TLocalContext = {
   error: (message: string, meta?: object) => ProcedureError
+  signal?: AbortSignal
 }
 
 export type TStreamContext = TLocalContext & {
@@ -292,9 +293,15 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
           }
         }
 
+        // Combine with external signal (e.g., from HTTP request) if provided
+        const incomingSignal = (ctx as { signal?: AbortSignal }).signal
+        const signal = incomingSignal
+          ? AbortSignal.any([incomingSignal, abortController.signal])
+          : abortController.signal
+
         const streamCtx: TStreamContext = {
           error: errorFactory,
-          signal: abortController.signal,
+          signal,
         }
 
         const userGenerator = handler(
@@ -344,8 +351,7 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
             throw err
           }
         } finally {
-          // Signal abort on early termination
-          abortController.abort()
+          abortController.abort('stream-completed')
         }
       } as (ctx: TContext, params?: any) => AsyncGenerator<any, any, unknown>,
     }