@tstdl/base 0.93.127 → 0.93.129

package/task-queue/tests/dependencies.test.js

@@ -22,6 +22,16 @@ describe('Queue Dependencies & Tree Tests', () => {
     afterAll(async () => {
         await injector?.dispose();
     });
+    async function waitForStatus(id, status) {
+        for (let i = 0; i < 20; i++) {
+            const task = await queue.getTask(id);
+            if (task?.status == status) {
+                return;
+            }
+            await queue.processPendingFanIn();
+            await timeout(50);
+        }
+    }
     describe('Dependencies (Fan-In)', () => {
         it('should schedule a task only after dependency completes (completeAfterTags)', async () => {
             // 1. Create a dependent task (Waiting)
@@ -35,7 +45,7 @@ describe('Queue Dependencies & Tree Tests', () => {
             const dequeued = await queue.dequeue({ types: ['prereq'] });
             expect(dequeued?.id).toBe(prereq.id);
             await queue.complete(dequeued);
-            await queue.processPendingFanIn();
+            await waitForStatus(dependent.id, TaskStatus.Completed);
             const updatedDependent = await queue.getTask(dependent.id);
             expect(updatedDependent?.status).toBe(TaskStatus.Completed);
         });
@@ -50,7 +60,7 @@ describe('Queue Dependencies & Tree Tests', () => {
             // 3. Complete prereq
             const dequeued = await queue.dequeue({ types: ['prereq'] });
             await queue.complete(dequeued);
-            await queue.processPendingFanIn();
+            await waitForStatus(dependent.id, TaskStatus.Pending);
             // 5. Dependent should be Pending (ready to run)
             const updatedDependent = await queue.getTask(dependent.id);
             expect(updatedDependent?.status).toBe(TaskStatus.Pending);
@@ -67,16 +77,8 @@ describe('Queue Dependencies & Tree Tests', () => {
             const dequeued = await queue.dequeue({ types: ['prereq'] });
             // Fail fatally
             await queue.fail(dequeued, new Error('boom'), { fatal: true });
-            // Trigger resolution
-            await queue.processPendingFanIn();
-            let updatedDependent;
-            for (let i = 0; i < 20; i++) {
-                await timeout(100);
-                updatedDependent = await queue.getTask(dependent.id);
-                if (updatedDependent?.status === TaskStatus.Dead)
-                    break;
-                await queue.processPendingFanIn(); // Retry processing if it didn't catch it yet
-            }
+            await waitForStatus(dependent.id, TaskStatus.Dead);
+            const updatedDependent = await queue.getTask(dependent.id);
             expect(updatedDependent?.status).toBe(TaskStatus.Dead);
             expect(updatedDependent?.error?.code).toBe('DependencyFailed');
         });
@@ -90,7 +92,7 @@ describe('Queue Dependencies & Tree Tests', () => {
             await queue.enqueue('t1', {}, { tags: ['tag-1'] });
             const d1 = await queue.dequeue({ types: ['t1'] });
             await queue.complete(d1);
-            await queue.processPendingFanIn();
+            await waitForStatus(dependent.id, TaskStatus.Pending);
             const updated = await queue.getTask(dependent.id);
             expect(updated?.status).toBe(TaskStatus.Pending);
         });

package/task-queue/tests/queue.test.js

@@ -134,11 +134,11 @@ describe('PostgresQueue (Distributed Task Orchestration)', () => {
         const queueProvider = injector.resolve(TaskQueueProvider);
         const queueName = `pg-test-queue-${Date.now()}-${Math.random()}`;
         queue = queueProvider.get(queueName, {
-            visibilityTimeout: 200, // Short timeout for testing
+            visibilityTimeout: 50, // Short timeout for testing
             retryDelayMinimum: 50,
             retryDelayGrowth: 1,
             circuitBreakerThreshold: 2,
-            circuitBreakerResetTimeout: 200,
+            circuitBreakerResetTimeout: 50,
         });
     });
     afterEach(async () => {
@@ -188,11 +188,11 @@ describe('PostgresQueue (Distributed Task Orchestration)', () => {
             expect((t3?.data)['foo']).toBe('low');
         });
         it('should not dequeue a task scheduled in the future', async () => {
-            const future = currentTimestamp() + 500;
+            const future = currentTimestamp() + 100;
             await queue.enqueue('foo', { foo: 'future' }, { scheduleTimestamp: future });
             const task = await queue.dequeue();
             expect(task).toBeUndefined();
-            await timeout(600);
+            await timeout(150);
             const taskLater = await queue.dequeue();
             expect(taskLater).toBeDefined();
         });
@@ -237,8 +237,8 @@ describe('PostgresQueue (Distributed Task Orchestration)', () => {
             ]);
             await queue.fail((await queue.dequeue()), 'err');
             await queue.fail((await queue.dequeue()), 'err');
-            // Breaker is Open. Wait for reset timeout (200ms)
-            await timeout(250);
+            // Breaker is Open. Wait for reset timeout (50ms)
+            await timeout(75);
             const probe = await queue.dequeue();
             expect(probe).toBeDefined();
             const secondAttempt = await queue.dequeue();
@@ -249,8 +249,8 @@ describe('PostgresQueue (Distributed Task Orchestration)', () => {
         it('should recover "Zombie" tasks (crashed workers)', async () => {
             const task = await queue.enqueue('foo', { foo: 'zombie' });
             await queue.dequeue(); // Task is now Running with a token
-            // processTimeout is 200ms. Wait for it to expire.
-            await timeout(300);
+            // processTimeout is 50ms. Wait for it to expire.
+            await timeout(100);
             await queue.maintenance();
             const recovered = await queue.getTask(task.id);
             expect(recovered?.status).toBe(TaskStatus.Pending);
@@ -260,10 +260,10 @@ describe('PostgresQueue (Distributed Task Orchestration)', () => {
         it('should fail tasks that exceed Hard Execution Timeout via prune', async () => {
             // Re-configure queue with very short execution timeout
             const queueProvider = injector.resolve(TaskQueueProvider);
-            const shortQueue = queueProvider.get(`prune-test-${Date.now()}`, { maxExecutionTime: 100 });
+            const shortQueue = queueProvider.get(`prune-test-${Date.now()}`, { maxExecutionTime: 50 });
             const task = await shortQueue.enqueue('foo', { foo: 'long-running' });
             await shortQueue.dequeue();
-            await timeout(200);
+            await timeout(75);
             await shortQueue.maintenance();
             const updated = await shortQueue.getTask(task.id);
             expect(updated?.status).toBe(TaskStatus.Dead);
@@ -274,7 +274,7 @@ describe('PostgresQueue (Distributed Task Orchestration)', () => {
             const task = await queue.enqueue('foo', { foo: 'work' });
             const dequeued = await queue.dequeue();
             const initialLock = dequeued.visibilityDeadline;
-            await timeout(50);
+            await timeout(20);
             const touched = await queue.touch(dequeued);
             expect(touched?.visibilityDeadline > initialLock).toBe(true);
         });
@@ -282,8 +282,8 @@ describe('PostgresQueue (Distributed Task Orchestration)', () => {
             await queue.enqueue('foo', { foo: 'work' });
             const dequeued = await queue.dequeue();
             expect(dequeued).toBeDefined();
-            // processTimeout is 200ms. Wait for it to expire.
-            await timeout(300);
+            // processTimeout is 50ms. Wait for it to expire.
+            await timeout(100);
             await queue.maintenance();
             await queue.dequeue(); // Stolen by another worker (tries=2)
             // Original worker tries to touch

package/task-queue/tests/worker.test.js

@@ -14,7 +14,7 @@ describe('Worker & Base Class Tests', () => {
         const queueProvider = injector.resolve(TaskQueueProvider);
         const queueName = `worker-queue-${Date.now()}-${Math.random()}`;
         queue = queueProvider.get(queueName, {
-            visibilityTimeout: 500, // Short visibility for testing lease loss
+            visibilityTimeout: 200, // Short visibility for testing lease loss
         });
         token = new CancellationToken();
     });
@@ -36,10 +36,10 @@ describe('Worker & Base Class Tests', () => {
             return TaskProcessResult.Complete();
         });
         // Wait until 2 tasks are processed
-        for (let i = 0; i < 20; i++) {
+        for (let i = 0; i < 50; i++) {
             if (processed.length === 2)
                 break;
-            await timeout(100);
+            await timeout(20);
         }
         token.set(); // Stop worker
         expect(processed).toContain(1);
@@ -55,7 +55,7 @@ describe('Worker & Base Class Tests', () => {
         queue.process({ cancellationSignal: token }, async () => {
             throw new Error('worker error');
         });
-        await timeout(200);
+        await timeout(50);
         token.set();
         const updated = await queue.getTask(task.id);
         expect(updated?.status).toBe(TaskStatus.Pending); // Should retry
@@ -66,12 +66,12 @@ describe('Worker & Base Class Tests', () => {
         const task = await queue.enqueue('long', {});
         let executed = false;
         queue.process({ cancellationSignal: token }, async (_context) => {
-            // Simulate long work > visibilityTimeout (500ms)
-            await timeout(700);
+            // Simulate long work > visibilityTimeout (200ms)
+            await timeout(300);
             executed = true;
             return TaskProcessResult.Complete();
         });
-        await timeout(1000);
+        await timeout(500);
         token.set();
         expect(executed).toBe(true);
         const updated = await queue.getTask(task.id);
@@ -91,10 +91,10 @@ describe('Worker & Base Class Tests', () => {
             }
             return TaskProcessResult.Complete();
         });
-        for (let i = 0; i < 20; i++) {
+        for (let i = 0; i < 50; i++) {
             if (processed.size === 2)
                 break;
-            await timeout(100);
+            await timeout(20);
         }
         token.set();
         const uFail = await queue.getTask(tFail.id);
@@ -129,10 +129,10 @@ describe('Worker & Base Class Tests', () => {
             executed = true;
             return TaskProcessResult.Complete();
         });
-        for (let i = 0; i < 20; i++) {
+        for (let i = 0; i < 50; i++) {
             if (executed)
                 break;
-            await timeout(100);
+            await timeout(20);
         }
         token.set();
         expect(executed).toBe(true);
@@ -159,7 +159,7 @@ describe('Worker & Base Class Tests', () => {
             if (finalAttemptValues.length === 2)
                 break;
             testQueue.notify();
-            await timeout(100);
+            await timeout(20);
         }
         token.set();
         expect(finalAttemptValues).toEqual([false, true]);

package/testing/integration-setup.d.ts

@@ -2,6 +2,7 @@ import type { PoolConfig } from 'pg';
 import { type AuthenticationAncillaryService } from '../authentication/server/index.js';
 import { Injector } from '../injector/index.js';
 import { LogLevel } from '../logger/index.js';
+import { type S3ObjectStorageProviderConfig } from '../object-storage/s3/index.js';
 import { Database } from '../orm/server/index.js';
 import type { Type } from '../types/index.js';
 export type IntegrationTestOptions = {
@@ -13,6 +14,7 @@ export type IntegrationTestOptions = {
         baseUrl?: string;
         port?: number;
     };
+    s3?: Partial<S3ObjectStorageProviderConfig>;
     logLevels?: Record<string, LogLevel>;
     modules?: {
         api?: boolean;

package/testing/integration-setup.js

@@ -98,7 +98,11 @@ export async function setupIntegrationTest(options = {}) {
         }
         if (options.modules?.authentication) {
             configureAuthenticationServer({
-                serviceOptions: { secret: 'test-secret' },
+                serviceOptions: {
+                    secret: 'test-secret',
+                    hashIterations: 10,
+                    signingSecretsDerivationIterations: 10,
+                },
                 authenticationAncillaryService: options.authenticationAncillaryService,
                 injector,
             });
@@ -121,13 +125,15 @@ export async function setupIntegrationTest(options = {}) {
             await runInInjectionContext(injector, migrateDocumentManagementSchema);
         }
         if (options.modules?.objectStorage) {
+            const bucketPerModule = options.s3?.bucketPerModule ?? configParser.boolean('S3_BUCKET_PER_MODULE', true);
             configureS3ObjectStorage({
-                endpoint: configParser.string('S3_ENDPOINT', 'http://127.0.0.1:9000'),
-                accessKey: configParser.string('S3_ACCESS_KEY', 'tstdl-dev'),
-                secretKey: configParser.string('S3_SECRET_KEY', 'tstdl-dev'),
-                bucket: configParser.string('S3_BUCKET', 'test-bucket'),
-                region: configParser.string('S3_REGION', 'us-east-1'),
-                forcePathStyle: configParser.boolean('S3_FORCE_PATH_STYLE', true),
+                endpoint: options.s3?.endpoint ?? configParser.string('S3_ENDPOINT', 'http://127.0.0.1:9000'),
+                accessKey: options.s3?.accessKey ?? configParser.string('S3_ACCESS_KEY', 'tstdl-dev'),
+                secretKey: options.s3?.secretKey ?? configParser.string('S3_SECRET_KEY', 'tstdl-dev'),
+                bucket: bucketPerModule ? undefined : (options.s3?.bucket ?? configParser.string('S3_BUCKET', 'test-bucket')),
+                bucketPerModule,
+                region: options.s3?.region ?? configParser.string('S3_REGION', 'us-east-1'),
+                forcePathStyle: options.s3?.forcePathStyle ?? configParser.boolean('S3_FORCE_PATH_STYLE', true),
                 injector,
             });
         }

package/utils/backoff.d.ts

@@ -1,5 +1,6 @@
 import type { CancellationSignal } from '../cancellation/token.js';
 export type BackoffStrategy = 'linear' | 'exponential';
+export type JitterStrategy = 'full' | 'proportional';
 /**
  * Configuration for the backoff behavior.
  */
@@ -11,6 +12,13 @@ export type BackoffOptions = {
      * @default 'exponential'
      */
     strategy?: BackoffStrategy;
+    /**
+     * The strategy to use for applying jitter.
+     * - `full`: Random value between 0 and the calculated delay.
+     * - `proportional`: Random value within `± jitter * delay`.
+     * @default 'proportional'
+     */
+    jitterStrategy?: JitterStrategy;
     /**
      * The initial delay in milliseconds. Must be non-negative.
      * @default 1000
@@ -32,7 +40,8 @@ export type BackoffOptions = {
     /**
      * A factor to randomize the delay, e.g., 0.1 for 10% jitter.
      * This helps prevent the "thundering herd" problem in distributed systems.
-     * The actual delay will be `delay ± delay * jitter`.
+     * For `proportional` jitter, the actual delay will be `delay ± delay * jitter`.
+     * For `full` jitter, this value is ignored.
      * Must be a value between 0 and 1.
      * @default 0.15
      */
@@ -59,14 +68,20 @@ export type BackoffLoopController = {
     /**
      * Schedules a backoff delay before the next iteration of the loop.
      * If this is not called, the backoff delay is reset for the next attempt.
+     * @param delay An optional explicit delay in milliseconds to use for the next backoff.
+     * If not provided, the backoff strategy is used.
      */
-    backoff: () => void;
+    backoff: (delay?: number) => void;
     /**
      * Immediately breaks out of the loop.
      */
     break: () => void;
 };
-export type BackoffLoopFunction = (controller: BackoffLoopController, cancellationSignal: CancellationSignal) => unknown;
+export type BackoffStatus = {
+    attempt: number;
+    currentDelay: number;
+};
+export type BackoffLoopFunction = (controller: BackoffLoopController, cancellationSignal: CancellationSignal, status: BackoffStatus) => unknown;
 /**
  * A function yielded by `backoffGenerator` to control the next iteration.
  */
@@ -82,6 +97,7 @@ export type BackoffGeneratorCallback = (options?: {
  */
 export declare const DEFAULT_BACKOFF_OPTIONS: {
     readonly strategy: "exponential";
+    readonly jitterStrategy: "proportional";
     readonly initialDelay: 1000;
     readonly increase: 2;
     readonly maximumDelay: 30000;
@@ -93,6 +109,14 @@ export declare const DEFAULT_BACKOFF_OPTIONS: {
 export declare class BackoffHelper {
     private readonly options;
     private currentDelay;
+    private attempt;
+    /**
+     * The current status of the backoff.
+     */
+    get status(): {
+        attempt: number;
+        currentDelay: number;
+    };
     /**
      * Creates a new BackoffHelper.
      * @param options Partial backoff options, which will be merged with sane defaults.

package/utils/backoff.js

@@ -8,6 +8,7 @@ import { isDefined } from './type-guards.js';
  */
 export const DEFAULT_BACKOFF_OPTIONS = {
     strategy: 'exponential',
+    jitterStrategy: 'proportional',
     initialDelay: 1000,
     increase: 2,
     maximumDelay: 30_000, // 30 seconds
@@ -19,6 +20,16 @@ export const DEFAULT_BACKOFF_OPTIONS = {
 export class BackoffHelper {
     options;
     currentDelay;
+    attempt;
+    /**
+     * The current status of the backoff.
+     */
+    get status() {
+        return {
+            attempt: this.attempt,
+            currentDelay: this.currentDelay,
+        };
+    }
     /**
      * Creates a new BackoffHelper.
      * @param options Partial backoff options, which will be merged with sane defaults.
@@ -39,12 +50,14 @@ export class BackoffHelper {
             console.warn('Using an exponential backoff with an increase factor <= 1 is not recommended as the delay will not grow.');
         }
         this.currentDelay = this.options.initialDelay;
+        this.attempt = 0;
     }
     /**
      * Resets the current delay to the initial delay.
      */
     reset() {
         this.currentDelay = this.options.initialDelay;
+        this.attempt = 0;
     }
     /**
      * Calculates and returns the next backoff delay based on the configured strategy.
@@ -52,13 +65,18 @@ export class BackoffHelper {
      * @returns The next delay in milliseconds.
      */
     getNextDelay() {
-        const newDelay = getNewDelay(this.options.strategy, this.currentDelay, this.options.increase, this.options.maximumDelay);
+        const baseDelay = this.currentDelay;
+        const newDelay = getNewDelay(this.options.strategy, baseDelay, this.options.increase, this.options.maximumDelay);
         this.currentDelay = newDelay;
+        this.attempt++;
+        if (this.options.jitterStrategy == 'full') {
+            return randomFloat(0, baseDelay);
+        }
         if (this.options.jitter > 0) {
-            const jitterAmount = newDelay * randomFloat(-this.options.jitter, this.options.jitter); // ±jitter
-            return Math.max(0, newDelay + jitterAmount);
+            const jitterAmount = baseDelay * randomFloat(-this.options.jitter, this.options.jitter); // ±jitter
+            return Math.max(0, baseDelay + jitterAmount);
         }
-        return newDelay;
+        return baseDelay;
     }
 }
 /**
@@ -72,9 +90,9 @@ export class BackoffHelper {
  */
 export async function autoBackoffLoop(loopFunction, options = {}) {
     const { errorHandler, ...loopOptions } = options;
-    await backoffLoop(async (controller, signal) => {
+    await backoffLoop(async (controller, signal, status) => {
         try {
-            await loopFunction(controller, signal);
+            await loopFunction(controller, signal, status);
         }
         catch (error) {
             errorHandler?.(error);
@@ -95,22 +113,26 @@ export async function backoffLoop(loopFunction, options = {}) {
     const backoffHelper = new BackoffHelper(backoffOptions);
     const loopToken = new CancellationToken();
     let shouldBackoff = false;
+    let customBackoffDelay;
     if (isDefined(cancellationSignal)) {
         loopToken.inherit(cancellationSignal, { set: true, unset: false, complete: false, error: false });
     }
     const controller = {
-        backoff: () => shouldBackoff = true,
+        backoff: (delay) => {
+            shouldBackoff = true;
+            customBackoffDelay = delay;
+        },
         break: () => loopToken.set(),
     };
     while (loopToken.isUnset) {
-        await loopFunction(controller, loopToken.signal);
+        await loopFunction(controller, loopToken.signal, backoffHelper.status);
         // Exit immediately if the loop function requested a break.
         if (loopToken.isSet) {
             return;
         }
         if (shouldBackoff) {
             shouldBackoff = false;
-            const delay = backoffHelper.getNextDelay();
+            const delay = customBackoffDelay ?? backoffHelper.getNextDelay();
             await cancelableTimeout(delay, loopToken.signal);
         }
         else {

package/utils/index.d.ts

@@ -39,6 +39,7 @@ export * from './random.js';
 export * from './reactive-value-to-signal.js';
 export * from './reflection.js';
 export * from './repl.js';
+export * from './retry-with-backoff.js';
 export * from './set.js';
 export * from './singleton.js';
 export * from './sort.js';

package/utils/index.js

@@ -39,6 +39,7 @@ export * from './random.js';
 export * from './reactive-value-to-signal.js';
 export * from './reflection.js';
 export * from './repl.js';
+export * from './retry-with-backoff.js';
 export * from './set.js';
 export * from './singleton.js';
 export * from './sort.js';

package/utils/retry-with-backoff.d.ts

@@ -0,0 +1,22 @@
+import type { CancellationSignal } from '../cancellation/token.js';
+import { type BackoffOptions } from './backoff.js';
+export type RetryWithBackoffOptions = {
+    /** Timeout for each individual attempt in milliseconds. */
+    timeout?: number;
+    /** Retry configuration. If not provided, it will not retry. */
+    retry?: {
+        /** Whether to retry when an error occurs. */
+        shouldRetry: (error: Error, attempt: number) => boolean | Promise<boolean>;
+        /** Backoff configuration for retries. */
+        backoff?: BackoffOptions;
+    };
+    /** Optional cancellation signal to abort the execution. */
+    signal?: CancellationSignal;
+};
+/**
+ * Executes a function with a specified policy including timeout and retries with backoff.
+ * @param func The function to execute. It receives a cancellation signal that is set when the attempt times out or is cancelled.
+ * @param options The retry options.
+ * @returns The result of the function.
+ */
+export declare function retryWithBackoff<T>(func: (signal: CancellationSignal) => T | Promise<T>, options?: RetryWithBackoffOptions): Promise<T>;

package/utils/retry-with-backoff.js

@@ -0,0 +1,64 @@
+import { HttpError } from '../http/http.error.js';
+import { isDefined, isInstanceOf, isNumber, isString } from '../utils/type-guards.js';
+import { backoffLoop } from './backoff.js';
+import { withTimeout } from './timing.js';
+/**
+ * Executes a function with a specified policy including timeout and retries with backoff.
+ * @param func The function to execute. It receives a cancellation signal that is set when the attempt times out or is cancelled.
+ * @param options The retry options.
+ * @returns The result of the function.
+ */
+export async function retryWithBackoff(func, options = {}) {
+    const { timeout, retry, signal } = options;
+    let result;
+    let lastError;
+    await backoffLoop(async (controller, loopSignal, status) => {
+        try {
+            const attemptSignal = isDefined(signal)
+                ? signal.createChild().inherit(loopSignal)
+                : loopSignal;
+            if (isDefined(timeout)) {
+                result = await withTimeout(timeout, async () => await func(attemptSignal));
+            }
+            else {
+                result = await func(attemptSignal);
+            }
+            controller.break();
+        }
+        catch (error) {
+            lastError = error;
+            if (isDefined(retry) && await retry.shouldRetry(lastError, status.attempt)) {
+                const retryAfter = tryGetRetryAfterDelay(lastError);
+                controller.backoff(retryAfter);
+            }
+            else {
+                throw error;
+            }
+        }
+    }, {
+        ...retry?.backoff,
+        cancellationSignal: signal,
+    });
+    return result;
+}
+function tryGetRetryAfterDelay(error) {
+    if (isInstanceOf(error, HttpError)) {
+        const retryAfter = error.responseInstance?.headers.tryGetSingle('Retry-After');
+        if (isDefined(retryAfter)) {
+            if (isNumber(retryAfter)) {
+                return retryAfter * 1000;
+            }
+            if (isString(retryAfter)) {
+                const seconds = Number.parseInt(retryAfter, 10);
+                if (!Number.isNaN(seconds)) {
+                    return seconds * 1000;
+                }
+                const date = Date.parse(retryAfter);
+                if (!Number.isNaN(date)) {
+                    return Math.max(0, date - Date.now());
+                }
+            }
+        }
+    }
+    return undefined;
+}

package/utils/tests/backoff.test.d.ts

@@ -0,0 +1 @@
+export {};

package/utils/tests/backoff.test.js

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+import { BackoffHelper } from '../backoff.js';
+describe('BackoffHelper', () => {
+    it('should support full jitter', () => {
+        const helper = new BackoffHelper({
+            initialDelay: 1000,
+            jitter: 1,
+            jitterStrategy: 'full',
+        });
+        for (let i = 0; i < 100; i++) {
+            const delay = helper.getNextDelay();
+            // Full jitter should be between 0 and the base delay (1000 for first call, then 2000, 4000, etc.)
+            expect(delay).toBeGreaterThanOrEqual(0);
+            expect(delay).toBeLessThanOrEqual(1000 * Math.pow(2, i));
+        }
+    });
+    it('should support proportional jitter (default)', () => {
+        const helper = new BackoffHelper({
+            initialDelay: 1000,
+            jitter: 0.1,
+            jitterStrategy: 'proportional',
+        });
+        for (let i = 0; i < 1; i++) {
+            const delay = helper.getNextDelay();
+            // Proportional jitter should be 1000 ± 100 (900 to 1100)
+            expect(delay).toBeGreaterThanOrEqual(900);
+            expect(delay).toBeLessThanOrEqual(1100);
+        }
+    });
+    it('should provide status emission', () => {
+        const helper = new BackoffHelper({ initialDelay: 1000 });
+        expect(helper.status.attempt).toBe(0);
+        expect(helper.status.currentDelay).toBe(1000);
+        helper.getNextDelay();
+        expect(helper.status.attempt).toBe(1);
+        expect(helper.status.currentDelay).toBe(2000);
+        helper.reset();
+        expect(helper.status.attempt).toBe(0);
+        expect(helper.status.currentDelay).toBe(1000);
+    });
+});

package/utils/tests/retry-with-backoff.test.d.ts

@@ -0,0 +1 @@
+export {};

package/utils/tests/retry-with-backoff.test.js

@@ -0,0 +1,49 @@
+import { TimeoutError } from '../../errors/timeout.error.js';
+import { describe, expect, it } from 'vitest';
+import { retryWithBackoff } from '../retry-with-backoff.js';
+describe('retryWithBackoff', () => {
+    it('should return result on success', async () => {
+        const result = await retryWithBackoff(async () => 'success');
+        expect(result).toBe('success');
+    });
+    it('should retry on failure if shouldRetry returns true', async () => {
+        let attempts = 0;
+        const result = await retryWithBackoff(async () => {
+            attempts++;
+            if (attempts < 3) {
+                throw new Error('fail');
+            }
+            return 'success';
+        }, {
+            retry: {
+                shouldRetry: (_error, attempt) => attempt < 5,
+                backoff: { initialDelay: 0 },
+            },
+        });
+        expect(result).toBe('success');
+        expect(attempts).toBe(3);
+    });
+    it('should throw after max retries', async () => {
+        let attempts = 0;
+        const execute = retryWithBackoff(async () => {
+            attempts++;
+            throw new Error('fail');
+        }, {
+            retry: {
+                shouldRetry: (_error, attempt) => attempt < 2,
+                backoff: { initialDelay: 0 },
+            },
+        });
+        await expect(execute).rejects.toThrow('fail');
+        expect(attempts).toBe(3); // 0, 1, 2
+    });
+    it('should timeout if execution takes too long', async () => {
+        const execute = retryWithBackoff(async () => {
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            return 'success';
+        }, {
+            timeout: 50,
+        });
+        await expect(execute).rejects.toThrow(TimeoutError);
+    });
+});