ts-procedures 5.15.0 → 6.0.0

package/src/client/stream.test.ts

@@ -7,6 +7,8 @@ import type {
   AdapterStreamResponse,
   ClientHooks,
   StreamDescriptor,
+  ProcedureCallDefaults,
+  ProcedureCallOptions,
 } from './types.js'
 
 // ── helpers ───────────────────────────────────────────────
@@ -47,6 +49,26 @@ function makeStreamAdapter(
   }
 }
 
+interface RunConfig {
+  adapter: ClientAdapter
+  hooks?: ClientHooks
+  defaults?: ProcedureCallDefaults
+  options?: ProcedureCallOptions
+  descriptor?: StreamDescriptor
+  basePath?: string
+}
+
+function run<TYield, TReturn = void>({
+  adapter,
+  hooks = {},
+  defaults,
+  options,
+  descriptor = makeDescriptor(),
+  basePath = 'https://api.example.com',
+}: RunConfig) {
+  return executeStream<TYield, TReturn>({ descriptor, basePath, adapter, hooks, defaults, options })
+}
+
 // ── createTypedStream — SSE mode ──────────────────────────
 
 describe('createTypedStream — SSE mode', () => {
@@ -55,15 +77,10 @@ describe('createTypedStream — SSE mode', () => {
       { data: { count: 1 }, event: 'update' },
       { data: { count: 2 }, event: 'update' },
     ]
-    const stream = createTypedStream<{ count: number }, void>(
-      makeAsyncIterable(sseItems),
-      'sse'
-    )
+    const stream = createTypedStream<{ count: number }, void>(makeAsyncIterable(sseItems), 'sse')
 
     const received: { count: number }[] = []
-    for await (const item of stream) {
-      received.push(item)
-    }
+    for await (const item of stream) received.push(item)
     expect(received).toEqual([{ count: 1 }, { count: 2 }])
   })
 
@@ -74,34 +91,23 @@ describe('createTypedStream — SSE mode', () => {
     ]
     const stream = createTypedStream<{ count: number }, { total: number }>(
       makeAsyncIterable(sseItems),
-      'sse'
+      'sse',
     )
 
     const yielded: { count: number }[] = []
-    for await (const item of stream) {
-      yielded.push(item)
-    }
+    for await (const item of stream) yielded.push(item)
 
-    // Only the 'update' event is yielded
     expect(yielded).toEqual([{ count: 1 }])
-
-    // The 'return' event resolves .result
-    const result = await stream.result
-    expect(result).toEqual({ total: 99 })
+    await expect(stream.result).resolves.toEqual({ total: 99 })
   })
 
   it('resolves .result with undefined when no return event', async () => {
-    const sseItems = [
-      { data: 'hello', event: 'message' },
-    ]
     const stream = createTypedStream<string, undefined>(
-      makeAsyncIterable(sseItems),
-      'sse'
+      makeAsyncIterable([{ data: 'hello', event: 'message' }]),
+      'sse',
     )
-
     for await (const _ of stream) { /* drain */ }
-    const result = await stream.result
-    expect(result).toBeUndefined()
+    await expect(stream.result).resolves.toBeUndefined()
   })
 
   it('rejects .result and re-throws on error', async () => {
@@ -111,30 +117,19 @@ describe('createTypedStream — SSE mode', () => {
     }
 
     const stream = createTypedStream<string, void>(errorIterable(), 'sse')
-
-    // Consuming the stream should throw
     await expect(async () => {
       for await (const _ of stream) { /* drain */ }
     }).rejects.toThrow('stream broke')
-
-    // .result should also reject
     await expect(stream.result).rejects.toThrow('stream broke')
   })
 
   it('handles SSE items without event field (defaults to yielding data)', async () => {
-    const sseItems = [
-      { data: 'a' },
-      { data: 'b' },
-    ]
     const stream = createTypedStream<string, void>(
-      makeAsyncIterable(sseItems),
-      'sse'
+      makeAsyncIterable([{ data: 'a' }, { data: 'b' }]),
+      'sse',
     )
-
     const yielded: string[] = []
-    for await (const item of stream) {
-      yielded.push(item)
-    }
+    for await (const item of stream) yielded.push(item)
     expect(yielded).toEqual(['a', 'b'])
   })
 })
@@ -144,27 +139,16 @@ describe('createTypedStream — SSE mode', () => {
 describe('createTypedStream — text mode', () => {
   it('yields each chunk as-is', async () => {
     const chunks = ['chunk1', 'chunk2', 'chunk3']
-    const stream = createTypedStream<string, void>(
-      makeAsyncIterable(chunks),
-      'text'
-    )
-
+    const stream = createTypedStream<string, void>(makeAsyncIterable(chunks), 'text')
     const received: string[] = []
-    for await (const chunk of stream) {
-      received.push(chunk)
-    }
+    for await (const chunk of stream) received.push(chunk)
     expect(received).toEqual(chunks)
   })
 
   it('.result resolves to void on normal completion', async () => {
-    const stream = createTypedStream<string, void>(
-      makeAsyncIterable(['a', 'b']),
-      'text'
-    )
-
+    const stream = createTypedStream<string, void>(makeAsyncIterable(['a', 'b']), 'text')
     for await (const _ of stream) { /* drain */ }
-    const result = await stream.result
-    expect(result).toBeUndefined()
+    await expect(stream.result).resolves.toBeUndefined()
   })
 
   it('rejects .result and re-throws on error', async () => {
@@ -172,13 +156,10 @@ describe('createTypedStream — text mode', () => {
       yield 'before error'
       throw new Error('text stream error')
     }
-
     const stream = createTypedStream<string, void>(errorIterable(), 'text')
-
     await expect(async () => {
       for await (const _ of stream) { /* drain */ }
     }).rejects.toThrow('text stream error')
-
     await expect(stream.result).rejects.toThrow('text stream error')
   })
 })
@@ -189,20 +170,11 @@ describe('executeStream', () => {
   it('calls adapter.stream and returns a TypedStream', async () => {
     const items = [{ data: 'hello', event: 'msg' }]
     const adapter = makeStreamAdapter({}, items)
-
-    const stream = await executeStream<string, void>(
-      makeDescriptor(),
-      'https://api.example.com',
-      adapter,
-      {},
-      undefined
-    )
+    const stream = await run<string, void>({ adapter })
 
     expect(adapter.stream).toHaveBeenCalledOnce()
     const received: string[] = []
-    for await (const item of stream) {
-      received.push(item)
-    }
+    for await (const item of stream) received.push(item)
     expect(received).toEqual(['hello'])
   })
 
@@ -216,23 +188,15 @@ describe('executeStream', () => {
       }),
     }
 
-    const globalHooks: ClientHooks = {
+    const hooks: ClientHooks = {
       onBeforeRequest: (ctx) => ({
         ...ctx,
         request: { ...ctx.request, headers: { 'x-stream-auth': 'stream-token' } },
       }),
     }
 
-    const stream = await executeStream(
-      makeDescriptor(),
-      'https://api.example.com',
-      adapter,
-      globalHooks,
-      undefined
-    )
-    // Drain
-    for await (const _ of stream) { /* noop */ }
-
+    const stream = await run({ adapter, hooks })
+    for await (const _ of stream) { /* drain */ }
     expect(capturedHeaders[0]?.['x-stream-auth']).toBe('stream-token')
   })
 
@@ -245,12 +209,11 @@ describe('executeStream', () => {
         return { status: 200, headers: {}, body: makeAsyncIterable([]) }
       }),
     }
-    const globalHooks: ClientHooks = {
+    const hooks: ClientHooks = {
       onAfterResponse: () => { order.push('afterResponse') },
     }
 
-    await executeStream(makeDescriptor(), 'https://api.example.com', adapter, globalHooks, undefined)
-    // After executeStream returns (before iteration), afterResponse should have fired
+    await run({ adapter, hooks })
     expect(order).toEqual(['adapter', 'afterResponse'])
   })
 
@@ -263,10 +226,7 @@ describe('executeStream', () => {
         body: makeAsyncIterable([]),
       })),
     }
-
-    await expect(
-      executeStream(makeDescriptor(), 'https://api.example.com', adapter, {}, undefined)
-    ).rejects.toThrow(ClientRequestError)
+    await expect(run({ adapter })).rejects.toThrow(ClientRequestError)
   })
 
   it('runs onError on adapter failure and re-throws', async () => {
@@ -276,13 +236,11 @@ describe('executeStream', () => {
       stream: vi.fn(async () => { throw adapterError }),
     }
     const receivedErrors: unknown[] = []
-    const globalHooks: ClientHooks = {
+    const hooks: ClientHooks = {
       onError: (ctx) => { receivedErrors.push(ctx.error) },
     }
 
-    await expect(
-      executeStream(makeDescriptor(), 'https://api.example.com', adapter, globalHooks, undefined)
-    ).rejects.toThrow('stream connection failed')
+    await expect(run({ adapter, hooks })).rejects.toThrow('stream connection failed')
     expect(receivedErrors[0]).toBe(adapterError)
   })
 
@@ -293,18 +251,13 @@ describe('executeStream', () => {
     ]
     const adapter = makeStreamAdapter({}, sseItems)
 
-    const stream = await executeStream<{ n: number }, { final: boolean }>(
-      makeDescriptor({ streamMode: 'sse' }),
-      'https://api.example.com',
+    const stream = await run<{ n: number }, { final: boolean }>({
       adapter,
-      {},
-      undefined
-    )
+      descriptor: makeDescriptor({ streamMode: 'sse' }),
+    })
 
     const yielded: { n: number }[] = []
-    for await (const item of stream) {
-      yielded.push(item)
-    }
+    for await (const item of stream) yielded.push(item)
     expect(yielded).toEqual([{ n: 1 }])
     await expect(stream.result).resolves.toEqual({ final: true })
   })
@@ -313,19 +266,91 @@ describe('executeStream', () => {
     const chunks = ['line1', 'line2']
     const adapter = makeStreamAdapter({}, chunks)
 
-    const stream = await executeStream<string, void>(
-      makeDescriptor({ streamMode: 'text' }),
-      'https://api.example.com',
+    const stream = await run<string, void>({
       adapter,
-      {},
-      undefined
-    )
+      descriptor: makeDescriptor({ streamMode: 'text' }),
+    })
 
     const received: string[] = []
-    for await (const chunk of stream) {
-      received.push(chunk)
-    }
+    for await (const chunk of stream) received.push(chunk)
     expect(received).toEqual(chunks)
     await expect(stream.result).resolves.toBeUndefined()
   })
+
+  // ── Per-call options ──
+
+  it('per-call timeout attaches a signal via AbortSignal.timeout', async () => {
+    const spy = vi.spyOn(AbortSignal, 'timeout')
+    try {
+      let observedSignal: AbortSignal | undefined
+      const adapter: ClientAdapter = {
+        request: vi.fn(async (): Promise<never> => { throw new Error('not expected') }),
+        stream: vi.fn(async (req: AdapterRequest): Promise<AdapterStreamResponse> => {
+          observedSignal = req.signal
+          return { status: 200, headers: {}, body: makeAsyncIterable([]) }
+        }),
+      }
+
+      await run({ adapter, options: { timeout: 5000 } })
+      expect(spy).toHaveBeenCalledWith(5000)
+      expect(observedSignal).toBeDefined()
+    } finally {
+      spy.mockRestore()
+    }
+  })
+
+  it('adapter receives a signal that reflects abort when the caller cancels', async () => {
+    const controller = new AbortController()
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (): Promise<never> => { throw new Error('not expected') }),
+      stream: vi.fn(async (req: AdapterRequest): Promise<AdapterStreamResponse> => {
+        return new Promise((_resolve, reject) => {
+          const abort = () => reject(new Error('aborted'))
+          if (req.signal?.aborted) abort()
+          else req.signal?.addEventListener('abort', abort, { once: true })
+        })
+      }),
+    }
+
+    const promise = run({ adapter, options: { signal: controller.signal } })
+    // Let executeStream reach the adapter before aborting
+    await Promise.resolve()
+    controller.abort()
+    await expect(promise).rejects.toThrow('aborted')
+  })
+
+  it('per-call basePath overrides base path for streams', async () => {
+    const capturedUrls: string[] = []
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (): Promise<never> => { throw new Error('not expected') }),
+      stream: vi.fn(async (req: AdapterRequest): Promise<AdapterStreamResponse> => {
+        capturedUrls.push(req.url)
+        return { status: 200, headers: {}, body: makeAsyncIterable([]) }
+      }),
+    }
+
+    const stream = await run({
+      adapter,
+      descriptor: makeDescriptor({ path: '/tail' }),
+      basePath: 'https://default.example.com',
+      options: { basePath: 'https://override.example.com' },
+    })
+    for await (const _ of stream) { /* drain */ }
+
+    expect(capturedUrls[0]).toBe('https://override.example.com/tail')
+  })
+
+  it('per-call meta is forwarded to the adapter', async () => {
+    let observedMeta: unknown
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (): Promise<never> => { throw new Error('not expected') }),
+      stream: vi.fn(async (req: AdapterRequest): Promise<AdapterStreamResponse> => {
+        observedMeta = req.meta
+        return { status: 200, headers: {}, body: makeAsyncIterable([]) }
+      }),
+    }
+
+    await run({ adapter, options: { meta: { traceId: 'stream-trace' } as never } })
+    expect(observedMeta).toEqual({ traceId: 'stream-trace' })
+  })
 })

package/src/client/stream.ts

@@ -1,12 +1,17 @@
 import { buildAdapterRequest } from './request-builder.js'
 import { runBeforeRequest, runAfterResponse, runOnError } from './hooks.js'
+import { applyRequestOptions, resolveBasePath } from './resolve-options.js'
 import { ClientRequestError } from './errors.js'
+import { dispatchTypedError } from './error-dispatch.js'
 import type {
   ClientAdapter,
   ClientHooks,
+  ErrorRegistry,
   StreamDescriptor,
   TypedStream,
   AdapterResponse,
+  ProcedureCallDefaults,
+  ProcedureCallOptions,
 } from './types.js'
 
 // ── SSE item shape ────────────────────────────────────────
@@ -90,66 +95,87 @@ export function createTypedStream<TYield, TReturn = void>(
 
 // ── executeStream ─────────────────────────────────────────
 
+export interface ExecuteStreamConfig {
+  descriptor: StreamDescriptor
+  basePath: string
+  adapter: ClientAdapter
+  hooks: ClientHooks
+  defaults?: ProcedureCallDefaults
+  options?: ProcedureCallOptions
+  errorRegistry?: ErrorRegistry
+}
+
 /**
  * Executes a streaming procedure call through the adapter.
  *
  * Flow:
- * 1. Build AdapterRequest from descriptor
- * 2. Run onBeforeRequest hooks
- * 3. Call adapter.stream()
- * 4. On adapter error: run onError hooks, re-throw
- * 5. Run onAfterResponse immediately (before iteration), body is null
- * 6. If non-2xx: throw ClientRequestError
- * 7. Return createTypedStream(streamResponse.body, descriptor.streamMode)
+ * 1. Resolve base path and build AdapterRequest
+ * 2. Apply request options (headers, signal, timeout, meta) from defaults + per-call
+ * 3. Run onBeforeRequest hooks
+ * 4. Call adapter.stream()
+ * 5. On adapter error: run onError hooks, re-throw
+ * 6. Run onAfterResponse immediately (before iteration), body is null
+ * 7. If non-2xx: throw ClientRequestError
+ * 8. Return createTypedStream(streamResponse.body, descriptor.streamMode)
  */
 export async function executeStream<TYield, TReturn = void>(
-  descriptor: StreamDescriptor,
-  basePath: string,
-  adapter: ClientAdapter,
-  globalHooks: ClientHooks,
-  localHooks: ClientHooks | undefined
+  config: ExecuteStreamConfig,
 ): Promise<TypedStream<TYield, TReturn>> {
+  const { descriptor, basePath, adapter, hooks, defaults, options, errorRegistry } = config
+
   // 1. Build the initial request
-  let request = buildAdapterRequest(descriptor, basePath)
+  const resolvedBasePath = resolveBasePath(defaults, options, basePath)
+  let request = buildAdapterRequest(descriptor, resolvedBasePath)
+
+  // 2. Apply request-level options (headers, signal, timeout, meta)
+  request = applyRequestOptions(request, defaults, options)
 
-  // 2. Run before-request hooks
+  // 3. Run before-request hooks
   const beforeCtx = await runBeforeRequest(
     { procedureName: descriptor.name, scope: descriptor.scope, request },
-    globalHooks,
-    localHooks
+    hooks,
+    options,
   )
   request = beforeCtx.request
 
-  // 3. Call the adapter
+  // 4. Call the adapter
   let streamResponse
   try {
     streamResponse = await adapter.stream(request)
   } catch (err) {
-    // 4. On adapter error: run error hooks, re-throw
+    // 5. On adapter error: run error hooks, re-throw
     await runOnError(
       { procedureName: descriptor.name, scope: descriptor.scope, request, error: err },
-      globalHooks,
-      localHooks
+      hooks,
+      options,
     )
     throw err
   }
 
-  // Build an AdapterResponse shape for the hooks (body is null for streams at this point)
+  // Build an AdapterResponse shape for the hooks. For success the body is null
+  // (the actual data flows through the async iterable); for non-2xx the adapter
+  // eagerly parses the JSON response body and surfaces it via `errorBody`.
   const responseForHooks: AdapterResponse = {
     status: streamResponse.status,
     headers: streamResponse.headers,
-    body: null,
+    body: streamResponse.errorBody ?? null,
   }
 
-  // 5. Run after-response hooks immediately (before iteration)
+  // 6. Run after-response hooks immediately (before iteration)
   await runAfterResponse(
     { procedureName: descriptor.name, scope: descriptor.scope, request, response: responseForHooks },
-    globalHooks,
-    localHooks
+    hooks,
+    options,
   )
 
-  // 6. Check status after hooks (hooks may mutate responseForHooks.status)
+  // 7. Check status after hooks (hooks may mutate responseForHooks.status)
   if (responseForHooks.status < 200 || responseForHooks.status >= 300) {
+    const typed = dispatchTypedError(errorRegistry, responseForHooks.body, {
+      status: responseForHooks.status,
+      procedureName: descriptor.name,
+      scope: descriptor.scope,
+    })
+    if (typed) throw typed
     throw new ClientRequestError({
       status: responseForHooks.status,
       headers: responseForHooks.headers,
@@ -159,6 +185,6 @@ export async function executeStream<TYield, TReturn = void>(
     })
   }
 
-  // 7. Return the typed stream
+  // 8. Return the typed stream
   return createTypedStream<TYield, TReturn>(streamResponse.body, descriptor.streamMode)
 }