ts-procedures 6.2.0 → 7.0.0-beta.1

package/docs/client-error-handling.md

@@ -0,0 +1,357 @@
+# Client Error Handling
+
+Canonical reference for downstream developers using ts-procedures generated clients to handle errors.
+
+## 1. Two Forms — Pick Either, Mix as Needed
+
+Every generated RPC and API callable supports two equivalent call styles.
+
+**Throwing form** (the canonical form): the call returns the response directly or throws a typed error class.
+
+```ts
+const response = await client.users.GetUser({ userId })
+```
+
+**`.safe()` form**: the call always resolves (never rejects) and returns a discriminated `Result<T, E>`. Useful when you want exhaustive failure handling with TypeScript narrowing inside an exhaustive `switch`.
+
+```ts
+const r = await client.users.GetUser.safe({ userId })
+if (r.ok) {
+  // r.value is typed as the response
+} else {
+  // r.kind narrows the failure category
+}
+```
+
+Both forms fire the same hooks, respect the same defaults, and go through the same error registry. You can mix them freely — per call site, use whichever reads most naturally.
+
+> Note: `.safe()` is only available on RPC and API callables. Stream callables keep the throwing form — their failure surface (mid-stream errors, backpressure, early disconnection) does not fit cleanly into `Result<T, E>`.
+
+---
+
+## 2. Framework Error Class Taxonomy
+
+All framework error classes are exported from `ts-procedures/client` (or from `./_types` in self-contained generated clients).
+
+| Class | When it is thrown | Notable properties |
+|---|---|---|
+| `ClientHttpError` | Adapter returned a non-2xx response and no error registry entry matched | `status`, `headers`, `body`, `procedureName`, `scope`, `cause` |
+| `ClientNetworkError` | Adapter threw a `TypeError` (e.g., DNS failure, connection refused) | `procedureName`, `scope`, `cause` |
+| `ClientTimeoutError` | The request was aborted because the timeout signal fired | `procedureName`, `scope`, `timeoutMs`, `cause` |
+| `ClientAbortError` | The request was aborted because a user-supplied signal fired | `procedureName`, `scope`, `reason`, `cause` |
+| `ClientPathParamError` | A required path parameter was missing when building the request | `cause` |
+| `ClientParseError` | Reserved for adapter authors who want stricter response-body parsing | `procedureName`, `scope`, `cause` |
+| `ClientStreamError` | A mid-stream SSE error event was received | `procedureName`, `scope`, `cause` |
+
+Every class carries `cause` to surface the underlying platform error — typically a `TypeError` or `DOMException` — when one exists.
+
+`ClientRequestError` is a deprecated alias for `ClientHttpError`. It is retained for one minor release after 7.0.0 and will be removed in a subsequent minor. See the [migration guide](#8-migration-6x--7x) below.
+
+---
+
+## 3. Throwing Form: Narrowing Pattern
+
+The throwing form is the most common pattern. Catch the error and narrow by class:
+
+```ts
+import { ClientHttpError, ClientTimeoutError, ClientNetworkError, ClientAbortError } from 'ts-procedures/client'
+// ApiErrors is exported from your generated index, e.g.:
+// import { ApiErrors } from './generated'
+
+try {
+  const response = await client.records.DownloadRecord(
+    { body: { recordId } },
+    { timeout: 60_000 },
+  )
+  if (response.pdfBase64) downloadBase64AsPdf(response.pdfBase64)
+} catch (err) {
+  if (err instanceof ApiErrors.UseCaseError) {
+    // Typed error declared on the route — strongly typed body
+    Alerts.error(err.body.message)
+  } else if (err instanceof ClientHttpError) {
+    Alerts.error(`Server returned ${err.status}`)
+  } else if (err instanceof ClientTimeoutError) {
+    Alerts.error('Request timed out')
+  } else if (err instanceof ClientNetworkError) {
+    Alerts.error('Network error — check your connection')
+  } else if (err instanceof ClientAbortError) {
+    // User cancelled — silent
+  } else {
+    throw err  // Programmer or framework bug — fail loud
+  }
+}
+```
+
+`ApiErrors.UseCaseError` is illustrative. The actual namespace is `${ServiceName}Errors` based on your `--service-name` codegen option (default: `ApiErrors`). Each error class name matches the key you declared in your server-side error taxonomy.
+
+The `else { throw err }` rethrow at the end is intentional: any error that slips past all your `instanceof` checks is a bug — do not swallow it.
+
+---
+
+## 4. `.safe()` Form: Exhaustive Narrowing
+
+The same operation rewritten with `.safe()`. The call never rejects. `r.ok` is the top-level gate; `r.kind` narrows the failure:
+
+```ts
+import { ApiErrors } from './generated'
+
+const r = await client.records.DownloadRecord.safe(
+  { body: { recordId } },
+  { timeout: 60_000 },
+)
+
+if (r.ok) {
+  if (r.value.pdfBase64) downloadBase64AsPdf(r.value.pdfBase64)
+  return
+}
+
+switch (r.kind) {
+  case 'typed':
+    if (r.error instanceof ApiErrors.UseCaseError) Alerts.error(r.error.body.message)
+    break
+  case 'http':
+    Alerts.error(`Server returned ${r.error.status}`)
+    break
+  case 'network':
+    Alerts.error('Network error')
+    break
+  case 'timeout':
+    Alerts.error('Request timed out')
+    break
+  case 'aborted':
+    break  // User cancelled — silent
+  case 'parse':
+  case 'usage':
+    throw r.error  // Programmer or framework bug — fail loud
+  case 'unknown':
+    Alerts.error('Unknown error')
+    console.error(r.error)
+    break
+}
+```
+
+The `Result<T, E>` type is:
+
+```ts
+type Result<T, ETyped> =
+  | { ok: true; value: T }
+  | { ok: false; kind: 'typed'; error: ETyped }   // route-declared, registry-dispatched
+  | { ok: false; kind: 'http'; error: ClientHttpError }
+  | { ok: false; kind: 'network'; error: ClientNetworkError }
+  | { ok: false; kind: 'timeout'; error: ClientTimeoutError }
+  | { ok: false; kind: 'aborted'; error: ClientAbortError }
+  | { ok: false; kind: 'parse'; error: ClientParseError }
+  | { ok: false; kind: 'usage'; error: ClientPathParamError }
+  | { ok: false; kind: 'unknown'; error: unknown }
+```
+
+When a route declares no typed errors, the generated callable returns `ResultNoTyped<T>` — the `kind: 'typed'` arm is omitted entirely so IDE hovers stay clean.
+
+---
+
+## 5. The Three Failure-Source Paths
+
+Understanding where errors originate helps you know what to expect at each stage:
+
+| # | Stage | Source of failure | Resulting kind(s) |
+|---|---|---|---|
+| 1 | **Pre-adapter** | `buildAdapterRequest` throws synchronously (e.g. missing path param) | `'usage'` (`ClientPathParamError`) — bypasses the classifier and `onError` hook |
+| 2 | **Adapter throws** | `adapter.request()` rejects (network failure, abort, or custom) | `'network'` / `'timeout'` / `'aborted'` / custom kinds / `'unknown'` |
+| 3 | **Adapter returns non-2xx** | `response.status < 200` or `>= 300` | `'typed'` (registry match) or `'http'` (no match → `ClientHttpError`) |
+
+Stage 1 (`'usage'`) is always a programming error — a required path parameter is absent. These bypass `onError` and the error classifier because the request was never sent.
+
+Stage 2 errors go through `adapter.classifyError` (if present) then `defaultClassifyError`. Anything the classifier does not recognise lands as `'unknown'`.
+
+Stage 3: when a non-2xx response body has a `name` field that matches an entry in the error registry, the client constructs and throws the matching typed error class. When no entry matches, the client throws `ClientHttpError`.
+
+---
+
+## 6. Custom Error Categories — `ClientErrorMap` Augmentation
+
+The `kind` discriminant set is open for extension via TypeScript declaration merging. This lets you teach the type system about custom error kinds produced by your adapter:
+
+```ts
+// Declare the new kind once in your app — usually alongside your adapter setup.
+class RateLimitError extends Error {
+  constructor(public retryAfter: number) {
+    super('rate limited')
+  }
+}
+
+// With the standard (non-self-contained) client:
+declare module 'ts-procedures/client' {
+  interface ClientErrorMap {
+    rateLimited: RateLimitError
+  }
+}
+```
+
+For self-contained generated clients, the augmentation target shifts to the bundled types file:
+
+```ts
+// With a self-contained (code-generated) client:
+declare module './generated/_types' {
+  interface ClientErrorMap {
+    rateLimited: RateLimitError
+  }
+}
+```
+
+This is the same pattern as `RequestMeta` augmentation — if you have used that, this is identical.
+
+After augmentation, `Result`'s union expands automatically. The new `kind` is exhaustively narrowable in every `.safe()` switch:
+
+```ts
+const r = await client.records.DownloadRecord.safe({ body: { recordId } })
+if (!r.ok && r.kind === 'rateLimited') {
+  Alerts.error(`Retry in ${r.error.retryAfter}s`)
+}
+```
+
+**`'typed'` is reserved.** Do not add it to your `ClientErrorMap` augmentation — it is used internally for route-declared errors dispatched via the codegen `errors` key. Adding it produces a TypeScript error about overlapping discriminants.
+
+---
+
+## 7. Adapter-Side Classifier Composition
+
+Custom error kinds only flow through the `Result` union if the adapter's classifier produces them. Configure the classifier on `createFetchAdapter`:
+
+```ts
+import { createFetchAdapter, defaultClassifyError } from 'ts-procedures/client'
+
+const adapter = createFetchAdapter({
+  classifyError: (raw, ctx) => {
+    if (raw instanceof MyRateLimitError) {
+      return { kind: 'rateLimited', error: raw }
+    }
+    // Fall through to the built-in classifier for TypeError / DOMException / etc.
+    return defaultClassifyError(raw, ctx)
+  },
+})
+```
+
+`defaultClassifyError` handles:
+- `TypeError` → `ClientNetworkError` (`kind: 'network'`)
+- `DOMException { name: 'AbortError' }` + timeout signal aborted → `ClientTimeoutError` (`kind: 'timeout'`)
+- `DOMException { name: 'AbortError' }` + user signal aborted → `ClientAbortError` (`kind: 'aborted'`)
+
+Composing with `defaultClassifyError` at the end is the recommended pattern. Adapter authors who want to completely replace the default can omit the fallthrough — anything the classifier returns `null` for lands as `kind: 'unknown'`.
+
+The classifier is called only when the adapter throws (Stage 2 above). Non-2xx responses go through the error registry path (Stage 3), not the classifier.
+
+---
+
+## 8. Migration: 6.x → 7.x
+
+Three breaking changes in 7.0.0 affect error handling.
+
+### 8a. `ClientRequestError` Renamed to `ClientHttpError`
+
+`ClientRequestError` is a deprecated alias for `ClientHttpError`, retained for one minor release after 7.0.0.
+
+**Action**: rename your imports from `ClientRequestError` to `ClientHttpError`. The `instanceof ClientRequestError` guard continues to work until the alias is removed.
+
+```ts
+// Before
+import { ClientRequestError } from 'ts-procedures/client'
+if (err instanceof ClientRequestError) { ... }
+
+// After
+import { ClientHttpError } from 'ts-procedures/client'
+if (err instanceof ClientHttpError) { ... }
+```
+
+### 8b. Raw `DOMException` / `TypeError` No Longer Reach Consumer Catch Blocks
+
+Before 7.0.0, the fetch adapter let platform errors propagate directly. After 7.0.0, all thrown errors from the adapter are normalized through the classifier before reaching your code.
+
+```ts
+// Before 6.x — catching raw platform errors
+try {
+  await client.users.GetUser(params)
+} catch (e) {
+  if (e instanceof DOMException && e.name === 'AbortError') {
+    // handle abort
+  }
+}
+
+// After 7.x — catching framework error classes
+try {
+  await client.users.GetUser(params)
+} catch (e) {
+  if (e instanceof ClientTimeoutError) {
+    // timed out
+  } else if (e instanceof ClientAbortError) {
+    // user-cancelled
+  }
+}
+```
+
+The original platform error is preserved on `error.cause` if you need to inspect it.
+
+### 8c. `onError` Hook Receives the Normalized Framework Error
+
+Before 7.0.0, the `onError` hook saw the raw `DOMException` or `TypeError`. After 7.0.0, the hook sees the normalized framework class (`ClientNetworkError`, `ClientTimeoutError`, etc.), with the original platform error on `.cause`.
+
+**Action**: update any hook logic that inspected the raw error shape. Most consumers only call `console.error(error)` or log `error.message` and are unaffected.
+
+---
+
+## 9. FAQ — `.safe()` and Retry Loops
+
+**Q: My retry loop using `.safe()` triggers `onError` once per attempt. Is that intentional?**
+
+Yes. `onError` fires on every failure regardless of which call style you use. Telemetry consumers want to see all attempts uniformly.
+
+To suppress logging on a retry loop, you have two options:
+
+**Option 1 — per-call `onError` no-op:**
+
+```ts
+for (let attempt = 0; attempt < 3; attempt++) {
+  const r = await client.users.GetUser.safe(params, {
+    onError: () => {},  // suppress onError for this call
+  })
+  if (r.ok) return r.value
+  // inspect r.kind to decide whether to retry
+}
+```
+
+**Option 2 — flag in `meta`, check in the global `onError`:**
+
+```ts
+// Augment RequestMeta once in your app:
+declare module 'ts-procedures/client' {
+  interface RequestMeta { isRetry?: boolean }
+}
+
+// In createClient setup:
+const client = createApiClient({
+  basePath: 'https://api.example.com',
+  hooks: {
+    onError: ({ request, error }) => {
+      if (request.meta?.isRetry) return  // skip telemetry for retries
+      logger.error(error)
+    },
+  },
+})
+
+// At call sites:
+for (let attempt = 0; attempt < 3; attempt++) {
+  const r = await client.users.GetUser.safe(params, {
+    meta: { isRetry: attempt > 0 },
+  })
+  if (r.ok) return r.value
+}
+```
+
+A framework-level "skip `onError` for `.safe()`" toggle was deliberately deferred to a future minor release. The workarounds above are sufficient for the common case.
+
+---
+
+## 10. Reference
+
+- Design spec: [`docs/superpowers/specs/2026-04-29-safe-result-api-design.md`](./superpowers/specs/2026-04-29-safe-result-api-design.md)
+- Client types and interfaces: `CLAUDE.md` — "Key Files" → `src/client/`
+- Agent config patterns and anti-patterns: `agent_config/claude-code/skills/ts-procedures/patterns.md` and `anti-patterns.md`