openworkflow 0.4.1 → 0.5.0

package/dist/sqlite/sqlite.js

@@ -0,0 +1,247 @@
+import { randomUUID } from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
+/**
+ * newDatabase creates a new SQLite database connection.
+ * @param path - Database file path (or ":memory:") for testing
+ * @returns SQLite database connection
+ */
+export function newDatabase(path) {
+    const db = new DatabaseSync(path);
+    // Only enable WAL mode for file-based databases
+    if (path !== ":memory:") {
+        db.exec("PRAGMA journal_mode = WAL;");
+    }
+    db.exec("PRAGMA foreign_keys = ON;");
+    return db;
+}
+/**
+ * migrations returns the list of migration SQL statements.
+ * @returns Migration SQL statements
+ */
+export function migrations() {
+    return [
+        // 0 - init
+        `BEGIN;
+
+    CREATE TABLE IF NOT EXISTS "openworkflow_migrations" (
+      "version" INTEGER NOT NULL PRIMARY KEY
+    );
+
+    INSERT OR IGNORE INTO "openworkflow_migrations" ("version")
+    VALUES (0);
+
+    COMMIT;`,
+        // 1 - add workflow_runs and step_attempts tables
+        `BEGIN;
+
+    PRAGMA defer_foreign_keys = ON;
+
+    CREATE TABLE IF NOT EXISTS "workflow_runs" (
+      "namespace_id" TEXT NOT NULL,
+      "id" TEXT NOT NULL,
+      --
+      "workflow_name" TEXT NOT NULL,
+      "version" TEXT,
+      "status" TEXT NOT NULL,
+      "idempotency_key" TEXT,
+      "config" TEXT NOT NULL,
+      "context" TEXT,
+      "input" TEXT,
+      "output" TEXT,
+      "error" TEXT,
+      "attempts" INTEGER NOT NULL,
+      "parent_step_attempt_namespace_id" TEXT,
+      "parent_step_attempt_id" TEXT,
+      "worker_id" TEXT,
+      "available_at" TEXT,
+      "deadline_at" TEXT,
+      "started_at" TEXT,
+      "finished_at" TEXT,
+      "created_at" TEXT NOT NULL,
+      "updated_at" TEXT NOT NULL,
+      PRIMARY KEY ("namespace_id", "id"),
+      FOREIGN KEY ("parent_step_attempt_namespace_id", "parent_step_attempt_id")
+        REFERENCES "step_attempts" ("namespace_id", "id")
+        ON DELETE SET NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS "step_attempts" (
+      "namespace_id" TEXT NOT NULL,
+      "id" TEXT NOT NULL,
+      --
+      "workflow_run_id" TEXT NOT NULL,
+      "step_name" TEXT NOT NULL,
+      "kind" TEXT NOT NULL,
+      "status" TEXT NOT NULL,
+      "config" TEXT NOT NULL,
+      "context" TEXT,
+      "output" TEXT,
+      "error" TEXT,
+      "child_workflow_run_namespace_id" TEXT,
+      "child_workflow_run_id" TEXT,
+      "started_at" TEXT,
+      "finished_at" TEXT,
+      "created_at" TEXT NOT NULL,
+      "updated_at" TEXT NOT NULL,
+      PRIMARY KEY ("namespace_id", "id"),
+      FOREIGN KEY ("namespace_id", "workflow_run_id")
+        REFERENCES "workflow_runs" ("namespace_id", "id")
+        ON DELETE CASCADE,
+      FOREIGN KEY ("child_workflow_run_namespace_id", "child_workflow_run_id")
+        REFERENCES "workflow_runs" ("namespace_id", "id")
+        ON DELETE SET NULL
+    );
+
+    INSERT OR IGNORE INTO "openworkflow_migrations" ("version")
+    VALUES (1);
+
+    COMMIT;`,
+        // 2 - foreign keys
+        `BEGIN;
+
+    -- Foreign keys are defined in migration 1 since SQLite requires them during table creation
+    -- This migration exists for version parity with PostgreSQL backend
+
+    INSERT OR IGNORE INTO "openworkflow_migrations" ("version")
+    VALUES (2);
+
+    COMMIT;`,
+        // 3 - validate foreign keys
+        `BEGIN;
+
+    -- Foreign key validation happens automatically in SQLite when PRAGMA foreign_keys = ON
+    -- This migration exists for version parity with PostgreSQL backend
+
+    INSERT OR IGNORE INTO "openworkflow_migrations" ("version")
+    VALUES (3);
+
+    COMMIT;`,
+        // 4 - indexes
+        `BEGIN;
+
+    CREATE INDEX IF NOT EXISTS "workflow_runs_status_available_at_created_at_idx"
+    ON "workflow_runs" ("namespace_id", "status", "available_at", "created_at");
+
+    CREATE INDEX IF NOT EXISTS "workflow_runs_workflow_name_idempotency_key_created_at_idx"
+    ON "workflow_runs" ("namespace_id", "workflow_name", "idempotency_key", "created_at");
+
+    CREATE INDEX IF NOT EXISTS "workflow_runs_parent_step_idx"
+    ON "workflow_runs" ("parent_step_attempt_namespace_id", "parent_step_attempt_id")
+    WHERE parent_step_attempt_namespace_id IS NOT NULL AND parent_step_attempt_id IS NOT NULL;
+
+    CREATE INDEX IF NOT EXISTS "workflow_runs_created_at_desc_idx"
+    ON "workflow_runs" ("namespace_id", "created_at" DESC);
+
+    CREATE INDEX IF NOT EXISTS "workflow_runs_status_created_at_desc_idx"
+    ON "workflow_runs" ("namespace_id", "status", "created_at" DESC);
+
+    CREATE INDEX IF NOT EXISTS "workflow_runs_workflow_name_status_created_at_desc_idx"
+    ON "workflow_runs" ("namespace_id", "workflow_name", "status", "created_at" DESC);
+
+    CREATE INDEX IF NOT EXISTS "step_attempts_workflow_run_created_at_idx"
+    ON "step_attempts" ("namespace_id", "workflow_run_id", "created_at");
+
+    CREATE INDEX IF NOT EXISTS "step_attempts_workflow_run_step_name_created_at_idx"
+    ON "step_attempts" ("namespace_id", "workflow_run_id", "step_name", "created_at");
+
+    CREATE INDEX IF NOT EXISTS "step_attempts_child_workflow_run_idx"
+    ON "step_attempts" ("child_workflow_run_namespace_id", "child_workflow_run_id")
+    WHERE child_workflow_run_namespace_id IS NOT NULL AND child_workflow_run_id IS NOT NULL;
+
+    INSERT OR IGNORE INTO "openworkflow_migrations" ("version")
+    VALUES (4);
+
+    COMMIT;`,
+    ];
+}
+/**
+ * migrate applies pending migrations to the database. Does nothing if the
+ * database is already up to date.
+ * @param db - SQLite database
+ */
+export function migrate(db) {
+    const currentMigrationVersion = getCurrentMigrationVersion(db);
+    for (const [i, migrationSql] of migrations().entries()) {
+        if (i <= currentMigrationVersion)
+            continue; // already applied
+        db.exec(migrationSql);
+    }
+}
+/**
+ * getCurrentMigrationVersion returns the current migration version of the database.
+ * @param db - SQLite database
+ * @returns Current migration version
+ */
+function getCurrentMigrationVersion(db) {
+    // check if migrations table exists
+    const existsStmt = db.prepare(`
+    SELECT COUNT(*) as count
+    FROM sqlite_master
+    WHERE type = 'table' AND name = 'openworkflow_migrations'
+  `);
+    const existsResult = existsStmt.get();
+    if (!existsResult || existsResult.count === 0)
+        return -1;
+    // get current version
+    const versionStmt = db.prepare(`SELECT MAX("version") AS "version" FROM "openworkflow_migrations";`);
+    const versionResult = versionStmt.get();
+    return versionResult?.version ?? -1;
+}
+/**
+ * Helper to generate UUIDs (SQLite doesn't have built-in UUID generation)
+ * @returns A UUID string
+ */
+export function generateUUID() {
+    return randomUUID();
+}
+/**
+ * Helper to get current timestamp in ISO8601 format
+ * @returns ISO8601 timestamp string
+ */
+export function now() {
+    return new Date().toISOString();
+}
+/**
+ * Helper to add milliseconds to a date and return ISO8601 string
+ * @param date - ISO8601 date string
+ * @param ms - Milliseconds to add
+ * @returns Updated ISO8601 date string
+ */
+export function addMilliseconds(date, ms) {
+    const d = new Date(date);
+    d.setMilliseconds(d.getMilliseconds() + ms);
+    return d.toISOString();
+}
+/**
+ * Helper to serialize JSON for SQLite storage
+ * @param value - Value to serialize
+ * @returns JSON string or null
+ */
+export function toJSON(value) {
+    return value === null || value === undefined ? null : JSON.stringify(value);
+}
+/**
+ * Helper to deserialize JSON from SQLite storage
+ * @param value - JSON string or null
+ * @returns Parsed value
+ */
+export function fromJSON(value) {
+    return value === null ? null : JSON.parse(value);
+}
+/**
+ * Helper to convert Date to ISO8601 string for SQLite
+ * @param date - Date or null
+ * @returns ISO8601 date string or null
+ */
+export function toISO(date) {
+    return date ? date.toISOString() : null;
+}
+/**
+ * Helper to convert ISO8601 string from SQLite to Date
+ * @param dateStr - ISO8601 date string or null
+ * @returns Date or null
+ */
+export function fromISO(dateStr) {
+    return dateStr ? new Date(dateStr) : null;
+}
+//# sourceMappingURL=sqlite.js.map

package/dist/sqlite/sqlite.js.map

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

package/dist/testing/backend.testsuite.d.ts

@@ -0,0 +1,20 @@
+import type { Backend } from "openworkflow/internal";
+/**
+ * Options for the Backend test suite.
+ */
+export interface TestBackendOptions {
+    /**
+     * Creates a new isolated Backend instance.
+     */
+    setup: () => Promise<Backend>;
+    /**
+     * Cleans up a Backend instance.
+     */
+    teardown: (backend: Backend) => Promise<void>;
+}
+/**
+ * Runs the Backend test suite.
+ * @param options - Test suite options
+ */
+export declare function testBackend(options: TestBackendOptions): void;
+//# sourceMappingURL=backend.testsuite.d.ts.map

package/dist/testing/backend.testsuite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.testsuite.d.ts","sourceRoot":"","sources":["../../testing/backend.testsuite.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAA4B,MAAM,uBAAuB,CAAC;AAG/E;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B;;OAEG;IACH,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CA8sC7D"}

package/dist/{core → testing}/backend.testsuite.js

@@ -2,10 +2,7 @@ import { randomUUID } from "node:crypto";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 /**
  * Runs the Backend test suite.
- *
- * This function wraps all the tests that verify a Backend implementation
- * conforms to the Backend interface contract. It uses the setup function to
- * create backend instances and the teardown function to clean them up.
+ * @param options - Test suite options
  */
 export function testBackend(options) {
     const { setup, teardown } = options;
@@ -90,7 +87,8 @@ export function testBackend(options) {
                 await sleep(10); // ensure timestamp difference
                 const second = await createPendingWorkflowRun(backend);
                 const listed = await backend.listWorkflowRuns({});
-                expect(listed.data.map((run) => run.id)).toEqual([first.id, second.id]);
+                const listedIds = listed.data.map((run) => run.id);
+                expect(listedIds).toEqual([first.id, second.id]);
                 await teardown(backend);
             });
             test("paginates workflow runs", async () => {
@@ -146,6 +144,47 @@ export function testBackend(options) {
                 expect(listed.pagination.prev).toBeNull();
                 await teardown(backend);
             });
+            test("paginates correctly with id as tiebreaker when multiple items have the same created_at timestamp", async () => {
+                const backend = await setup();
+                const runs = [];
+                for (let i = 0; i < 5; i++) {
+                    runs.push(await createPendingWorkflowRun(backend));
+                }
+                runs.sort((a, b) => {
+                    const timeDiff = a.createdAt.getTime() - b.createdAt.getTime();
+                    if (timeDiff !== 0)
+                        return timeDiff;
+                    return a.id.localeCompare(b.id);
+                });
+                const page1 = await backend.listWorkflowRuns({ limit: 2 });
+                expect(page1.data).toHaveLength(2);
+                expect(page1.data[0]?.id).toBe(runs[0]?.id);
+                expect(page1.data[1]?.id).toBe(runs[1]?.id);
+                expect(page1.pagination.next).not.toBeNull();
+                const page2 = await backend.listWorkflowRuns({
+                    limit: 2,
+                    after: page1.pagination.next, // eslint-disable-line @typescript-eslint/no-non-null-assertion
+                });
+                expect(page2.data).toHaveLength(2);
+                expect(page2.data[0]?.id).toBe(runs[2]?.id);
+                expect(page2.data[1]?.id).toBe(runs[3]?.id);
+                expect(page2.pagination.next).not.toBeNull();
+                const page3 = await backend.listWorkflowRuns({
+                    limit: 2,
+                    after: page2.pagination.next, // eslint-disable-line @typescript-eslint/no-non-null-assertion
+                });
+                expect(page3.data).toHaveLength(1);
+                expect(page3.data[0]?.id).toBe(runs[4]?.id);
+                expect(page3.pagination.next).toBeNull();
+                const page2Back = await backend.listWorkflowRuns({
+                    limit: 2,
+                    before: page3.pagination.prev, // eslint-disable-line @typescript-eslint/no-non-null-assertion
+                });
+                expect(page2Back.data).toHaveLength(2);
+                expect(page2Back.data[0]?.id).toBe(runs[2]?.id);
+                expect(page2Back.data[1]?.id).toBe(runs[3]?.id);
+                await teardown(backend);
+            });
         });
         describe("claimWorkflowRun()", () => {
             // because claims involve timing and leases, we create and teardown a new
@@ -169,7 +208,7 @@ export function testBackend(options) {
                     leaseDurationMs: 10,
                 });
                 expect(blocked).toBeNull();
-                await sleep(firstLeaseMs);
+                await sleep(firstLeaseMs + 5); // small buffer for timing variability
                 const reclaimed = await backend.claimWorkflowRun({
                     workerId: secondWorker,
                     leaseDurationMs: 10,
@@ -278,7 +317,7 @@ export function testBackend(options) {
                 await backend.failWorkflowRun({
                     workflowRunId: claimed.id,
                     workerId: claimed.workerId ?? "",
-                    error: null,
+                    error: { message: "failed" },
                 });
                 await expect(backend.sleepWorkflowRun({
                     workflowRunId: claimed.id,
@@ -344,6 +383,7 @@ export function testBackend(options) {
                 expect(failed.output).toBeNull();
                 expect(failed.finishedAt).toBeNull();
                 expect(failed.workerId).toBeNull();
+                expect(failed.startedAt).toBeNull(); // cleared on failure for retry
                 expect(failed.availableAt).not.toBeNull();
                 if (!failed.availableAt)
                     throw new Error("Expected availableAt");
@@ -351,7 +391,7 @@ export function testBackend(options) {
                 expect(delayMs).toBeGreaterThanOrEqual(900); // ~1s with some tolerance
                 expect(delayMs).toBeLessThan(1500);
             });
-            test("reschedules with increasing backoff on multiple failures (known slow test)", async () => {
+            test("reschedules with increasing backoff on multiple failures", async () => {
                 // this test needs isolated namespace
                 const backend = await setup();
                 await createPendingWorkflowRun(backend);
@@ -470,6 +510,7 @@ export function testBackend(options) {
                     workerId: claimed.workerId, // eslint-disable-line @typescript-eslint/no-non-null-assertion,
                     output: { ok: true },
                 });
+                await sleep(10); // ensure timestamp difference
                 const second = await backend.createStepAttempt({
                     workflowRunId: claimed.id,
                     workerId: claimed.workerId, // eslint-disable-line @typescript-eslint/no-non-null-assertion
@@ -481,10 +522,8 @@ export function testBackend(options) {
                 const listed = await backend.listStepAttempts({
                     workflowRunId: claimed.id,
                 });
-                expect(listed.data.map((step) => step.stepName)).toEqual([
-                    first.stepName,
-                    second.stepName,
-                ]);
+                const listedStepNames = listed.data.map((step) => step.stepName);
+                expect(listedStepNames).toEqual([first.stepName, second.stepName]);
             });
             test("paginates step attempts", async () => {
                 const claimed = await createClaimedWorkflowRun(backend);
@@ -570,23 +609,6 @@ export function testBackend(options) {
                 expect(listed.pagination.prev).toBeNull();
             });
         });
-        describe("getStepAttempt() duplicate", () => {
-            test("returns a persisted step attempt", async () => {
-                const claimed = await createClaimedWorkflowRun(backend);
-                const created = await backend.createStepAttempt({
-                    workflowRunId: claimed.id,
-                    workerId: claimed.workerId, // eslint-disable-line @typescript-eslint/no-non-null-assertion
-                    stepName: randomUUID(),
-                    kind: "function",
-                    config: {},
-                    context: null,
-                });
-                const got = await backend.getStepAttempt({
-                    stepAttemptId: created.id,
-                });
-                expect(got).toEqual(created);
-            });
-        });
         describe("completeStepAttempt()", () => {
             test("marks running step attempts as completed", async () => {
                 const claimed = await createClaimedWorkflowRun(backend);
@@ -617,6 +639,50 @@ export function testBackend(options) {
                 expect(fetched?.error).toBeNull();
                 expect(fetched?.finishedAt).not.toBeNull();
             });
+            test("throws when workflow is not running", async () => {
+                const backend = await setup();
+                await createPendingWorkflowRun(backend);
+                // create a step attempt by first claiming the workflow
+                const claimed = await backend.claimWorkflowRun({
+                    workerId: randomUUID(),
+                    leaseDurationMs: 100,
+                });
+                if (!claimed)
+                    throw new Error("Failed to claim workflow run");
+                const stepAttempt = await backend.createStepAttempt({
+                    workflowRunId: claimed.id,
+                    workerId: claimed.workerId, // eslint-disable-line @typescript-eslint/no-non-null-assertion
+                    stepName: randomUUID(),
+                    kind: "function",
+                    config: {},
+                    context: null,
+                });
+                // complete the workflow so it's no longer running
+                await backend.completeWorkflowRun({
+                    workflowRunId: claimed.id,
+                    workerId: claimed.workerId, // eslint-disable-line @typescript-eslint/no-non-null-assertion
+                    output: null,
+                });
+                // try to complete the step attempt
+                await expect(backend.completeStepAttempt({
+                    workflowRunId: claimed.id,
+                    stepAttemptId: stepAttempt.id,
+                    workerId: claimed.workerId, // eslint-disable-line @typescript-eslint/no-non-null-assertion
+                    output: { foo: "bar" },
+                })).rejects.toThrow("Failed to mark step attempt completed");
+                await teardown(backend);
+            });
+            test("throws when step attempt does not exist", async () => {
+                const backend = await setup();
+                const claimed = await createClaimedWorkflowRun(backend);
+                await expect(backend.completeStepAttempt({
+                    workflowRunId: claimed.id,
+                    stepAttemptId: randomUUID(),
+                    workerId: claimed.workerId, // eslint-disable-line @typescript-eslint/no-non-null-assertion
+                    output: { foo: "bar" },
+                })).rejects.toThrow("Failed to mark step attempt completed");
+                await teardown(backend);
+            });
         });
         describe("failStepAttempt()", () => {
             test("marks running step attempts as failed", async () => {
@@ -648,6 +714,50 @@ export function testBackend(options) {
                 expect(fetched?.output).toBeNull();
                 expect(fetched?.finishedAt).not.toBeNull();
             });
+            test("throws when workflow is not running", async () => {
+                const backend = await setup();
+                await createPendingWorkflowRun(backend);
+                // create a step attempt by first claiming the workflow
+                const claimed = await backend.claimWorkflowRun({
+                    workerId: randomUUID(),
+                    leaseDurationMs: 100,
+                });
+                if (!claimed)
+                    throw new Error("Failed to claim workflow run");
+                const stepAttempt = await backend.createStepAttempt({
+                    workflowRunId: claimed.id,
+                    workerId: claimed.workerId, // eslint-disable-line @typescript-eslint/no-non-null-assertion
+                    stepName: randomUUID(),
+                    kind: "function",
+                    config: {},
+                    context: null,
+                });
+                // complete the workflow so it's no longer running
+                await backend.completeWorkflowRun({
+                    workflowRunId: claimed.id,
+                    workerId: claimed.workerId, // eslint-disable-line @typescript-eslint/no-non-null-assertion
+                    output: null,
+                });
+                // try to fail the step attempt
+                await expect(backend.failStepAttempt({
+                    workflowRunId: claimed.id,
+                    stepAttemptId: stepAttempt.id,
+                    workerId: claimed.workerId, // eslint-disable-line @typescript-eslint/no-non-null-assertion
+                    error: { message: "nope" },
+                })).rejects.toThrow("Failed to mark step attempt failed");
+                await teardown(backend);
+            });
+            test("throws when step attempt does not exist", async () => {
+                const backend = await setup();
+                const claimed = await createClaimedWorkflowRun(backend);
+                await expect(backend.failStepAttempt({
+                    workflowRunId: claimed.id,
+                    stepAttemptId: randomUUID(),
+                    workerId: claimed.workerId, // eslint-disable-line @typescript-eslint/no-non-null-assertion
+                    error: { message: "nope" },
+                })).rejects.toThrow("Failed to mark step attempt failed");
+                await teardown(backend);
+            });
         });
         describe("deadline_at", () => {
             test("creates a workflow run with a deadline", async () => {
@@ -744,6 +854,7 @@ export function testBackend(options) {
                 expect(failed.status).toBe("failed");
                 expect(failed.availableAt).toBeNull();
                 expect(failed.finishedAt).not.toBeNull();
+                expect(failed.startedAt).toBeNull(); // cleared on permanent failure
                 await teardown(backend);
             });
             test("reschedules failed workflow runs if retry would complete before deadline", async () => {
@@ -916,42 +1027,64 @@ export function testBackend(options) {
                 await teardown(backend);
             });
         });
-        // Helper function for creating workflow runs that uses the shared backend
-        async function createPendingWorkflowRun(b) {
-            return await b.createWorkflowRun({
-                workflowName: randomUUID(),
-                version: null,
-                idempotencyKey: null,
-                input: null,
-                config: {},
-                context: null,
-                availableAt: null,
-                deadlineAt: null,
-            });
-        }
-        async function createClaimedWorkflowRun(b) {
-            await createPendingWorkflowRun(b);
-            const claimed = await b.claimWorkflowRun({
-                workerId: randomUUID(),
-                leaseDurationMs: 100,
-            });
-            if (!claimed)
-                throw new Error("Failed to claim workflow run");
-            return claimed;
-        }
     });
 }
-// Helper functions
+/**
+ * Create a pending workflow run for tests.
+ * @param b - Backend
+ * @returns Created workflow run
+ */
+async function createPendingWorkflowRun(b) {
+    return await b.createWorkflowRun({
+        workflowName: randomUUID(),
+        version: null,
+        idempotencyKey: null,
+        input: null,
+        config: {},
+        context: null,
+        availableAt: null,
+        deadlineAt: null,
+    });
+}
+/**
+ * Create and claim a workflow run for tests.
+ * @param b - Backend
+ * @returns Claimed workflow run
+ */
+async function createClaimedWorkflowRun(b) {
+    await createPendingWorkflowRun(b);
+    const claimed = await b.claimWorkflowRun({
+        workerId: randomUUID(),
+        leaseDurationMs: 100,
+    });
+    if (!claimed)
+        throw new Error("Failed to claim workflow run");
+    return claimed;
+}
+/**
+ * Get delta in seconds from now.
+ * @param date - Date to compare
+ * @returns Delta in seconds
+ */
 function deltaSeconds(date) {
     if (!date)
         return Infinity;
     return Math.abs((Date.now() - date.getTime()) / 1000);
 }
+/**
+ * Create a Date one year in the future.
+ * @returns Future Date
+ */
 function newDateInOneYear() {
     const d = new Date();
     d.setFullYear(d.getFullYear() + 1);
     return d;
 }
+/**
+ * Sleep for a given duration.
+ * @param ms - Milliseconds to sleep
+ * @returns Promise resolved after sleeping
+ */
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }