@naturalcycles/js-lib 15.82.0 → 15.84.0

package/dist/decorators/asyncMemo.decorator.d.ts

@@ -1,6 +1,7 @@
 import type { CommonLogger } from '../log/commonLogger.js';
 import type { AnyAsyncFunction, AnyFunction, AnyObject, MaybeParameters } from '../types.js';
-import type { AsyncMemoCache, MethodDecorator } from './memo.util.js';
+import type { MethodDecorator } from './decorator.util.js';
+import type { AsyncMemoCache } from './memo.util.js';
 export interface AsyncMemoOptions<FN> {
     /**
      * Provide a custom implementation of AsyncMemoCache.

package/dist/decorators/debounce.d.ts

@@ -1,31 +1,101 @@
-import type { AnyFunction } from '../types.js';
+import type { AnyAsyncFunction, AnyFunction } from '../types.js';
+export declare function _debounce<T extends AnyFunction>(func: T, wait: number, opt?: DebounceOptions): T & Cancelable;
+export declare function _throttle<T extends AnyFunction>(func: T, wait: number, opt?: ThrottleOptions): T & Cancelable;
+/**
+ * Like `_debounce`, but for async functions.
+ *
+ * Unlike `_debounce` (which returns a stale `result`/`undefined` for suppressed calls),
+ * `_asyncDebounce` always returns a real Promise, resolving with the coalesced invocation's result.
+ *
+ * @experimental
+ */
+export declare function _asyncDebounce<T extends AnyAsyncFunction>(func: T, wait: number, opt?: AsyncDebounceOptions): AsyncDebounced<T>;
+/**
+ * Like `_throttle`, but for async functions. See `_asyncDebounce` for the Promise semantics.
+ *
+ * @experimental
+ */
+export declare function _asyncThrottle<T extends AnyAsyncFunction>(func: T, wait: number, opt?: AsyncThrottleOptions): AsyncDebounced<T>;
 export interface Cancelable {
     cancel: () => void;
     flush: () => void;
 }
+/**
+ * Like `Cancelable`, but for the async debounced functions: `flush()` resolves with the flushed
+ * invocation's result (or `undefined` if nothing was pending), and `pending()` is exposed.
+ */
+export interface AsyncCancelable<T> {
+    cancel: () => void;
+    flush: () => Promise<T | undefined>;
+    pending: () => boolean;
+}
 export interface ThrottleOptions {
     /**
+     * Invoke on the leading edge of the window (immediately, on the first call).
+     *
      * @default true
      */
     leading?: boolean;
     /**
+     * Invoke on the trailing edge of the window (after `wait` has elapsed).
+     *
      * @default true
      */
     trailing?: boolean;
 }
 export interface DebounceOptions {
     /**
+     * Invoke on the leading edge of the window (immediately, on the first call).
+     *
      * @default false
      */
     leading?: boolean;
     /**
+     * Invoke on the trailing edge of the window (after `wait` has elapsed).
+     *
+     * @default true
+     */
+    trailing?: boolean;
+    /**
+     * Maximum time `func` is allowed to be delayed before it's forcibly invoked.
+     */
+    maxWait?: number;
+}
+export interface AsyncThrottleOptions {
+    /**
+     * Invoke on the leading edge of the window (immediately, on the first call).
+     *
+     * @default true
+     */
+    leading?: boolean;
+    /**
+     * Invoke on the trailing edge of the window (after `wait` has elapsed).
+     *
+     * When `false`, calls dropped within the window (not served by a leading invocation) resolve
+     * with `undefined`. There's no invocation for them to await. This is why the returned function
+     * can resolve with `undefined` even though the original function's return type doesn't express that.
+     *
      * @default true
      */
     trailing?: boolean;
+}
+export interface AsyncDebounceOptions extends AsyncThrottleOptions {
     /**
+     * Invoke on the leading edge of the window (immediately, on the first call).
      *
+     * @default false
+     */
+    leading?: boolean;
+    /**
+     * Maximum time `func` is allowed to be delayed before it's forcibly invoked.
      */
     maxWait?: number;
 }
-export declare function _debounce<T extends AnyFunction>(func: T, wait: number, opt?: DebounceOptions): T & Cancelable;
-export declare function _throttle<T extends AnyFunction>(func: T, wait: number, opt?: ThrottleOptions): T & Cancelable;
+/**
+ * The function returned by `_asyncDebounce`/`_asyncThrottle`. Same signature as `T`, but resolves
+ * `Awaited<ReturnType<T>> | undefined`
+ *
+ * This is because some configurations (e.g. `trailing: false`) may drop calls without invoking
+ * the original function, so there's no result to await.
+ */
+export type AsyncDebounced<T extends AnyAsyncFunction> = ((this: ThisParameterType<T>, ...args: Parameters<T>) => Promise<Awaited<ReturnType<T>> | undefined>) & AsyncCancelable<Awaited<ReturnType<T>>>;

package/dist/decorators/debounce.decorator.d.ts

@@ -1,3 +1,23 @@
-import type { DebounceOptions, ThrottleOptions } from './debounce.js';
-export declare function _Debounce(wait: number, opt?: DebounceOptions): MethodDecorator;
-export declare function _Throttle(wait: number, opt?: ThrottleOptions): MethodDecorator;
+import type { AnyAsyncFunction, AnyFunction } from '../types.js';
+import type { AsyncDebounceOptions, AsyncThrottleOptions, DebounceOptions, ThrottleOptions } from './debounce.js';
+import type { MethodDecorator } from './decorator.util.js';
+export declare function _Debounce<T extends AnyFunction>(wait: number, opt?: DebounceOptions): MethodDecorator<T>;
+export declare function _Throttle<T extends AnyFunction>(wait: number, opt?: ThrottleOptions): MethodDecorator<T>;
+/**
+ * Like `@_Debounce`, but for async methods: every call returns a real Promise resolving with the
+ * coalesced invocation's result, so `await`-ing never yields a stale value or a non-promise
+ *
+ * Be aware that the decorated method may resolve `undefined` if the config yields no invocation,
+ * which the method's `T` type can't express.
+ *
+ * @experimental
+ */
+export declare function _AsyncDebounce<T extends AnyAsyncFunction>(wait: number, opt?: AsyncDebounceOptions): MethodDecorator<T>;
+/**
+ * Like `@_Throttle`, but for async methods.
+ *
+ * @see {@link _AsyncDebounce}
+ *
+ * @experimental
+ */
+export declare function _AsyncThrottle<T extends AnyAsyncFunction>(wait: number, opt?: AsyncThrottleOptions): MethodDecorator<T>;

package/dist/decorators/debounce.decorator.js

@@ -1,4 +1,4 @@
-import { _debounce, _throttle } from './debounce.js';
+import { _asyncDebounce, _asyncThrottle, _debounce, _throttle } from './debounce.js';
 export function _Debounce(wait, opt = {}) {
     return (_target, _key, descriptor) => {
         const originalFn = descriptor.value;
@@ -13,3 +13,33 @@ export function _Throttle(wait, opt = {}) {
         return descriptor;
     };
 }
+/**
+ * Like `@_Debounce`, but for async methods: every call returns a real Promise resolving with the
+ * coalesced invocation's result, so `await`-ing never yields a stale value or a non-promise
+ *
+ * Be aware that the decorated method may resolve `undefined` if the config yields no invocation,
+ * which the method's `T` type can't express.
+ *
+ * @experimental
+ */
+export function _AsyncDebounce(wait, opt = {}) {
+    return (_target, _key, descriptor) => {
+        const originalFn = descriptor.value;
+        descriptor.value = _asyncDebounce(originalFn, wait, opt);
+        return descriptor;
+    };
+}
+/**
+ * Like `@_Throttle`, but for async methods.
+ *
+ * @see {@link _AsyncDebounce}
+ *
+ * @experimental
+ */
+export function _AsyncThrottle(wait, opt = {}) {
+    return (_target, _key, descriptor) => {
+        const originalFn = descriptor.value;
+        descriptor.value = _asyncThrottle(originalFn, wait, opt);
+        return descriptor;
+    };
+}

package/dist/decorators/debounce.js

@@ -1,59 +1,43 @@
+import { _anyToError } from '../error/error.util.js';
+import { pDefer } from '../promise/pDefer.js';
 export function _debounce(func, wait, opt = {}) {
     let lastArgs;
     let lastThis;
     let result;
     let timerId;
-    let lastCallTime;
-    let lastInvokeTime = 0;
     const maxing = 'maxWait' in opt;
     const { leading = false, trailing = true } = opt;
-    const maxWait = maxing ? Math.max(Number(opt.maxWait) || 0, wait) : opt.maxWait;
+    const state = {
+        lastCallTime: undefined,
+        lastInvokeTime: 0,
+        wait,
+        maxing,
+        maxWait: maxing ? Math.max(Number(opt.maxWait) || 0, wait) : opt.maxWait,
+    };
     function invokeFunc(time) {
         const args = lastArgs;
         const thisArg = lastThis;
         lastArgs = lastThis = undefined;
-        lastInvokeTime = time;
+        state.lastInvokeTime = time;
         result = func.apply(thisArg, args);
         return result;
     }
-    function startTimer(pendingFunc, wait) {
-        return setTimeout(pendingFunc, wait);
-    }
-    function cancelTimer(id) {
-        clearTimeout(id);
-    }
     function leadingEdge(time) {
         // Reset any `maxWait` timer.
-        lastInvokeTime = time;
+        state.lastInvokeTime = time;
         // Start the timer for the trailing edge.
-        timerId = startTimer(timerExpired, wait);
+        timerId = startTimer(timerExpired, state.wait);
         // Invoke the leading edge.
         return leading ? invokeFunc(time) : result;
     }
-    function remainingWait(time) {
-        const timeSinceLastCall = time - lastCallTime;
-        const timeSinceLastInvoke = time - lastInvokeTime;
-        const timeWaiting = wait - timeSinceLastCall;
-        return maxing ? Math.min(timeWaiting, maxWait - timeSinceLastInvoke) : timeWaiting;
-    }
-    function shouldInvoke(time) {
-        const timeSinceLastCall = time - lastCallTime;
-        const timeSinceLastInvoke = time - lastInvokeTime;
-        // Either this is the first call, activity has stopped and we're at the
-        // trailing edge, the system time has gone backwards and we're treating
-        // it as the trailing edge, or we've hit the `maxWait` limit.
-        return (lastCallTime === undefined ||
-            timeSinceLastCall >= wait ||
-            timeSinceLastCall < 0 ||
-            (maxing && timeSinceLastInvoke >= maxWait));
-    }
     function timerExpired() {
         const time = Date.now();
-        if (shouldInvoke(time)) {
-            return trailingEdge(time);
+        if (shouldInvoke(time, state)) {
+            trailingEdge(time);
+            return;
         }
         // Restart the timer.
-        timerId = startTimer(timerExpired, remainingWait(time));
+        timerId = startTimer(timerExpired, remainingWait(time, state));
     }
     function trailingEdge(time) {
         timerId = undefined;
@@ -69,8 +53,9 @@ export function _debounce(func, wait, opt = {}) {
         if (timerId !== undefined) {
             cancelTimer(timerId);
         }
-        lastInvokeTime = 0;
-        lastArgs = lastCallTime = lastThis = timerId = undefined;
+        state.lastInvokeTime = 0;
+        state.lastCallTime = undefined;
+        lastArgs = lastThis = timerId = undefined;
     }
     function flush() {
         return timerId === undefined ? result : trailingEdge(Date.now());
@@ -80,22 +65,22 @@ export function _debounce(func, wait, opt = {}) {
     }
     function debounced(...args) {
         const time = Date.now();
-        const isInvoking = shouldInvoke(time);
+        const isInvoking = shouldInvoke(time, state);
         lastArgs = args;
         lastThis = this;
-        lastCallTime = time;
+        state.lastCallTime = time;
         if (isInvoking) {
             if (timerId === undefined) {
-                return leadingEdge(lastCallTime);
+                return leadingEdge(state.lastCallTime);
             }
-            if (maxing) {
+            if (state.maxing) {
                 // Handle invocations in a tight loop.
-                timerId = startTimer(timerExpired, wait);
-                return invokeFunc(lastCallTime);
+                timerId = startTimer(timerExpired, state.wait);
+                return invokeFunc(state.lastCallTime);
             }
         }
         if (timerId === undefined) {
-            timerId = startTimer(timerExpired, wait);
+            timerId = startTimer(timerExpired, state.wait);
         }
         return result;
     }
@@ -112,3 +97,174 @@ export function _throttle(func, wait, opt = {}) {
         maxWait: wait,
     });
 }
+/**
+ * Like `_debounce`, but for async functions.
+ *
+ * Unlike `_debounce` (which returns a stale `result`/`undefined` for suppressed calls),
+ * `_asyncDebounce` always returns a real Promise, resolving with the coalesced invocation's result.
+ *
+ * @experimental
+ */
+export function _asyncDebounce(func, wait, opt = {}) {
+    let lastArgs;
+    let lastThis;
+    let timerId;
+    // Promise shared by all calls coalesced into the next invocation (undefined when none pending).
+    let deferred;
+    const { leading = false, trailing = true } = opt;
+    const maxing = 'maxWait' in opt;
+    const maxWait = maxing ? Math.max(Number(opt.maxWait) || 0, wait) : opt.maxWait;
+    const state = {
+        lastCallTime: undefined,
+        lastInvokeTime: 0,
+        wait,
+        maxing,
+        maxWait,
+    };
+    async function invokeFunc(time) {
+        const args = lastArgs;
+        const thisArg = lastThis;
+        lastArgs = lastThis = undefined;
+        state.lastInvokeTime = time;
+        // Detach and settle the current batch.
+        const d = deferred;
+        deferred = undefined;
+        try {
+            const result = await func.apply(thisArg, args);
+            d.resolve(result);
+        }
+        catch (err) {
+            d.reject(_anyToError(err));
+        }
+    }
+    async function leadingEdge(time) {
+        // Reset any `maxWait` timer.
+        state.lastInvokeTime = time;
+        // Start the timer for the trailing edge.
+        timerId = startTimer(timerExpired, state.wait);
+        // Capture the batch before `invokeFunc` detaches it.
+        const d = deferred;
+        // Invoke the leading edge.
+        if (leading) {
+            await invokeFunc(time);
+        }
+        return d;
+    }
+    function timerExpired() {
+        const time = Date.now();
+        if (shouldInvoke(time, state)) {
+            void trailingEdge(time);
+            return;
+        }
+        // Restart the timer.
+        timerId = startTimer(timerExpired, remainingWait(time, state));
+    }
+    async function trailingEdge(time) {
+        timerId = undefined;
+        // Only invoke if we have `lastArgs` which means `func` has been
+        // debounced at least once.
+        if (trailing && lastArgs && deferred) {
+            await invokeFunc(time);
+            return;
+        }
+        lastArgs = lastThis = undefined;
+        // Dropped batch (only reachable with `trailing: false`): no invocation, so resolve `undefined`.
+        if (deferred) {
+            const d = deferred;
+            deferred = undefined;
+            d.resolve(undefined);
+        }
+    }
+    function cancel() {
+        if (timerId !== undefined) {
+            cancelTimer(timerId);
+        }
+        state.lastInvokeTime = 0;
+        state.lastCallTime = undefined;
+        lastArgs = lastThis = timerId = undefined;
+        // Reject pending awaiters.
+        if (deferred) {
+            const d = deferred;
+            deferred = undefined;
+            d.reject(new Error('asyncDebounce cancelled'));
+        }
+    }
+    async function flush() {
+        if (timerId === undefined || !deferred) {
+            return undefined;
+        }
+        const d = deferred;
+        cancelTimer(timerId);
+        await trailingEdge(Date.now());
+        return d;
+    }
+    function pending() {
+        return timerId !== undefined;
+    }
+    async function debounced(...args) {
+        const time = Date.now();
+        const isInvoking = shouldInvoke(time, state);
+        lastArgs = args;
+        lastThis = this;
+        state.lastCallTime = time;
+        deferred ||= pDefer();
+        const currentDeferred = deferred;
+        if (isInvoking) {
+            if (timerId === undefined) {
+                return leadingEdge(state.lastCallTime);
+            }
+            if (state.maxing) {
+                // Handle invocations in a tight loop.
+                timerId = startTimer(timerExpired, state.wait);
+                await invokeFunc(state.lastCallTime);
+                return currentDeferred;
+            }
+        }
+        if (timerId === undefined) {
+            timerId = startTimer(timerExpired, state.wait);
+        }
+        return currentDeferred;
+    }
+    debounced.cancel = cancel;
+    debounced.flush = flush;
+    debounced.pending = pending;
+    return debounced;
+}
+/**
+ * Like `_throttle`, but for async functions. See `_asyncDebounce` for the Promise semantics.
+ *
+ * @experimental
+ */
+export function _asyncThrottle(func, wait, opt = {}) {
+    return _asyncDebounce(func, wait, {
+        leading: true,
+        trailing: true,
+        ...opt,
+        maxWait: wait,
+    });
+}
+function remainingWait(time, state) {
+    const { lastCallTime, lastInvokeTime, wait, maxing, maxWait } = state;
+    const timeSinceLastCall = time - lastCallTime;
+    const timeSinceLastInvoke = time - lastInvokeTime;
+    const timeWaiting = wait - timeSinceLastCall;
+    return maxing ? Math.min(timeWaiting, maxWait - timeSinceLastInvoke) : timeWaiting;
+}
+function shouldInvoke(time, state) {
+    const { lastCallTime, lastInvokeTime, wait, maxing, maxWait } = state;
+    const timeSinceLastCall = time - lastCallTime;
+    const timeSinceLastInvoke = time - lastInvokeTime;
+    // Either this is the first call, activity has stopped and we're at the
+    // trailing edge, the system time has gone backwards and we're treating
+    // it as the trailing edge, or we've hit the `maxWait` limit.
+    return (lastCallTime === undefined ||
+        timeSinceLastCall >= wait ||
+        timeSinceLastCall < 0 ||
+        (maxing && timeSinceLastInvoke >= maxWait));
+}
+function startTimer(pendingFunc, wait) {
+    return setTimeout(pendingFunc, wait);
+}
+function cancelTimer(id) {
+    clearTimeout(id);
+}

package/dist/decorators/decorator.util.d.ts

@@ -1,4 +1,10 @@
 import type { AnyObject } from '../types.js';
+/**
+ * Generic override of TypeScript's built-in legacy MethodDecorator, that
+ * allows us to infer the parameters of the decorated method from the parameters
+ * of a decorator.
+ */
+export type MethodDecorator<T> = (target: AnyObject, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T> | undefined;
 /**
  * @returns
  * e.g `NameOfYourClass.methodName`

package/dist/decorators/memo.decorator.d.ts

@@ -1,6 +1,7 @@
 import type { CommonLogger } from '../log/commonLogger.js';
 import type { AnyFunction, AnyObject, MaybeParameters } from '../types.js';
-import type { MemoCache, MethodDecorator } from './memo.util.js';
+import type { MethodDecorator } from './decorator.util.js';
+import type { MemoCache } from './memo.util.js';
 export interface MemoOptions<FN> {
     /**
      * Provide a custom implementation of MemoCache.

package/dist/decorators/memo.util.d.ts

@@ -1,4 +1,4 @@
-import type { AnyObject, UnixTimestamp } from '../types.js';
+import type { UnixTimestamp } from '../types.js';
 import { MISS } from '../types.js';
 export type MemoSerializer = (args: any[]) => any;
 export declare const jsonMemoSerializer: MemoSerializer;
@@ -59,9 +59,3 @@ export declare class MapAsyncMemoCache<KEY = any, VALUE = any> implements AsyncM
     set(k: KEY, v: VALUE): Promise<void>;
     clear(): Promise<void>;
 }
-/**
- * Generic override of Typescript's built in legacy MethodDecorator, that
- * allows us to infer the parameters of the decorated method from the parameters
- * of a decorator.
- */
-export type MethodDecorator<T> = (target: AnyObject, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T> | undefined;

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.84.0",
   "dependencies": {
     "tslib": "^2"
   },

package/src/decorators/asyncMemo.decorator.ts

@@ -2,8 +2,9 @@ import { _assert, _assertTypeOf } from '../error/assert.js'
 import type { CommonLogger } from '../log/commonLogger.js'
 import type { AnyAsyncFunction, AnyFunction, AnyObject, MaybeParameters } from '../types.js'
 import { _objectAssign, MISS } from '../types.js'
+import type { MethodDecorator } from './decorator.util.js'
 import { _getTargetMethodSignature } from './decorator.util.js'
-import type { AsyncMemoCache, MethodDecorator } from './memo.util.js'
+import type { AsyncMemoCache } from './memo.util.js'
 import { jsonMemoSerializer } from './memo.util.js'
 
 export interface AsyncMemoOptions<FN> {