@tstdl/base 0.93.126 → 0.93.128

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);
+    });
+});

package/mail/drizzle/0000_previous_malcolm_colcord.sql

@@ -1,13 +0,0 @@
-CREATE TABLE "mail"."log" (
-	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
-	"timestamp" timestamp with time zone NOT NULL,
-	"template" text,
-	"data" jsonb NOT NULL,
-	"send_result" jsonb,
-	"errors" text[],
-	"revision" integer NOT NULL,
-	"revision_timestamp" timestamp with time zone NOT NULL,
-	"create_timestamp" timestamp with time zone NOT NULL,
-	"delete_timestamp" timestamp with time zone,
-	"attributes" jsonb DEFAULT '{}'::jsonb NOT NULL
-);

package/mail/drizzle/0001_flimsy_bloodscream.sql

@@ -1,5 +0,0 @@
-ALTER TABLE "mail"."log" DROP COLUMN "revision";--> statement-breakpoint
-ALTER TABLE "mail"."log" DROP COLUMN "revision_timestamp";--> statement-breakpoint
-ALTER TABLE "mail"."log" DROP COLUMN "create_timestamp";--> statement-breakpoint
-ALTER TABLE "mail"."log" DROP COLUMN "delete_timestamp";--> statement-breakpoint
-ALTER TABLE "mail"."log" DROP COLUMN "attributes";

package/mail/drizzle/meta/0001_snapshot.json

@@ -1,69 +0,0 @@
-{
-  "id": "28ddafef-64f4-437d-9406-82a02c76570e",
-  "prevId": "f8cdba37-11b9-477a-9f5a-5ef4b5026011",
-  "version": "7",
-  "dialect": "postgresql",
-  "tables": {
-    "mail.log": {
-      "name": "log",
-      "schema": "mail",
-      "columns": {
-        "id": {
-          "name": "id",
-          "type": "uuid",
-          "primaryKey": true,
-          "notNull": true,
-          "default": "gen_random_uuid()"
-        },
-        "timestamp": {
-          "name": "timestamp",
-          "type": "timestamp with time zone",
-          "primaryKey": false,
-          "notNull": true
-        },
-        "template": {
-          "name": "template",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": false
-        },
-        "data": {
-          "name": "data",
-          "type": "jsonb",
-          "primaryKey": false,
-          "notNull": true
-        },
-        "send_result": {
-          "name": "send_result",
-          "type": "jsonb",
-          "primaryKey": false,
-          "notNull": false
-        },
-        "errors": {
-          "name": "errors",
-          "type": "text[]",
-          "primaryKey": false,
-          "notNull": false
-        }
-      },
-      "indexes": {},
-      "foreignKeys": {},
-      "compositePrimaryKeys": {},
-      "uniqueConstraints": {},
-      "policies": {},
-      "checkConstraints": {},
-      "isRLSEnabled": false
-    }
-  },
-  "enums": {},
-  "schemas": {},
-  "sequences": {},
-  "roles": {},
-  "policies": {},
-  "views": {},
-  "_meta": {
-    "columns": {},
-    "schemas": {},
-    "tables": {}
-  }
-}