ts-procedures 6.2.0 → 7.0.0-beta.0

package/docs/client-and-codegen.md

@@ -60,7 +60,7 @@ const api = createClient({
   adapter: createFetchAdapter(),
   basePath: 'http://localhost:3000',
   scopes: createApiBindings,
-  errorRegistry: ApiErrors.ApiErrorRegistry,  // opt in to typed dispatch — omit to get the plain ClientRequestError transport shape
+  errorRegistry: ApiErrors.ApiErrorRegistry,  // opt in to typed dispatch — omit to get the plain ClientHttpError transport shape
 })
 ```
 
@@ -127,6 +127,19 @@ const axiosAdapter: ClientAdapter = {
 }
 ```
 
+Both `ClientAdapter` and `createFetchAdapter` accept an optional `classifyError` field. When provided, the classifier overrides the default mapping from raw platform errors (`TypeError`, `DOMException`) to framework error classes. Pass a custom `ErrorClassifier` to emit your own `ClientErrorMap` categories.
+
+```typescript
+import { createFetchAdapter, defaultClassifyError } from 'ts-procedures/client'
+
+const adapter = createFetchAdapter({
+  classifyError: (err, ctx) => {
+    // delegate to the built-in classifier for everything except your own cases
+    return defaultClassifyError(err, ctx)
+  },
+})
+```
+
 ## Per-Call Options
 
 Every generated callable accepts an optional second argument for per-call configuration. The options bag covers both request-level config (timeout, cancellation, headers, base path) and hooks.
@@ -259,8 +272,8 @@ try {
     // err.body is typed to UseCaseErrorBody; err.status, err.procedureName, err.scope available
   } else if (err instanceof ApiErrors.ApiProcedureError) {
     // Catch-all for any generated service error
-  } else if (err instanceof ClientRequestError) {
-    // Transport-level error (unmatched body.name, or non-JSON response)
+  } else if (err instanceof ClientHttpError) {
+    // Transport-level error (unmatched body.name, or non-JSON response) — err.status, err.cause
   }
 }
 ```
@@ -282,7 +295,7 @@ export namespace Users {
 // Consumer:
 try { await api.users.GetUser({ pathParams: { id: 'x' } }) }
 catch (err) {
-  const e = err as Users.GetUser.Errors | ClientRequestError   // TS has no typed-throws; manual annotation
+  const e = err as Users.GetUser.Errors | ClientHttpError   // TS has no typed-throws; manual annotation
   if (e instanceof ApiErrors.UseCaseError) { /* ... */ }
 }
 ```
@@ -296,10 +309,42 @@ Route-errors that reference keys missing from `_errors.ts` are filtered out at c
 1. If no registry, or body isn't an object with a string `name`, or no registry key matches → returns `null`.
 2. Otherwise calls `registry[body.name].fromResponse(body, meta)` and returns the typed `Error` instance.
 
-When the helper returns `null`, the call falls back to `ClientRequestError` — the plain transport-error shape, used for unmatched names, non-JSON bodies, and when no registry is configured.
+When the helper returns `null`, the call falls back to `ClientHttpError` — the plain transport-error shape, used for unmatched names, non-JSON bodies, and when no registry is configured.
 
 Stream endpoints get the same treatment for **pre-stream** errors (thrown before the first yield — e.g. validation or auth). The fetch adapter's `stream()` eagerly parses a JSON body when status is non-2xx and exposes it via `AdapterStreamResponse.errorBody`, which `executeStream` passes through the registry. **Mid-stream** SSE error events continue to flow through `onMidStreamError` on the server and re-throw on the client without registry dispatch.
 
+### Result-returning `.safe()` form
+
+Every generated RPC and API callable has a `.safe()` sibling that returns `Result<T, ETyped>` instead of throwing. This eliminates `try/catch` for callers that prefer exhaustive narrowing via a discriminated union.
+
+```typescript
+const r = await api.users.GetUser.safe({ pathParams: { id: '123' } })
+
+if (r.ok) {
+  console.log(r.value) // typed as GetUser.Response
+} else {
+  switch (r.kind) {
+    case 'typed':   // registry-dispatched error (instanceof ApiErrors.UseCaseError, etc.)
+      console.error(r.error.body)
+      break
+    case 'http':    // ClientHttpError — non-2xx with unmatched or non-JSON body
+      console.error(`HTTP ${r.error.status}`)
+      break
+    case 'network': // ClientNetworkError
+    case 'timeout': // ClientTimeoutError
+    case 'aborted': // ClientAbortError
+    case 'parse':   // ClientParseError — response body could not be parsed
+    case 'usage':   // programming error (e.g., missing path param)
+    case 'unknown': // catch-all
+      console.error(r.error)
+  }
+}
+```
+
+The underlying method is `ClientInstance.safeCall<TResponse, ETyped>(descriptor, options)` — all generated `.safe()` callables delegate to it. Streams keep the throwing form; `.safe()` is intentionally absent on stream procedures.
+
+Custom error categories can be added to `r.kind`'s union via `ClientErrorMap` interface augmentation. See [`docs/client-error-handling.md`](./client-error-handling.md) for the full reference, including `Result<T, E>`, `ResultNoTyped<T>`, `FrameworkFailure`, `ErrorClassifier`, and `ClientErrorMap` augmentation patterns.
+
 ## Hooks
 
 Hooks let you intercept requests and responses globally or per-procedure call. Global hooks apply to every call made through the client instance; per-procedure hooks run after global ones for a single invocation.
@@ -378,7 +423,7 @@ await generateClient({
 By default, the generated output includes two additional files in the output directory:
 
 - **`_types.ts`** — All client type definitions (`ClientInstance`, `TypedStream`, `ProcedureCallOptions`, hooks, adapters, descriptors)
-- **`_client.ts`** — Full client runtime: `createClient`, `createFetchAdapter`, hook pipeline, and error classes (`ClientRequestError`, `ClientPathParamError`, `ClientStreamError`)
+- **`_client.ts`** — Full client runtime: `createClient`, `createFetchAdapter`, hook pipeline, and error classes (`ClientHttpError`, `ClientNetworkError`, `ClientTimeoutError`, `ClientAbortError`, `ClientParseError`, `ClientPathParamError`, `ClientStreamError`)
 
 All generated scope files and `index.ts` import from `./_types` instead of `ts-procedures/client`, so app consumers can import everything from the generated directory without needing `ts-procedures` as a runtime dependency. `ts-procedures` becomes a devDependency only.
 
@@ -396,7 +441,21 @@ import { createClient, createFetchAdapter } from 'ts-procedures/client'
 
 ```typescript
 // Client Runtime
-import { createClient, createFetchAdapter, dispatchTypedError } from 'ts-procedures/client'
+import {
+  createClient,
+  createFetchAdapter,
+  dispatchTypedError,
+  defaultClassifyError,
+  // Error classes (7.0+)
+  ClientHttpError,       // non-2xx HTTP response (renamed from ClientRequestError)
+  ClientNetworkError,    // network-level failure (e.g., fetch TypeError)
+  ClientTimeoutError,    // request timed out via AbortSignal.timeout
+  ClientAbortError,      // request aborted by caller signal
+  ClientParseError,      // response body could not be parsed as JSON
+  ClientPathParamError,  // programming error: path param missing at call time
+  ClientStreamError,     // stream-level transport error
+} from 'ts-procedures/client'
+
 import type {
   ClientAdapter,
   ClientHooks,
@@ -405,8 +464,19 @@ import type {
   ErrorRegistry,
   ErrorFactory,
   ErrorResponseMeta,
+  // Safe-result types (7.0+)
+  Result,            // Result<T, ETyped> — ok branch or failure branch
+  ResultNoTyped,     // Result<T, never> — when no typed error registry is wired
+  FrameworkFailure,  // The failure branch of Result (discriminated by `kind`)
+  ClientErrorMap,    // Augmentable interface for custom error categories
+  // Classifier types (7.0+)
+  ErrorClassifier,
+  ClassifyErrorContext,
+  ClassifiedError,
 } from 'ts-procedures/client'
 
 // Code Generation
 import { generateClient } from 'ts-procedures/codegen'
 ```
+
+> **Migration note:** `ClientRequestError` was renamed to `ClientHttpError` in 7.0.0. The old name is re-exported as a deprecated alias for one minor cycle. Update imports when possible.

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`