ts-procedures 5.15.0 → 6.0.0

package/src/client/error-dispatch.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from 'vitest'
+import { dispatchTypedError } from './error-dispatch.js'
+import type { ErrorRegistry, ErrorResponseMeta } from './types.js'
+
+class SyntheticError extends Error {
+  constructor(
+    message: string,
+    readonly props: string[]
+  ) {
+    super(message)
+    this.name = 'SyntheticError'
+    Object.setPrototypeOf(this, SyntheticError.prototype)
+  }
+}
+
+const meta: ErrorResponseMeta = { status: 422, procedureName: 'Test', scope: 'users' }
+
+function makeRegistry(): ErrorRegistry {
+  return {
+    SyntheticError: {
+      fromResponse(body, m) {
+        const b = body as { message: string; props: string[] }
+        return new SyntheticError(b.message, b.props)
+      },
+    },
+  }
+}
+
+describe('dispatchTypedError', () => {
+  test('returns a typed error when body.name matches a registry key', () => {
+    const err = dispatchTypedError(
+      makeRegistry(),
+      { name: 'SyntheticError', message: 'bad', props: ['x'] },
+      meta
+    )
+    expect(err).toBeInstanceOf(SyntheticError)
+    expect(err).toBeInstanceOf(Error)
+    expect((err as SyntheticError).props).toEqual(['x'])
+  })
+
+  test('returns null when no registry is provided', () => {
+    const err = dispatchTypedError(undefined, { name: 'SyntheticError' }, meta)
+    expect(err).toBeNull()
+  })
+
+  test('returns null when body is not an object', () => {
+    expect(dispatchTypedError(makeRegistry(), 'oops', meta)).toBeNull()
+    expect(dispatchTypedError(makeRegistry(), null, meta)).toBeNull()
+    expect(dispatchTypedError(makeRegistry(), 42, meta)).toBeNull()
+  })
+
+  test('returns null when body.name is missing or not a string', () => {
+    expect(dispatchTypedError(makeRegistry(), {}, meta)).toBeNull()
+    expect(dispatchTypedError(makeRegistry(), { name: 123 }, meta)).toBeNull()
+  })
+
+  test('returns null when body.name does not match any registry key', () => {
+    expect(
+      dispatchTypedError(makeRegistry(), { name: 'UnregisteredError' }, meta)
+    ).toBeNull()
+  })
+
+  test('returns null when fromResponse returns a non-Error value', () => {
+    const registry: ErrorRegistry = {
+      Broken: {
+        // Intentionally returns a non-Error — defensive guard in dispatch.
+        fromResponse: () => 'not an error' as unknown as Error,
+      },
+    }
+    expect(dispatchTypedError(registry, { name: 'Broken' }, meta)).toBeNull()
+  })
+})

package/src/client/error-dispatch.ts

@@ -0,0 +1,27 @@
+import type { ErrorRegistry, ErrorResponseMeta } from './types.js'
+
+/**
+ * Attempts to construct a typed error from the response body using the
+ * registry. Returns `null` when:
+ *   - no registry is configured,
+ *   - the body is not a plain object with a `name` string,
+ *   - no registry key matches the body's `name`, or
+ *   - `fromResponse` returns a non-Error value (defensive — registry entries
+ *     are expected to return `Error` subclasses).
+ *
+ * Callers fall back to `ClientRequestError` when this returns `null`.
+ */
+export function dispatchTypedError(
+  registry: ErrorRegistry | undefined,
+  body: unknown,
+  meta: ErrorResponseMeta
+): Error | null {
+  if (!registry) return null
+  if (!body || typeof body !== 'object') return null
+  const name = (body as { name?: unknown }).name
+  if (typeof name !== 'string') return null
+  const factory = registry[name]
+  if (!factory?.fromResponse) return null
+  const result = factory.fromResponse(body, meta)
+  return result instanceof Error ? result : null
+}

package/src/client/fetch-adapter.ts

@@ -174,17 +174,23 @@ export function createFetchAdapter(config?: FetchAdapterConfig): ClientAdapter {
       })
 
       const headers = extractHeaders(response)
+      const emptyBody: AsyncIterable<unknown> = {
+        [Symbol.asyncIterator]: async function* () {},
+      }
+
+      // Non-2xx responses on a stream endpoint are JSON, not SSE. Parse the
+      // body eagerly and surface it via errorBody so the client can dispatch
+      // a typed error (or fall back to ClientRequestError with a real body).
+      if (response.status < 200 || response.status >= 300) {
+        const errorBody = await parseResponseBody(response)
+        return { status: response.status, headers, body: emptyBody, errorBody }
+      }
 
       if (!response.body) {
-        // No body — return an empty async iterable
-        const emptyBody: AsyncIterable<unknown> = {
-          [Symbol.asyncIterator]: async function* () {},
-        }
         return { status: response.status, headers, body: emptyBody }
       }
 
       const body = parseSseStream(response.body as ReadableStream<Uint8Array>)
-
       return { status: response.status, headers, body }
     },
   }

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,40 @@ 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 = {},
+    errorRegistry,
+    scopes,
+  } = config
 
   const instance: ClientInstance = {
     basePath,
     adapter,
     hooks: globalHooks,
+    defaults: globalDefaults,
+    errorRegistry,
 
     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,
+        errorRegistry,
+      })
     },
 
     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 +75,15 @@ 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,
+            errorRegistry,
+          })
         } catch (err) {
           rejectResult(err)
           throw err
@@ -107,10 +126,17 @@ export type {
   StreamDescriptor,
   TypedStream,
   ClientInstance,
+  ProcedureCallDefaults,
   ProcedureCallOptions,
   CreateClientConfig,
+  RequestMeta,
+  ErrorRegistry,
+  ErrorFactory,
+  ErrorResponseMeta,
 } from './types.js'
 
+export { dispatchTypedError } from './error-dispatch.js'
+
 export { ClientRequestError, ClientPathParamError, ClientStreamError } from './errors.js'
 
 export { createTypedStream } from './stream.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 }
+}