@marianmeres/http-utils 2.9.0 → 2.10.0

package/AGENTS.md

@@ -162,7 +162,8 @@ function getErrorMessage(e: unknown, stripErrorPrefix?: boolean): string;
 // 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 kind: "abort" | "timeout" | "network" (throw => swallowed, real error preserved).
+//   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(

package/API.md

@@ -746,6 +746,8 @@ interface FetchOrThrowOptions {
 		url: string;
 		what?: string;
 		kind: "abort" | "timeout" | "network";
+		/** Human-readable reason (via `getErrorMessage`); always a string. */
+		reason: string;
 	}) => void;
 }
 
@@ -773,8 +775,8 @@ Set defaults once on `fetchOrThrow.global`; per-call options win (resolution is
 ```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}`);
+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: () => {} });

package/README.md

@@ -240,8 +240,8 @@ where neither a response nor an error ever arrives. Set defaults once on
 ```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"
+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: () => {} });

package/dist/api.d.ts

@@ -151,6 +151,14 @@ export interface FetchOrThrowOptions {
         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;
 }
 /**
@@ -200,8 +208,8 @@ export type FetchOrThrowGlobalOptions = Pick<FetchOrThrowOptions, "onRequest" |
  *
  * // 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}`);
+ * 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");

package/dist/api.js

@@ -228,15 +228,22 @@ const _FOT_GLOBAL =
     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.
+ * 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) {
+function _notifyFetchError(hook, error, describe, input, what, kind, reason) {
     if (!hook)
         return;
     try {
-        hook({ error, url: describe(input), what, kind });
+        hook({
+            error,
+            url: describe(input),
+            what,
+            kind,
+            reason: reason ?? getErrorMessage(error),
+        });
     }
     catch {
         /* observer hooks must not alter control flow */
@@ -283,8 +290,8 @@ function _notifyFetchError(hook, error, describe, input, what, kind) {
  *
  * // 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}`);
+ * 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");
@@ -332,7 +339,7 @@ export async function fetchOrThrow(input, init, what) {
             ? `${label} unreachable (${url}): ${reason}`
             : `Network request to ${url} failed: ${reason}`;
         const networkError = new NetworkError(message, { cause: underlying });
-        _notifyFetchError(onError, networkError, () => url, input, label, kind);
+        _notifyFetchError(onError, networkError, () => url, input, label, kind, reason);
         throw networkError;
     }
 }

package/package.json

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