@sonamu-kit/tasks 0.0.1

package/src/core/duration.test.ts

@@ -0,0 +1,326 @@
+import { describe, expect, test } from "vitest";
+import type { DurationString } from "./duration";
+import { parseDuration } from "./duration";
+import { err, ok } from "./result";
+
+describe("parseDuration", () => {
+  describe("milliseconds", () => {
+    test("parses integer milliseconds", () => {
+      expect(parseDuration("100ms")).toEqual(ok(100));
+      expect(parseDuration("1ms")).toEqual(ok(1));
+      expect(parseDuration("5000ms")).toEqual(ok(5000));
+    });
+
+    test("parses decimal milliseconds", () => {
+      expect(parseDuration("1.5ms")).toEqual(ok(1.5));
+      expect(parseDuration("10.25ms")).toEqual(ok(10.25));
+    });
+
+    test("parses milliseconds with long format", () => {
+      expect(parseDuration("53 milliseconds")).toEqual(ok(53));
+      expect(parseDuration("17 msecs")).toEqual(ok(17));
+      expect(parseDuration("100 millisecond")).toEqual(ok(100));
+    });
+
+    test("parses numbers without unit as milliseconds", () => {
+      expect(parseDuration("100")).toEqual(ok(100));
+      expect(parseDuration("1000")).toEqual(ok(1000));
+    });
+
+    test("parses negative milliseconds", () => {
+      expect(parseDuration("-100ms")).toEqual(ok(-100));
+      expect(parseDuration("-100 milliseconds")).toEqual(ok(-100));
+    });
+  });
+
+  describe("seconds", () => {
+    test("parses integer seconds", () => {
+      expect(parseDuration("1s")).toEqual(ok(1000));
+      expect(parseDuration("5s")).toEqual(ok(5000));
+      expect(parseDuration("60s")).toEqual(ok(60_000));
+    });
+
+    test("parses decimal seconds", () => {
+      expect(parseDuration("1.5s")).toEqual(ok(1500));
+      expect(parseDuration("0.1s")).toEqual(ok(100));
+      expect(parseDuration("2.5s")).toEqual(ok(2500));
+      expect(parseDuration("0.001s")).toEqual(ok(1));
+    });
+
+    test("parses seconds with long format", () => {
+      expect(parseDuration("1 sec")).toEqual(ok(1000));
+      expect(parseDuration("5 seconds")).toEqual(ok(5000));
+      expect(parseDuration("10 secs")).toEqual(ok(10_000));
+    });
+
+    test("parses seconds with leading decimal", () => {
+      expect(parseDuration(".5s")).toEqual(ok(500));
+      expect(parseDuration(".5ms")).toEqual(ok(0.5));
+    });
+
+    test("parses negative seconds", () => {
+      expect(parseDuration("-5s")).toEqual(ok(-5000));
+      expect(parseDuration("-.5s")).toEqual(ok(-500));
+    });
+  });
+
+  describe("minutes", () => {
+    test("parses integer minutes", () => {
+      expect(parseDuration("1m")).toEqual(ok(60 * 1000));
+      expect(parseDuration("5m")).toEqual(ok(5 * 60 * 1000));
+      expect(parseDuration("30m")).toEqual(ok(30 * 60 * 1000));
+    });
+
+    test("parses decimal minutes", () => {
+      expect(parseDuration("1.5m")).toEqual(ok(1.5 * 60 * 1000));
+      expect(parseDuration("0.5m")).toEqual(ok(30 * 1000));
+    });
+
+    test("parses minutes with long format", () => {
+      expect(parseDuration("1 min")).toEqual(ok(60_000));
+      expect(parseDuration("5 minutes")).toEqual(ok(5 * 60 * 1000));
+      expect(parseDuration("10 mins")).toEqual(ok(10 * 60 * 1000));
+    });
+  });
+
+  describe("hours", () => {
+    test("parses integer hours", () => {
+      expect(parseDuration("1h")).toEqual(ok(60 * 60 * 1000));
+      expect(parseDuration("2h")).toEqual(ok(2 * 60 * 60 * 1000));
+      expect(parseDuration("24h")).toEqual(ok(24 * 60 * 60 * 1000));
+    });
+
+    test("parses decimal hours", () => {
+      expect(parseDuration("1.5h")).toEqual(ok(1.5 * 60 * 60 * 1000));
+      expect(parseDuration("0.25h")).toEqual(ok(15 * 60 * 1000));
+    });
+
+    test("parses hours with long format", () => {
+      expect(parseDuration("1 hr")).toEqual(ok(3_600_000));
+      expect(parseDuration("2 hours")).toEqual(ok(2 * 60 * 60 * 1000));
+      expect(parseDuration("3 hrs")).toEqual(ok(3 * 60 * 60 * 1000));
+      expect(parseDuration("1.5 hours")).toEqual(ok(5_400_000));
+    });
+
+    test("parses negative hours", () => {
+      expect(parseDuration("-1.5h")).toEqual(ok(-5_400_000));
+      expect(parseDuration("-10.5h")).toEqual(ok(-37_800_000));
+      expect(parseDuration("-.5h")).toEqual(ok(-1_800_000));
+      expect(parseDuration("-1.5 hours")).toEqual(ok(-5_400_000));
+      expect(parseDuration("-.5 hr")).toEqual(ok(-1_800_000));
+    });
+  });
+
+  describe("days", () => {
+    test("parses integer days", () => {
+      expect(parseDuration("1d")).toEqual(ok(24 * 60 * 60 * 1000));
+      expect(parseDuration("7d")).toEqual(ok(7 * 24 * 60 * 60 * 1000));
+      expect(parseDuration("30d")).toEqual(ok(30 * 24 * 60 * 60 * 1000));
+    });
+
+    test("parses decimal days", () => {
+      expect(parseDuration("1.5d")).toEqual(ok(1.5 * 24 * 60 * 60 * 1000));
+      expect(parseDuration("0.5d")).toEqual(ok(12 * 60 * 60 * 1000));
+    });
+
+    test("parses days with long format", () => {
+      expect(parseDuration("2 days")).toEqual(ok(172_800_000));
+      expect(parseDuration("1 day")).toEqual(ok(24 * 60 * 60 * 1000));
+    });
+  });
+
+  describe("weeks", () => {
+    test("parses integer weeks", () => {
+      expect(parseDuration("1w")).toEqual(ok(7 * 24 * 60 * 60 * 1000));
+      expect(parseDuration("2w")).toEqual(ok(2 * 7 * 24 * 60 * 60 * 1000));
+      expect(parseDuration("3w")).toEqual(ok(1_814_400_000));
+    });
+
+    test("parses decimal weeks", () => {
+      expect(parseDuration("1.5w")).toEqual(ok(1.5 * 7 * 24 * 60 * 60 * 1000));
+      expect(parseDuration("0.5w")).toEqual(ok(3.5 * 24 * 60 * 60 * 1000));
+    });
+
+    test("parses weeks with long format", () => {
+      expect(parseDuration("1 week")).toEqual(ok(604_800_000));
+      expect(parseDuration("2 weeks")).toEqual(ok(2 * 7 * 24 * 60 * 60 * 1000));
+    });
+  });
+
+  describe("months", () => {
+    test("parses integer months", () => {
+      expect(parseDuration("1mo")).toEqual(ok(2_629_800_000));
+      expect(parseDuration("2mo")).toEqual(ok(2 * 2_629_800_000));
+      expect(parseDuration("6mo")).toEqual(ok(6 * 2_629_800_000));
+    });
+
+    test("parses decimal months", () => {
+      expect(parseDuration("1.5mo")).toEqual(ok(1.5 * 2_629_800_000));
+      expect(parseDuration("0.5mo")).toEqual(ok(0.5 * 2_629_800_000));
+    });
+
+    test("parses months with long format", () => {
+      expect(parseDuration("1 month")).toEqual(ok(2_629_800_000));
+      expect(parseDuration("2 months")).toEqual(ok(2 * 2_629_800_000));
+    });
+  });
+
+  describe("years", () => {
+    test("parses integer years", () => {
+      expect(parseDuration("1y")).toEqual(ok(31_557_600_000));
+      expect(parseDuration("2y")).toEqual(ok(2 * 31_557_600_000));
+      expect(parseDuration("5y")).toEqual(ok(5 * 31_557_600_000));
+    });
+
+    test("parses decimal years", () => {
+      expect(parseDuration("1.5y")).toEqual(ok(1.5 * 31_557_600_000));
+      expect(parseDuration("0.5y")).toEqual(ok(0.5 * 31_557_600_000));
+    });
+
+    test("parses years with long format", () => {
+      expect(parseDuration("1 year")).toEqual(ok(31_557_600_000));
+      expect(parseDuration("2 years")).toEqual(ok(2 * 31_557_600_000));
+      expect(parseDuration("1 yr")).toEqual(ok(31_557_600_000));
+      expect(parseDuration("2 yrs")).toEqual(ok(2 * 31_557_600_000));
+    });
+  });
+
+  describe("case insensitivity", () => {
+    test("parses case-insensitive units", () => {
+      expect(parseDuration("5S")).toEqual(ok(5000));
+      expect(parseDuration("5M")).toEqual(ok(5 * 60 * 1000));
+      expect(parseDuration("5H")).toEqual(ok(5 * 60 * 60 * 1000));
+      expect(parseDuration("5D")).toEqual(ok(5 * 24 * 60 * 60 * 1000));
+      expect(parseDuration("5W")).toEqual(ok(5 * 7 * 24 * 60 * 60 * 1000));
+    });
+
+    test("parses case-insensitive long format", () => {
+      // @ts-expect-error - mixed-case (not in type but accepted at runtime)
+      expect(parseDuration("53 YeArS")).toEqual(ok(1_672_552_800_000));
+      // @ts-expect-error - mixed-case (not in type but accepted at runtime)
+      expect(parseDuration("53 WeEkS")).toEqual(ok(32_054_400_000));
+      // @ts-expect-error - mixed-case (not in type but accepted at runtime)
+      expect(parseDuration("53 DaYS")).toEqual(ok(4_579_200_000));
+      // @ts-expect-error - mixed-case (not in type but accepted at runtime)
+      expect(parseDuration("53 HoUrs")).toEqual(ok(190_800_000));
+      // @ts-expect-error - mixed-case (not in type but accepted at runtime)
+      expect(parseDuration("53 MiLliSeCondS")).toEqual(ok(53));
+    });
+  });
+
+  describe("whitespace handling", () => {
+    test("parses with single space", () => {
+      expect(parseDuration("1 s")).toEqual(ok(1000));
+      expect(parseDuration("5 m")).toEqual(ok(5 * 60 * 1000));
+      expect(parseDuration("2 h")).toEqual(ok(2 * 60 * 60 * 1000));
+    });
+
+    test("parses with multiple spaces", () => {
+      expect(parseDuration("1   s")).toEqual(ok(1000));
+      expect(parseDuration("5   m")).toEqual(ok(5 * 60 * 1000));
+    });
+  });
+
+  describe("edge cases", () => {
+    test("parses zero values", () => {
+      expect(parseDuration("0ms")).toEqual(ok(0));
+      expect(parseDuration("0s")).toEqual(ok(0));
+      expect(parseDuration("0m")).toEqual(ok(0));
+      expect(parseDuration("0h")).toEqual(ok(0));
+      expect(parseDuration("0d")).toEqual(ok(0));
+      expect(parseDuration("0")).toEqual(ok(0));
+    });
+
+    test("parses very small decimals", () => {
+      expect(parseDuration("0.001s")).toEqual(ok(1));
+      expect(parseDuration("0.1ms")).toEqual(ok(0.1));
+    });
+
+    test("parses large numbers", () => {
+      expect(parseDuration("999999ms")).toEqual(ok(999_999));
+      expect(parseDuration("1000s")).toEqual(ok(1_000_000));
+    });
+  });
+
+  describe("error cases", () => {
+    test("returns error on invalid format", () => {
+      // @ts-expect-error - invalid format
+      expect(parseDuration("invalid")).toEqual(
+        err(new Error('Invalid duration format: "invalid"')),
+      );
+      // @ts-expect-error - invalid format
+      expect(parseDuration("10-.5")).toEqual(err(new Error('Invalid duration format: "10-.5"')));
+      // @ts-expect-error - invalid format
+      expect(parseDuration("foo")).toEqual(err(new Error('Invalid duration format: "foo"')));
+    });
+
+    test("returns error on empty string", () => {
+      // @ts-expect-error - empty string
+      expect(parseDuration("")).toEqual(err(new Error('Invalid duration format: ""')));
+    });
+
+    test("returns error on missing number", () => {
+      // @ts-expect-error - unit without number
+      expect(parseDuration("ms")).toEqual(err(new Error('Invalid duration format: "ms"')));
+      // @ts-expect-error - unit without number
+      expect(parseDuration("s")).toEqual(err(new Error('Invalid duration format: "s"')));
+      // @ts-expect-error - unit without number
+      expect(parseDuration("m")).toEqual(err(new Error('Invalid duration format: "m"')));
+      // @ts-expect-error - unit without number
+      expect(parseDuration("h")).toEqual(err(new Error('Invalid duration format: "h"')));
+    });
+
+    test("returns error on unknown unit", () => {
+      // @ts-expect-error - unknown unit
+      expect(parseDuration("100x")).toEqual(err(new Error('Invalid duration format: "100x"')));
+      // @ts-expect-error - unknown unit
+      expect(parseDuration("5z")).toEqual(err(new Error('Invalid duration format: "5z"')));
+    });
+
+    test("returns error on multiple units", () => {
+      // @ts-expect-error - multiple units
+      expect(parseDuration("1h30m")).toEqual(err(new Error('Invalid duration format: "1h30m"')));
+      // @ts-expect-error - multiple units
+      expect(parseDuration("5s100ms")).toEqual(
+        err(new Error('Invalid duration format: "5s100ms"')),
+      );
+    });
+
+    test("returns error on leading/trailing spaces", () => {
+      expect(parseDuration(" 5s")).toEqual(err(new Error('Invalid duration format: " 5s"')));
+      // @ts-expect-error - trailing space
+      expect(parseDuration("5s ")).toEqual(err(new Error('Invalid duration format: "5s "')));
+    });
+
+    test("returns error on special characters", () => {
+      // @ts-expect-error - special characters
+      expect(parseDuration("5s!")).toEqual(err(new Error('Invalid duration format: "5s!"')));
+      // @ts-expect-error - special characters
+      expect(parseDuration("@5s")).toEqual(err(new Error('Invalid duration format: "@5s"')));
+    });
+
+    test("returns error on non-string types", () => {
+      expect(parseDuration(undefined as unknown as DurationString)).toEqual(
+        err(new TypeError("Invalid duration format: expected a string but received undefined")),
+      );
+      expect(parseDuration(null as unknown as DurationString)).toEqual(
+        err(new TypeError("Invalid duration format: expected a string but received object")),
+      );
+      expect(parseDuration([] as unknown as DurationString)).toEqual(
+        err(new TypeError("Invalid duration format: expected a string but received object")),
+      );
+      expect(parseDuration({} as unknown as DurationString)).toEqual(
+        err(new TypeError("Invalid duration format: expected a string but received object")),
+      );
+      expect(parseDuration(Number.NaN as unknown as DurationString)).toEqual(
+        err(new TypeError("Invalid duration format: expected a string but received number")),
+      );
+      expect(parseDuration(Number.POSITIVE_INFINITY as unknown as DurationString)).toEqual(
+        err(new TypeError("Invalid duration format: expected a string but received number")),
+      );
+      expect(parseDuration(Number.NEGATIVE_INFINITY as unknown as DurationString)).toEqual(
+        err(new TypeError("Invalid duration format: expected a string but received number")),
+      );
+    });
+  });
+});

package/src/core/duration.ts

@@ -0,0 +1,86 @@
+import type { Result } from "./result";
+import { err, ok } from "./result";
+
+type Years = "years" | "year" | "yrs" | "yr" | "y";
+type Months = "months" | "month" | "mo";
+type Weeks = "weeks" | "week" | "w";
+type Days = "days" | "day" | "d";
+type Hours = "hours" | "hour" | "hrs" | "hr" | "h";
+type Minutes = "minutes" | "minute" | "mins" | "min" | "m";
+type Seconds = "seconds" | "second" | "secs" | "sec" | "s";
+type Milliseconds = "milliseconds" | "millisecond" | "msecs" | "msec" | "ms";
+type Unit = Years | Months | Weeks | Days | Hours | Minutes | Seconds | Milliseconds;
+type UnitAnyCase = Capitalize<Unit> | Uppercase<Unit> | Lowercase<Unit>;
+export type DurationString = `${number}` | `${number}${UnitAnyCase}` | `${number} ${UnitAnyCase}`;
+
+/**
+ * Parse a duration string into milliseconds. Exmaples:
+ * - short units: "1ms", "5s", "30m", "2h", "7d", "3w", "1y"
+ * - long units: "1 millisecond", "5 seconds", "30 minutes", "2 hours", "7 days", "3 weeks", "1 year"
+ * @param str - Duration string
+ * @returns Milliseconds
+ */
+export function parseDuration(str: DurationString): Result<number> {
+  if (typeof str !== "string") {
+    return err(
+      new TypeError(`Invalid duration format: expected a string but received ${typeof str}`),
+    );
+  }
+
+  if (str.length === 0) {
+    return err(new Error('Invalid duration format: ""'));
+  }
+
+  const match = /^(-?\.?\d+(?:\.\d+)?)\s*([a-z]+)?$/i.exec(str);
+
+  if (!match?.[1]) {
+    return err(new Error(`Invalid duration format: "${str}"`));
+  }
+
+  const numValue = Number.parseFloat(match[1]);
+  const unit = match[2]?.toLowerCase() ?? "ms"; // default to ms if not provided
+
+  const multipliers: Record<string, number> = {
+    millisecond: 1,
+    milliseconds: 1,
+    msec: 1,
+    msecs: 1,
+    ms: 1,
+    second: 1000,
+    seconds: 1000,
+    sec: 1000,
+    secs: 1000,
+    s: 1000,
+    minute: 60 * 1000,
+    minutes: 60 * 1000,
+    min: 60 * 1000,
+    mins: 60 * 1000,
+    m: 60 * 1000,
+    hour: 60 * 60 * 1000,
+    hours: 60 * 60 * 1000,
+    hr: 60 * 60 * 1000,
+    hrs: 60 * 60 * 1000,
+    h: 60 * 60 * 1000,
+    day: 24 * 60 * 60 * 1000,
+    days: 24 * 60 * 60 * 1000,
+    d: 24 * 60 * 60 * 1000,
+    week: 7 * 24 * 60 * 60 * 1000,
+    weeks: 7 * 24 * 60 * 60 * 1000,
+    w: 7 * 24 * 60 * 60 * 1000,
+    month: 2_629_800_000,
+    months: 2_629_800_000,
+    mo: 2_629_800_000,
+    year: 31_557_600_000,
+    years: 31_557_600_000,
+    yr: 31_557_600_000,
+    yrs: 31_557_600_000,
+    y: 31_557_600_000,
+  };
+
+  const multiplier = multipliers[unit];
+  if (multiplier === undefined) {
+    return err(new Error(`Invalid duration format: "${str}"`));
+  }
+
+  return ok(numValue * multiplier);
+}

package/src/core/error.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "vitest";
+import { serializeError } from "./error";
+
+describe("serializeError", () => {
+  test("serializes Error instance with name, message, and stack", () => {
+    const error = new Error("Something went wrong");
+    const result = serializeError(error);
+
+    expect(result.name).toBe("Error");
+    expect(result.message).toBe("Something went wrong");
+    expect(result.stack).toBeDefined();
+    expect(typeof result.stack).toBe("string");
+  });
+
+  test("serializes TypeError with correct name", () => {
+    const error = new TypeError("Invalid type");
+    const result = serializeError(error);
+
+    expect(result.name).toBe("TypeError");
+    expect(result.message).toBe("Invalid type");
+  });
+
+  test("serializes custom Error subclass", () => {
+    class CustomError extends Error {
+      constructor(message: string) {
+        super(message);
+        this.name = "CustomError";
+      }
+    }
+    const error = new CustomError("Custom error message");
+    const result = serializeError(error);
+
+    expect(result.name).toBe("CustomError");
+    expect(result.message).toBe("Custom error message");
+  });
+
+  test("serializes Error without stack as undefined", () => {
+    const error = new Error("No stack");
+    error.stack = undefined;
+    const result = serializeError(error);
+
+    expect(result.stack).toBeUndefined();
+  });
+
+  test("serializes string to message", () => {
+    const result = serializeError("string error");
+
+    expect(result.message).toBe("string error");
+    expect(result.name).toBeUndefined();
+    expect(result.stack).toBeUndefined();
+  });
+
+  test("serializes number to message", () => {
+    const result = serializeError(42);
+
+    expect(result.message).toBe("42");
+  });
+
+  test("serializes null to message", () => {
+    const result = serializeError(null);
+
+    expect(result.message).toBe("null");
+  });
+
+  test("serializes undefined to message", () => {
+    // eslint-disable-next-line unicorn/no-useless-undefined
+    const result = serializeError(undefined);
+
+    expect(result.message).toBe("undefined");
+  });
+
+  test("serializes object to message using String()", () => {
+    const result = serializeError({ foo: "bar" });
+
+    expect(result.message).toBe("[object Object]");
+  });
+});

package/src/core/error.ts

@@ -0,0 +1,30 @@
+import type { JsonValue } from "./json";
+
+export type SerializedError = {
+  name?: string;
+  message: string;
+  stack?: string;
+} & {
+  [key: string]: JsonValue;
+};
+
+/**
+ * Serialize an error to a JSON-compatible format.
+ * @param error - The error to serialize (can be Error instance or any value)
+ * @returns A JSON-serializable error object
+ */
+export function serializeError(error: unknown): SerializedError {
+  if (error instanceof Error) {
+    const { name, message, stack } = error;
+
+    if (stack) {
+      return { name, message, stack };
+    }
+
+    return { name, message };
+  }
+
+  return {
+    message: String(error),
+  };
+}

package/src/core/json.ts

@@ -0,0 +1,2 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };

package/src/core/result.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, test } from "vitest";
+import { err, ok } from "./result";
+
+describe("Result helpers", () => {
+  test("ok creates success result", () => {
+    expect(ok(123)).toEqual({ ok: true, value: 123 });
+  });
+
+  test("err creates error result", () => {
+    const error = new Error("oops");
+    expect(err(error)).toEqual({ ok: false, error });
+  });
+});

package/src/core/result.ts

@@ -0,0 +1,29 @@
+export type Result<T> = Ok<T> | Err;
+
+export interface Ok<T> {
+  ok: true;
+  value: T;
+}
+
+export interface Err {
+  ok: false;
+  error: Error;
+}
+
+/**
+ * Create an Ok result.
+ * @param value - Result value
+ * @returns Ok result
+ */
+export function ok<T>(value: T): Ok<T> {
+  return { ok: true, value };
+}
+
+/**
+ * Create an Err result.
+ * @param error - Result error
+ * @returns Err result
+ */
+export function err(error: Readonly<Error>): Err {
+  return { ok: false, error };
+}

package/src/core/retry.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "vitest";
+import { calculateRetryDelayMs, DEFAULT_RETRY_POLICY, shouldRetry } from "./retry";
+
+describe("calculateRetryDelayMs", () => {
+  test("calculates exponential backoff correctly", () => {
+    expect(calculateRetryDelayMs(1)).toBe(1000);
+    expect(calculateRetryDelayMs(2)).toBe(2000);
+    expect(calculateRetryDelayMs(3)).toBe(4000);
+    expect(calculateRetryDelayMs(4)).toBe(8000);
+    expect(calculateRetryDelayMs(5)).toBe(16_000);
+    expect(calculateRetryDelayMs(6)).toBe(32_000);
+    expect(calculateRetryDelayMs(7)).toBe(64_000);
+  });
+
+  test("caps delay at maximum interval", () => {
+    const { maximumIntervalMs } = DEFAULT_RETRY_POLICY;
+
+    // attempt 8: 1s * 2^7 = 128s = 128000ms, but capped at 100000ms (max)
+    expect(calculateRetryDelayMs(8)).toBe(maximumIntervalMs);
+
+    // attempts 10 & 100: should still be capped
+    expect(calculateRetryDelayMs(10)).toBe(maximumIntervalMs);
+    expect(calculateRetryDelayMs(100)).toBe(maximumIntervalMs);
+  });
+
+  test("handles edge cases", () => {
+    // attempt 0: 1s * 2^-1 = 0.5s = 500ms
+    expect(calculateRetryDelayMs(0)).toBe(500);
+    expect(calculateRetryDelayMs(Infinity)).toBe(100_000);
+  });
+});
+
+describe("shouldRetry", () => {
+  test("always returns true with default policy (infinite retries)", () => {
+    const retryPolicy = DEFAULT_RETRY_POLICY;
+    expect(shouldRetry(retryPolicy, 1)).toBe(true);
+    expect(shouldRetry(retryPolicy, 10)).toBe(true);
+    expect(shouldRetry(retryPolicy, 100)).toBe(true);
+    expect(shouldRetry(retryPolicy, 1000)).toBe(true);
+  });
+});

package/src/core/retry.ts

@@ -0,0 +1,29 @@
+export const DEFAULT_RETRY_POLICY = {
+  initialIntervalMs: 1000, // 1s
+  backoffCoefficient: 2,
+  maximumIntervalMs: 100 * 1000, // 100s
+  maximumAttempts: Infinity, // unlimited
+} as const;
+
+export type RetryPolicy = typeof DEFAULT_RETRY_POLICY;
+
+/**
+ * Calculate the next retry delay using exponential backoff.
+ * @param attemptNumber - Attempt number (1-based)
+ * @returns Delay in milliseconds
+ */
+export function calculateRetryDelayMs(attemptNumber: number): number {
+  const { initialIntervalMs, backoffCoefficient, maximumIntervalMs } = DEFAULT_RETRY_POLICY;
+  const backoffMs = initialIntervalMs * backoffCoefficient ** (attemptNumber - 1);
+  return Math.min(backoffMs, maximumIntervalMs);
+}
+
+/**
+ * Check if an operation should be retried based on the retry policy.
+ * @param retryPolicy - Retry policy
+ * @param attemptNumber - Attempt number (1-based)
+ * @returns True if another attempt should be made
+ */
+export function shouldRetry(retryPolicy: RetryPolicy, attemptNumber: number): boolean {
+  return attemptNumber < retryPolicy.maximumAttempts;
+}