ts-procedures 5.14.0 → 5.16.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,5 +1,6 @@
 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 type {
   ClientAdapter,
@@ -7,6 +8,8 @@ import type {
   StreamDescriptor,
   TypedStream,
   AdapterResponse,
+  ProcedureCallDefaults,
+  ProcedureCallOptions,
 } from './types.js'
 
 // ── SSE item shape ────────────────────────────────────────
@@ -90,46 +93,58 @@ export function createTypedStream<TYield, TReturn = void>(
 
 // ── executeStream ─────────────────────────────────────────
 
+export interface ExecuteStreamConfig {
+  descriptor: StreamDescriptor
+  basePath: string
+  adapter: ClientAdapter
+  hooks: ClientHooks
+  defaults?: ProcedureCallDefaults
+  options?: ProcedureCallOptions
+}
+
 /**
  * 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 } = 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
   }
@@ -141,14 +156,14 @@ export async function executeStream<TYield, TReturn = void>(
     body: 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) {
     throw new ClientRequestError({
       status: responseForHooks.status,
@@ -159,6 +174,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)
 }

package/src/client/types.ts

@@ -1,3 +1,35 @@
+// ── Request Metadata ─────────────────────────────────────
+
+/**
+ * Per-request metadata visible to adapters and hooks. Defined as an empty
+ * interface so consumers can augment it via TypeScript declaration merging
+ * to get end-to-end type safety for their own metadata fields.
+ *
+ * @example With a non-self-contained client:
+ * ```ts
+ * declare module 'ts-procedures/client' {
+ *   interface RequestMeta {
+ *     traceId?: string
+ *     priority?: 'high' | 'low'
+ *   }
+ * }
+ * ```
+ *
+ * @example With a self-contained (code-generated) client:
+ * ```ts
+ * declare module './generated/_types' {
+ *   interface RequestMeta {
+ *     traceId?: string
+ *   }
+ * }
+ * ```
+ *
+ * After augmentation, `request.meta.traceId` is typed everywhere — per-call
+ * options, hooks, and adapters.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface RequestMeta {}
+
 // ── Adapter ──────────────────────────────────────────────
 
 export interface ClientAdapter {
@@ -11,6 +43,11 @@ export interface AdapterRequest {
   headers?: Record<string, string>
   body?: unknown
   signal?: AbortSignal
+  /**
+   * Per-request metadata. Augment `RequestMeta` via declaration merging to
+   * type your own fields. See {@link RequestMeta}.
+   */
+  meta?: RequestMeta
 }
 
 export interface AdapterResponse {
@@ -81,14 +118,43 @@ export interface TypedStream<TYield, TReturn = void> extends AsyncIterable<TYiel
   result: Promise<TReturn>
 }
 
-// ── Client Instance ──────────────────────────────────────
+// ── Request Options ──────────────────────────────────────
+
+/**
+ * Request-level configuration that can be set as client-level defaults
+ * (via `CreateClientConfig.defaults`) or per-call (via `ProcedureCallOptions`).
+ *
+ * - `signal`: AbortSignal for cancellation. When both a default and per-call
+ *   signal are provided, they're combined — whichever aborts first wins.
+ * - `timeout`: Timeout in milliseconds. Combined with `signal` the same way.
+ *   A per-call `timeout: 0` disables an inherited default timeout.
+ * - `headers`: Extra headers merged into the request. Per-call keys win over
+ *   default keys. Still subject to further mutation by `onBeforeRequest` hooks.
+ * - `basePath`: Override the base path for this call. Per-call > default > config.
+ * - `meta`: Per-request metadata typed via the {@link RequestMeta} interface.
+ *   Merged shallowly (per-call keys win over default keys).
+ */
+export interface ProcedureCallDefaults {
+  signal?: AbortSignal
+  timeout?: number
+  headers?: Record<string, string>
+  basePath?: string
+  meta?: RequestMeta
+}
+
+/**
+ * Per-call options. Extends both `ProcedureCallDefaults` (request config) and
+ * `ClientHooks` (hooks), so a single options bag covers both concerns.
+ */
+export interface ProcedureCallOptions extends ProcedureCallDefaults, ClientHooks {}
 
-export type ProcedureCallOptions = ClientHooks
+// ── Client Instance ──────────────────────────────────────
 
 export interface ClientInstance {
   basePath: string
   adapter: ClientAdapter
   hooks: ClientHooks
+  defaults: ProcedureCallDefaults
   call<TResponse>(descriptor: CallDescriptor, options?: ProcedureCallOptions): Promise<TResponse>
   stream<TYield, TReturn>(descriptor: StreamDescriptor, options?: ProcedureCallOptions): TypedStream<TYield, TReturn>
 }
@@ -100,4 +166,10 @@ export interface CreateClientConfig<TScopes> {
   basePath: string
   scopes: (client: ClientInstance) => TScopes
   hooks?: ClientHooks
+  /**
+   * Default request options applied to every call. Per-call options override
+   * these (except `signal`, which combines via AbortSignal.any — whichever
+   * fires first cancels the request).
+   */
+  defaults?: ProcedureCallDefaults
 }

package/src/codegen/bin/cli.test.ts

@@ -170,6 +170,41 @@ describe('parseArgs', () => {
     const result = parseArgs(['--url', 'http://x.com/docs', '--out', './out'])
     expect(result.serviceName).toBeUndefined()
   })
+
+  it('parses --clean-out-dir flag', () => {
+    const result = parseArgs(['--url', 'http://x.com/docs', '--out', './out', '--clean-out-dir'])
+    expect(result.cleanOutDir).toBe(true)
+  })
+
+  it('defaults cleanOutDir to false when not provided', () => {
+    const result = parseArgs(['--url', 'http://x.com/docs', '--out', './out'])
+    expect(result.cleanOutDir).toBe(false)
+  })
+
+  it('parses --no-clean-out-dir flag', () => {
+    const result = parseArgs(['--url', 'http://x.com/docs', '--out', './out', '--no-clean-out-dir'])
+    expect(result.cleanOutDir).toBe(false)
+  })
+
+  it('CLI --no-clean-out-dir overrides config cleanOutDir', () => {
+    const config: CodegenConfig = {
+      url: 'http://config.com/docs',
+      outDir: './out',
+      cleanOutDir: true,
+    }
+    const result = parseArgs(['--no-clean-out-dir'], config)
+    expect(result.cleanOutDir).toBe(false)
+  })
+
+  it('config cleanOutDir is used as default', () => {
+    const config: CodegenConfig = {
+      url: 'http://config.com/docs',
+      outDir: './out',
+      cleanOutDir: true,
+    }
+    const result = parseArgs([], config)
+    expect(result.cleanOutDir).toBe(true)
+  })
 })
 
 describe('config file support', () => {