@marianmeres/http-utils 2.8.0 → 2.10.0

package/AGENTS.md

@@ -160,10 +160,16 @@ function createHttpError(
 function getErrorMessage(e: unknown, stripErrorPrefix?: boolean): string;
 // Wraps fetch; on transport failure throws NetworkError("<what> unreachable (<url>): <reason>", { cause }).
 // AbortError/TimeoutError pass through untouched. Used internally by HttpApi.
+// 3rd arg is a label string OR FetchOrThrowOptions { what?, onRequest?, onError? } (pure observers; a string normalizes to { what }).
+// onRequest fires before dispatch (throw => request not sent). onError fires on every failure
+//   with { error, url, what?, kind: "abort"|"timeout"|"network", reason } (reason via getErrorMessage;
+//   throw => swallowed, real error preserved).
+// Global defaults (overridable per call; resolution: per-call ?? global; instruments HttpApi too):
+//   fetchOrThrow.global.onRequest / fetchOrThrow.global.onError
 function fetchOrThrow(
 	input: string | URL | Request,
 	init?: RequestInit,
-	what?: string,
+	whatOrOptions?: string | FetchOrThrowOptions,
 ): Promise<Response>;
 ```
 
@@ -209,6 +215,9 @@ class HTTP_STATUS {
     host) throw `HTTP_ERROR.NetworkError` (status 0) via `fetchOrThrow`, with the real
     reason in the message and the underlying error as `cause` — never an opaque "fetch
     failed". Deliberate `AbortError`/`TimeoutError` are not wrapped.
+11. **Request tracing**: `fetchOrThrow.global.onRequest` / `onError` are observer-only
+    hooks (no recovery/transform), overridable per call (`per-call ?? global`). They also
+    fire for `HttpApi` requests, since the client routes through `fetchOrThrow`.
 
 ## Request Body Serialization
 

package/API.md

@@ -704,13 +704,14 @@ too — you only need `fetchOrThrow` directly when wrapping your own `fetch` cal
 function fetchOrThrow(
 	input: string | URL | Request,
 	init?: RequestInit,
-	what?: string,
+	whatOrOptions?: string | FetchOrThrowOptions,
 ): Promise<Response>;
 ```
 
 Like the native `fetch`, this does **not** throw on non-2xx HTTP statuses — only on
-transport-level failures. The optional `what` is a label describing the target (e.g.
-`"Token issuer"`) used to prefix the error message.
+transport-level failures. The 3rd argument is either a label string (e.g.
+`"Token issuer"`) used to prefix the error message, or a `FetchOrThrowOptions` object
+carrying that label plus observer hooks (a bare string is normalized to `{ what }`).
 
 **Example:**
 
@@ -731,6 +732,56 @@ try {
 }
 ```
 
+#### Observer hooks & global defaults
+
+```ts
+interface FetchOrThrowOptions {
+	/** Label for the target, used to prefix the error message. */
+	what?: string;
+	/** Fires synchronously before the request is dispatched. If it throws, the request is NOT sent. */
+	onRequest?: (info: { url: string; method?: string; what?: string }) => void;
+	/** Fires before a failure is (re-)thrown. A throw here is swallowed. */
+	onError?: (info: {
+		error: unknown;
+		url: string;
+		what?: string;
+		kind: "abort" | "timeout" | "network";
+		/** Human-readable reason (via `getErrorMessage`); always a string. */
+		reason: string;
+	}) => void;
+}
+
+// Observer hooks only — `what` is per-call by nature.
+type FetchOrThrowGlobalOptions = Pick<FetchOrThrowOptions, "onRequest" | "onError">;
+```
+
+`onRequest`/`onError` are **pure observers**: their return value is ignored and they
+cannot recover or transform the request/error. Reach for them to trace requests — notably
+the _hang_ case, where neither a response nor an error ever arrives. For recovery or
+retries use the `HttpApi` interceptors or your own `catch`.
+
+- `onError` fires for **every** terminal failure; `kind`
+  (`"abort" | "timeout" | "network"`) lets you filter — e.g. skip deliberate aborts. Only
+  a `"network"` failure is wrapped in a `NetworkError`; aborts/timeouts propagate
+  untouched (the `error` passed to the hook is always the one that actually throws).
+- A throwing `onRequest` aborts before the request is sent (clear consumer bug, no
+  original error to lose). A throwing `onError` is **swallowed**, so a broken hook can
+  never mask the real error. This asymmetry is intentional.
+
+Set defaults once on `fetchOrThrow.global`; per-call options win (resolution is
+`per-call ?? global`, an override — not a chain). Because `HttpApi` routes through
+`fetchOrThrow`, these globals instrument the client's requests 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, reason }) =>
+	kind !== "abort" && console.error(`✗ ${url}: ${reason}`);
+
+// per-call object form (overrides the global onRequest for this call only)
+await fetchOrThrow(url, init, { what: "Token issuer", onRequest: () => {} });
+```
+
 ### createHttpError
 
 Creates an HTTP error from a status code and optional details.

package/README.md

@@ -203,7 +203,7 @@ utilities, see **[API.md](API.md)**.
 
 ## Utilities
 
-### `fetchOrThrow(input, init?, what?)`
+### `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
@@ -212,6 +212,9 @@ 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";
 
@@ -228,6 +231,24 @@ try {
 }
 ```
 
+**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, reason }) =>
+	kind !== "abort" && console.error(`✗ ${url}: ${reason}`); // 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:

package/dist/api.d.ts

@@ -117,6 +117,56 @@ 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";
+        /**
+         * Human-readable failure reason, extracted via `getErrorMessage`. For a
+         * `network` failure this is the resolved transport reason embedded in the
+         * `NetworkError` message (e.g. `"ENOTFOUND"`); for `abort`/`timeout` it is
+         * the message of the original error. Always a string — handy for structured
+         * logging without re-parsing `error` yourself.
+         */
+        reason: string;
+    }) => 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".
@@ -133,10 +183,18 @@ export declare function opts<T extends GetOptions | DataOptions>(options: T): T;
  * 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 - Optional label describing the target (e.g. "Token issuer"),
- *   used to prefix the error message.
+ * @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`.
@@ -148,6 +206,11 @@ export declare function opts<T extends GetOptions | DataOptions>(options: T): T;
  * ```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, reason }) =>
+ *   kind !== "abort" && console.error(`✗ ${url}: ${reason}`);
+ *
  * try {
  *   const res = await fetchOrThrow("https://issuer.example.com/jwks", undefined, "Token issuer");
  * } catch (e) {
@@ -158,7 +221,10 @@ export declare function opts<T extends GetOptions | DataOptions>(options: T): T;
  * }
  * ```
  */
-export declare function fetchOrThrow(input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1], what?: string): Promise<Response>;
+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

@@ -218,6 +218,37 @@ function _describeFetchTarget(input) {
         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` and `reason` are only computed
+ * when a hook is present (the network path passes its already-resolved `reason`
+ * to avoid a second extraction), 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, reason) {
+    if (!hook)
+        return;
+    try {
+        hook({
+            error,
+            url: describe(input),
+            what,
+            kind,
+            reason: reason ?? getErrorMessage(error),
+        });
+    }
+    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".
@@ -234,10 +265,18 @@ function _describeFetchTarget(input) {
  * 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 - Optional label describing the target (e.g. "Token issuer"),
- *   used to prefix the error message.
+ * @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`.
@@ -249,6 +288,11 @@ function _describeFetchTarget(input) {
  * ```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, reason }) =>
+ *   kind !== "abort" && console.error(`✗ ${url}: ${reason}`);
+ *
  * try {
  *   const res = await fetchOrThrow("https://issuer.example.com/jwks", undefined, "Token issuer");
  * } catch (e) {
@@ -260,26 +304,55 @@ function _describeFetchTarget(input) {
  * ```
  */
 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 (name === "AbortError" || name === "TimeoutError")
+        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 = what
-            ? `${what} unreachable (${url}): ${reason}`
+        const message = label
+            ? `${label} unreachable (${url}): ${reason}`
             : `Network request to ${url} failed: ${reason}`;
-        throw new NetworkError(message, { cause: underlying });
+        const networkError = new NetworkError(message, { cause: underlying });
+        _notifyFetchError(onError, networkError, () => url, input, label, kind, reason);
+        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;

package/dist/mod.d.ts

@@ -21,6 +21,6 @@
  * }
  * ```
  */
-export { createHttpApi, type DataOptions, type ErrorMessageExtractor, fetchOrThrow, type FetchParams, type GetOptions, HttpApi, opts, type QueryValue, type RequestData, type RequestInterceptor, type ResponseHeaders, type ResponseInterceptor, } from "./api.js";
+export { createHttpApi, type DataOptions, type ErrorMessageExtractor, fetchOrThrow, type FetchOrThrowGlobalOptions, type FetchOrThrowOptions, type FetchParams, type GetOptions, HttpApi, opts, type QueryValue, type RequestData, type RequestInterceptor, type ResponseHeaders, type ResponseInterceptor, } from "./api.js";
 export { createHttpError, getErrorMessage, HTTP_ERROR } from "./error.js";
 export { HTTP_STATUS } from "./status.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/http-utils",
-	"version": "2.8.0",
+	"version": "2.10.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",