ts-procedures 5.15.0 → 5.16.0

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 }
+}