@fragno-dev/db 0.1.13 → 0.1.15

package/src/query/retry-policy.test.ts

@@ -0,0 +1,217 @@
+import { describe, it, expect } from "vitest";
+import {
+  ExponentialBackoffRetryPolicy,
+  LinearBackoffRetryPolicy,
+  NoRetryPolicy,
+} from "./retry-policy";
+
+describe("ExponentialBackoffRetryPolicy", () => {
+  describe("default options", () => {
+    it("should use default maxRetries of 3", () => {
+      const policy = new ExponentialBackoffRetryPolicy();
+
+      expect(policy.shouldRetry(0)).toBe(true);
+      expect(policy.shouldRetry(1)).toBe(true);
+      expect(policy.shouldRetry(2)).toBe(true);
+      expect(policy.shouldRetry(3)).toBe(false);
+    });
+
+    it("should use default initialDelayMs of 100", () => {
+      const policy = new ExponentialBackoffRetryPolicy();
+
+      expect(policy.getDelayMs(0)).toBe(100);
+    });
+
+    it("should use default backoffMultiplier of 2", () => {
+      const policy = new ExponentialBackoffRetryPolicy();
+
+      expect(policy.getDelayMs(0)).toBe(100);
+      expect(policy.getDelayMs(1)).toBe(200);
+      expect(policy.getDelayMs(2)).toBe(400);
+    });
+
+    it("should cap at maxDelayMs of 10000", () => {
+      const policy = new ExponentialBackoffRetryPolicy();
+
+      expect(policy.getDelayMs(10)).toBe(10000);
+    });
+  });
+
+  describe("custom options", () => {
+    it("should respect custom maxRetries", () => {
+      const policy = new ExponentialBackoffRetryPolicy({ maxRetries: 5 });
+
+      expect(policy.shouldRetry(4)).toBe(true);
+      expect(policy.shouldRetry(5)).toBe(false);
+    });
+
+    it("should respect custom initialDelayMs", () => {
+      const policy = new ExponentialBackoffRetryPolicy({ initialDelayMs: 50 });
+
+      expect(policy.getDelayMs(0)).toBe(50);
+      expect(policy.getDelayMs(1)).toBe(100);
+    });
+
+    it("should respect custom maxDelayMs", () => {
+      const policy = new ExponentialBackoffRetryPolicy({ maxDelayMs: 500 });
+
+      expect(policy.getDelayMs(10)).toBe(500);
+    });
+
+    it("should respect custom backoffMultiplier", () => {
+      const policy = new ExponentialBackoffRetryPolicy({
+        initialDelayMs: 100,
+        backoffMultiplier: 3,
+      });
+
+      expect(policy.getDelayMs(0)).toBe(100);
+      expect(policy.getDelayMs(1)).toBe(300);
+      expect(policy.getDelayMs(2)).toBe(900);
+    });
+  });
+
+  describe("AbortSignal handling", () => {
+    it("should return false if signal is aborted", () => {
+      const policy = new ExponentialBackoffRetryPolicy();
+      const controller = new AbortController();
+      controller.abort();
+
+      expect(policy.shouldRetry(0, undefined, controller.signal)).toBe(false);
+    });
+
+    it("should return true if signal is not aborted", () => {
+      const policy = new ExponentialBackoffRetryPolicy();
+      const controller = new AbortController();
+
+      expect(policy.shouldRetry(0, undefined, controller.signal)).toBe(true);
+    });
+  });
+
+  describe("exponential delay calculation", () => {
+    it("should calculate correct exponential delays", () => {
+      const policy = new ExponentialBackoffRetryPolicy({
+        initialDelayMs: 10,
+        backoffMultiplier: 2,
+        maxDelayMs: 1000,
+      });
+
+      expect(policy.getDelayMs(0)).toBe(10);
+      expect(policy.getDelayMs(1)).toBe(20);
+      expect(policy.getDelayMs(2)).toBe(40);
+      expect(policy.getDelayMs(3)).toBe(80);
+      expect(policy.getDelayMs(4)).toBe(160);
+      expect(policy.getDelayMs(5)).toBe(320);
+      expect(policy.getDelayMs(6)).toBe(640);
+      expect(policy.getDelayMs(7)).toBe(1000); // capped at maxDelayMs
+    });
+  });
+});
+
+describe("LinearBackoffRetryPolicy", () => {
+  describe("default options", () => {
+    it("should use default maxRetries of 3", () => {
+      const policy = new LinearBackoffRetryPolicy();
+
+      expect(policy.shouldRetry(0)).toBe(true);
+      expect(policy.shouldRetry(1)).toBe(true);
+      expect(policy.shouldRetry(2)).toBe(true);
+      expect(policy.shouldRetry(3)).toBe(false);
+    });
+
+    it("should use default delayMs of 100", () => {
+      const policy = new LinearBackoffRetryPolicy();
+
+      expect(policy.getDelayMs(0)).toBe(100);
+    });
+
+    it("should use default incrementMs of 100", () => {
+      const policy = new LinearBackoffRetryPolicy();
+
+      expect(policy.getDelayMs(0)).toBe(100);
+      expect(policy.getDelayMs(1)).toBe(200);
+      expect(policy.getDelayMs(2)).toBe(300);
+    });
+  });
+
+  describe("custom options", () => {
+    it("should respect custom maxRetries", () => {
+      const policy = new LinearBackoffRetryPolicy({ maxRetries: 5 });
+
+      expect(policy.shouldRetry(4)).toBe(true);
+      expect(policy.shouldRetry(5)).toBe(false);
+    });
+
+    it("should respect custom delayMs", () => {
+      const policy = new LinearBackoffRetryPolicy({ delayMs: 50 });
+
+      expect(policy.getDelayMs(0)).toBe(50);
+      expect(policy.getDelayMs(1)).toBe(150);
+    });
+
+    it("should respect custom incrementMs", () => {
+      const policy = new LinearBackoffRetryPolicy({ incrementMs: 50 });
+
+      expect(policy.getDelayMs(0)).toBe(100);
+      expect(policy.getDelayMs(1)).toBe(150);
+      expect(policy.getDelayMs(2)).toBe(200);
+    });
+  });
+
+  describe("AbortSignal handling", () => {
+    it("should return false if signal is aborted", () => {
+      const policy = new LinearBackoffRetryPolicy();
+      const controller = new AbortController();
+      controller.abort();
+
+      expect(policy.shouldRetry(0, undefined, controller.signal)).toBe(false);
+    });
+
+    it("should return true if signal is not aborted", () => {
+      const policy = new LinearBackoffRetryPolicy();
+      const controller = new AbortController();
+
+      expect(policy.shouldRetry(0, undefined, controller.signal)).toBe(true);
+    });
+  });
+
+  describe("linear delay calculation", () => {
+    it("should calculate correct linear delays", () => {
+      const policy = new LinearBackoffRetryPolicy({
+        delayMs: 10,
+        incrementMs: 5,
+      });
+
+      expect(policy.getDelayMs(0)).toBe(10);
+      expect(policy.getDelayMs(1)).toBe(15);
+      expect(policy.getDelayMs(2)).toBe(20);
+      expect(policy.getDelayMs(3)).toBe(25);
+      expect(policy.getDelayMs(4)).toBe(30);
+    });
+  });
+});
+
+describe("NoRetryPolicy", () => {
+  it("should always return false for shouldRetry", () => {
+    const policy = new NoRetryPolicy();
+
+    expect(policy.shouldRetry(0)).toBe(false);
+    expect(policy.shouldRetry(1)).toBe(false);
+    expect(policy.shouldRetry(100)).toBe(false);
+  });
+
+  it("should always return 0 for getDelayMs", () => {
+    const policy = new NoRetryPolicy();
+
+    expect(policy.getDelayMs(0)).toBe(0);
+    expect(policy.getDelayMs(1)).toBe(0);
+    expect(policy.getDelayMs(100)).toBe(0);
+  });
+
+  it("should ignore abort signal", () => {
+    const policy = new NoRetryPolicy();
+    const controller = new AbortController();
+    controller.abort();
+
+    expect(policy.shouldRetry(0, undefined, controller.signal)).toBe(false);
+  });
+});

package/src/query/retry-policy.ts

@@ -0,0 +1,141 @@
+/**
+ * Policy for retrying failed Unit of Work operations
+ */
+export interface RetryPolicy {
+  /**
+   * Determines if the operation should be retried
+   * @param attempt - The current attempt number (0-indexed)
+   * @param error - Optional error from the previous attempt
+   * @param signal - Optional AbortSignal to check for cancellation
+   * @returns true if the operation should be retried, false otherwise
+   */
+  shouldRetry(attempt: number, error?: unknown, signal?: AbortSignal): boolean;
+
+  /**
+   * Gets the delay in milliseconds before the next retry attempt
+   * @param attempt - The current attempt number (0-indexed)
+   * @returns Delay in milliseconds
+   */
+  getDelayMs(attempt: number): number;
+}
+
+/**
+ * Options for exponential backoff retry policy
+ */
+export interface ExponentialBackoffRetryPolicyOptions {
+  /**
+   * Maximum number of retry attempts (default: 3)
+   */
+  maxRetries?: number;
+
+  /**
+   * Initial delay in milliseconds (default: 100)
+   */
+  initialDelayMs?: number;
+
+  /**
+   * Maximum delay in milliseconds (default: 10000)
+   */
+  maxDelayMs?: number;
+
+  /**
+   * Multiplier for exponential backoff (default: 2)
+   */
+  backoffMultiplier?: number;
+}
+
+/**
+ * Exponential backoff retry policy
+ * Delay increases exponentially: initialDelay * (multiplier ^ attempt)
+ */
+export class ExponentialBackoffRetryPolicy implements RetryPolicy {
+  readonly #maxRetries: number;
+  readonly #initialDelayMs: number;
+  readonly #maxDelayMs: number;
+  readonly #backoffMultiplier: number;
+
+  constructor(options: ExponentialBackoffRetryPolicyOptions = {}) {
+    this.#maxRetries = options.maxRetries ?? 3;
+    this.#initialDelayMs = options.initialDelayMs ?? 100;
+    this.#maxDelayMs = options.maxDelayMs ?? 10000;
+    this.#backoffMultiplier = options.backoffMultiplier ?? 2;
+  }
+
+  shouldRetry(attempt: number, _error?: unknown, signal?: AbortSignal): boolean {
+    // Check if operation was aborted
+    if (signal?.aborted) {
+      return false;
+    }
+
+    // Check if we've exceeded max retries
+    return attempt < this.#maxRetries;
+  }
+
+  getDelayMs(attempt: number): number {
+    const delay = this.#initialDelayMs * Math.pow(this.#backoffMultiplier, attempt);
+    return Math.min(delay, this.#maxDelayMs);
+  }
+}
+
+/**
+ * Options for linear backoff retry policy
+ */
+export interface LinearBackoffRetryPolicyOptions {
+  /**
+   * Maximum number of retry attempts (default: 3)
+   */
+  maxRetries?: number;
+
+  /**
+   * Base delay in milliseconds (default: 100)
+   */
+  delayMs?: number;
+
+  /**
+   * Increment added to delay for each attempt in milliseconds (default: 100)
+   */
+  incrementMs?: number;
+}
+
+/**
+ * Linear backoff retry policy
+ * Delay increases linearly: delayMs + (attempt * incrementMs)
+ */
+export class LinearBackoffRetryPolicy implements RetryPolicy {
+  readonly #maxRetries: number;
+  readonly #delayMs: number;
+  readonly #incrementMs: number;
+
+  constructor(options: LinearBackoffRetryPolicyOptions = {}) {
+    this.#maxRetries = options.maxRetries ?? 3;
+    this.#delayMs = options.delayMs ?? 100;
+    this.#incrementMs = options.incrementMs ?? 100;
+  }
+
+  shouldRetry(attempt: number, _error?: unknown, signal?: AbortSignal): boolean {
+    // Check if operation was aborted
+    if (signal?.aborted) {
+      return false;
+    }
+
+    // Check if we've exceeded max retries
+    return attempt < this.#maxRetries;
+  }
+
+  getDelayMs(attempt: number): number {
+    return this.#delayMs + attempt * this.#incrementMs;
+  }
+}
+
+/**
+ * No retry policy - never retries failed operations
+ */
+export class NoRetryPolicy implements RetryPolicy {
+  shouldRetry(_attempt: number, _error?: unknown, _signal?: AbortSignal): boolean {
+    return false;
+  }
+
+  getDelayMs(_attempt: number): number {
+    return 0;
+  }
+}