ts-procedures 6.2.0 → 7.0.0-beta.1

package/src/client/call.ts

@@ -1,15 +1,27 @@
 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 {
+  ClientHttpError,
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+  ClientParseError,
+  ClientPathParamError,
+} from './errors.js'
 import { dispatchTypedError } from './error-dispatch.js'
+import { defaultClassifyError } from './classify-error.js'
 import type {
   ClientAdapter,
   ClientHooks,
   CallDescriptor,
+  ClassifyErrorContext,
   ErrorRegistry,
   ProcedureCallDefaults,
   ProcedureCallOptions,
+  Result,
+  ClientErrorMap,
+  FrameworkFailure,
 } from './types.js'
 
 export interface ExecuteCallConfig {
@@ -32,7 +44,7 @@ export interface ExecuteCallConfig {
  * 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
+ * 7. If response status is non-2xx: throw ClientHttpError
  * 8. Return response.body as TResponse
  */
 export async function executeCall<TResponse>(config: ExecuteCallConfig): Promise<TResponse> {
@@ -43,7 +55,9 @@ export async function executeCall<TResponse>(config: ExecuteCallConfig): Promise
   let request = buildAdapterRequest(descriptor, resolvedBasePath)
 
   // 2. Apply request-level options (headers, signal, timeout, meta)
-  request = applyRequestOptions(request, defaults, options)
+  const applied = applyRequestOptions(request, defaults, options)
+  request = applied.request
+  const signalSources = applied.signalSources
 
   // 3. Run before-request hooks — they may further mutate the request
   const beforeCtx = await runBeforeRequest(
@@ -57,14 +71,36 @@ export async function executeCall<TResponse>(config: ExecuteCallConfig): Promise
   let response
   try {
     response = await adapter.request(request)
-  } catch (err) {
-    // 5. On adapter error: run error hooks, re-throw
+  } catch (rawErr) {
+    // 5. On adapter error: classify (adapter > default > fallthrough), then run
+    //    onError hooks with the normalized error, then throw.
+    const classifyCtx: ClassifyErrorContext = {
+      procedureName: descriptor.name,
+      scope: descriptor.scope,
+      timeoutSignal: signalSources.timeoutSignal,
+      userSignal: signalSources.userSignal,
+      timeoutMs: signalSources.timeoutMs,
+    }
+    const classified =
+      adapter.classifyError?.(rawErr, classifyCtx) ??
+      defaultClassifyError(rawErr, classifyCtx)
+    // Tag the classified error so executeSafeCall can identify its kind without
+    // re-classifying. Default kinds are recognized via instanceof in
+    // classifyThrownError; only custom adapter kinds need an explicit tag.
+    if (classified) {
+      const defaultKinds = new Set(['network', 'timeout', 'aborted', 'parse'])
+      if (!defaultKinds.has(classified.kind)) {
+        ;(classified.error as unknown as { __tsProceduresKind?: string }).__tsProceduresKind = classified.kind
+      }
+    }
+    const finalError = classified?.error ?? rawErr
+
     await runOnError(
-      { procedureName: descriptor.name, scope: descriptor.scope, request, error: err },
+      { procedureName: descriptor.name, scope: descriptor.scope, request, error: finalError },
       hooks,
       options,
     )
-    throw err
+    throw finalError
   }
 
   // 6. Run after-response hooks — they may mutate response.status to swallow errors
@@ -81,8 +117,13 @@ export async function executeCall<TResponse>(config: ExecuteCallConfig): Promise
       procedureName: descriptor.name,
       scope: descriptor.scope,
     })
-    if (typed) throw typed
-    throw new ClientRequestError({
+    if (typed) {
+      // Tag so executeSafeCall can distinguish typed registry errors from plain
+      // ClientHttpError without re-inspecting the registry.
+      ;(typed as unknown as { __tsProceduresTyped?: boolean }).__tsProceduresTyped = true
+      throw typed
+    }
+    throw new ClientHttpError({
       status: response.status,
       headers: response.headers,
       body: response.body,
@@ -94,3 +135,64 @@ export async function executeCall<TResponse>(config: ExecuteCallConfig): Promise
   // 8. Return the body
   return response.body as TResponse
 }
+
+/**
+ * Wraps `executeCall` and returns a discriminated `Result` instead of throwing.
+ *
+ * Three failure-source paths map to distinct kinds:
+ *   1. Pre-adapter throw (e.g. `ClientPathParamError`) → `kind: 'usage'`
+ *   2. Adapter throw, classified → `kind: 'network' | 'timeout' | 'aborted' | <custom> | 'unknown'`
+ *   3. Adapter returns non-2xx → `kind: 'typed'` (registry match) or `kind: 'http'`
+ *
+ * `onError` hook fires on path 2 and 3 (cross-cutting telemetry); NOT on
+ * path 1 (usage errors bypass the classifier and onError entirely).
+ */
+export async function executeSafeCall<TResponse, ETyped = never>(
+  config: ExecuteCallConfig,
+): Promise<Result<TResponse, ETyped>> {
+  try {
+    const value = await executeCall<TResponse>(config)
+    return { ok: true, value }
+  } catch (err) {
+    return classifyThrownError<ETyped>(err)
+  }
+}
+
+function classifyThrownError<ETyped>(err: unknown): Result<never, ETyped> {
+  // Path 1: pre-adapter usage error — bypasses classifier and onError
+  if (err instanceof ClientPathParamError) {
+    return { ok: false, kind: 'usage', error: err }
+  }
+  // Path 3: post-status-check typed registry match — tagged by executeCall
+  if (err instanceof Error && (err as unknown as { __tsProceduresTyped?: boolean }).__tsProceduresTyped) {
+    return { ok: false, kind: 'typed', error: err as ETyped }
+  }
+  // Path 3: non-2xx fallback (no registry match)
+  if (err instanceof ClientHttpError) {
+    return { ok: false, kind: 'http', error: err }
+  }
+  // Path 2: classifier output (already normalized by executeCall)
+  if (err instanceof ClientNetworkError) {
+    return { ok: false, kind: 'network', error: err }
+  }
+  if (err instanceof ClientTimeoutError) {
+    return { ok: false, kind: 'timeout', error: err }
+  }
+  if (err instanceof ClientAbortError) {
+    return { ok: false, kind: 'aborted', error: err }
+  }
+  if (err instanceof ClientParseError) {
+    return { ok: false, kind: 'parse', error: err }
+  }
+  // Custom adapter-classified error — tagged with its kind by executeCall.
+  // The cast is intentional: the framework knows only the default ClientErrorMap
+  // keys, but consumer-augmented kinds are valid at the consumer's site (where
+  // the augmented map is in scope). The runtime kind string is whatever the
+  // adapter classifier returned; we trust it to match a registered entry.
+  if (err instanceof Error && typeof (err as unknown as { __tsProceduresKind?: string }).__tsProceduresKind === 'string') {
+    const kind = (err as unknown as { __tsProceduresKind: string }).__tsProceduresKind
+    return { ok: false, kind: kind as keyof ClientErrorMap, error: err } as FrameworkFailure
+  }
+  // Fallthrough — unrecognized throw type (non-Error or unclassified)
+  return { ok: false, kind: 'unknown', error: err }
+}

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

@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest'
+import { defaultClassifyError } from './classify-error.js'
+import {
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+} from './errors.js'
+
+const meta = { procedureName: 'GetUser', scope: 'users' }
+
+describe('defaultClassifyError', () => {
+  it('classifies fetch TypeError as network', () => {
+    const result = defaultClassifyError(new TypeError('Failed to fetch'), { ...meta })
+    expect(result?.kind).toBe('network')
+    expect(result?.error).toBeInstanceOf(ClientNetworkError)
+    expect(result?.error.cause).toBeInstanceOf(TypeError)
+  })
+
+  it('classifies AbortError as timeout when timeout signal fired', () => {
+    const timeoutSignal = AbortSignal.timeout(0)
+    // wait a tick for the timeout to fire
+    return new Promise<void>((resolve) => setTimeout(() => {
+      const abortErr = new DOMException('aborted', 'AbortError')
+      const result = defaultClassifyError(abortErr, { ...meta, timeoutSignal, timeoutMs: 5000 })
+      expect(result?.kind).toBe('timeout')
+      expect(result?.error).toBeInstanceOf(ClientTimeoutError)
+      expect((result?.error as ClientTimeoutError).timeoutMs).toBe(5000)
+      resolve()
+    }, 1))
+  })
+
+  it('classifies AbortError as aborted when user signal fired', () => {
+    const userController = new AbortController()
+    userController.abort('user-cancelled')
+    const abortErr = new DOMException('aborted', 'AbortError')
+    const result = defaultClassifyError(abortErr, { ...meta, userSignal: userController.signal })
+    expect(result?.kind).toBe('aborted')
+    expect(result?.error).toBeInstanceOf(ClientAbortError)
+    expect((result?.error as ClientAbortError).reason).toBe('user-cancelled')
+  })
+
+  it('classifies AbortError as timeout when both fired (timeout precedence)', () => {
+    const timeoutSignal = AbortSignal.timeout(0)
+    const userController = new AbortController()
+    return new Promise<void>((resolve) => setTimeout(() => {
+      userController.abort('user')
+      const abortErr = new DOMException('aborted', 'AbortError')
+      const result = defaultClassifyError(abortErr, {
+        ...meta, timeoutSignal, timeoutMs: 1, userSignal: userController.signal,
+      })
+      expect(result?.kind).toBe('timeout')
+      resolve()
+    }, 1))
+  })
+
+  it('returns null for unknown errors', () => {
+    const result = defaultClassifyError(new Error('weird'), { ...meta })
+    expect(result).toBeNull()
+  })
+
+  it('returns null for non-Error throws', () => {
+    expect(defaultClassifyError('string-thrown', { ...meta })).toBeNull()
+    expect(defaultClassifyError(42, { ...meta })).toBeNull()
+  })
+})

package/src/client/classify-error.ts

@@ -0,0 +1,59 @@
+import {
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+} from './errors.js'
+import type { ErrorClassifier } from './types.js'
+
+/**
+ * Default classifier — recognizes:
+ *   - `TypeError` from fetch → `ClientNetworkError`
+ *   - `DOMException` with `name: 'AbortError'` + timeout-signal-aborted → `ClientTimeoutError`
+ *   - `DOMException` with `name: 'AbortError'` + user-signal-aborted → `ClientAbortError`
+ *
+ * Returns `null` for anything else. Timeout precedence: when both signals
+ * fired, classifies as `timeout`.
+ */
+export const defaultClassifyError: ErrorClassifier = (raw, ctx) => {
+  const meta = { procedureName: ctx.procedureName, scope: ctx.scope }
+
+  if (raw instanceof TypeError) {
+    return {
+      kind: 'network',
+      error: new ClientNetworkError({ ...meta, cause: raw, message: raw.message }),
+    }
+  }
+
+  if (
+    raw instanceof DOMException &&
+    raw.name === 'AbortError'
+  ) {
+    if (ctx.timeoutSignal?.aborted) {
+      return {
+        kind: 'timeout',
+        error: new ClientTimeoutError({
+          ...meta,
+          timeoutMs: ctx.timeoutMs ?? 0,
+          cause: raw,
+        }),
+      }
+    }
+    if (ctx.userSignal?.aborted) {
+      return {
+        kind: 'aborted',
+        error: new ClientAbortError({
+          ...meta,
+          reason: ctx.userSignal.reason,
+          cause: raw,
+        }),
+      }
+    }
+    // AbortError without a tracked source — treat as user abort with no reason.
+    return {
+      kind: 'aborted',
+      error: new ClientAbortError({ ...meta, cause: raw }),
+    }
+  }
+
+  return null
+}

package/src/client/error-dispatch.ts

@@ -9,7 +9,7 @@ import type { ErrorRegistry, ErrorResponseMeta } from './types.js'
  *   - `fromResponse` returns a non-Error value (defensive — registry entries
  *     are expected to return `Error` subclasses).
  *
- * Callers fall back to `ClientRequestError` when this returns `null`.
+ * Callers fall back to `ClientHttpError` when this returns `null`.
  */
 export function dispatchTypedError(
   registry: ErrorRegistry | undefined,

package/src/client/errors.test.ts

@@ -1,9 +1,40 @@
 import { describe, it, expect } from 'vitest'
-import { ClientRequestError, ClientPathParamError, ClientStreamError } from './errors.js'
+import {
+  ClientHttpError,
+  ClientRequestError,
+  ClientPathParamError,
+  ClientStreamError,
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+  ClientParseError,
+} from './errors.js'
+
+describe('ClientHttpError', () => {
+  it('exposes status, headers, body, procedureName, scope', () => {
+    const err = new ClientHttpError({
+      status: 500, headers: { 'x-trace': 'abc' }, body: { error: 'boom' },
+      procedureName: 'GetUser', scope: 'users',
+    })
+    expect(err.status).toBe(500)
+    expect(err.headers['x-trace']).toBe('abc')
+    expect(err.body).toEqual({ error: 'boom' })
+    expect(err.procedureName).toBe('GetUser')
+    expect(err.scope).toBe('users')
+    expect(err.name).toBe('ClientHttpError')
+  })
+
+  it('accepts cause', () => {
+    const cause = new Error('underlying')
+    const err = new ClientHttpError({
+      status: 500, headers: {}, body: null,
+      procedureName: 'X', scope: 'y', cause,
+    })
+    expect(err.cause).toBe(cause)
+  })
 
-describe('ClientRequestError', () => {
   it('includes status, headers, and body', () => {
-    const err = new ClientRequestError({
+    const err = new ClientHttpError({
       status: 401,
       headers: { 'x-request-id': 'abc' },
       body: { message: 'Unauthorized' },
@@ -11,7 +42,7 @@ describe('ClientRequestError', () => {
       scope: 'users',
     })
     expect(err).toBeInstanceOf(Error)
-    expect(err.name).toBe('ClientRequestError')
+    expect(err.name).toBe('ClientHttpError')
     expect(err.status).toBe(401)
     expect(err.headers['x-request-id']).toBe('abc')
     expect(err.body).toEqual({ message: 'Unauthorized' })
@@ -21,6 +52,23 @@ describe('ClientRequestError', () => {
   })
 })
 
+describe('ClientRequestError deprecated alias', () => {
+  it('is identical to ClientHttpError', () => {
+    expect(ClientRequestError).toBe(ClientHttpError)
+  })
+
+  it('instanceof check works against thrown ClientHttpError', () => {
+    // Consumers on the previous major used `catch (e) { if (e instanceof
+    // ClientRequestError) ... }`. The alias must keep that pattern working
+    // until the alias is removed in the next minor cycle's deprecation window.
+    const err = new ClientHttpError({
+      status: 500, headers: {}, body: null,
+      procedureName: 'X', scope: 'y',
+    })
+    expect(err instanceof ClientRequestError).toBe(true)
+  })
+})
+
 describe('ClientPathParamError', () => {
   it('reports missing param', () => {
     const err = new ClientPathParamError('id', '/users/:id', 'GetUser')
@@ -29,6 +77,12 @@ describe('ClientPathParamError', () => {
     expect(err.message).toContain('id')
     expect(err.message).toContain('/users/:id')
   })
+
+  it('accepts and stores cause', () => {
+    const cause = new TypeError('underlying')
+    const err = new ClientPathParamError('id', '/u/:id', 'GetUser', cause)
+    expect(err.cause).toBe(cause)
+  })
 })
 
 describe('ClientStreamError', () => {
@@ -40,4 +94,54 @@ describe('ClientStreamError', () => {
     expect(err.scope).toBe('events')
     expect(err.message).toBe('stream interrupted')
   })
+
+  it('accepts and stores cause', () => {
+    const cause = new Error('underlying')
+    const err = new ClientStreamError('boom', 'StreamUsers', 'users', cause)
+    expect(err.cause).toBe(cause)
+  })
+})
+
+describe('ClientNetworkError', () => {
+  it('carries procedureName, scope, cause', () => {
+    const cause = new TypeError('fetch failed')
+    const err = new ClientNetworkError({
+      procedureName: 'X', scope: 'y', cause,
+    })
+    expect(err.name).toBe('ClientNetworkError')
+    expect(err.procedureName).toBe('X')
+    expect(err.scope).toBe('y')
+    expect(err.cause).toBe(cause)
+  })
+})
+
+describe('ClientTimeoutError', () => {
+  it('carries timeoutMs', () => {
+    const err = new ClientTimeoutError({
+      procedureName: 'X', scope: 'y', timeoutMs: 5000,
+    })
+    expect(err.name).toBe('ClientTimeoutError')
+    expect(err.timeoutMs).toBe(5000)
+  })
+})
+
+describe('ClientAbortError', () => {
+  it('carries reason from abort signal', () => {
+    const err = new ClientAbortError({
+      procedureName: 'X', scope: 'y', reason: 'user-cancelled',
+    })
+    expect(err.name).toBe('ClientAbortError')
+    expect(err.reason).toBe('user-cancelled')
+  })
+})
+
+describe('ClientParseError', () => {
+  it('carries procedureName, scope, cause', () => {
+    const cause = new SyntaxError('Unexpected token')
+    const err = new ClientParseError({
+      procedureName: 'X', scope: 'y', cause,
+    })
+    expect(err.name).toBe('ClientParseError')
+    expect(err.cause).toBe(cause)
+  })
 })

package/src/client/errors.ts

@@ -1,5 +1,5 @@
-export class ClientRequestError extends Error {
-  readonly name = 'ClientRequestError'
+export class ClientHttpError extends Error {
+  readonly name = 'ClientHttpError'
   readonly status: number
   readonly headers: Record<string, string>
   readonly body: unknown
@@ -12,8 +12,12 @@ export class ClientRequestError extends Error {
     body: unknown
     procedureName: string
     scope: string
+    cause?: unknown
   }) {
-    super(`${opts.procedureName} (${opts.scope}) failed with status ${opts.status}`)
+    super(
+      `${opts.procedureName} (${opts.scope}) failed with status ${opts.status}`,
+      { cause: opts.cause }
+    )
     this.status = opts.status
     this.headers = opts.headers
     this.body = opts.body
@@ -22,11 +26,18 @@ export class ClientRequestError extends Error {
   }
 }
 
+/** @deprecated Renamed to `ClientHttpError`. The alias is retained for one minor release after the 7.0.0 major bump and will be removed in a subsequent minor (e.g. 7.1.0). Migrate to `ClientHttpError` now. */
+// eslint-disable-next-line no-redeclare
+export const ClientRequestError = ClientHttpError
+/** @deprecated Renamed to `ClientHttpError`. The alias is retained for one minor release after the 7.0.0 major bump and will be removed in a subsequent minor (e.g. 7.1.0). Migrate to `ClientHttpError` now. */
+// eslint-disable-next-line no-redeclare
+export type ClientRequestError = ClientHttpError
+
 export class ClientPathParamError extends Error {
   readonly name = 'ClientPathParamError'
 
-  constructor(param: string, path: string, procedureName: string) {
-    super(`Missing path parameter "${param}" in "${path}" for procedure ${procedureName}`)
+  constructor(param: string, path: string, procedureName: string, cause?: unknown) {
+    super(`Missing path parameter "${param}" in "${path}" for procedure ${procedureName}`, { cause })
   }
 }
 
@@ -35,9 +46,61 @@ export class ClientStreamError extends Error {
   readonly procedureName: string
   readonly scope: string
 
-  constructor(message: string, procedureName: string, scope: string) {
-    super(message)
+  constructor(message: string, procedureName: string, scope: string, cause?: unknown) {
+    super(message, { cause })
     this.procedureName = procedureName
     this.scope = scope
   }
 }
+
+export class ClientNetworkError extends Error {
+  readonly name = 'ClientNetworkError'
+  readonly procedureName: string
+  readonly scope: string
+
+  constructor(opts: { procedureName: string; scope: string; cause?: unknown; message?: string }) {
+    super(opts.message ?? `${opts.procedureName} (${opts.scope}) failed: network error`, { cause: opts.cause })
+    this.procedureName = opts.procedureName
+    this.scope = opts.scope
+  }
+}
+
+export class ClientTimeoutError extends Error {
+  readonly name = 'ClientTimeoutError'
+  readonly procedureName: string
+  readonly scope: string
+  readonly timeoutMs: number
+
+  constructor(opts: { procedureName: string; scope: string; timeoutMs: number; cause?: unknown }) {
+    super(`${opts.procedureName} (${opts.scope}) timed out after ${opts.timeoutMs}ms`, { cause: opts.cause })
+    this.procedureName = opts.procedureName
+    this.scope = opts.scope
+    this.timeoutMs = opts.timeoutMs
+  }
+}
+
+export class ClientAbortError extends Error {
+  readonly name = 'ClientAbortError'
+  readonly procedureName: string
+  readonly scope: string
+  readonly reason: unknown
+
+  constructor(opts: { procedureName: string; scope: string; reason?: unknown; cause?: unknown }) {
+    super(`${opts.procedureName} (${opts.scope}) aborted`, { cause: opts.cause })
+    this.procedureName = opts.procedureName
+    this.scope = opts.scope
+    this.reason = opts.reason
+  }
+}
+
+export class ClientParseError extends Error {
+  readonly name = 'ClientParseError'
+  readonly procedureName: string
+  readonly scope: string
+
+  constructor(opts: { procedureName: string; scope: string; cause?: unknown; message?: string }) {
+    super(opts.message ?? `${opts.procedureName} (${opts.scope}) response could not be parsed`, { cause: opts.cause })
+    this.procedureName = opts.procedureName
+    this.scope = opts.scope
+  }
+}

package/src/client/fetch-adapter.test.ts

@@ -338,3 +338,18 @@ describe('createFetchAdapter — stream()', () => {
     expect(items).toEqual([{ data: { ok: true }, event: 'message', id: undefined }])
   })
 })
+
+// ── classifyError config ──────────────────────────────
+
+describe('createFetchAdapter classifyError', () => {
+  it('passes through to adapter.classifyError', () => {
+    const customClassifier = vi.fn()
+    const adapter = createFetchAdapter({ classifyError: customClassifier })
+    expect(adapter.classifyError).toBe(customClassifier)
+  })
+
+  it('does not set classifyError when not provided', () => {
+    const adapter = createFetchAdapter()
+    expect(adapter.classifyError).toBeUndefined()
+  })
+})

package/src/client/fetch-adapter.ts

@@ -1,9 +1,10 @@
-import type { ClientAdapter, AdapterRequest, AdapterResponse, AdapterStreamResponse } from './types.js'
+import type { ClientAdapter, AdapterRequest, AdapterResponse, AdapterStreamResponse, ErrorClassifier } from './types.js'
 
 // ── Config ────────────────────────────────────────────────
 
 export interface FetchAdapterConfig {
   headers?: Record<string, string>
+  classifyError?: ErrorClassifier
 }
 
 // ── SSE parser ────────────────────────────────────────────
@@ -180,7 +181,7 @@ export function createFetchAdapter(config?: FetchAdapterConfig): ClientAdapter {
 
       // 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).
+      // a typed error (or fall back to ClientHttpError with a real body).
       if (response.status < 200 || response.status >= 300) {
         const errorBody = await parseResponseBody(response)
         return { status: response.status, headers, body: emptyBody, errorBody }
@@ -193,5 +194,7 @@ export function createFetchAdapter(config?: FetchAdapterConfig): ClientAdapter {
       const body = parseSseStream(response.body as ReadableStream<Uint8Array>)
       return { status: response.status, headers, body }
     },
+
+    classifyError: config?.classifyError,
   }
 }