@theholocron/http-client 1.56.0 → 1.57.0

package/README.md

@@ -62,6 +62,20 @@ const client = createRestClient({ baseUrl: "...", token: "...", logger, errors }
 typically expected and already handled by the caller (a 404 from a
 "does this exist" check, etc.).
 
+### `onRetry(listener)`
+
+Hear about every retry any client in this process is about to make, so a command line can say "retrying GitHub, attempt 2 of 3" instead of sitting silent. Returns a function that stops listening.
+
+```ts
+const stop = onRetry(({ vendor, attempt, of, code, delayMs }) => {
+  console.error(`retrying ${vendor}, attempt ${attempt} of ${of} (${code}, in ${delayMs} ms)`);
+});
+// …requests…
+stop();
+```
+
+It is per process, not per client, so nothing has to be handed to each client. It needs one copy of this package in the process (a workspace pins it); with two, the other copy's retries go unseen. A listener that throws is ignored.
+
 ### `createResolveToken(config)`
 
 Factory for the standard token resolution used by all holocron plugins. Resolution order:

package/dist/index.d.mts

@@ -117,4 +117,30 @@ interface RestClient {
 }
 declare function createRestClient(config: RestClientConfig): RestClient;
 //#endregion
-export { AuthError, ProviderApiError, type RequestOptions, type ResolveTokenConfig, type ResolveTokenInput, type RestClient, type RestClientConfig, createResolveToken, createRestClient };
+//#region src/retry-events.d.ts
+/** A request about to be sent again after a transport failure. */
+interface RetryEvent {
+  /** The client's `vendor` label, e.g. `GitHub`. */
+  vendor?: string;
+  method: string;
+  path: string;
+  /** What went wrong (`ECONNRESET`, `UND_ERR_CONNECT_TIMEOUT`); a failure with no known cause is never retried. */
+  code: string;
+  /** The number of the send that is about to happen: 2 for the first retry. */
+  attempt: number;
+  /** How many sends there can be in all (the retries plus the first). */
+  of: number;
+  /** How long it waits before sending. */
+  delayMs: number;
+}
+/**
+ * Hear about every retry any client in this process is about to make, so a command line can say "retrying GitHub,
+ * attempt 2 of 3" instead of sitting silent. Returns the way to stop listening. A listener that throws is ignored: a
+ * display problem must not fail a request.
+ *
+ * This is per process, not per client, so a command need not hand a hook to every client it builds. It relies on there
+ * being one copy of this package, which the workspace already requires; with two, retries by the other copy go unseen.
+ */
+declare function onRetry(listener: (event: RetryEvent) => void): () => void;
+//#endregion
+export { AuthError, ProviderApiError, type RequestOptions, type ResolveTokenConfig, type ResolveTokenInput, type RestClient, type RestClientConfig, type RetryEvent, createResolveToken, createRestClient, onRetry };

package/dist/index.mjs

@@ -47,6 +47,26 @@ var ProviderApiError = class extends Error {
 	}
 };
 //#endregion
+//#region src/retry-events.ts
+const listeners = /* @__PURE__ */ new Set();
+/**
+* Hear about every retry any client in this process is about to make, so a command line can say "retrying GitHub,
+* attempt 2 of 3" instead of sitting silent. Returns the way to stop listening. A listener that throws is ignored: a
+* display problem must not fail a request.
+*
+* This is per process, not per client, so a command need not hand a hook to every client it builds. It relies on there
+* being one copy of this package, which the workspace already requires; with two, retries by the other copy go unseen.
+*/
+function onRetry(listener) {
+	listeners.add(listener);
+	return () => void listeners.delete(listener);
+}
+function notifyRetry(event) {
+	for (const listener of [...listeners]) try {
+		listener(event);
+	} catch {}
+}
+//#endregion
 //#region src/transport.ts
 /**
 * Node's `fetch` rejects with a bare `TypeError: fetch failed`; the reason (a DNS miss, a connect timeout, a reset) is on
@@ -138,7 +158,17 @@ function createRestClient(config) {
 						code,
 						attempt: attempt + 1
 					}, "retrying");
-					await new Promise((resolve) => setTimeout(resolve, retryDelay * 3 ** attempt));
+					const delayMs = retryDelay * 3 ** attempt;
+					notifyRetry({
+						...vendor ? { vendor } : {},
+						method: init.method,
+						path,
+						code,
+						attempt: attempt + 2,
+						of: maxRetries + 1,
+						delayMs
+					});
+					await new Promise((resolve) => setTimeout(resolve, delayMs));
 					continue;
 				}
 				const apiErr = new ProviderApiError(`${tag} failed: ${err instanceof Error ? `${err.name}: ${err.message}` : String(err)}${code ? ` (${code})` : ""}`, 0, void 0);
@@ -165,4 +195,4 @@ function createRestClient(config) {
 	};
 }
 //#endregion
-export { AuthError, ProviderApiError, createResolveToken, createRestClient };
+export { AuthError, ProviderApiError, createResolveToken, createRestClient, onRetry };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/http-client",
-  "version": "1.56.0",
+  "version": "1.57.0",
   "description": "Shared HTTP primitives for theholocron — REST client factory, auth resolver, and error types",
   "keywords": [
     "typescript",