ts-procedures 5.15.0 → 5.16.0

package/src/client/call.test.ts

@@ -7,6 +7,8 @@ import type {
   AdapterResponse,
   ClientHooks,
   CallDescriptor,
+  ProcedureCallDefaults,
+  ProcedureCallOptions,
 } from './types.js'
 
 // ── helpers ───────────────────────────────────────────────
@@ -37,43 +39,55 @@ function makeAdapter(response?: Partial<AdapterResponse>): ClientAdapter {
   }
 }
 
+interface RunConfig {
+  adapter: ClientAdapter
+  hooks?: ClientHooks
+  defaults?: ProcedureCallDefaults
+  options?: ProcedureCallOptions
+  descriptor?: CallDescriptor
+  basePath?: string
+}
+
+function run<T>({
+  adapter,
+  hooks = {},
+  defaults,
+  options,
+  descriptor = makeDescriptor(),
+  basePath = 'https://api.example.com',
+}: RunConfig): Promise<T> {
+  return executeCall<T>({ descriptor, basePath, adapter, hooks, defaults, options })
+}
+
 // ── executeCall ───────────────────────────────────────────
 
 describe('executeCall', () => {
   it('calls adapter.request and returns body', async () => {
     const adapter = makeAdapter({ body: { id: '1', name: 'Bob' } })
-    const result = await executeCall(makeDescriptor(), 'https://api.example.com', adapter, {}, undefined)
+    const result = await run({ adapter })
     expect(adapter.request).toHaveBeenCalledOnce()
     expect(result).toEqual({ id: '1', name: 'Bob' })
   })
 
   it('throws ClientRequestError on 4xx response', async () => {
     const adapter = makeAdapter({ status: 404, body: { message: 'Not Found' } })
-    await expect(
-      executeCall(makeDescriptor(), 'https://api.example.com', adapter, {}, undefined)
-    ).rejects.toThrow(ClientRequestError)
+    await expect(run({ adapter })).rejects.toThrow(ClientRequestError)
   })
 
   it('throws ClientRequestError on 5xx response', async () => {
     const adapter = makeAdapter({ status: 500, body: { message: 'Server Error' } })
-    await expect(
-      executeCall(makeDescriptor(), 'https://api.example.com', adapter, {}, undefined)
-    ).rejects.toThrow(ClientRequestError)
+    await expect(run({ adapter })).rejects.toThrow(ClientRequestError)
   })
 
   it('throws ClientRequestError on 199 response (below 200)', async () => {
     const adapter = makeAdapter({ status: 199, body: null })
-    await expect(
-      executeCall(makeDescriptor(), 'https://api.example.com', adapter, {}, undefined)
-    ).rejects.toThrow(ClientRequestError)
+    await expect(run({ adapter })).rejects.toThrow(ClientRequestError)
   })
 
   it('does not throw on 2xx boundary responses (200, 201, 299)', async () => {
     for (const status of [200, 201, 204, 299]) {
       const adapter = makeAdapter({ status, body: null })
-      await expect(
-        executeCall(makeDescriptor(), 'https://api.example.com', adapter, {}, undefined)
-      ).resolves.not.toThrow()
+      await expect(run({ adapter })).resolves.not.toThrow()
     }
   })
 
@@ -87,7 +101,7 @@ describe('executeCall', () => {
       stream: vi.fn(async () => { throw new Error('not expected') }),
     }
 
-    const globalHooks: ClientHooks = {
+    const hooks: ClientHooks = {
       onBeforeRequest: (ctx) => ({
         ...ctx,
         request: {
@@ -97,7 +111,7 @@ describe('executeCall', () => {
       }),
     }
 
-    await executeCall(makeDescriptor(), 'https://api.example.com', adapter, globalHooks, undefined)
+    await run({ adapter, hooks })
     expect(capturedHeaders[0]?.['x-auth']).toBe('token-123')
   })
 
@@ -110,26 +124,23 @@ describe('executeCall', () => {
       }),
       stream: vi.fn(async () => { throw new Error('not expected') }),
     }
-    const globalHooks: ClientHooks = {
+    const hooks: ClientHooks = {
       onAfterResponse: () => { order.push('afterResponse') },
     }
 
-    await executeCall(makeDescriptor(), 'https://api.example.com', adapter, globalHooks, undefined)
+    await run({ adapter, hooks })
     expect(order).toEqual(['adapter', 'afterResponse'])
   })
 
   it('does not throw when onAfterResponse swallows non-2xx by mutating status', async () => {
     const adapter = makeAdapter({ status: 401, body: { message: 'Unauthorized' } })
-    const globalHooks: ClientHooks = {
+    const hooks: ClientHooks = {
       onAfterResponse: (ctx) => {
-        // Swallow the error by setting status to 200
         ctx.response.status = 200
       },
     }
 
-    await expect(
-      executeCall(makeDescriptor(), 'https://api.example.com', adapter, globalHooks, undefined)
-    ).resolves.not.toThrow()
+    await expect(run({ adapter, hooks })).resolves.not.toThrow()
   })
 
   it('runs onError on adapter failure and re-throws', async () => {
@@ -139,24 +150,186 @@ describe('executeCall', () => {
       stream: vi.fn(async () => { throw new Error('not expected') }),
     }
     const receivedErrors: unknown[] = []
-    const globalHooks: ClientHooks = {
+    const hooks: ClientHooks = {
       onError: (ctx) => { receivedErrors.push(ctx.error) },
     }
 
-    await expect(
-      executeCall(makeDescriptor(), 'https://api.example.com', adapter, globalHooks, undefined)
-    ).rejects.toThrow('Network failure')
+    await expect(run({ adapter, hooks })).rejects.toThrow('Network failure')
     expect(receivedErrors[0]).toBe(adapterError)
   })
 
-  it('passes per-procedure hooks as local hooks', async () => {
+  it('passes per-procedure hooks as local options', async () => {
     const adapter = makeAdapter()
     const localOrder: string[] = []
-    const localHooks: ClientHooks = {
+    const options: ProcedureCallOptions = {
       onBeforeRequest: (ctx) => { localOrder.push('local-before'); return ctx },
     }
 
-    await executeCall(makeDescriptor(), 'https://api.example.com', adapter, {}, localHooks)
+    await run({ adapter, options })
     expect(localOrder).toContain('local-before')
   })
+
+  // ── Per-call options: signal / timeout / headers / basePath / meta ──
+
+  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 (req: AdapterRequest): Promise<AdapterResponse> => {
+          observedSignal = req.signal
+          return { status: 200, headers: {}, body: {} }
+        }),
+        stream: vi.fn(async () => { throw new Error('not expected') }),
+      }
+
+      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 (req: AdapterRequest): Promise<AdapterResponse> => {
+        return new Promise((_resolve, reject) => {
+          const abort = () => reject(new Error('aborted'))
+          if (req.signal?.aborted) abort()
+          else req.signal?.addEventListener('abort', abort, { once: true })
+        })
+      }),
+      stream: vi.fn(async () => { throw new Error('not expected') }),
+    }
+
+    const promise = run({ adapter, options: { signal: controller.signal } })
+    // Let executeCall reach the adapter before aborting
+    await Promise.resolve()
+    controller.abort()
+    await expect(promise).rejects.toThrow('aborted')
+  })
+
+  it('per-call signal is forwarded to the adapter', async () => {
+    const controller = new AbortController()
+    let observedSignal: AbortSignal | undefined
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (req: AdapterRequest): Promise<AdapterResponse> => {
+        observedSignal = req.signal
+        return { status: 200, headers: {}, body: {} }
+      }),
+      stream: vi.fn(async () => { throw new Error('not expected') }),
+    }
+
+    await run({ adapter, options: { signal: controller.signal } })
+    expect(observedSignal).toBe(controller.signal)
+  })
+
+  it('per-call headers are merged into the request before hooks', async () => {
+    const capturedHeaders: Record<string, string>[] = []
+    const seenByHook: Record<string, string>[] = []
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (req: AdapterRequest): Promise<AdapterResponse> => {
+        capturedHeaders.push(req.headers ?? {})
+        return { status: 200, headers: {}, body: {} }
+      }),
+      stream: vi.fn(async () => { throw new Error('not expected') }),
+    }
+
+    const hooks: ClientHooks = {
+      onBeforeRequest: (ctx) => {
+        seenByHook.push({ ...ctx.request.headers })
+        return ctx
+      },
+    }
+
+    await run({ adapter, hooks, options: { headers: { 'x-request-id': 'req-123' } } })
+    expect(seenByHook[0]?.['x-request-id']).toBe('req-123')
+    expect(capturedHeaders[0]?.['x-request-id']).toBe('req-123')
+  })
+
+  it('per-call basePath overrides the client base path', async () => {
+    const capturedUrls: string[] = []
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (req: AdapterRequest): Promise<AdapterResponse> => {
+        capturedUrls.push(req.url)
+        return { status: 200, headers: {}, body: {} }
+      }),
+      stream: vi.fn(async () => { throw new Error('not expected') }),
+    }
+
+    await run({
+      adapter,
+      descriptor: makeDescriptor({ path: '/users' }),
+      basePath: 'https://default.example.com',
+      options: { basePath: 'https://override.example.com' },
+    })
+    expect(capturedUrls[0]).toBe('https://override.example.com/users')
+  })
+
+  it('global defaults apply when no per-call options', async () => {
+    const capturedHeaders: Record<string, string>[] = []
+    const capturedUrls: string[] = []
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (req: AdapterRequest): Promise<AdapterResponse> => {
+        capturedHeaders.push(req.headers ?? {})
+        capturedUrls.push(req.url)
+        return { status: 200, headers: {}, body: {} }
+      }),
+      stream: vi.fn(async () => { throw new Error('not expected') }),
+    }
+
+    await run({
+      adapter,
+      descriptor: makeDescriptor({ path: '/users' }),
+      basePath: 'https://default.example.com',
+      defaults: {
+        headers: { 'x-client-version': '1.0' },
+        basePath: 'https://region-us.example.com',
+      },
+    })
+    expect(capturedHeaders[0]?.['x-client-version']).toBe('1.0')
+    expect(capturedUrls[0]).toBe('https://region-us.example.com/users')
+  })
+
+  it('onBeforeRequest can still override resolved signal/headers', async () => {
+    let observedSignal: AbortSignal | undefined
+    const hookController = new AbortController()
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (req: AdapterRequest): Promise<AdapterResponse> => {
+        observedSignal = req.signal
+        return { status: 200, headers: {}, body: {} }
+      }),
+      stream: vi.fn(async () => { throw new Error('not expected') }),
+    }
+
+    const hooks: ClientHooks = {
+      onBeforeRequest: (ctx) => ({
+        ...ctx,
+        request: { ...ctx.request, signal: hookController.signal },
+      }),
+    }
+
+    await run({ adapter, hooks, options: { timeout: 10_000 } })
+    expect(observedSignal).toBe(hookController.signal)
+  })
+
+  it('merges default + per-call meta; per-call keys win', async () => {
+    let observedMeta: unknown
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (req: AdapterRequest): Promise<AdapterResponse> => {
+        observedMeta = req.meta
+        return { status: 200, headers: {}, body: {} }
+      }),
+      stream: vi.fn(async () => { throw new Error('not expected') }),
+    }
+
+    await run({
+      adapter,
+      defaults: { meta: { traceId: 'default-trace', attempt: 1 } as never },
+      options: { meta: { traceId: 'override' } as never },
+    })
+    expect(observedMeta).toEqual({ traceId: 'override', attempt: 1 })
+  })
 })

package/src/client/call.ts

@@ -1,64 +1,77 @@
 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,
   ClientHooks,
   CallDescriptor,
+  ProcedureCallDefaults,
+  ProcedureCallOptions,
 } from './types.js'
 
+export interface ExecuteCallConfig {
+  descriptor: CallDescriptor
+  basePath: string
+  adapter: ClientAdapter
+  hooks: ClientHooks
+  defaults?: ProcedureCallDefaults
+  options?: ProcedureCallOptions
+}
+
 /**
  * Executes a single procedure call through the adapter.
  *
  * Flow:
- * 1. Build AdapterRequest from descriptor
- * 2. Run onBeforeRequest hooks (global then local)
- * 3. Call adapter.request()
- * 4. On adapter error: run onError hooks, re-throw
- * 5. Run onAfterResponse hooks (hooks may mutate response.status)
- * 6. If response status is non-2xx: throw ClientRequestError
- * 7. Return response.body as TResponse
+ * 1. Resolve base path (per-call > defaults > config) and build AdapterRequest
+ * 2. Apply request options (headers, signal, timeout, meta) from defaults + per-call
+ * 3. Run onBeforeRequest hooks (global then local) — may further mutate request
+ * 4. Call adapter.request()
+ * 5. On adapter error: run onError hooks, re-throw
+ * 6. Run onAfterResponse hooks (may mutate response.status to swallow errors)
+ * 7. If response status is non-2xx: throw ClientRequestError
+ * 8. Return response.body as TResponse
  */
-export async function executeCall<TResponse>(
-  descriptor: CallDescriptor,
-  basePath: string,
-  adapter: ClientAdapter,
-  globalHooks: ClientHooks,
-  localHooks: ClientHooks | undefined
-): Promise<TResponse> {
-  // 1. Build the initial request
-  let request = buildAdapterRequest(descriptor, basePath)
+export async function executeCall<TResponse>(config: ExecuteCallConfig): Promise<TResponse> {
+  const { descriptor, basePath, adapter, hooks, defaults, options } = config
+
+  // 1. Build the initial request (path/query/body from descriptor)
+  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 — they may mutate the request
+  // 3. Run before-request hooks — they may further mutate the request
   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 response
   try {
     response = await adapter.request(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
   }
 
-  // 5. Run after-response hooks — they may mutate response.status to swallow errors
+  // 6. Run after-response hooks — they may mutate response.status to swallow errors
   await runAfterResponse(
     { procedureName: descriptor.name, scope: descriptor.scope, request, response },
-    globalHooks,
-    localHooks
+    hooks,
+    options,
   )
 
-  // 6. Check status AFTER hooks (hooks may have swallowed the error by mutating status)
+  // 7. Check status AFTER hooks (hooks may have swallowed the error by mutating status)
   if (response.status < 200 || response.status >= 300) {
     throw new ClientRequestError({
       status: response.status,
@@ -69,6 +82,6 @@ export async function executeCall<TResponse>(
     })
   }
 
-  // 7. Return the body
+  // 8. Return the body
   return response.body as TResponse
 }

package/src/client/index.test.ts

@@ -287,4 +287,121 @@ describe('createClient', () => {
     const { ClientRequestError: CRE } = await import('./index.js')
     expect(CRE).toBeDefined()
   })
+
+  // ── defaults + per-call options ───────────────────────────
+
+  it('applies config.defaults to every call', async () => {
+    const capturedHeaders: Record<string, string>[] = []
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (req: AdapterRequest): Promise<AdapterResponse> => {
+        capturedHeaders.push(req.headers ?? {})
+        return { status: 200, headers: {}, body: {} }
+      }),
+      stream: vi.fn(async (): Promise<AdapterStreamResponse> => ({
+        status: 200,
+        headers: {},
+        body: makeAsyncIterable([]),
+      })),
+    }
+
+    const client = createClient({
+      adapter,
+      basePath: 'https://api.example.com',
+      defaults: { headers: { 'x-client': 'web' } },
+      scopes: (instance: ClientInstance) => ({
+        users: {
+          getUser: () => instance.call<unknown>(makeCallDescriptor()),
+        },
+      }),
+    })
+
+    await client.users.getUser()
+    expect(capturedHeaders[0]?.['x-client']).toBe('web')
+  })
+
+  it('per-call options override defaults — headers merge, per-call wins', async () => {
+    const capturedHeaders: Record<string, string>[] = []
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (req: AdapterRequest): Promise<AdapterResponse> => {
+        capturedHeaders.push(req.headers ?? {})
+        return { status: 200, headers: {}, body: {} }
+      }),
+      stream: vi.fn(async (): Promise<AdapterStreamResponse> => ({
+        status: 200,
+        headers: {},
+        body: makeAsyncIterable([]),
+      })),
+    }
+
+    const client = createClient({
+      adapter,
+      basePath: 'https://api.example.com',
+      defaults: { headers: { 'x-client': 'web', 'x-trace': 'default' } },
+      scopes: (instance: ClientInstance) => ({
+        users: {
+          getUser: (options?: { headers?: Record<string, string> }) =>
+            instance.call<unknown>(makeCallDescriptor(), options),
+        },
+      }),
+    })
+
+    await client.users.getUser({ headers: { 'x-trace': 'override', 'x-extra': 'yes' } })
+    expect(capturedHeaders[0]).toMatchObject({
+      'x-client': 'web',
+      'x-trace': 'override',
+      'x-extra': 'yes',
+    })
+  })
+
+  it('per-call timeout attaches an AbortSignal.timeout signal', async () => {
+    const spy = vi.spyOn(AbortSignal, 'timeout')
+    try {
+      let observedSignal: AbortSignal | undefined
+      const adapter: ClientAdapter = {
+        request: vi.fn(async (req: AdapterRequest): Promise<AdapterResponse> => {
+          observedSignal = req.signal
+          return { status: 200, headers: {}, body: {} }
+        }),
+        stream: vi.fn(async (): Promise<AdapterStreamResponse> => ({
+          status: 200,
+          headers: {},
+          body: makeAsyncIterable([]),
+        })),
+      }
+
+      const client = createClient({
+        adapter,
+        basePath: 'https://api.example.com',
+        scopes: (instance: ClientInstance) => ({
+          users: {
+            call: () => instance.call<unknown>(makeCallDescriptor(), { timeout: 5000 }),
+          },
+        }),
+      })
+
+      await client.users.call()
+      expect(spy).toHaveBeenCalledWith(5000)
+      expect(observedSignal).toBeDefined()
+    } finally {
+      spy.mockRestore()
+    }
+  })
+
+  it('ClientInstance exposes defaults', () => {
+    const adapter = makeAdapter()
+    const defaults = { timeout: 5000, headers: { 'x-client': 'test' } }
+
+    let capturedInstance: ClientInstance | undefined
+    createClient({
+      adapter,
+      basePath: 'https://api.example.com',
+      defaults,
+      scopes: (instance: ClientInstance) => {
+        capturedInstance = instance
+        return {}
+      },
+    })
+
+    expect(capturedInstance?.defaults).toEqual(defaults)
+  })
 })

package/src/client/index.ts

@@ -25,23 +25,37 @@ import type {
  * - The outer `.result` is wired up to the inner stream's `.result`.
  */
 export function createClient<TScopes>(config: CreateClientConfig<TScopes>): TScopes {
-  const { adapter, basePath, hooks: globalHooks = {}, scopes } = config
+  const {
+    adapter,
+    basePath,
+    hooks: globalHooks = {},
+    defaults: globalDefaults = {},
+    scopes,
+  } = config
 
   const instance: ClientInstance = {
     basePath,
     adapter,
     hooks: globalHooks,
+    defaults: globalDefaults,
 
     call<TResponse>(
       descriptor: CallDescriptor,
-      options?: ProcedureCallOptions
+      options?: ProcedureCallOptions,
     ): Promise<TResponse> {
-      return executeCall<TResponse>(descriptor, basePath, adapter, globalHooks, options)
+      return executeCall<TResponse>({
+        descriptor,
+        basePath,
+        adapter,
+        hooks: globalHooks,
+        defaults: globalDefaults,
+        options,
+      })
     },
 
     stream<TYield, TReturn>(
       descriptor: StreamDescriptor,
-      options?: ProcedureCallOptions
+      options?: ProcedureCallOptions,
     ): TypedStream<TYield, TReturn> {
       // executeStream is async but stream() must be synchronous.
       // Create a deferred TypedStream that wraps the async executeStream call.
@@ -58,13 +72,14 @@ export function createClient<TScopes>(config: CreateClientConfig<TScopes>): TSco
       async function* deferredGenerator(): AsyncGenerator<TYield> {
         let innerStream: TypedStream<TYield, TReturn>
         try {
-          innerStream = await executeStream<TYield, TReturn>(
+          innerStream = await executeStream<TYield, TReturn>({
             descriptor,
             basePath,
             adapter,
-            globalHooks,
-            options
-          )
+            hooks: globalHooks,
+            defaults: globalDefaults,
+            options,
+          })
         } catch (err) {
           rejectResult(err)
           throw err
@@ -107,8 +122,10 @@ export type {
   StreamDescriptor,
   TypedStream,
   ClientInstance,
+  ProcedureCallDefaults,
   ProcedureCallOptions,
   CreateClientConfig,
+  RequestMeta,
 } from './types.js'
 
 export { ClientRequestError, ClientPathParamError, ClientStreamError } from './errors.js'