feat(#36): safe() no-throw mode — { ok, data, error, response } discriminated result

ofetch #370. Hot UI code can't union-type a try/catch — TS treats the
catch as unknown. Go-style result tuple gives both branches first-class
types via a discriminated union:

  type MisinaResult<T, E> =
    | { ok: true; data: T; response: MisinaResponse<T> }
    | { ok: false; error: HTTPError<E> | Error; response?: MisinaResponse<unknown> }

API:
  const result = await misina.safe.get<User, ApiError>('/users/42')
  if (result.ok) {
    result.data         // User
    result.response     // MisinaResponse<User>
  } else {
    result.error        // HTTPError<ApiError> | Error
    result.response?.status  // available for HTTPError; undefined on NetworkError
  }

Every Misina shorthand is mirrored on .safe — get/post/put/patch/delete/
head/options/query/request. No try/catch needed at call sites.

Implementation:
- MisinaResult<T, E> discriminated union in types.ts
- SafeMisina interface (parallel to Misina)
- misina.safe — synthesized from the existing callable() pipeline,
  catching errors into the result shape
- Closes #36

Audit pass 51 (test/safe-mode.test.ts, 6 tests):
  ok: true with typed data, ok: false with typed error body via second
  generic, network-error case (response: undefined), POST with body,
  no-throw guarantee, default ok: true preserves T.

Suite: 435 / 435 (was 429). Lint+typecheck clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: productdevbook

src/misina.ts

@@ -25,6 +25,8 @@ import type {
   MisinaResolvedOptions,
   MisinaResponse,
   MisinaResponsePromise,
+  MisinaResult,
+  SafeMisina,
 } from "./types.ts"
 
 // Methods that never accept a request body. DELETE is intentionally absent —
@@ -309,6 +311,58 @@ export function createMisina(defaults: MisinaOptions = {}): Misina {
     ): MisinaResponsePromise<T> => callable<T>(url, { ...init, method, body })
   }
 
+  async function safeCall<T, E>(
+    method: HttpMethod,
+    input: string,
+    body: unknown,
+    init?: MisinaRequestInit,
+  ): Promise<MisinaResult<T, E>> {
+    try {
+      const response = await callable<T>(input, { ...init, method, body })
+      return { ok: true, data: response.data, response }
+    } catch (e) {
+      const error = e as Error
+      const response = (error as { response?: Response }).response as Response | undefined
+      // For HTTPError we already have the parsed body — surface a
+      // synthesized MisinaResponse<unknown> so callers can read headers.
+      let outResponse: MisinaResponse<unknown> | undefined
+      if (response instanceof Response) {
+        outResponse = {
+          data: (error as { data?: unknown }).data,
+          status: response.status,
+          statusText: response.statusText,
+          headers: Object.fromEntries(response.headers),
+          url: response.url,
+          type: response.type,
+          timings: { start: 0, responseStart: 0, end: 0, total: 0 },
+          raw: response,
+        }
+      }
+      return { ok: false, response: outResponse, error: error as HTTPError<E> | Error }
+    }
+  }
+
+  const safe: SafeMisina = {
+    request: <T = unknown, E = unknown>(input: string, init?: MisinaRequestInit) =>
+      safeCall<T, E>((init?.method ?? "GET") as HttpMethod, input, init?.body, init),
+    get: <T = unknown, E = unknown>(url: string, init?: MisinaRequestInit) =>
+      safeCall<T, E>("GET", url, undefined, init),
+    post: <T = unknown, E = unknown>(url: string, body?: unknown, init?: MisinaRequestInit) =>
+      safeCall<T, E>("POST", url, body, init),
+    put: <T = unknown, E = unknown>(url: string, body?: unknown, init?: MisinaRequestInit) =>
+      safeCall<T, E>("PUT", url, body, init),
+    patch: <T = unknown, E = unknown>(url: string, body?: unknown, init?: MisinaRequestInit) =>
+      safeCall<T, E>("PATCH", url, body, init),
+    delete: <T = unknown, E = unknown>(url: string, init?: MisinaRequestInit) =>
+      safeCall<T, E>("DELETE", url, undefined, init),
+    head: <T = unknown, E = unknown>(url: string, init?: MisinaRequestInit) =>
+      safeCall<T, E>("HEAD", url, undefined, init),
+    options: <T = unknown, E = unknown>(url: string, init?: MisinaRequestInit) =>
+      safeCall<T, E>("OPTIONS", url, undefined, init),
+    query: <T = unknown, E = unknown>(url: string, body?: unknown, init?: MisinaRequestInit) =>
+      safeCall<T, E>("QUERY", url, body, init),
+  }
+
   const misina: Misina = {
     extend: (input) => {
       const child = typeof input === "function" ? input(defaults) : input
@@ -324,6 +378,7 @@ export function createMisina(defaults: MisinaOptions = {}): Misina {
     head: bind("HEAD"),
     options: bind("OPTIONS"),
     query: bindWithBody("QUERY"),
+    safe,
   }
 
   return misina

src/types.ts

@@ -387,6 +387,67 @@ export interface ResponseTimings {
 
 export type CatchMatcher = number | number[] | string | ((error: unknown) => boolean)
 
+/**
+ * Discriminated result type returned by `misina.safe.*` methods. Uses Go-style
+ * branching so both success and failure paths get full type safety.
+ */
+export type MisinaResult<T, E = unknown> =
+  | { ok: true; data: T; response: MisinaResponse<T>; error?: undefined }
+  | {
+      ok: false
+      data?: undefined
+      response: MisinaResponse<unknown> | undefined
+      error: HTTPError<E> | Error
+    }
+
+/**
+ * Same surface as `Misina` but every method returns a `MisinaResult` instead
+ * of throwing. Perfect for hot UI code where TypeScript needs to discriminate
+ * branches without `try/catch` widening to `unknown`.
+ */
+export interface SafeMisina {
+  request: <T = unknown, E = unknown>(
+    input: string,
+    init?: MisinaRequestInit,
+  ) => Promise<MisinaResult<T, E>>
+  get: <T = unknown, E = unknown>(
+    url: string,
+    init?: MisinaRequestInit,
+  ) => Promise<MisinaResult<T, E>>
+  post: <T = unknown, E = unknown>(
+    url: string,
+    body?: unknown,
+    init?: MisinaRequestInit,
+  ) => Promise<MisinaResult<T, E>>
+  put: <T = unknown, E = unknown>(
+    url: string,
+    body?: unknown,
+    init?: MisinaRequestInit,
+  ) => Promise<MisinaResult<T, E>>
+  patch: <T = unknown, E = unknown>(
+    url: string,
+    body?: unknown,
+    init?: MisinaRequestInit,
+  ) => Promise<MisinaResult<T, E>>
+  delete: <T = unknown, E = unknown>(
+    url: string,
+    init?: MisinaRequestInit,
+  ) => Promise<MisinaResult<T, E>>
+  head: <T = unknown, E = unknown>(
+    url: string,
+    init?: MisinaRequestInit,
+  ) => Promise<MisinaResult<T, E>>
+  options: <T = unknown, E = unknown>(
+    url: string,
+    init?: MisinaRequestInit,
+  ) => Promise<MisinaResult<T, E>>
+  query: <T = unknown, E = unknown>(
+    url: string,
+    body?: unknown,
+    init?: MisinaRequestInit,
+  ) => Promise<MisinaResult<T, E>>
+}
+
 export interface MisinaResponsePromise<T, E = unknown> extends Promise<MisinaResponse<T>> {
   /**
    * Recover from specific errors. Matcher can be a status code, an array of
@@ -452,6 +513,12 @@ export interface Misina {
     body?: unknown,
     init?: MisinaRequestInit,
   ) => MisinaResponsePromise<T, E>
+  /**
+   * No-throw companion. `misina.safe.get<T, E>(url)` returns
+   * `Promise<MisinaResult<T, E>>` — a discriminated `{ ok, data, error,
+   * response }` object so both branches are type-safe at the call site.
+   */
+  safe: SafeMisina
 }
 
 /**

test/safe-mode.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from "vitest"
+import { createMisina, HTTPError } from "../src/index.ts"
+
+describe("misina.safe — no-throw mode", () => {
+  it("ok: true on 200 with typed data", async () => {
+    const driver = {
+      name: "p",
+      request: async () =>
+        new Response('{"name":"alice"}', { headers: { "content-type": "application/json" } }),
+    }
+    const m = createMisina({ driver, retry: 0 })
+
+    const result = await m.safe.get<{ name: string }>("https://api.test/users/1")
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.data.name).toBe("alice")
+      expect(result.response.status).toBe(200)
+      expect(result.error).toBeUndefined()
+    }
+  })
+
+  it("ok: false on HTTPError; error is typed via second generic", async () => {
+    interface ApiError {
+      code: string
+      message: string
+    }
+    const driver = {
+      name: "p",
+      request: async () =>
+        new Response(JSON.stringify({ code: "E_FORBIDDEN", message: "nope" }), {
+          status: 403,
+          headers: { "content-type": "application/json" },
+        }),
+    }
+    const m = createMisina({ driver, retry: 0 })
+
+    const result = await m.safe.get<{ name: string }, ApiError>("https://api.test/users/1")
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(HTTPError)
+      const httpErr = result.error as HTTPError<ApiError>
+      expect(httpErr.data.code).toBe("E_FORBIDDEN")
+      expect(result.response?.status).toBe(403)
+    }
+  })
+
+  it("ok: false on network error; response is undefined", async () => {
+    const driver = {
+      name: "broken",
+      request: async () => {
+        throw Object.assign(new TypeError("fetch failed"), { name: "TypeError" })
+      },
+    }
+    const m = createMisina({ driver, retry: 0 })
+
+    const result = await m.safe.get("https://api.test/")
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.error.name).toBe("NetworkError")
+      expect(result.response).toBeUndefined()
+    }
+  })
+
+  it("safe.post sends body, returns success on 201", async () => {
+    let captured: Request | undefined
+    const driver = {
+      name: "p",
+      request: async (req: Request) => {
+        captured = req
+        return new Response('{"id":"42"}', {
+          status: 201,
+          headers: { "content-type": "application/json" },
+        })
+      },
+    }
+    const m = createMisina({ driver, retry: 0 })
+
+    const result = await m.safe.post<{ id: string }>("https://api.test/users", { name: "alice" })
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.data.id).toBe("42")
+    }
+    expect(captured?.method).toBe("POST")
+    expect(await captured?.text()).toBe('{"name":"alice"}')
+  })
+
+  it("safe doesn't throw — discriminated union covers all branches", async () => {
+    const driver = {
+      name: "p",
+      request: async () => new Response("err", { status: 500 }),
+    }
+    const m = createMisina({ driver, retry: 0 })
+
+    // Critical: this never enters a `catch` — TypeScript sees branches.
+    let entered = false
+    const result = await m.safe.get("https://api.test/")
+    entered = true
+    expect(entered).toBe(true)
+    expect(result.ok).toBe(false)
+  })
+
+  it("default ok: true keeps the parsed body type", async () => {
+    const driver = {
+      name: "p",
+      request: async () =>
+        new Response("[1,2,3]", { headers: { "content-type": "application/json" } }),
+    }
+    const m = createMisina({ driver, retry: 0 })
+
+    const result = await m.safe.get<number[]>("https://api.test/list")
+    if (result.ok) {
+      expect(result.data).toEqual([1, 2, 3])
+    } else {
+      throw new Error("should not be reached")
+    }
+  })
+})