@naturalcycles/js-lib 15.82.0 → 15.83.0

package/dist/http/fetcher.d.ts

@@ -35,8 +35,15 @@ export declare class Fetcher {
      * See FetcherInitHook docs.
      */
     onInit(hook: FetcherInitHook): this;
+    /**
+     * Clears the cached result of the init hooks, so they re-run before the next request.
+     * Useful when the state acquired during init (e.g an auth token) becomes stale.
+     * See also `cfg.hooks.shouldReinit`, which calls this automatically.
+     */
+    resetInit(): void;
     cfg: FetcherNormalizedCfg;
     private initPromise?;
+    private initGeneration;
     static create(cfg?: FetcherCfg & FetcherOptions): Fetcher;
     get: <T = unknown>(url: string, opt?: FetcherOptions) => Promise<T>;
     post: <T = unknown>(url: string, opt?: FetcherOptions) => Promise<T>;
@@ -110,6 +117,12 @@ export declare class Fetcher {
      * Note: responseType defaults to the Fetcher's cfg responseType (`json`, unless overridden).
      */
     doFetch<T = unknown>(opt: FetcherOptions): Promise<FetcherResponse<T>>;
+    /**
+     * Consults cfg.hooks.shouldReinit to detect "stale init" (e.g expired auth token).
+     * If detected - resets the init (so it re-runs) and returns true,
+     * telling the caller to retry the request. At most once per request.
+     */
+    private detectStaleInit;
     private runInitHooks;
     private onOkResponse;
     /**

package/dist/http/fetcher.js

@@ -101,8 +101,18 @@ export class Fetcher {
         (this.cfg.hooks.init ||= []).push(hook);
         return this;
     }
+    /**
+     * Clears the cached result of the init hooks, so they re-run before the next request.
+     * Useful when the state acquired during init (e.g an auth token) becomes stale.
+     * See also `cfg.hooks.shouldReinit`, which calls this automatically.
+     */
+    resetInit() {
+        this.initPromise = undefined;
+        this.initGeneration++;
+    }
     cfg;
     initPromise;
+    initGeneration = 0;
     static create(cfg = {}) {
         return new Fetcher(cfg);
     }
@@ -271,15 +281,17 @@ export class Fetcher {
      * Note: responseType defaults to the Fetcher's cfg responseType (`json`, unless overridden).
      */
     async doFetch(opt) {
+        let initGeneration = 0;
         if (this.cfg.hooks.init) {
             try {
                 await (this.initPromise ??= this.runInitHooks());
             }
             catch (err) {
                 // Reset, so init hooks are re-attempted on the next request
-                this.initPromise = undefined;
+                this.resetInit();
                 throw err;
             }
+            initGeneration = this.initGeneration;
         }
         const req = this.normalizeOptions(opt);
         const { logger } = this.cfg;
@@ -368,8 +380,31 @@ export class Fetcher {
         for (const hook of this.cfg.hooks.afterResponse || []) {
             await hook(res);
         }
+        if (res.err && (await this.detectStaleInit(opt, res, initGeneration))) {
+            // Stale init (e.g expired auth token) was detected and reset - retry the request once
+            return await this.doFetch({ ...opt, [reinitAttempted]: true });
+        }
         return res;
     }
+    /**
+     * Consults cfg.hooks.shouldReinit to detect "stale init" (e.g expired auth token).
+     * If detected - resets the init (so it re-runs) and returns true,
+     * telling the caller to retry the request. At most once per request.
+     */
+    async detectStaleInit(opt, res, initGeneration) {
+        const { shouldReinit, init } = this.cfg.hooks;
+        if (!shouldReinit || !init)
+            return false;
+        if (opt[reinitAttempted])
+            return false;
+        if (!(await shouldReinit(res)))
+            return false;
+        // Generation check prevents concurrent stale requests from resetting the already-fresh init
+        if (initGeneration === this.initGeneration) {
+            this.resetInit();
+        }
+        return true;
+    }
     async runInitHooks() {
         for (const hook of this.cfg.hooks.init || []) {
             await hook(this.cfg);
@@ -816,6 +851,9 @@ export class Fetcher {
 export function getFetcher(cfg = {}) {
     return Fetcher.create(cfg);
 }
+// Marks FetcherOptions of a request that was already retried due to a reinit,
+// to guarantee at most one reinit per request
+const reinitAttempted = Symbol('reinitAttempted');
 const acceptByResponseType = {
     text: 'text/plain',
     json: 'application/json',

package/dist/http/fetcher.model.d.ts

@@ -30,6 +30,15 @@ export type FetcherOnErrorHook = (err: Error) => Promisable<void>;
  * and set `cfg.init.headers` based on it.
  */
 export type FetcherInitHook = (cfg: FetcherNormalizedCfg) => Promisable<void>;
+/**
+ * Decides, based on the error response, if the Fetcher init state is "stale",
+ * e.g the auth token acquired in the init hook has expired.
+ * Returning true triggers `resetInit()`, so the init hooks re-run,
+ * and the request is then retried (at most once per request).
+ *
+ * Only consulted when init hooks are defined and the request resulted in an error.
+ */
+export type FetcherShouldReinitFn = (res: FetcherErrorResponse) => Promisable<boolean>;
 /**
  * FetcherCfg: configuration of the Fetcher instance. One per instance.
  * FetcherOptions: options for a single request. One per request.
@@ -56,6 +65,13 @@ export interface FetcherCfg {
          * See FetcherInitHook docs.
          */
         init?: FetcherInitHook[];
+        /**
+         * Allows to detect "stale init" (e.g the auth token acquired in the init hook
+         * has expired) based on the error response, and trigger reinit+retry.
+         * Unlike other hooks, it's a single decision predicate, not an array.
+         * See FetcherShouldReinitFn docs.
+         */
+        shouldReinit?: FetcherShouldReinitFn;
         /**
          * Allows to mutate req.
          */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/js-lib",
   "type": "module",
-  "version": "15.82.0",
+  "version": "15.83.0",
   "dependencies": {
     "tslib": "^2"
   },

package/src/http/fetcher.model.ts

@@ -59,6 +59,15 @@ export type FetcherOnErrorHook = (err: Error) => Promisable<void>
  * and set `cfg.init.headers` based on it.
  */
 export type FetcherInitHook = (cfg: FetcherNormalizedCfg) => Promisable<void>
+/**
+ * Decides, based on the error response, if the Fetcher init state is "stale",
+ * e.g the auth token acquired in the init hook has expired.
+ * Returning true triggers `resetInit()`, so the init hooks re-run,
+ * and the request is then retried (at most once per request).
+ *
+ * Only consulted when init hooks are defined and the request resulted in an error.
+ */
+export type FetcherShouldReinitFn = (res: FetcherErrorResponse) => Promisable<boolean>
 
 /**
  * FetcherCfg: configuration of the Fetcher instance. One per instance.
@@ -88,6 +97,13 @@ export interface FetcherCfg {
      * See FetcherInitHook docs.
      */
     init?: FetcherInitHook[]
+    /**
+     * Allows to detect "stale init" (e.g the auth token acquired in the init hook
+     * has expired) based on the error response, and trigger reinit+retry.
+     * Unlike other hooks, it's a single decision predicate, not an array.
+     * See FetcherShouldReinitFn docs.
+     */
+    shouldReinit?: FetcherShouldReinitFn
     /**
      * Allows to mutate req.
      */

package/src/http/fetcher.ts

@@ -42,6 +42,7 @@ import type {
   FetcherBeforeRequestHook,
   FetcherBeforeRetryHook,
   FetcherCfg,
+  FetcherErrorResponse,
   FetcherGraphQLOptions,
   FetcherInitHook,
   FetcherNormalizedCfg,
@@ -154,9 +155,20 @@ export class Fetcher {
     return this
   }
 
+  /**
+   * Clears the cached result of the init hooks, so they re-run before the next request.
+   * Useful when the state acquired during init (e.g an auth token) becomes stale.
+   * See also `cfg.hooks.shouldReinit`, which calls this automatically.
+   */
+  resetInit(): void {
+    this.initPromise = undefined
+    this.initGeneration++
+  }
+
   cfg: FetcherNormalizedCfg
 
   private initPromise?: Promise<void>
+  private initGeneration = 0
 
   static create(cfg: FetcherCfg & FetcherOptions = {}): Fetcher {
     return new Fetcher(cfg)
@@ -349,14 +361,16 @@ export class Fetcher {
    * Note: responseType defaults to the Fetcher's cfg responseType (`json`, unless overridden).
    */
   async doFetch<T = unknown>(opt: FetcherOptions): Promise<FetcherResponse<T>> {
+    let initGeneration = 0
     if (this.cfg.hooks.init) {
       try {
         await (this.initPromise ??= this.runInitHooks())
       } catch (err) {
         // Reset, so init hooks are re-attempted on the next request
-        this.initPromise = undefined
+        this.resetInit()
         throw err
       }
+      initGeneration = this.initGeneration
     }
 
     const req = this.normalizeOptions(opt)
@@ -469,9 +483,36 @@ export class Fetcher {
       await hook(res)
     }
 
+    if (res.err && (await this.detectStaleInit(opt, res, initGeneration))) {
+      // Stale init (e.g expired auth token) was detected and reset - retry the request once
+      return await this.doFetch<T>({ ...opt, [reinitAttempted]: true } as FetcherOptions)
+    }
+
     return res
   }
 
+  /**
+   * Consults cfg.hooks.shouldReinit to detect "stale init" (e.g expired auth token).
+   * If detected - resets the init (so it re-runs) and returns true,
+   * telling the caller to retry the request. At most once per request.
+   */
+  private async detectStaleInit(
+    opt: FetcherOptions,
+    res: FetcherErrorResponse,
+    initGeneration: number,
+  ): Promise<boolean> {
+    const { shouldReinit, init } = this.cfg.hooks
+    if (!shouldReinit || !init) return false
+    if ((opt as any)[reinitAttempted]) return false
+    if (!(await shouldReinit(res))) return false
+
+    // Generation check prevents concurrent stale requests from resetting the already-fresh init
+    if (initGeneration === this.initGeneration) {
+      this.resetInit()
+    }
+    return true
+  }
+
   private async runInitHooks(): Promise<void> {
     for (const hook of this.cfg.hooks.init || []) {
       await hook(this.cfg)
@@ -970,6 +1011,10 @@ export function getFetcher(cfg: FetcherCfg & FetcherOptions = {}): Fetcher {
   return Fetcher.create(cfg)
 }
 
+// Marks FetcherOptions of a request that was already retried due to a reinit,
+// to guarantee at most one reinit per request
+const reinitAttempted = Symbol('reinitAttempted')
+
 const acceptByResponseType: Record<FetcherResponseType, string> = {
   text: 'text/plain',
   json: 'application/json',