@venizia/ignis-helpers 0.2.0-2 → 0.2.0-21

package/dist/esm/modules/retry/common/constants.js

@@ -0,0 +1,29 @@
+export class RetryBackoffStrategies {
+    static { this.FIXED = 'fixed'; }
+    static { this.LINEAR = 'linear'; }
+    static { this.EXPONENTIAL = 'exponential'; }
+    /** An explicit per-attempt cap schedule, e.g. [250, 1000, 4000]; the last entry repeats. */
+    static { this.SCHEDULE = 'schedule'; }
+    static { this.SCHEME_SET = new Set([
+        this.FIXED,
+        this.LINEAR,
+        this.EXPONENTIAL,
+        this.SCHEDULE,
+    ]); }
+    static isValid(value) {
+        return this.SCHEME_SET.has(value);
+    }
+}
+export class RetryJitterModes {
+    /** The computed delay is used as-is. */
+    static { this.NONE = 'none'; }
+    /** Uniform random in [0, delay) - decorrelates a thundering herd hardest. */
+    static { this.FULL = 'full'; }
+    /** delay/2 + uniform random in [0, delay/2) - jittered but never less than half the delay. */
+    static { this.EQUAL = 'equal'; }
+    static { this.SCHEME_SET = new Set([this.NONE, this.FULL, this.EQUAL]); }
+    static isValid(value) {
+        return this.SCHEME_SET.has(value);
+    }
+}
+//# sourceMappingURL=constants.js.map

package/dist/esm/modules/retry/common/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../../src/modules/retry/common/constants.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,sBAAsB;aACjB,UAAK,GAAG,OAAO,CAAC;aAChB,WAAM,GAAG,QAAQ,CAAC;aAClB,gBAAW,GAAG,aAAa,CAAC;IAE5C,4FAA4F;aAC5E,aAAQ,GAAG,UAAU,CAAC;aAEtB,eAAU,GAAG,IAAI,GAAG,CAAS;QAC3C,IAAI,CAAC,KAAK;QACV,IAAI,CAAC,MAAM;QACX,IAAI,CAAC,WAAW;QAChB,IAAI,CAAC,QAAQ;KACd,CAAC,CAAC;IAEH,MAAM,CAAC,OAAO,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;;AAKH,MAAM,OAAO,gBAAgB;IAC3B,wCAAwC;aACxB,SAAI,GAAG,MAAM,CAAC;IAE9B,6EAA6E;aAC7D,SAAI,GAAG,MAAM,CAAC;IAE9B,8FAA8F;aAC9E,UAAK,GAAG,OAAO,CAAC;aAEhB,eAAU,GAAG,IAAI,GAAG,CAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAEjF,MAAM,CAAC,OAAO,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC"}

package/dist/esm/modules/retry/common/index.d.ts

@@ -0,0 +1,3 @@
+export * from './constants.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/modules/retry/common/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/modules/retry/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC"}

package/dist/esm/modules/retry/common/index.js

@@ -0,0 +1,3 @@
+export * from './constants.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/modules/retry/common/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/modules/retry/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC"}

package/dist/esm/modules/retry/common/types.d.ts

@@ -0,0 +1,21 @@
+import type { TRetryBackoffStrategy, TRetryJitterMode } from './constants.js';
+export interface IRetryBackoffOptions {
+    /** Default EXPONENTIAL. */
+    strategy?: TRetryBackoffStrategy;
+    /** First delay, default 250ms. LINEAR adds it per attempt; EXPONENTIAL multiplies from it. */
+    initialDelayMs?: number;
+    /** EXPONENTIAL growth factor, default 2. Ignored by other strategies. */
+    multiplier?: number;
+    /** Upper cap applied BEFORE jitter, default 30000ms. */
+    maxDelayMs?: number;
+    /** Required when strategy is SCHEDULE; the last entry repeats for later attempts. */
+    scheduleMs?: readonly number[];
+    /** Default FULL. */
+    jitter?: TRetryJitterMode;
+}
+export interface IRetryContext {
+    attempt: number;
+    error: unknown;
+    elapsedMs: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/modules/retry/common/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/modules/retry/common/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE3E,MAAM,WAAW,oBAAoB;IACnC,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IAEjC,8FAA8F;IAC9F,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,qFAAqF;IACrF,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE/B,oBAAoB;IACpB,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/esm/modules/retry/common/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../src/modules/retry/common/types.ts"],"names":[],"mappings":""}

package/dist/esm/modules/retry/helper.d.ts

@@ -0,0 +1,71 @@
+import type { ValueOrPromise } from '../../common/index.js';
+import type { ILogger } from '../logger/index.js';
+import type { IRetryBackoffOptions, IRetryContext } from './common/types.js';
+import { BaseHelper } from '../base.js';
+/**
+ * Static members call each other through the class name (`RetryHelper.xxx`), never `this` - a
+ * detached static method loses its `this` binding.
+ */
+export declare class RetryHelper extends BaseHelper {
+    private static readonly RETRY_TIMEOUT_MARKER;
+    /** True when `error` is a per-attempt timeout raised by `runWithTimeout`/`executeWithRetry`. */
+    static isRetryTimeoutError(error: unknown): boolean;
+    private static buildTimeoutError;
+    private static throwIfAborted;
+    /** `sleep` that wakes up early (and rejects) when `signal` aborts mid-wait. */
+    private static sleepWithSignal;
+    /** Races `execution` against `timeoutMs` (`<= 0`/omitted = no timeout). The losing execution keeps running - JS promises cannot be cancelled - so pass `signal` through for cooperative cancellation. */
+    static runWithTimeout<T>(opts: {
+        operation: string;
+        timeoutMs?: number;
+        execution: () => ValueOrPromise<T>;
+    }): Promise<T>;
+    /** The pre-jitter delay for `attempt` (1-based, i.e. the delay AFTER attempt N failed). */
+    static computeBackoffDelayMs(opts: {
+        attempt: number;
+        backoff?: IRetryBackoffOptions;
+    }): number;
+    /** One `executeWithRetry` attempt and everything that follows a failure: `shouldRetry` refusing rethrows, otherwise the bounds are checked and - when another attempt is allowed - the retry is logged, `onRetry` awaited and the backoff slept, all before returning. */
+    private static runRetryAttempt;
+    /** Retries `execution` with backoff, bounded by `maxAttempts`/`maxTotalMs`. JS cannot cancel a running promise - `signal` only stops between attempts/sleeps, so a timed-out execution keeps running unless it honors the signal itself. */
+    static executeWithRetry<T>(opts: {
+        signal?: AbortSignal;
+        logger?: ILogger;
+        operation: string;
+        /** Default 3. */
+        maxAttempts?: number;
+        /** Total budget across attempts AND sleeps. Default: unlimited. */
+        maxTotalMs?: number;
+        /** Per-attempt race. Default: no per-attempt timeout. */
+        perAttemptTimeoutMs?: number;
+        backoff?: IRetryBackoffOptions;
+        execution: (context: {
+            attempt: number;
+            signal?: AbortSignal;
+        }) => ValueOrPromise<T>;
+        /** Return `false` to stop retrying and rethrow `context.error` immediately. */
+        shouldRetry?: (context: IRetryContext) => boolean;
+        /** Observability hook, awaited before the backoff sleep. */
+        onRetry?: (context: IRetryContext & {
+            nextDelayMs: number;
+        }) => ValueOrPromise<void>;
+    }): Promise<T>;
+    /** Retries `execution` while `until(result)` returns false - for read-after-write staleness behind a replicated pool. Never worse than a single un-retried call: on exhaustion the LAST result is returned rather than an error, and a thrown error propagates immediately instead of being retried. Only wrap idempotent operations. */
+    static executeWithRetryUntil<T>(opts: {
+        signal?: AbortSignal;
+        logger?: ILogger;
+        operation: string;
+        /** Default 3. */
+        maxAttempts?: number;
+        /** Bounds when a NEW attempt may start; it never interrupts an attempt already in flight, so the first execution always runs to completion - a budget of 0 just means "no retries". */
+        maxTotalMs?: number;
+        backoff?: IRetryBackoffOptions;
+        execution: (context: {
+            attempt: number;
+            signal?: AbortSignal;
+        }) => ValueOrPromise<T>;
+        /** Retry while this returns false. */
+        until: (result: T) => boolean;
+    }): Promise<T>;
+}
+//# sourceMappingURL=helper.d.ts.map

package/dist/esm/modules/retry/helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../../../../src/modules/retry/helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAGhD,OAAO,KAAK,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAK5C;;;GAGG;AACH,qBAAa,WAAY,SAAQ,UAAU;IACzC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAsD;IAElG,gGAAgG;IAChG,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAInD,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAQhC,OAAO,CAAC,MAAM,CAAC,cAAc;IAQ7B,+EAA+E;mBAC1D,eAAe;IAsCpC,yMAAyM;WAC5L,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE;QACnC,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,cAAc,CAAC,CAAC,CAAC,CAAC;KACpC,GAAG,OAAO,CAAC,CAAC,CAAC;IAqBd,2FAA2F;IAC3F,MAAM,CAAC,qBAAqB,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,oBAAoB,CAAA;KAAE,GAAG,MAAM;IAmE/F,0QAA0Q;mBACrP,eAAe;IAyEpC,4OAA4O;WAC/N,gBAAgB,CAAC,CAAC,EAAE,IAAI,EAAE;QACrC,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAElB,iBAAiB;QACjB,WAAW,CAAC,EAAE,MAAM,CAAC;QAErB,mEAAmE;QACnE,UAAU,CAAC,EAAE,MAAM,CAAC;QAEpB,yDAAyD;QACzD,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAE7B,OAAO,CAAC,EAAE,oBAAoB,CAAC;QAE/B,SAAS,EAAE,CAAC,OAAO,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,WAAW,CAAA;SAAE,KAAK,cAAc,CAAC,CAAC,CAAC,CAAC;QAErF,+EAA+E;QAC/E,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC;QAElD,4DAA4D;QAC5D,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,GAAG;YAAE,WAAW,EAAE,MAAM,CAAA;SAAE,KAAK,cAAc,CAAC,IAAI,CAAC,CAAC;KACtF,GAAG,OAAO,CAAC,CAAC,CAAC;IA+Ed,yUAAyU;WAC5T,qBAAqB,CAAC,CAAC,EAAE,IAAI,EAAE;QAC1C,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAElB,iBAAiB;QACjB,WAAW,CAAC,EAAE,MAAM,CAAC;QAErB,uLAAuL;QACvL,UAAU,CAAC,EAAE,MAAM,CAAC;QAEpB,OAAO,CAAC,EAAE,oBAAoB,CAAC;QAE/B,SAAS,EAAE,CAAC,OAAO,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,WAAW,CAAA;SAAE,KAAK,cAAc,CAAC,CAAC,CAAC,CAAC;QAErF,sCAAsC;QACtC,KAAK,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC;KAC/B,GAAG,OAAO,CAAC,CAAC,CAAC;CAoDf"}

package/dist/esm/modules/retry/helper.js

@@ -0,0 +1,255 @@
+import { getError } from '../error/index.js';
+import { sleep } from '../../utilities/sleep.utility.js';
+import { RetryBackoffStrategies, RetryJitterModes } from './common/constants.js';
+import { BaseHelper } from '../base.js';
+/**
+ * Static members call each other through the class name (`RetryHelper.xxx`), never `this` - a
+ * detached static method loses its `this` binding.
+ */
+export class RetryHelper extends BaseHelper {
+    static { this.RETRY_TIMEOUT_MARKER = Symbol.for('@venizia/ignis-helpers:retry-timeout'); }
+    /** True when `error` is a per-attempt timeout raised by `runWithTimeout`/`executeWithRetry`. */
+    static isRetryTimeoutError(error) {
+        return typeof error === 'object' && error !== null && RetryHelper.RETRY_TIMEOUT_MARKER in error;
+    }
+    static buildTimeoutError(opts) {
+        const error = getError({
+            message: `[runWithTimeout][${opts.operation}] Timed out after ${opts.timeoutMs}ms`,
+        });
+        Object.defineProperty(error, RetryHelper.RETRY_TIMEOUT_MARKER, { value: true });
+        return error;
+    }
+    static throwIfAborted(opts) {
+        if (opts.signal?.aborted) {
+            throw getError({
+                message: `[executeWithRetry][${opts.operation}] Aborted | Reason: ${String(opts.signal.reason ?? 'unknown')}`,
+            });
+        }
+    }
+    /** `sleep` that wakes up early (and rejects) when `signal` aborts mid-wait. */
+    static async sleepWithSignal(opts) {
+        const { ms, operation, signal } = opts;
+        if (!signal) {
+            await sleep(ms);
+            return;
+        }
+        RetryHelper.throwIfAborted({ operation, signal });
+        // The listener is removed in `finally` rather than by the timer callback - the two would otherwise have to reference each other, and a leaked listener on a long-lived signal accumulates across retries.
+        let removeAbortListener = () => { };
+        try {
+            await new Promise((resolve, reject) => {
+                const timer = setTimeout(resolve, ms);
+                const onAbort = () => {
+                    clearTimeout(timer);
+                    reject(getError({
+                        message: `[executeWithRetry][${operation}] Aborted during backoff | Reason: ${String(signal.reason ?? 'unknown')}`,
+                    }));
+                };
+                removeAbortListener = () => signal.removeEventListener('abort', onAbort);
+                signal.addEventListener('abort', onAbort, { once: true });
+            });
+        }
+        finally {
+            removeAbortListener();
+        }
+    }
+    /** Races `execution` against `timeoutMs` (`<= 0`/omitted = no timeout). The losing execution keeps running - JS promises cannot be cancelled - so pass `signal` through for cooperative cancellation. */
+    static async runWithTimeout(opts) {
+        const { operation, timeoutMs, execution } = opts;
+        if (!timeoutMs || timeoutMs <= 0) {
+            return execution();
+        }
+        let timer;
+        const timeoutPromise = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+                reject(RetryHelper.buildTimeoutError({ operation, timeoutMs }));
+            }, timeoutMs);
+        });
+        try {
+            return await Promise.race([Promise.resolve().then(execution), timeoutPromise]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** The pre-jitter delay for `attempt` (1-based, i.e. the delay AFTER attempt N failed). */
+    static computeBackoffDelayMs(opts) {
+        const { attempt } = opts;
+        const { strategy = RetryBackoffStrategies.EXPONENTIAL, initialDelayMs = 250, multiplier = 2, maxDelayMs = 30_000, scheduleMs, jitter = RetryJitterModes.FULL, } = opts.backoff ?? {};
+        let delayMs;
+        switch (strategy) {
+            case RetryBackoffStrategies.FIXED: {
+                delayMs = initialDelayMs;
+                break;
+            }
+            case RetryBackoffStrategies.LINEAR: {
+                delayMs = initialDelayMs * attempt;
+                break;
+            }
+            case RetryBackoffStrategies.EXPONENTIAL: {
+                delayMs = initialDelayMs * Math.pow(multiplier, attempt - 1);
+                break;
+            }
+            case RetryBackoffStrategies.SCHEDULE: {
+                if (!scheduleMs?.length) {
+                    throw getError({
+                        message: '[computeBackoffDelayMs] strategy SCHEDULE requires a non-empty backoff.scheduleMs',
+                    });
+                }
+                delayMs = scheduleMs[Math.min(attempt - 1, scheduleMs.length - 1)];
+                break;
+            }
+            default: {
+                throw getError({
+                    message: `[computeBackoffDelayMs] Unknown backoff strategy '${strategy}' | Expected one of: ${[...RetryBackoffStrategies.SCHEME_SET].join(', ')}`,
+                });
+            }
+        }
+        delayMs = Math.min(delayMs, maxDelayMs);
+        if (delayMs <= 0) {
+            return 0;
+        }
+        switch (jitter) {
+            case RetryJitterModes.NONE: {
+                return delayMs;
+            }
+            case RetryJitterModes.FULL: {
+                return Math.floor(Math.random() * delayMs);
+            }
+            case RetryJitterModes.EQUAL: {
+                const half = delayMs / 2;
+                return Math.floor(half + Math.random() * half);
+            }
+            default: {
+                throw getError({
+                    message: `[computeBackoffDelayMs] Unknown jitter mode '${jitter}' | Expected one of: ${[...RetryJitterModes.SCHEME_SET].join(', ')}`,
+                });
+            }
+        }
+    }
+    /** One `executeWithRetry` attempt and everything that follows a failure: `shouldRetry` refusing rethrows, otherwise the bounds are checked and - when another attempt is allowed - the retry is logged, `onRetry` awaited and the backoff slept, all before returning. */
+    static async runRetryAttempt(opts) {
+        const { attempt, attemptTimeoutMs, startedAt, deadline, maxAttempts, operation, signal, logger, backoff, execution, shouldRetry, onRetry, } = opts;
+        try {
+            const value = await RetryHelper.runWithTimeout({
+                operation,
+                timeoutMs: attemptTimeoutMs,
+                execution: () => execution({ attempt, signal }),
+            });
+            return { isResolved: true, value };
+        }
+        catch (error) {
+            const elapsedMs = Date.now() - startedAt;
+            if (shouldRetry && !shouldRetry({ attempt, error, elapsedMs })) {
+                throw error;
+            }
+            if (attempt >= maxAttempts) {
+                return { isResolved: false, error, isRetryAllowed: false };
+            }
+            const nextDelayMs = RetryHelper.computeBackoffDelayMs({ attempt, backoff });
+            if (deadline && Date.now() + nextDelayMs >= deadline) {
+                return { isResolved: false, error, isRetryAllowed: false };
+            }
+            logger
+                ?.for('executeWithRetry')
+                .debug('[%s] Attempt %d/%d failed - retrying in %dms | Error: %s', operation, attempt, maxAttempts, nextDelayMs, error);
+            await onRetry?.({ attempt, error, elapsedMs, nextDelayMs });
+            if (nextDelayMs > 0) {
+                await RetryHelper.sleepWithSignal({ ms: nextDelayMs, operation, signal });
+            }
+            return { isResolved: false, error, isRetryAllowed: true };
+        }
+    }
+    /** Retries `execution` with backoff, bounded by `maxAttempts`/`maxTotalMs`. JS cannot cancel a running promise - `signal` only stops between attempts/sleeps, so a timed-out execution keeps running unless it honors the signal itself. */
+    static async executeWithRetry(opts) {
+        const { operation, execution, maxAttempts = 3, maxTotalMs, perAttemptTimeoutMs, backoff, shouldRetry, onRetry, signal, logger, } = opts;
+        if (maxAttempts < 1) {
+            throw getError({
+                message: `[executeWithRetry][${operation}] maxAttempts must be >= 1 | Got: ${maxAttempts}`,
+            });
+        }
+        const startedAt = Date.now();
+        // `!== undefined`, never truthiness: a budget of 0 - or a negative one, which is what `deadline - Date.now()` yields under load - means NO time left, not unlimited time.
+        const deadline = maxTotalMs !== undefined ? startedAt + maxTotalMs : undefined;
+        let lastError;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            RetryHelper.throwIfAborted({ operation, signal });
+            const remainingMs = deadline ? deadline - Date.now() : undefined;
+            if (remainingMs !== undefined && remainingMs <= 0) {
+                break;
+            }
+            let attemptTimeoutMs = perAttemptTimeoutMs;
+            if (remainingMs !== undefined) {
+                attemptTimeoutMs = attemptTimeoutMs ? Math.min(attemptTimeoutMs, remainingMs) : remainingMs;
+            }
+            const outcome = await RetryHelper.runRetryAttempt({
+                attempt,
+                attemptTimeoutMs,
+                startedAt,
+                deadline,
+                maxAttempts,
+                operation,
+                signal,
+                logger,
+                backoff,
+                execution,
+                shouldRetry,
+                onRetry,
+            });
+            if (outcome.isResolved) {
+                return outcome.value;
+            }
+            lastError = outcome.error;
+            if (!outcome.isRetryAllowed) {
+                break;
+            }
+        }
+        const elapsedMs = Date.now() - startedAt;
+        // The budget can run out BEFORE the first attempt (an expired `maxTotalMs`), leaving no error to rethrow; `throw undefined` would detonate inside the caller's own handler on `error.message`.
+        if (lastError === undefined) {
+            throw getError({
+                message: `[executeWithRetry][${operation}] Time budget exhausted before any attempt ran | maxTotalMs: ${maxTotalMs}`,
+            });
+        }
+        logger
+            ?.for('executeWithRetry')
+            .warn('[%s] Exhausted retries | Elapsed: %dms | Error: %s', operation, elapsedMs, lastError);
+        throw lastError;
+    }
+    /** Retries `execution` while `until(result)` returns false - for read-after-write staleness behind a replicated pool. Never worse than a single un-retried call: on exhaustion the LAST result is returned rather than an error, and a thrown error propagates immediately instead of being retried. Only wrap idempotent operations. */
+    static async executeWithRetryUntil(opts) {
+        const { signal, logger, operation, maxAttempts = 3, maxTotalMs, backoff, execution, until, } = opts;
+        if (maxAttempts < 1) {
+            throw getError({
+                message: `[executeWithRetryUntil][${operation}] maxAttempts must be >= 1 | Got: ${maxAttempts}`,
+            });
+        }
+        // Surfaced before the first execution - a misconfigured backoff discovered mid-loop would discard an already-fetched result.
+        RetryHelper.computeBackoffDelayMs({ attempt: 1, backoff });
+        const startedAt = Date.now();
+        let lastResult;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            RetryHelper.throwIfAborted({ operation, signal });
+            lastResult = await execution({ attempt, signal });
+            if (until(lastResult)) {
+                return lastResult;
+            }
+            const elapsedMs = Date.now() - startedAt;
+            if (attempt >= maxAttempts || (maxTotalMs !== undefined && elapsedMs >= maxTotalMs)) {
+                break;
+            }
+            logger
+                ?.for('executeWithRetryUntil')
+                .debug('[%s] until condition not met | Attempt: %d', operation, attempt);
+            const nextDelayMs = RetryHelper.computeBackoffDelayMs({ attempt, backoff });
+            if (nextDelayMs > 0) {
+                await RetryHelper.sleepWithSignal({ ms: nextDelayMs, operation, signal });
+            }
+        }
+        logger
+            ?.for('executeWithRetryUntil')
+            .warn('[%s] Exhausted retries - returning last (stale) result', operation);
+        return lastResult;
+    }
+}
+//# sourceMappingURL=helper.js.map

package/dist/esm/modules/retry/helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.js","sourceRoot":"","sources":["../../../../src/modules/retry/helper.ts"],"names":[],"mappings":"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"}

package/dist/esm/modules/retry/index.d.ts

@@ -0,0 +1,3 @@
+export * from './common/index.js';
+export * from './helper.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/modules/retry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/modules/retry/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC"}

package/dist/esm/modules/retry/index.js

@@ -0,0 +1,3 @@
+export * from './common/index.js';
+export * from './helper.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/modules/retry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/modules/retry/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC"}

package/dist/esm/modules/secrets/base/abstract.helper.d.ts

@@ -1,4 +1,4 @@
-import { BaseHelper } from '../../../modules/base.js';
+import { BaseHelper } from '../../base.js';
 import type { IClock, IGetSecretOptions, ISecretLease, ISecretRotatable, ISecretsHelper, ISecretsHelperOptions, ITimerAdapter, TSecretRotationHandler } from '../common/index.js';
 interface IRawFetchResult {
     value: Record<string, string>;

package/dist/esm/modules/secrets/base/abstract.helper.js

@@ -1,5 +1,5 @@
-import { BaseHelper } from '../../../modules/base.js';
-import { getError } from '../../../modules/error/index.js';
+import { BaseHelper } from '../../base.js';
+import { getError } from '../../error/index.js';
 const DEFAULT_CLOCK = { now: () => Date.now() };
 const DEFAULT_TIMERS = {
     set: (handler, ms) => setTimeout(handler, ms),

package/dist/esm/modules/secrets/common/constants.d.ts

@@ -1,4 +1,4 @@
-import type { TConstValue } from '../../../common/types.js';
+import type { TConstValue } from '../../../common/types/index.js';
 export declare class SecretProviders {
     static readonly SYSTEM_ENVS = "system-envs";
     static readonly HASHICORP_VAULT = "hashicorp-vault";

package/dist/esm/modules/secrets/common/index.d.ts

@@ -1,3 +1,3 @@
 export * from './constants.js';
-export * from './types.js';
+export * from './types/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/modules/secrets/common/index.js

@@ -1,3 +1,3 @@
 export * from './constants.js';
-export * from './types.js';
+export * from './types/index.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/modules/secrets/common/types/helper.d.ts

@@ -0,0 +1,33 @@
+import type { IConfigurable } from '../../../../common/types/index.js';
+import type { ISecretLease, ISecretRotatable, TSecretRotationHandler } from './lease.js';
+import type { IClock, ITimerAdapter } from './timer.js';
+export interface IGetSecretOptions<TValue = string> {
+    path: string;
+    key?: string;
+    defaultValue?: TValue;
+}
+export interface ISecretsHelper extends IConfigurable {
+    get<TValue = string>(opts: IGetSecretOptions<TValue>): Promise<TValue>;
+    getBundle(opts: {
+        path: string;
+    }): Promise<Record<string, string>>;
+    lease(opts: {
+        path: string;
+        key: string;
+    }): Promise<ISecretLease>;
+    onRotate(handler: TSecretRotationHandler): void;
+    registerRotatable(opts: {
+        key: string;
+        target: ISecretRotatable;
+    }): void;
+    shutdown(): Promise<void>;
+}
+export interface ISecretsHelperOptions {
+    scope: string;
+    identifier?: string;
+    cacheTtlSeconds?: number;
+    renewBeforeRatio?: number;
+    clock?: IClock;
+    timers?: ITimerAdapter;
+}
+//# sourceMappingURL=helper.d.ts.map

package/dist/esm/modules/secrets/common/types/helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../../../../../../src/modules/secrets/common/types/helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AACtF,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAErD,MAAM,WAAW,iBAAiB,CAAC,MAAM,GAAG,MAAM;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAe,SAAQ,aAAa;IACnD,GAAG,CAAC,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvE,SAAS,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnE,KAAK,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAClE,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAChD,iBAAiB,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,gBAAgB,CAAA;KAAE,GAAG,IAAI,CAAC;IACzE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB"}

package/dist/esm/modules/secrets/common/types/helper.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=helper.js.map

package/dist/esm/modules/secrets/common/types/helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.js","sourceRoot":"","sources":["../../../../../../src/modules/secrets/common/types/helper.ts"],"names":[],"mappings":""}

package/dist/esm/modules/secrets/common/types/index.d.ts

@@ -0,0 +1,5 @@
+export * from './helper.js';
+export * from './lease.js';
+export * from './registration.js';
+export * from './timer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/modules/secrets/common/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/modules/secrets/common/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC"}

package/dist/esm/modules/secrets/common/types/index.js

@@ -0,0 +1,5 @@
+export * from './helper.js';
+export * from './lease.js';
+export * from './registration.js';
+export * from './timer.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/modules/secrets/common/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../src/modules/secrets/common/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC"}

package/dist/esm/modules/secrets/common/types/lease.d.ts

@@ -0,0 +1,21 @@
+import type { ValueOrPromise } from '../../../../common/types/index.js';
+/** A dynamic, lease-bearing secret (e.g. Vault `database/creds/...`). */
+export interface ISecretLease {
+    value: Record<string, string>;
+    leaseId: string;
+    ttlSeconds: number;
+    renewable: boolean;
+}
+export interface ISecretRotationEvent {
+    key: string;
+    lease: ISecretLease;
+}
+export type TSecretRotationHandler = (event: ISecretRotationEvent) => ValueOrPromise<void>;
+/** A live consumer (pool holder) that rebuilds gracefully when its secret rotates. */
+export interface ISecretRotatable {
+    onSecretRotated(opts: {
+        key: string;
+        secret: Record<string, string>;
+    }): Promise<void>;
+}
+//# sourceMappingURL=lease.d.ts.map

package/dist/esm/modules/secrets/common/types/lease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease.d.ts","sourceRoot":"","sources":["../../../../../../src/modules/secrets/common/types/lease.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,MAAM,sBAAsB,GAAG,CAAC,KAAK,EAAE,oBAAoB,KAAK,cAAc,CAAC,IAAI,CAAC,CAAC;AAE3F,sFAAsF;AACtF,MAAM,WAAW,gBAAgB;IAC/B,eAAe,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvF"}

package/dist/esm/modules/secrets/common/types/lease.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=lease.js.map

package/dist/esm/modules/secrets/common/types/lease.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease.js","sourceRoot":"","sources":["../../../../../../src/modules/secrets/common/types/lease.ts"],"names":[],"mappings":""}

package/dist/esm/modules/secrets/common/types/registration.d.ts

@@ -0,0 +1,24 @@
+import type { AnyObject } from '../../../../common/types/index.js';
+import type { TSecretProvider } from '../constants.js';
+export interface ISecretHydrateEntry {
+    path: string;
+    prefix?: string;
+    /** Explicit vaultKey -> envKey overrides. Takes precedence over `prefix`. */
+    keys?: Record<string, string>;
+}
+export interface ISecretLeaseEntry {
+    /** Logical/binding key of the consuming datasource, e.g. 'datasources.postgres'. */
+    key: string;
+    path: string;
+}
+export interface ISecretsRegistration {
+    provider: TSecretProvider;
+    config?: AnyObject;
+    hydrate?: Array<ISecretHydrateEntry>;
+    lease?: Array<ISecretLeaseEntry>;
+    /** Renew a lease at ttl * ratio. Default 0.66. */
+    renewBeforeRatio?: number;
+    /** TTL (seconds) for the static get/getBundle cache. Default 300. */
+    cacheTtlSeconds?: number;
+}
+//# sourceMappingURL=registration.d.ts.map

package/dist/esm/modules/secrets/common/types/registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration.d.ts","sourceRoot":"","sources":["../../../../../../src/modules/secrets/common/types/registration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,oFAAoF;IACpF,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,eAAe,CAAC;IAC1B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,OAAO,CAAC,EAAE,KAAK,CAAC,mBAAmB,CAAC,CAAC;IACrC,KAAK,CAAC,EAAE,KAAK,CAAC,iBAAiB,CAAC,CAAC;IACjC,kDAAkD;IAClD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B"}

package/dist/esm/modules/secrets/common/types/registration.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=registration.js.map

package/dist/esm/modules/secrets/common/types/registration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration.js","sourceRoot":"","sources":["../../../../../../src/modules/secrets/common/types/registration.ts"],"names":[],"mappings":""}