@marianmeres/http-utils 2.7.1 → 2.9.0

package/README.md

@@ -4,14 +4,18 @@
 [![JSR version](https://jsr.io/badges/@marianmeres/http-utils)](https://jsr.io/@marianmeres/http-utils)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Opinionated, lightweight HTTP client wrapper for `fetch` with type-safe errors and convenient defaults.
+Opinionated, lightweight HTTP client wrapper for `fetch` with type-safe errors and
+convenient defaults.
 
 ## Features
 
 - 🎯 **Type-safe HTTP errors** - Well-known status codes map to specific error classes
 - 🔧 **Convenient defaults** - Auto JSON parsing, Bearer tokens, base URLs
 - 🪶 **Lightweight** - Zero dependencies, thin wrapper over native `fetch`
-- 🎨 **Flexible error handling** - Three-tier error message extraction (local → factory → global)
+- 🎨 **Flexible error handling** - Three-tier error message extraction (local → factory →
+  global)
+- 🛰️ **No swallowed transport errors** - DNS/connection failures surface the host and real
+  reason instead of an opaque "fetch failed"
 - 📦 **Deno & Node.js** - Works in both runtimes
 - 🦾 **Generic return types** - Optional type parameters for typed responses
 
@@ -26,51 +30,60 @@ npm install @marianmeres/http-utils
 ```
 
 ```ts
-import { createHttpApi, opts, HTTP_ERROR } from "@marianmeres/http-utils";
+import { createHttpApi, HTTP_ERROR, opts } from "@marianmeres/http-utils";
 ```
 
 ## Quick Start
 
 ```ts
-import { createHttpApi, opts, HTTP_ERROR, NotFound } from "@marianmeres/http-utils";
+import { createHttpApi, HTTP_ERROR, NotFound, opts } from "@marianmeres/http-utils";
 
 // Create an API client with base URL
 const api = createHttpApi("https://api.example.com", {
-  headers: { "Authorization": "Bearer your-token" }
+	headers: { "Authorization": "Bearer your-token" },
 });
 
 // GET request (options API with opts() wrapper)
-const users = await api.get("/users", opts({
-  params: { headers: { "X-Custom": "value" } }
-}));
+const users = await api.get(
+	"/users",
+	opts({
+		params: { headers: { "X-Custom": "value" } },
+	}),
+);
 
 // POST request (options API with opts() wrapper)
-const newUser = await api.post("/users", opts({
-  data: { name: "John Doe" },
-  params: { headers: { "X-Custom": "value" } }
-}));
+const newUser = await api.post(
+	"/users",
+	opts({
+		data: { name: "John Doe" },
+		params: { headers: { "X-Custom": "value" } },
+	}),
+);
 
 // Legacy API (default behavior without opts())
 const legacyUsers = await api.get("/users", { headers: { "X-Custom": "value" } });
 const legacyUser = await api.post("/users", { name: "John Doe" });
 
 // With type parameters for typed responses
-interface User { id: number; name: string; }
+interface User {
+	id: number;
+	name: string;
+}
 const user = await api.get<User>("/users/1");
 const created = await api.post<User>("/users", opts({ data: { name: "Jane" } }));
 
 // Error handling
 try {
-  await api.get("/not-found");
+	await api.get("/not-found");
 } catch (error) {
-  if (error instanceof NotFound) {
-    console.log("Resource not found");
-  }
-  // or use the namespace
-  if (error instanceof HTTP_ERROR.NotFound) {
-    console.log(error.status); // 404
-    console.log(error.body);   // Response body
-  }
+	if (error instanceof NotFound) {
+		console.log("Resource not found");
+	}
+	// or use the namespace
+	if (error instanceof HTTP_ERROR.NotFound) {
+		console.log(error.status); // 404
+		console.log(error.body); // Response body
+	}
 }
 ```
 
@@ -82,7 +95,7 @@ Creates an HTTP API client.
 
 ```ts
 const api = createHttpApi("https://api.example.com", {
-  headers: { "Authorization": "Bearer token" }
+	headers: { "Authorization": "Bearer token" },
 });
 ```
 
@@ -90,16 +103,22 @@ const api = createHttpApi("https://api.example.com", {
 
 ```ts
 // GET (options API with opts() wrapper)
-const data = await api.get("/users", opts({
-  params: { headers: { "X-Custom": "value" } },
-  respHeaders: {}
-}));
+const data = await api.get(
+	"/users",
+	opts({
+		params: { headers: { "X-Custom": "value" } },
+		respHeaders: {},
+	}),
+);
 
 // POST/PUT/PATCH/DELETE (options API with opts() wrapper)
-await api.post("/users", opts({
-  data: { name: "John" },
-  params: { token: "bearer-token" }
-}));
+await api.post(
+	"/users",
+	opts({
+		data: { name: "John" },
+		params: { token: "bearer-token" },
+	}),
+);
 
 // Legacy API (default behavior without opts())
 const data = await api.get("/users", { headers: { "X-Custom": "value" } });
@@ -108,14 +127,15 @@ await api.post("/users", { name: "John" });
 
 ### The `opts()` Helper
 
-The `opts()` function explicitly marks an options object for the options-based API. Without it, arguments are treated as legacy positional parameters.
+The `opts()` function explicitly marks an options object for the options-based API.
+Without it, arguments are treated as legacy positional parameters.
 
 ```ts
 // Without opts() - legacy behavior: object is sent as request body
-await api.post("/users", { data: { name: "John" } });  // Sends: { data: { name: "John" } }
+await api.post("/users", { data: { name: "John" } }); // Sends: { data: { name: "John" } }
 
 // With opts() - options API: data is extracted and sent as body
-await api.post("/users", opts({ data: { name: "John" } }));  // Sends: { name: "John" }
+await api.post("/users", opts({ data: { name: "John" } })); // Sends: { name: "John" }
 ```
 
 This makes the API unambiguous and prevents accidental misinterpretation of request data.
@@ -126,27 +146,37 @@ This makes the API unambiguous and prevents accidental misinterpretation of requ
 import { HTTP_ERROR, NotFound } from "@marianmeres/http-utils";
 
 try {
-  await api.get("/resource");
+	await api.get("/resource");
 } catch (error) {
-  if (error instanceof NotFound) {
-    console.log("Not found:", error.body);
-  }
-  // All errors have: status, statusText, body, cause
+	if (error instanceof NotFound) {
+		console.log("Not found:", error.body);
+	}
+	// Transport-level failures (DNS, refused connection, unreachable host) throw
+	// a NetworkError (status 0) instead of an opaque "fetch failed":
+	if (error instanceof HTTP_ERROR.NetworkError) {
+		console.log(error.message); // e.g. "GET unreachable (https://...): ECONNREFUSED"
+		console.log(error.cause); // underlying transport error
+	}
+	// All errors have: status, statusText, body, cause
 }
 ```
 
 ### Key Features
 
-- **Auto JSON**: Response bodies are automatically parsed as JSON; empty bodies (204/205) return `null`
-- **Smart body handling**: Plain objects → JSON; `FormData` / `URLSearchParams` / `Blob` / typed arrays / `ReadableStream` pass through; strings sent as-is
+- **Auto JSON**: Response bodies are automatically parsed as JSON; empty bodies (204/205)
+  return `null`
+- **Smart body handling**: Plain objects → JSON; `FormData` / `URLSearchParams` / `Blob` /
+  typed arrays / `ReadableStream` pass through; strings sent as-is
 - **Query params**: Pass `query: { page: 1, tag: ["a", "b"] }` for URL search params
 - **Timeouts**: Pass `timeout: 5000` for automatic request cancellation
 - **Bearer tokens**: Use `token` param to auto-add `Authorization: Bearer` header
 - **Response headers**: Pass `respHeaders: {}` to capture response headers
-- **Raw response**: Use `raw: true` to get the raw Response object (caller must consume the body)
+- **Raw response**: Use `raw: true` to get the raw Response object (caller must consume
+  the body)
 - **Non-throwing**: Use `assert: false` to prevent throwing on errors
 - **AbortController**: Pass `signal` for request cancellation (composes with `timeout`)
-- **Interceptors**: `api.onRequest(...)` / `api.onResponse(...)` for tracing, auth refresh, etc.
+- **Interceptors**: `api.onRequest(...)` / `api.onResponse(...)` for tracing, auth
+  refresh, etc.
 - **Typed responses**: Use generics for type-safe responses: `api.get<User>("/users/1")`
 
 ### Query, Timeout, Interceptors
@@ -160,18 +190,65 @@ await api.get("/slow", { timeout: 5000 });
 
 // Interceptors
 api.onRequest((init, { method, url }) => {
-  console.log(method, url);
+	console.log(method, url);
 }).onResponse(async (resp) => {
-  if (resp.status === 401) await refreshToken();
+	if (resp.status === 401) await refreshToken();
 });
 ```
 
 ## Full API Reference
 
-For complete API documentation including all error classes, HTTP status codes, types, and utilities, see **[API.md](API.md)**.
+For complete API documentation including all error classes, HTTP status codes, types, and
+utilities, see **[API.md](API.md)**.
 
 ## Utilities
 
+### `fetchOrThrow(input, init?, whatOrOptions?)`
+
+Wraps the native `fetch` so a transport-level failure surfaces the target host and the
+real reason instead of an opaque `TypeError: fetch failed`. On failure it throws a
+`NetworkError` (in the `HTTP_ERROR` namespace) whose message includes the URL and reason,
+and whose `cause` is the underlying transport error. Deliberate
+`AbortError`/`TimeoutError` are re-thrown untouched. The `HttpApi` client uses this
+internally — reach for it directly when wrapping your own `fetch` calls.
+
+The 3rd argument is either a label string or a `FetchOrThrowOptions` object carrying that
+label plus optional `onRequest`/`onError` observer hooks.
+
+```ts
+import { fetchOrThrow, HTTP_ERROR } from "@marianmeres/http-utils";
+
+try {
+	const res = await fetchOrThrow(
+		"https://issuer.example.com/jwks",
+		undefined,
+		"Token issuer",
+	);
+} catch (e) {
+	if (e instanceof HTTP_ERROR.NetworkError) {
+		console.log(e.message); // "Token issuer unreachable (https://issuer.example.com/jwks): ENOTFOUND"
+	}
+}
+```
+
+**Tracing requests.** The `onRequest`/`onError` hooks are pure observers (they can't
+recover or transform anything) — handy for logging, and the only way to catch a _hang_
+where neither a response nor an error ever arrives. Set defaults once on
+`fetchOrThrow.global` (overridable per call; resolution is `per-call ?? global`). Because
+`HttpApi` routes through `fetchOrThrow`, the global hooks instrument it too.
+
+```ts
+// app-wide defaults (also fire for every HttpApi request)
+fetchOrThrow.global.onRequest = ({ method, url }) => console.debug(`→ ${method} ${url}`);
+fetchOrThrow.global.onError = ({ url, kind }) =>
+	kind !== "abort" && console.error(`✗ ${url}`); // kind: "abort" | "timeout" | "network"
+
+// per-call override (here: silence the global tracer for one call)
+await fetchOrThrow(url, init, { what: "Token issuer", onRequest: () => {} });
+```
+
+See [API.md](./API.md#fetchorthrow) for the full options reference.
+
 ### `getErrorMessage(error)`
 
 Extracts human-readable messages from any error format:
@@ -180,9 +257,9 @@ Extracts human-readable messages from any error format:
 import { getErrorMessage } from "@marianmeres/http-utils";
 
 try {
-  await api.get("/fail");
+	await api.get("/fail");
 } catch (error) {
-  console.log(getErrorMessage(error)); // "Not Found"
+	console.log(getErrorMessage(error)); // "Not Found"
 }
 ```
 
@@ -195,4 +272,4 @@ import { createHttpError } from "@marianmeres/http-utils";
 
 const error = createHttpError(404, "User not found", { userId: 123 });
 throw error; // instanceof NotFound
-```
+```

package/dist/api.d.ts

@@ -117,6 +117,106 @@ export interface DataOptions {
  * ```
  */
 export declare function opts<T extends GetOptions | DataOptions>(options: T): T;
+/**
+ * Options for {@link fetchOrThrow}. Pass as the 3rd argument in place of a bare
+ * `what` string (a string is normalized to `{ what }`).
+ *
+ * `onRequest`/`onError` are **pure observers** — their return value is ignored,
+ * they cannot recover or transform the request/error. For recovery or retries
+ * use the {@link HttpApi} interceptors or your own `catch`.
+ */
+export interface FetchOrThrowOptions {
+    /** Human-readable label for the target (e.g. "Token issuer"), used in error messages. */
+    what?: string;
+    /**
+     * Called synchronously just before the request is dispatched. No-op by
+     * default. Useful for request tracing — including the hang case where
+     * neither a response nor an error ever arrives. If this throws, the request
+     * is NOT sent (a throwing tracer is a clear consumer bug, and there is no
+     * original error to preserve — unlike {@link FetchOrThrowOptions.onError}).
+     */
+    onRequest?: (info: {
+        url: string;
+        method?: string;
+        what?: string;
+    }) => void;
+    /**
+     * Called just before a transport-level failure is (re-)thrown. Pure observer:
+     * its return value is ignored and the original error always propagates. A
+     * throw here is swallowed so a broken hook can never mask the real error.
+     * `kind` classifies the failure so callers can, e.g., skip deliberate aborts.
+     */
+    onError?: (info: {
+        error: unknown;
+        url: string;
+        what?: string;
+        kind: "abort" | "timeout" | "network";
+    }) => void;
+}
+/**
+ * Global defaults for {@link fetchOrThrow}, exposed as `fetchOrThrow.global` and
+ * overridable per call (resolution is `per-call ?? global`). Observer hooks only
+ * — `what` is per-call by nature, so it is intentionally excluded.
+ */
+export type FetchOrThrowGlobalOptions = Pick<FetchOrThrowOptions, "onRequest" | "onError">;
+/**
+ * Wraps the native `fetch` so a transport-level failure surfaces the target host
+ * and the real reason instead of an opaque "fetch failed".
+ *
+ * Node/undici collapses DNS failures, refused connections and connect timeouts
+ * into a `TypeError: fetch failed` whose actual code (`ENOTFOUND`,
+ * `ECONNREFUSED`, `UND_ERR_CONNECT_TIMEOUT`, ...) lives on `err.cause` and is
+ * absent from the message and stack. On such a failure this throws a
+ * `NetworkError` (see {@link HTTP_ERROR}) whose message includes the URL and the
+ * resolved reason, and whose `cause` is the underlying transport error (so both
+ * `error.message` and `getErrorMessage(error)` report the real reason).
+ *
+ * Deliberate cancellations (`AbortError`) and timeouts (`TimeoutError`) are
+ * re-thrown untouched — they already carry clear semantics and must not be
+ * masked as "host unreachable".
+ *
+ * Optional observer hooks (`onRequest`/`onError`, see {@link FetchOrThrowOptions})
+ * can trace the request without wrapping the call site in `try/catch`; the most
+ * useful case is detecting a hang, where neither a response nor an error ever
+ * arrives. Defaults can be set once on `fetchOrThrow.global` and overridden per
+ * call (resolution is `per-call ?? global`). Because {@link HttpApi} routes every
+ * request through this function, the global hooks instrument it too.
+ *
+ * @param input - The `fetch` resource (URL string, `URL`, or `Request`).
+ * @param init - The `fetch` `RequestInit` options.
+ * @param what - Either a label describing the target (e.g. "Token issuer"), used
+ *   to prefix the error message, or a {@link FetchOrThrowOptions} object carrying
+ *   that label plus the `onRequest`/`onError` observer hooks.
+ *
+ * @returns The `Response`. This does NOT throw on non-2xx HTTP statuses — only
+ *   on transport-level failures, exactly like the native `fetch`.
+ *
+ * @throws A `NetworkError` on a transport-level failure (DNS, refused
+ *   connection, unreachable host, ...).
+ *
+ * @example
+ * ```ts
+ * import { fetchOrThrow, HTTP_ERROR } from "@marianmeres/http-utils";
+ *
+ * // Configure tracing once, app-wide (also instruments the HttpApi client):
+ * fetchOrThrow.global.onRequest = ({ method, url }) => console.debug(`→ ${method} ${url}`);
+ * fetchOrThrow.global.onError = ({ url, kind }) =>
+ *   kind !== "abort" && console.error(`✗ ${url}`);
+ *
+ * try {
+ *   const res = await fetchOrThrow("https://issuer.example.com/jwks", undefined, "Token issuer");
+ * } catch (e) {
+ *   if (e instanceof HTTP_ERROR.NetworkError) {
+ *     // e.message → "Token issuer unreachable (https://issuer.example.com/jwks): ENOTFOUND"
+ *     // e.cause   → underlying transport error
+ *   }
+ * }
+ * ```
+ */
+export declare function fetchOrThrow(input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1], what?: string | FetchOrThrowOptions): Promise<Response>;
+export declare namespace fetchOrThrow {
+    var global: FetchOrThrowGlobalOptions;
+}
 /**
  * HTTP API client with convenient defaults and error handling.
  */

package/dist/api.js

@@ -4,7 +4,7 @@
  * HTTP API client factory and related types.
  * Provides a convenient wrapper over the native `fetch` API with sensible defaults.
  */
-import { createHttpError } from "./error.js";
+import { createHttpError, getErrorMessage, NetworkError } from "./error.js";
 /**
  * Deep merges two objects. Later properties overwrite earlier properties.
  * Arrays are overwritten, not concatenated (conventional behavior).
@@ -101,8 +101,9 @@ function composeSignal(userSignal, timeoutMs) {
         userSignal.addEventListener("abort", () => abort(userSignal.reason));
     if (timeoutSignal.aborted)
         abort(timeoutSignal.reason);
-    else
+    else {
         timeoutSignal.addEventListener("abort", () => abort(timeoutSignal.reason));
+    }
     return ctrl.signal;
 }
 /** Symbol marker for explicit options API detection. */
@@ -209,6 +210,142 @@ function buildRequest(params) {
         url = appendQuery(url, query);
     return { url, init };
 }
+/** Best-effort human-readable description of a `fetch` target for error messages. */
+function _describeFetchTarget(input) {
+    if (typeof input === "string")
+        return input;
+    if (input instanceof URL)
+        return input.href;
+    return input?.url ?? String(input);
+}
+// `Symbol.for` + `globalThis` so multiple bundled copies of this package still
+// share one config object (same approach as `@marianmeres/clog`'s global state).
+const _FOT_GLOBAL_KEY = Symbol.for("@marianmeres/http-utils/fetchOrThrow");
+const _FOT_GLOBAL = 
+// deno-lint-ignore no-explicit-any
+(globalThis[_FOT_GLOBAL_KEY] ??= {
+    onRequest: undefined,
+    onError: undefined,
+});
+/**
+ * Invoke an `onError` observer defensively: `url` is only computed when a hook
+ * is present, and a throwing hook is swallowed so it can never replace the real
+ * error that is about to propagate.
+ */
+function _notifyFetchError(hook, error, describe, input, what, kind) {
+    if (!hook)
+        return;
+    try {
+        hook({ error, url: describe(input), what, kind });
+    }
+    catch {
+        /* observer hooks must not alter control flow */
+    }
+}
+/**
+ * Wraps the native `fetch` so a transport-level failure surfaces the target host
+ * and the real reason instead of an opaque "fetch failed".
+ *
+ * Node/undici collapses DNS failures, refused connections and connect timeouts
+ * into a `TypeError: fetch failed` whose actual code (`ENOTFOUND`,
+ * `ECONNREFUSED`, `UND_ERR_CONNECT_TIMEOUT`, ...) lives on `err.cause` and is
+ * absent from the message and stack. On such a failure this throws a
+ * `NetworkError` (see {@link HTTP_ERROR}) whose message includes the URL and the
+ * resolved reason, and whose `cause` is the underlying transport error (so both
+ * `error.message` and `getErrorMessage(error)` report the real reason).
+ *
+ * Deliberate cancellations (`AbortError`) and timeouts (`TimeoutError`) are
+ * re-thrown untouched — they already carry clear semantics and must not be
+ * masked as "host unreachable".
+ *
+ * Optional observer hooks (`onRequest`/`onError`, see {@link FetchOrThrowOptions})
+ * can trace the request without wrapping the call site in `try/catch`; the most
+ * useful case is detecting a hang, where neither a response nor an error ever
+ * arrives. Defaults can be set once on `fetchOrThrow.global` and overridden per
+ * call (resolution is `per-call ?? global`). Because {@link HttpApi} routes every
+ * request through this function, the global hooks instrument it too.
+ *
+ * @param input - The `fetch` resource (URL string, `URL`, or `Request`).
+ * @param init - The `fetch` `RequestInit` options.
+ * @param what - Either a label describing the target (e.g. "Token issuer"), used
+ *   to prefix the error message, or a {@link FetchOrThrowOptions} object carrying
+ *   that label plus the `onRequest`/`onError` observer hooks.
+ *
+ * @returns The `Response`. This does NOT throw on non-2xx HTTP statuses — only
+ *   on transport-level failures, exactly like the native `fetch`.
+ *
+ * @throws A `NetworkError` on a transport-level failure (DNS, refused
+ *   connection, unreachable host, ...).
+ *
+ * @example
+ * ```ts
+ * import { fetchOrThrow, HTTP_ERROR } from "@marianmeres/http-utils";
+ *
+ * // Configure tracing once, app-wide (also instruments the HttpApi client):
+ * fetchOrThrow.global.onRequest = ({ method, url }) => console.debug(`→ ${method} ${url}`);
+ * fetchOrThrow.global.onError = ({ url, kind }) =>
+ *   kind !== "abort" && console.error(`✗ ${url}`);
+ *
+ * try {
+ *   const res = await fetchOrThrow("https://issuer.example.com/jwks", undefined, "Token issuer");
+ * } catch (e) {
+ *   if (e instanceof HTTP_ERROR.NetworkError) {
+ *     // e.message → "Token issuer unreachable (https://issuer.example.com/jwks): ENOTFOUND"
+ *     // e.cause   → underlying transport error
+ *   }
+ * }
+ * ```
+ */
+export async function fetchOrThrow(input, init, what) {
+    const opts = typeof what === "string" ? { what } : (what ?? {});
+    const label = opts.what;
+    // Per-call wins over the global default (override, not chain).
+    const onRequest = opts.onRequest ?? _FOT_GLOBAL.onRequest;
+    const onError = opts.onError ?? _FOT_GLOBAL.onError;
+    if (onRequest) {
+        const method = init?.method ??
+            (input instanceof Request ? input.method : undefined);
+        onRequest({ url: _describeFetchTarget(input), method, what: label });
+    }
+    try {
+        return await fetch(input, init);
+    }
+    catch (err) {
+        const name = err?.name;
+        const kind = name === "AbortError"
+            ? "abort"
+            : name === "TimeoutError"
+                ? "timeout"
+                : "network";
+        // Preserve deliberate cancellations and timeouts as-is.
+        if (kind !== "network") {
+            _notifyFetchError(onError, err, _describeFetchTarget, input, label, kind);
+            throw err;
+        }
+        // undici/Node bury the real reason on `err.cause`; prefer it so both
+        // `.message` and `getErrorMessage(networkError)` surface ENOTFOUND/etc.
+        // rather than re-surfacing the opaque outer "fetch failed".
+        const underlying = err?.cause ?? err;
+        const reason = getErrorMessage(underlying);
+        const url = _describeFetchTarget(input);
+        const message = label
+            ? `${label} unreachable (${url}): ${reason}`
+            : `Network request to ${url} failed: ${reason}`;
+        const networkError = new NetworkError(message, { cause: underlying });
+        _notifyFetchError(onError, networkError, () => url, input, label, kind);
+        throw networkError;
+    }
+}
+/**
+ * Global defaults for {@link fetchOrThrow}'s observer hooks, overridable per call.
+ * Mirrors `createHttpApi.defaultErrorMessageExtractor` and `createClog.global`.
+ *
+ * @example
+ * ```ts
+ * fetchOrThrow.global.onRequest = ({ method, url }) => console.debug(`→ ${method} ${url}`);
+ * ```
+ */
+fetchOrThrow.global = _FOT_GLOBAL;
 const _fetch = async (params, respHeaders = null, errorMessageExtractor = null, requestInterceptor = null, responseInterceptor = null, _dumpParams = false) => {
     if (_dumpParams)
         return params;
@@ -221,7 +358,7 @@ const _fetch = async (params, respHeaders = null, errorMessageExtractor = null,
         if (patched)
             init = patched;
     }
-    let r = await fetch(url, init);
+    let r = await fetchOrThrow(url, init, params.method);
     if (responseInterceptor) {
         const patched = await responseInterceptor(r, {
             method: params.method,
@@ -232,7 +369,9 @@ const _fetch = async (params, respHeaders = null, errorMessageExtractor = null,
             try {
                 await r.body?.cancel();
             }
-            catch (_e) { /* ignore */ }
+            catch (_e) {
+                /* ignore */
+            }
             r = patched;
         }
     }

package/dist/error.d.ts

@@ -124,7 +124,33 @@ declare class ServiceUnavailable extends HttpError {
     status: number;
     statusText: string;
 }
-export { HttpError, BadRequest, Unauthorized, Forbidden, NotFound, MethodNotAllowed, RequestTimeout, Conflict, Gone, LengthRequired, ImATeapot, UnprocessableContent, TooManyRequests, InternalServerError, NotImplemented, BadGateway, ServiceUnavailable, };
+/**
+ * Transport-level failure: DNS resolution failure, refused connection, connect
+ * timeout, unreachable host, etc. No HTTP response was received, so `status` is
+ * `0` (the de-facto web convention for network-level failures, mirroring
+ * `XMLHttpRequest.status`). Thrown by `fetchOrThrow` (and, by extension, by the
+ * `HttpApi` client) with the underlying transport error attached as `cause`, so
+ * the real reason (`ENOTFOUND`, `ECONNREFUSED`, ...) is never swallowed behind
+ * an opaque "fetch failed".
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await api.get("/resource");
+ * } catch (error) {
+ *   if (error instanceof HTTP_ERROR.NetworkError) {
+ *     console.log(error.message); // e.g. "GET unreachable (https://...): ECONNREFUSED"
+ *     console.log(error.cause);   // the underlying transport error
+ *   }
+ * }
+ * ```
+ */
+declare class NetworkError extends HttpError {
+    name: string;
+    status: number;
+    statusText: string;
+}
+export { BadGateway, BadRequest, Conflict, Forbidden, Gone, HttpError, ImATeapot, InternalServerError, LengthRequired, MethodNotAllowed, NetworkError, NotFound, NotImplemented, RequestTimeout, ServiceUnavailable, TooManyRequests, Unauthorized, UnprocessableContent, };
 /**
  * Namespace containing all HTTP error classes for convenient access.
  *
@@ -162,6 +188,7 @@ export declare const HTTP_ERROR: {
     NotImplemented: typeof NotImplemented;
     BadGateway: typeof BadGateway;
     ServiceUnavailable: typeof ServiceUnavailable;
+    NetworkError: typeof NetworkError;
 };
 /**
  * Creates an HTTP error from a status code and optional details.