feat(typed)(#113): kind discriminator on safe error envelope (#115)

* feat(typed)(#113): kind discriminator on safe error envelope

Replace TypedSafeErr<R> with a discriminated union on `kind`:

- `kind: "http"`  — server responded with a non-2xx status declared in
  `responses`. `error.status` narrows to the `ErrorCodes` union and
  `error.data` narrows to the body shape for that status. `response`
  is a real `Response`.
- `kind: "network"` — no server response (TCP/TLS failure, DNS, timeout,
  abort). `error` is the raw `Error`; `response` is `undefined`.

Why: the previous shape coerced network failures into a synthetic
`{ status: 0, data: error.message }` envelope. When `ErrorCodes` was
declared as `404 | 429`, TypeScript narrowed `error.status` to that
union but at runtime `status` could be 0 — the type lied. The new
shape exposes the raw `Error` so callers branch on `kind === "network"`
before touching `status`.

Migration: callers now check `result.kind` before reading `error.status`:

  if (!result.ok) {
    if (result.kind === "network") result.error          // Error
    else if (result.error.status === 429) ...            // narrows
  }

The success branch (`ok: true`) is unchanged — issue #113's proposal
keeps `kind` only on the error side.

Closes #113

* chore(review): drop defensive Error coercion in safe wrapper

Drivers and misina's internal request path always throw `Error`
subclasses per AGENTS.md ("drivers throw TypeError('fetch failed')"
to trip the NetworkError mapper). The `e instanceof Error ? e : new
Error(...)` shim was defensive code against a contract violation that
internal callers cannot produce — `e as Error` matches the same
runtime behavior without the dead branch.

Author: productdevbook

README.md

@@ -1876,12 +1876,27 @@ const result = await api.safe.get("/users/:id", { params: { id: "42" } })
 if (result.ok) {
   result.data // User
   result.status // 200
+} else if (result.kind === "network") {
+  result.error // Error — fetch failed, timeout, abort
 } else {
+  // result.kind === "http"
   if (result.error.status === 404) result.error.data.message // string
   if (result.error.status === 429) result.error.data.retryAfter // number
 }
 ```
 
+The error envelope is a discriminated union on `kind`:
+
+- `kind: "http"` — the server responded with a non-2xx status declared in
+  `responses`. `error.status` narrows to the `ErrorCodes` union and
+  `error.data` narrows to the body shape for that status. `response` is a
+  real `Response`.
+- `kind: "network"` — the request never reached a server (TCP/TLS failure,
+  DNS, timeout, abort). `error` is the raw `Error` instance and
+  `response` is `undefined`. There is no HTTP status to discriminate on,
+  so the envelope is kept honest by exposing `Error` directly instead of
+  forging a synthetic `status: 0`.
+
 The throwing surface (`api.get(...)`) is unchanged: it returns the
 2xx body as before. `response: T` remains valid as shorthand for
 `responses: { 200: T }`.

examples/07-typed.ts

@@ -57,7 +57,10 @@ const result = await gh.safe.get("/repos/:owner/:repo", {
 
 if (result.ok) {
   console.log(`fetched ${result.data.full_name}`)
+} else if (result.kind === "network") {
+  console.log(`network error: ${result.error.message}`)
 } else {
+  // result.kind === "http" — error.status narrows to the ErrorCodes union.
   if (result.error.status === 404) console.log(`not found: ${result.error.data.message}`)
   if (result.error.status === 403) console.log(`forbidden: ${result.error.data.message}`)
 }

src/index.ts

@@ -93,7 +93,9 @@ export type {
   SuccessCodes,
   TypedMisina,
   TypedSafeErr,
+  TypedSafeHttpErr,
   TypedSafeMisina,
+  TypedSafeNetworkErr,
   TypedSafeOk,
   TypedSafeResult,
 } from "./typed.ts"

src/typed.ts

@@ -64,15 +64,44 @@ export type TypedSafeOk<R> = {
   error?: undefined
 }
 
-export type TypedSafeErr<R> = {
+/**
+ * Per-status HTTP error branch. The server responded with a status the
+ * endpoint declared as an error — `error.status` narrows to the union of
+ * declared `ErrorCodes`, and `error.data` narrows to the body shape for
+ * that status.
+ */
+export type TypedSafeHttpErr<R> = {
   ok: false
+  kind: "http"
   data?: undefined
   error: [keyof R & ErrorCodes] extends [never]
     ? { status: number; data: unknown }
     : { [K in keyof R & ErrorCodes]: { status: K; data: R[K] } }[keyof R & ErrorCodes]
-  response: Response | undefined
+  response: Response
+}
+
+/**
+ * Network / timeout / abort branch. The request never received a server
+ * response — there is no HTTP status to discriminate on. `error` is the
+ * raw thrown `Error` (TypeError, TimeoutError, etc.); `response` is
+ * `undefined`.
+ */
+export type TypedSafeNetworkErr = {
+  ok: false
+  kind: "network"
+  data?: undefined
+  error: Error
+  response: undefined
 }
 
+/**
+ * Discriminated union covering both error branches. Use `result.kind` to
+ * separate the wire-level HTTP error (where `result.error.status` is a
+ * declared `ErrorCodes`) from the transport-level failure (where
+ * `result.error` is a raw `Error`).
+ */
+export type TypedSafeErr<R> = TypedSafeHttpErr<R> | TypedSafeNetworkErr
+
 export type TypedSafeResult<R> = TypedSafeOk<R> | TypedSafeErr<R>
 
 type Method<S extends string> = S extends `${infer M} ${string}` ? M : never
@@ -182,9 +211,17 @@ export function createMisinaTyped<E extends EndpointsMap>(
     | { ok: true; data: unknown; status: number; response: Response; error?: undefined }
     | {
         ok: false
+        kind: "http"
         data?: undefined
         error: { status: number; data: unknown }
-        response: Response | undefined
+        response: Response
+      }
+    | {
+        ok: false
+        kind: "network"
+        data?: undefined
+        error: Error
+        response: undefined
       }
 
   async function safeCall(
@@ -199,17 +236,22 @@ export function createMisinaTyped<E extends EndpointsMap>(
       if (e instanceof HTTPError) {
         return {
           ok: false,
+          kind: "http",
           error: { status: e.status, data: e.data },
           response: e.response,
         }
       }
-      // Network / timeout / other non-HTTP errors don't fit the per-status
-      // shape — surface a synthetic error envelope so callers can still
-      // discriminate on `ok`. Rethrowing would defeat .safe's purpose.
-      const err = e as Error & { status?: number; data?: unknown }
+      // Network / timeout / abort / anything non-HTTP. There is no server
+      // response to discriminate on, so surface the raw `Error` and let
+      // the caller branch on `kind === "network"`. Rethrowing would
+      // defeat .safe's purpose; coercing into a fake `status: 0` would
+      // lie about the typed `ErrorCodes` union. Drivers and internal code
+      // throw `Error` subclasses per AGENTS.md ("drivers throw
+      // TypeError('fetch failed')"), so no defensive coercion here.
       return {
         ok: false,
-        error: { status: err.status ?? 0, data: err.data ?? err.message },
+        kind: "network",
+        error: e as Error,
         response: undefined,
       }
     }

test/typed-safe.test.ts

@@ -1,6 +1,13 @@
 import { describe, expect, expectTypeOf, it } from "vitest"
 import { createMisinaTyped } from "../src/index.ts"
-import type { ResponsesOf, SuccessBodyOf, TypedSafeResult } from "../src/typed.ts"
+import type {
+  ResponsesOf,
+  SuccessBodyOf,
+  TypedSafeErr,
+  TypedSafeHttpErr,
+  TypedSafeNetworkErr,
+  TypedSafeResult,
+} from "../src/typed.ts"
 import mockDriverFactory from "../src/driver/mock.ts"
 
 interface User {
@@ -71,7 +78,7 @@ describe("createMisinaTyped — .safe namespace", () => {
     }
   })
 
-  it("safe.get returns ok=false with error.status === 404 and typed data", async () => {
+  it("safe.get returns ok=false, kind=http with error.status === 404 and typed data", async () => {
     const driver = mockDriverFactory({
       response: jsonResponse({ message: "not found" }, 404),
     })
@@ -80,8 +87,9 @@ describe("createMisinaTyped — .safe namespace", () => {
     const result = await api.safe.get("/users/:id", { params: { id: "x" } })
 
     expect(result.ok).toBe(false)
-    if (!result.ok) {
+    if (!result.ok && result.kind === "http") {
       expect([404, 429]).toContain(result.error.status)
+      expect(result.response).toBeInstanceOf(Response)
       // Discriminated narrowing on status:
       if (result.error.status === 404) {
         expectTypeOf(result.error.data).toEqualTypeOf<NotFound>()
@@ -90,7 +98,7 @@ describe("createMisinaTyped — .safe namespace", () => {
     }
   })
 
-  it("safe.get carries 429 body shape on rate-limit", async () => {
+  it("safe.get carries 429 body shape on rate-limit (kind=http)", async () => {
     const driver = mockDriverFactory({
       response: jsonResponse({ retryAfter: 30 }, 429),
     })
@@ -99,7 +107,7 @@ describe("createMisinaTyped — .safe namespace", () => {
     const result = await api.safe.get("/users/:id", { params: { id: "x" } })
 
     expect(result.ok).toBe(false)
-    if (!result.ok && result.error.status === 429) {
+    if (!result.ok && result.kind === "http" && result.error.status === 429) {
       expectTypeOf(result.error.data).toEqualTypeOf<RateLimited>()
       expect(result.error.data.retryAfter).toBe(30)
     }
@@ -120,7 +128,7 @@ describe("createMisinaTyped — .safe namespace", () => {
     }
   })
 
-  it("safe.post returns ok=false with 422 validation error", async () => {
+  it("safe.post returns ok=false, kind=http with 422 validation error", async () => {
     const driver = mockDriverFactory({
       response: jsonResponse({ issues: ["name too short"] }, 422),
     })
@@ -129,7 +137,7 @@ describe("createMisinaTyped — .safe namespace", () => {
     const result = await api.safe.post("/users", { body: { name: "" } })
 
     expect(result.ok).toBe(false)
-    if (!result.ok && result.error.status === 422) {
+    if (!result.ok && result.kind === "http" && result.error.status === 422) {
       expectTypeOf(result.error.data).toEqualTypeOf<{ issues: string[] }>()
       expect(result.error.data.issues).toEqual(["name too short"])
     }
@@ -147,7 +155,7 @@ describe("createMisinaTyped — .safe namespace", () => {
     }
   })
 
-  it("safe.get surfaces network errors as ok=false with status 0 instead of throwing", async () => {
+  it("safe.get surfaces network errors as ok=false, kind=network with raw Error", async () => {
     const driver = {
       name: "boom",
       request: async (): Promise<Response> => {
@@ -160,10 +168,49 @@ describe("createMisinaTyped — .safe namespace", () => {
 
     expect(result.ok).toBe(false)
     if (!result.ok) {
-      expect(result.error.status).toBe(0)
-      expect(result.response).toBeUndefined()
+      expect(result.kind).toBe("network")
+      if (result.kind === "network") {
+        expectTypeOf(result.error).toEqualTypeOf<Error>()
+        expect(result.error).toBeInstanceOf(Error)
+        // The driver throws TypeError("fetch failed"), which misina maps
+        // to a NetworkError before bubbling. Either message indicates the
+        // raw Error survived the .safe wrapper.
+        expect(result.error.message).toMatch(/fetch failed|Network request/)
+        expect(result.response).toBeUndefined()
+      }
     }
   })
+
+  it("safe.get on HTTPError 429 has kind=http, error.status === 429, and a Response", async () => {
+    const driver = mockDriverFactory({
+      response: jsonResponse({ retryAfter: 5 }, 429),
+    })
+    const api = createMisinaTyped<Api>({ driver, retry: 0, baseURL: "https://api.test" })
+
+    const result = await api.safe.get("/users/:id", { params: { id: "x" } })
+
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.kind).toBe("http")
+      if (result.kind === "http") {
+        expect(result.error.status).toBe(429)
+        expect(result.response).toBeInstanceOf(Response)
+        expect(result.response.status).toBe(429)
+      }
+    }
+  })
+
+  it("kind discriminator narrows error shape at compile time", async () => {
+    type R = ResponsesOf<Api["GET /users/:id"]>
+    type Err = TypedSafeErr<R>
+    type HttpBranch = Extract<Err, { kind: "http" }>
+    type NetBranch = Extract<Err, { kind: "network" }>
+
+    expectTypeOf<HttpBranch["error"]["status"]>().toEqualTypeOf<404 | 429>()
+    expectTypeOf<HttpBranch["response"]>().toEqualTypeOf<Response>()
+    expectTypeOf<NetBranch["error"]>().toEqualTypeOf<Error>()
+    expectTypeOf<NetBranch["response"]>().toEqualTypeOf<undefined>()
+  })
 })
 
 describe("ResponsesOf / SuccessBodyOf — type-only narrowing", () => {
@@ -183,12 +230,18 @@ describe("ResponsesOf / SuccessBodyOf — type-only narrowing", () => {
     expectTypeOf<S>().toEqualTypeOf<User | { id: string }>()
   })
 
-  it("TypedSafeResult is a discriminated union by ok", () => {
+  it("TypedSafeResult is a discriminated union by ok, then by kind on the error side", () => {
     type R = { 200: User; 404: NotFound }
     type T = TypedSafeResult<R>
     type Ok = Extract<T, { ok: true }>
     type Err = Extract<T, { ok: false }>
+    type ErrHttp = Extract<Err, { kind: "http" }>
+    type ErrNet = Extract<Err, { kind: "network" }>
+
     expectTypeOf<Ok["data"]>().toEqualTypeOf<User>()
-    expectTypeOf<Err["error"]>().toEqualTypeOf<{ status: 404; data: NotFound }>()
+    expectTypeOf<ErrHttp["error"]>().toEqualTypeOf<{ status: 404; data: NotFound }>()
+    expectTypeOf<ErrHttp>().toEqualTypeOf<TypedSafeHttpErr<R>>()
+    expectTypeOf<ErrNet>().toEqualTypeOf<TypedSafeNetworkErr>()
+    expectTypeOf<ErrNet["error"]>().toEqualTypeOf<Error>()
   })
 })

test/types.test.ts

@@ -26,7 +26,7 @@ import {
   type MisinaResult,
   type TypedMisina,
 } from "../src/index.ts"
-import type { TypedSafeResult } from "../src/typed.ts"
+import type { TypedSafeHttpErr, TypedSafeNetworkErr, TypedSafeResult } from "../src/typed.ts"
 import { tracing } from "../src/tracing/index.ts"
 
 describe("createMisina return type", () => {
@@ -173,6 +173,28 @@ describe("TypedMisina.safe — typed per-status-code result", () => {
     >()
   })
 
+  it("TypedSafeResult error branch splits on `kind` into http vs network", () => {
+    type R = {
+      200: { id: string; name: string }
+      404: { message: string }
+      429: { retryAfter: number }
+    }
+    type Result = TypedSafeResult<R>
+    type Err = Extract<Result, { ok: false }>
+    type Http = Extract<Err, { kind: "http" }>
+    type Net = Extract<Err, { kind: "network" }>
+
+    // The HTTP branch carries the per-status discriminated union and a
+    // real Response. The network branch carries a raw Error and no
+    // Response. status is never widened to `number`.
+    expectTypeOf<Http>().toEqualTypeOf<TypedSafeHttpErr<R>>()
+    expectTypeOf<Net>().toEqualTypeOf<TypedSafeNetworkErr>()
+    expectTypeOf<Http["error"]["status"]>().toEqualTypeOf<404 | 429>()
+    expectTypeOf<Http["response"]>().toEqualTypeOf<Response>()
+    expectTypeOf<Net["error"]>().toEqualTypeOf<Error>()
+    expectTypeOf<Net["response"]>().toEqualTypeOf<undefined>()
+  })
+
   it("TypedMisina exposes raw + safe alongside throwing methods", () => {
     type T = TypedMisina<Api>
     expectTypeOf<T["raw"]>().toEqualTypeOf<Misina>()