ts-procedures 5.14.0 → 5.16.0

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'

package/src/client/resolve-options.test.ts

@@ -0,0 +1,205 @@
+import { describe, it, expect, vi } from 'vitest'
+import {
+  applyRequestOptions,
+  resolveBasePath,
+  resolveHeaders,
+  resolveMeta,
+  resolveSignal,
+} from './resolve-options.js'
+import type { AdapterRequest, ProcedureCallDefaults, ProcedureCallOptions } from './types.js'
+
+// ── resolveBasePath ───────────────────────────────────────
+
+describe('resolveBasePath', () => {
+  it('uses fallback when nothing is set', () => {
+    expect(resolveBasePath(undefined, undefined, 'https://api.example.com')).toBe(
+      'https://api.example.com',
+    )
+  })
+
+  it('uses default when only defaults.basePath is set', () => {
+    expect(
+      resolveBasePath({ basePath: 'https://default.example.com' }, undefined, 'https://fallback'),
+    ).toBe('https://default.example.com')
+  })
+
+  it('per-call basePath overrides default', () => {
+    expect(
+      resolveBasePath(
+        { basePath: 'https://default.example.com' },
+        { basePath: 'https://percall.example.com' },
+        'https://fallback',
+      ),
+    ).toBe('https://percall.example.com')
+  })
+})
+
+// ── resolveHeaders ────────────────────────────────────────
+
+describe('resolveHeaders', () => {
+  it('returns undefined when neither side sets headers', () => {
+    expect(resolveHeaders(undefined, undefined)).toBeUndefined()
+  })
+
+  it('returns default headers when only defaults set', () => {
+    expect(resolveHeaders({ headers: { 'x-a': '1' } }, undefined)).toEqual({ 'x-a': '1' })
+  })
+
+  it('per-call keys override default keys', () => {
+    const defaults: ProcedureCallDefaults = { headers: { 'x-a': 'default', 'x-b': 'keep' } }
+    const options: ProcedureCallOptions = { headers: { 'x-a': 'override' } }
+    expect(resolveHeaders(defaults, options)).toEqual({
+      'x-a': 'override',
+      'x-b': 'keep',
+    })
+  })
+})
+
+// ── resolveMeta ───────────────────────────────────────────
+
+describe('resolveMeta', () => {
+  it('returns undefined when neither side sets meta', () => {
+    expect(resolveMeta(undefined, undefined)).toBeUndefined()
+  })
+
+  it('merges default + per-call meta (shallow), per-call keys win', () => {
+    const defaults: ProcedureCallDefaults = { meta: { a: 1, b: 2 } as never }
+    const options: ProcedureCallOptions = { meta: { b: 99, c: 3 } as never }
+    expect(resolveMeta(defaults, options)).toEqual({ a: 1, b: 99, c: 3 })
+  })
+})
+
+// ── resolveSignal ─────────────────────────────────────────
+
+describe('resolveSignal', () => {
+  it('returns undefined when nothing is set', () => {
+    expect(resolveSignal(undefined, undefined)).toBeUndefined()
+  })
+
+  it('returns the default signal when no timeout and no per-call signal', () => {
+    const controller = new AbortController()
+    expect(resolveSignal({ signal: controller.signal }, undefined)).toBe(controller.signal)
+  })
+
+  it('returns the per-call signal when no default and no timeout', () => {
+    const controller = new AbortController()
+    expect(resolveSignal(undefined, { signal: controller.signal })).toBe(controller.signal)
+  })
+
+  it('combines default + per-call signals — default aborts combined signal', () => {
+    const defaultCtrl = new AbortController()
+    const callCtrl = new AbortController()
+    const signal = resolveSignal({ signal: defaultCtrl.signal }, { signal: callCtrl.signal })!
+
+    expect(signal.aborted).toBe(false)
+    defaultCtrl.abort(new Error('default-abort'))
+    expect(signal.aborted).toBe(true)
+  })
+
+  it('combines default + per-call signals — per-call aborts combined signal', () => {
+    const defaultCtrl = new AbortController()
+    const callCtrl = new AbortController()
+    const signal = resolveSignal({ signal: defaultCtrl.signal }, { signal: callCtrl.signal })!
+
+    callCtrl.abort(new Error('call-abort'))
+    expect(signal.aborted).toBe(true)
+  })
+
+  it('applies timeout via AbortSignal.timeout', () => {
+    const spy = vi.spyOn(AbortSignal, 'timeout')
+    try {
+      const signal = resolveSignal(undefined, { timeout: 100 })
+      expect(spy).toHaveBeenCalledWith(100)
+      expect(signal).toBeDefined()
+    } finally {
+      spy.mockRestore()
+    }
+  })
+
+  it('per-call timeout overrides default timeout', () => {
+    const spy = vi.spyOn(AbortSignal, 'timeout')
+    try {
+      resolveSignal({ timeout: 10_000 }, { timeout: 100 })
+      expect(spy).toHaveBeenCalledWith(100)
+      expect(spy).not.toHaveBeenCalledWith(10_000)
+    } finally {
+      spy.mockRestore()
+    }
+  })
+
+  it('combines signal + timeout — signal aborts first', () => {
+    const controller = new AbortController()
+    const signal = resolveSignal(undefined, { signal: controller.signal, timeout: 10_000 })!
+    expect(signal.aborted).toBe(false)
+    controller.abort()
+    expect(signal.aborted).toBe(true)
+  })
+
+  it('per-call timeout: 0 disables default timeout', () => {
+    const signal = resolveSignal({ timeout: 1000 }, { timeout: 0 })
+    expect(signal).toBeUndefined()
+  })
+})
+
+// ── applyRequestOptions ───────────────────────────────────
+
+describe('applyRequestOptions', () => {
+  const baseRequest: AdapterRequest = {
+    url: 'https://api.example.com/foo',
+    method: 'POST',
+    body: { hello: 'world' },
+  }
+
+  it('returns the request unchanged when nothing is provided', () => {
+    const result = applyRequestOptions(baseRequest, undefined, undefined)
+    expect(result.url).toBe(baseRequest.url)
+    expect(result.body).toEqual({ hello: 'world' })
+    expect(result.headers).toBeUndefined()
+    expect(result.signal).toBeUndefined()
+    expect(result.meta).toBeUndefined()
+  })
+
+  it('merges default + per-call headers, preserving route-declared headers', () => {
+    const reqWithHeaders: AdapterRequest = {
+      ...baseRequest,
+      headers: { 'content-type': 'application/json', 'x-route': 'declared' },
+    }
+    const result = applyRequestOptions(
+      reqWithHeaders,
+      { headers: { 'x-default': 'd', 'x-route': 'from-default' } },
+      { headers: { 'x-call': 'c', 'x-route': 'from-call' } },
+    )
+    expect(result.headers).toEqual({
+      'x-default': 'd',
+      'x-call': 'c',
+      // Route-declared headers WIN over resolved options (typed contract)
+      'content-type': 'application/json',
+      'x-route': 'declared',
+    })
+  })
+
+  it('attaches meta to the request when provided', () => {
+    const result = applyRequestOptions(baseRequest, undefined, {
+      meta: { traceId: 'abc' } as never,
+    })
+    expect(result.meta).toEqual({ traceId: 'abc' })
+  })
+
+  it('passes per-call signal through', () => {
+    const controller = new AbortController()
+    const result = applyRequestOptions(baseRequest, undefined, { signal: controller.signal })
+    expect(result.signal).toBe(controller.signal)
+  })
+
+  it('attaches a signal when per-call timeout is set', () => {
+    const spy = vi.spyOn(AbortSignal, 'timeout')
+    try {
+      const result = applyRequestOptions(baseRequest, undefined, { timeout: 100 })
+      expect(spy).toHaveBeenCalledWith(100)
+      expect(result.signal).toBeDefined()
+      expect(result.signal?.aborted).toBe(false)
+    } finally {
+      spy.mockRestore()
+    }
+  })
+})

package/src/client/resolve-options.ts

@@ -0,0 +1,113 @@
+import type {
+  AdapterRequest,
+  ProcedureCallDefaults,
+  ProcedureCallOptions,
+  RequestMeta,
+} from './types.js'
+
+/**
+ * Resolves the effective base path:
+ *   per-call `basePath` > default `basePath` > config `basePath` (fallback).
+ */
+export function resolveBasePath(
+  defaults: ProcedureCallDefaults | undefined,
+  options: ProcedureCallOptions | undefined,
+  fallback: string,
+): string {
+  return options?.basePath ?? defaults?.basePath ?? fallback
+}
+
+/**
+ * Resolves the effective AbortSignal by combining (via `AbortSignal.any`):
+ *   - default signal (if any)
+ *   - per-call signal (if any)
+ *   - timeout signal (if resolved timeout > 0)
+ *
+ * Returns undefined when none apply. Per-call `timeout: 0` disables an
+ * inherited default timeout.
+ */
+export function resolveSignal(
+  defaults: ProcedureCallDefaults | undefined,
+  options: ProcedureCallOptions | undefined,
+): AbortSignal | undefined {
+  const signals: AbortSignal[] = []
+
+  if (defaults?.signal) signals.push(defaults.signal)
+  if (options?.signal) signals.push(options.signal)
+
+  const timeout = options?.timeout ?? defaults?.timeout
+  if (timeout != null && timeout > 0) {
+    signals.push(AbortSignal.timeout(timeout))
+  }
+
+  if (signals.length === 0) return undefined
+  if (signals.length === 1) return signals[0]
+  return AbortSignal.any(signals)
+}
+
+/**
+ * Merges headers with precedence: default < per-call. Returns undefined if
+ * no headers would be set.
+ */
+export function resolveHeaders(
+  defaults: ProcedureCallDefaults | undefined,
+  options: ProcedureCallOptions | undefined,
+): Record<string, string> | undefined {
+  const defaultHeaders = defaults?.headers
+  const callHeaders = options?.headers
+
+  if (!defaultHeaders && !callHeaders) return undefined
+
+  return { ...defaultHeaders, ...callHeaders }
+}
+
+/**
+ * Merges meta with precedence: default < per-call. Returns undefined if
+ * no meta fields would be set.
+ *
+ * The cast is load-bearing: when a developer augments `RequestMeta` with
+ * required fields, spread of two `RequestMeta | undefined` values widens to
+ * a partial shape, which TypeScript can't prove satisfies `RequestMeta`.
+ * At runtime, the merged object carries whichever keys the caller supplied —
+ * the contract is "if you declare required fields in RequestMeta, supply them
+ * somewhere (defaults or per-call)."
+ */
+export function resolveMeta(
+  defaults: ProcedureCallDefaults | undefined,
+  options: ProcedureCallOptions | undefined,
+): RequestMeta | undefined {
+  const defaultMeta = defaults?.meta
+  const callMeta = options?.meta
+
+  if (!defaultMeta && !callMeta) return undefined
+
+  return { ...defaultMeta, ...callMeta } as RequestMeta
+}
+
+/**
+ * Applies resolved default + per-call options to an AdapterRequest.
+ *
+ * Runs before hooks, so `onBeforeRequest` observes the merged request and can
+ * still override any field.
+ *
+ * Headers produced by the request builder (e.g., `schema.input.headers` for
+ * API routes) are preserved; resolved headers merge underneath them so the
+ * route-declared headers win, matching the adapter.config → defaults → call
+ * → route-declared → hooks precedence chain documented in the types.
+ */
+export function applyRequestOptions(
+  request: AdapterRequest,
+  defaults: ProcedureCallDefaults | undefined,
+  options: ProcedureCallOptions | undefined,
+): AdapterRequest {
+  const signal = resolveSignal(defaults, options)
+  const resolvedHeaders = resolveHeaders(defaults, options)
+  const meta = resolveMeta(defaults, options)
+
+  const headers =
+    resolvedHeaders || request.headers
+      ? { ...resolvedHeaders, ...request.headers }
+      : undefined
+
+  return { ...request, headers, signal, meta }
+}