@marianmeres/http-utils 2.7.1 → 2.8.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,44 @@ 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?, what?)`
+
+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.
+
+```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"
+	}
+}
+```
+
 ### `getErrorMessage(error)`
 
 Extracts human-readable messages from any error format:
@@ -180,9 +236,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 +251,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,48 @@ export interface DataOptions {
  * ```
  */
 export declare function opts<T extends GetOptions | DataOptions>(options: T): T;
+/**
+ * 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".
+ *
+ * @param input - The `fetch` resource (URL string, `URL`, or `Request`).
+ * @param init - The `fetch` `RequestInit` options.
+ * @param what - Optional label describing the target (e.g. "Token issuer"),
+ *   used to prefix the error message.
+ *
+ * @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";
+ *
+ * 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): Promise<Response>;
 /**
  * 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,76 @@ 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);
+}
+/**
+ * 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".
+ *
+ * @param input - The `fetch` resource (URL string, `URL`, or `Request`).
+ * @param init - The `fetch` `RequestInit` options.
+ * @param what - Optional label describing the target (e.g. "Token issuer"),
+ *   used to prefix the error message.
+ *
+ * @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";
+ *
+ * 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) {
+    try {
+        return await fetch(input, init);
+    }
+    catch (err) {
+        const name = err?.name;
+        // Preserve deliberate cancellations and timeouts as-is.
+        if (name === "AbortError" || name === "TimeoutError")
+            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 = what
+            ? `${what} unreachable (${url}): ${reason}`
+            : `Network request to ${url} failed: ${reason}`;
+        throw new NetworkError(message, { cause: underlying });
+    }
+}
 const _fetch = async (params, respHeaders = null, errorMessageExtractor = null, requestInterceptor = null, responseInterceptor = null, _dumpParams = false) => {
     if (_dumpParams)
         return params;
@@ -221,7 +292,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 +303,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.