@absurd-sqlite/sdk 0.2.0-alpha.0

package/test/hooks.test.ts

@@ -0,0 +1,347 @@
+import { describe, test, expect, beforeAll, afterEach } from "vitest";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createTestAbsurd, randomName, type TestContext } from "./setup.js";
+import { type Absurd, type SpawnOptions } from "../src/index.js";
+
+describe("Hooks", () => {
+  let ctx: TestContext;
+  let queueName: string;
+
+  beforeAll(async () => {
+    ctx = await createTestAbsurd(randomName("hooks_queue"));
+    queueName = ctx.queueName;
+  });
+
+  afterEach(async () => {
+    await ctx.cleanupTasks();
+    await ctx.setFakeNow(null);
+  });
+
+  describe("beforeSpawn hook", () => {
+    test("can inject headers before spawn", async () => {
+      const injectedHeaders: SpawnOptions["headers"][] = [];
+
+      const absurd = ctx.createClient({
+        queueName,
+        hooks: {
+          beforeSpawn: (_taskName, _params, options) => {
+            return {
+              ...options,
+              headers: {
+                ...options.headers,
+                traceId: "trace-123",
+                correlationId: "corr-456",
+              },
+            };
+          },
+        },
+      });
+
+      let capturedHeaders: any = null;
+      absurd.registerTask({ name: "capture-headers" }, async (_params, ctx) => {
+        capturedHeaders = ctx.headers;
+        return "done";
+      });
+
+      await absurd.spawn("capture-headers", { test: true });
+      await absurd.workBatch("worker1", 60, 1);
+
+      expect(capturedHeaders).toEqual({
+        traceId: "trace-123",
+        correlationId: "corr-456",
+      });
+    });
+
+    test("can use async beforeSpawn hook", async () => {
+      const absurd = ctx.createClient({
+        queueName,
+        hooks: {
+          beforeSpawn: async (_taskName, _params, options) => {
+            // Simulate async operation (e.g., fetching context)
+            await new Promise((resolve) => setTimeout(resolve, 10));
+            return {
+              ...options,
+              headers: {
+                ...options.headers,
+                asyncHeader: "fetched-value",
+              },
+            };
+          },
+        },
+      });
+
+      let capturedHeader: any = null;
+      absurd.registerTask({ name: "async-header" }, async (_params, ctx) => {
+        capturedHeader = ctx.headers["asyncHeader"];
+        return "done";
+      });
+
+      await absurd.spawn("async-header", {});
+      await absurd.workBatch("worker1", 60, 1);
+
+      expect(capturedHeader).toBe("fetched-value");
+    });
+
+    test("preserves existing headers when adding new ones", async () => {
+      const absurd = ctx.createClient({
+        queueName,
+        hooks: {
+          beforeSpawn: (_taskName, _params, options) => {
+            return {
+              ...options,
+              headers: {
+                ...options.headers,
+                injected: "by-hook",
+              },
+            };
+          },
+        },
+      });
+
+      let capturedHeaders: any = null;
+      absurd.registerTask({ name: "merge-headers" }, async (_params, ctx) => {
+        capturedHeaders = ctx.headers;
+        return "done";
+      });
+
+      await absurd.spawn(
+        "merge-headers",
+        {},
+        {
+          headers: { existing: "user-provided" },
+        }
+      );
+      await absurd.workBatch("worker1", 60, 1);
+
+      expect(capturedHeaders).toEqual({
+        existing: "user-provided",
+        injected: "by-hook",
+      });
+    });
+  });
+
+  describe("wrapTaskExecution hook", () => {
+    test("wraps task execution", async () => {
+      const executionOrder: string[] = [];
+
+      const absurd = ctx.createClient({
+        queueName,
+        hooks: {
+          wrapTaskExecution: async (_ctx, execute) => {
+            executionOrder.push("before");
+            const result = await execute();
+            executionOrder.push("after");
+            return result;
+          },
+        },
+      });
+
+      absurd.registerTask({ name: "wrapped-task" }, async () => {
+        executionOrder.push("handler");
+        return "done";
+      });
+
+      await absurd.spawn("wrapped-task", {});
+      await absurd.workBatch("worker1", 60, 1);
+
+      expect(executionOrder).toEqual(["before", "handler", "after"]);
+    });
+
+    test("provides TaskContext to wrapper", async () => {
+      let capturedTaskId: string | null = null;
+      let capturedHeaders: any = null;
+
+      const absurd = ctx.createClient({
+        queueName,
+        hooks: {
+          beforeSpawn: (_taskName, _params, options) => ({
+            ...options,
+            headers: { traceId: "from-spawn" },
+          }),
+          wrapTaskExecution: async (ctx, execute) => {
+            capturedTaskId = ctx.taskID;
+            capturedHeaders = ctx.headers;
+            return execute();
+          },
+        },
+      });
+
+      absurd.registerTask({ name: "ctx-in-wrapper" }, async () => "done");
+
+      const { taskID } = await absurd.spawn("ctx-in-wrapper", {});
+      await absurd.workBatch("worker1", 60, 1);
+
+      expect(capturedTaskId).toBe(taskID);
+      expect(capturedHeaders).toEqual({ traceId: "from-spawn" });
+    });
+  });
+
+  describe("AsyncLocalStorage integration", () => {
+    test("full round-trip: inject context on spawn, restore on execution", async () => {
+      interface TraceContext {
+        traceId: string;
+        spanId: string;
+      }
+      const als = new AsyncLocalStorage<TraceContext>();
+
+      const absurd = ctx.createClient({
+        queueName,
+        hooks: {
+          beforeSpawn: (_taskName, _params, options) => {
+            const store = als.getStore();
+            if (store) {
+              return {
+                ...options,
+                headers: {
+                  ...options.headers,
+                  traceId: store.traceId,
+                  spanId: store.spanId,
+                },
+              };
+            }
+            return options;
+          },
+          wrapTaskExecution: async (ctx, execute) => {
+            const traceId = ctx.headers["traceId"] as string | undefined;
+            const spanId = ctx.headers["spanId"] as string | undefined;
+            if (traceId && spanId) {
+              return als.run({ traceId, spanId }, execute);
+            }
+            return execute();
+          },
+        },
+      });
+
+      let capturedInHandler: TraceContext | undefined;
+      absurd.registerTask({ name: "als-test" }, async () => {
+        capturedInHandler = als.getStore();
+        return "done";
+      });
+
+      // Spawn within an ALS context
+      await als.run({ traceId: "trace-abc", spanId: "span-xyz" }, async () => {
+        await absurd.spawn("als-test", {});
+      });
+
+      // Execute the task (outside original ALS context)
+      await absurd.workBatch("worker1", 60, 1);
+
+      // Handler should have received the context via wrapTaskExecution
+      expect(capturedInHandler).toEqual({
+        traceId: "trace-abc",
+        spanId: "span-xyz",
+      });
+    });
+
+    test("child spawns inherit context from parent task", async () => {
+      interface TraceContext {
+        traceId: string;
+      }
+      const als = new AsyncLocalStorage<TraceContext>();
+
+      const absurd = ctx.createClient({
+        queueName,
+        hooks: {
+          beforeSpawn: (_taskName, _params, options) => {
+            const store = als.getStore();
+            if (store) {
+              return {
+                ...options,
+                headers: {
+                  ...options.headers,
+                  traceId: store.traceId,
+                },
+              };
+            }
+            return options;
+          },
+          wrapTaskExecution: async (ctx, execute) => {
+            const traceId = ctx.headers["traceId"] as string | undefined;
+            if (traceId) {
+              return als.run({ traceId }, execute);
+            }
+            return execute();
+          },
+        },
+      });
+
+      let childTraceId: string | undefined;
+
+      absurd.registerTask({ name: "parent-task" }, async (_params, _ctx) => {
+        // Spawn child task - should inherit trace context via beforeSpawn hook
+        await absurd.spawn("child-task", {});
+        return "parent-done";
+      });
+
+      absurd.registerTask({ name: "child-task" }, async (_params, ctx) => {
+        childTraceId = ctx.headers["traceId"] as string | undefined;
+        return "child-done";
+      });
+
+      // Spawn parent within ALS context
+      await als.run({ traceId: "parent-trace" }, async () => {
+        await absurd.spawn("parent-task", {});
+      });
+
+      // Execute parent task
+      await absurd.workBatch("worker1", 60, 1);
+      // Execute child task
+      await absurd.workBatch("worker1", 60, 1);
+
+      expect(childTraceId).toBe("parent-trace");
+    });
+  });
+
+  describe("TaskContext header accessors", () => {
+    test("headers returns undefined for missing key", async () => {
+      const absurd = ctx.createClient({ queueName });
+
+      let result: any;
+      absurd.registerTask({ name: "no-headers" }, async (_params, ctx) => {
+        result = ctx.headers["nonexistent"];
+        return "done";
+      });
+
+      await absurd.spawn("no-headers", {});
+      await absurd.workBatch("worker1", 60, 1);
+
+      expect(result).toBeUndefined();
+    });
+
+    test("headers getter returns empty object when no headers set", async () => {
+      const absurd = ctx.createClient({ queueName });
+
+      let result: any;
+      absurd.registerTask({ name: "empty-headers" }, async (_params, ctx) => {
+        result = ctx.headers;
+        return "done";
+      });
+
+      await absurd.spawn("empty-headers", {});
+      await absurd.workBatch("worker1", 60, 1);
+
+      expect(result).toEqual({});
+    });
+
+    test("headers getter returns all headers", async () => {
+      const absurd = ctx.createClient({ queueName });
+
+      let result: any;
+      absurd.registerTask({ name: "all-headers" }, async (_params, ctx) => {
+        result = ctx.headers;
+        return "done";
+      });
+
+      await absurd.spawn(
+        "all-headers",
+        {},
+        {
+          headers: { a: 1, b: "two", c: true },
+        }
+      );
+      await absurd.workBatch("worker1", 60, 1);
+
+      expect(result).toEqual({ a: 1, b: "two", c: true });
+    });
+  });
+});

package/test/idempotent.test.ts

@@ -0,0 +1,195 @@
+import { describe, test, expect, beforeAll, afterEach } from "vitest";
+import { createTestAbsurd, randomName, type TestContext } from "./setup.js";
+import type { Absurd } from "../src/index.js";
+
+describe("Idempotent Task Spawning", () => {
+  let ctx: TestContext;
+  let absurd: Absurd;
+
+  beforeAll(async () => {
+    ctx = await createTestAbsurd(randomName("idempotent"));
+    absurd = ctx.absurd;
+  });
+
+  afterEach(async () => {
+    await ctx.cleanupTasks();
+    await ctx.setFakeNow(null);
+  });
+
+  describe("spawn with idempotencyKey", () => {
+    test("creates task when idempotencyKey is new", async () => {
+      absurd.registerTask({ name: "idempotent-task" }, async () => {
+        return { done: true };
+      });
+
+      const result = await absurd.spawn(
+        "idempotent-task",
+        { value: 42 },
+        { idempotencyKey: "unique-key-1" },
+      );
+
+      expect(result.taskID).toBeDefined();
+      expect(result.runID).toBeDefined();
+      expect(result.attempt).toBe(1);
+      expect(Boolean(result.created)).toBe(true);
+
+      const task = await ctx.getTask(result.taskID);
+      expect(task).toBeDefined();
+      expect(task?.state).toBe("pending");
+    });
+
+    test("returns existing task when idempotencyKey already exists", async () => {
+      absurd.registerTask({ name: "dup-task" }, async () => {
+        return { done: true };
+      });
+
+      const first = await absurd.spawn(
+        "dup-task",
+        { value: 1 },
+        { idempotencyKey: "dup-key" },
+      );
+
+      expect(first.taskID).toBeDefined();
+      expect(first.runID).toBeDefined();
+      expect(first.attempt).toBe(1);
+      expect(Boolean(first.created)).toBe(true);
+
+      const second = await absurd.spawn(
+        "dup-task",
+        { value: 2 },
+        { idempotencyKey: "dup-key" },
+      );
+
+      expect(second.taskID).toBe(first.taskID);
+      expect(second.runID).toBe(first.runID);
+      expect(second.attempt).toBe(first.attempt);
+      expect(Boolean(second.created)).toBe(false);
+    });
+
+    test("spawn without idempotencyKey always creates new task", async () => {
+      absurd.registerTask({ name: "no-idem-task" }, async () => {
+        return { done: true };
+      });
+
+      const first = await absurd.spawn("no-idem-task", { value: 1 });
+      const second = await absurd.spawn("no-idem-task", { value: 2 });
+
+      expect(first.taskID).not.toBe(second.taskID);
+      expect(first.runID).toBeDefined();
+      expect(second.runID).toBeDefined();
+      expect(Boolean(first.created)).toBe(true);
+      expect(Boolean(second.created)).toBe(true);
+    });
+
+    test("different idempotencyKeys create separate tasks", async () => {
+      absurd.registerTask({ name: "diff-keys-task" }, async () => {
+        return { done: true };
+      });
+
+      const first = await absurd.spawn(
+        "diff-keys-task",
+        { value: 1 },
+        { idempotencyKey: "key-a" },
+      );
+      const second = await absurd.spawn(
+        "diff-keys-task",
+        { value: 2 },
+        { idempotencyKey: "key-b" },
+      );
+
+      expect(first.taskID).not.toBe(second.taskID);
+      expect(first.runID).toBeDefined();
+      expect(second.runID).toBeDefined();
+      expect(Boolean(first.created)).toBe(true);
+      expect(Boolean(second.created)).toBe(true);
+    });
+
+    test("idempotencyKey persists after task completes", async () => {
+      absurd.registerTask({ name: "complete-idem-task" }, async () => {
+        return { result: "done" };
+      });
+
+      const first = await absurd.spawn(
+        "complete-idem-task",
+        { value: 1 },
+        { idempotencyKey: "complete-key" },
+      );
+
+      await absurd.workBatch("test-worker", 60, 1);
+
+      const task = await ctx.getTask(first.taskID);
+      expect(task?.state).toBe("completed");
+
+      const second = await absurd.spawn(
+        "complete-idem-task",
+        { value: 2 },
+        { idempotencyKey: "complete-key" },
+      );
+
+      expect(second.taskID).toBe(first.taskID);
+      expect(second.runID).toBe(first.runID);
+      expect(second.attempt).toBe(first.attempt);
+      expect(Boolean(second.created)).toBe(false);
+    });
+
+    test("idempotencyKey is scoped to queue", async () => {
+      const otherQueueName = randomName("other_queue");
+      await absurd.createQueue(otherQueueName);
+
+      absurd.registerTask(
+        { name: "queue-scoped-task", queue: ctx.queueName },
+        async () => ({ done: true }),
+      );
+      absurd.registerTask(
+        { name: "queue-scoped-task-other", queue: otherQueueName },
+        async () => ({ done: true }),
+      );
+
+      const first = await absurd.spawn(
+        "queue-scoped-task",
+        { value: 1 },
+        { idempotencyKey: "scoped-key" },
+      );
+
+      const second = await absurd.spawn(
+        "queue-scoped-task-other",
+        { value: 2 },
+        { idempotencyKey: "scoped-key" },
+      );
+
+      expect(first.taskID).not.toBe(second.taskID);
+      expect(Boolean(first.created)).toBe(true);
+      expect(Boolean(second.created)).toBe(true);
+
+      await absurd.dropQueue(otherQueueName);
+    });
+
+    test("idempotent spawn can be used for fire-and-forget patterns", async () => {
+      let execCount = 0;
+      absurd.registerTask({ name: "fire-forget-task" }, async () => {
+        execCount++;
+        return { done: true };
+      });
+
+      await absurd.spawn(
+        "fire-forget-task",
+        {},
+        { idempotencyKey: "daily-report:2025-01-15" },
+      );
+      await absurd.spawn(
+        "fire-forget-task",
+        {},
+        { idempotencyKey: "daily-report:2025-01-15" },
+      );
+      await absurd.spawn(
+        "fire-forget-task",
+        {},
+        { idempotencyKey: "daily-report:2025-01-15" },
+      );
+
+      await absurd.workBatch("test-worker", 60, 10);
+
+      expect(execCount).toBe(1);
+    });
+  });
+});

package/test/index.test.ts

@@ -0,0 +1,92 @@
+import sqlite from "better-sqlite3";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { Absurd, SQLiteDatabase } from "../src/index";
+
+const testDir = fileURLToPath(new URL(".", import.meta.url));
+const repoRoot = join(testDir, "../../..");
+const extensionBase = join(repoRoot, "target/release/libabsurd");
+
+function resolveExtensionPath(base: string): string {
+  const platformExt =
+    process.platform === "win32"
+      ? ".dll"
+      : process.platform === "darwin"
+      ? ".dylib"
+      : ".so";
+  const candidates = [base, `${base}${platformExt}`];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  throw new Error(
+    `SQLite extension not found at ${base} (expected ${platformExt})`
+  );
+}
+
+const extensionPath = resolveExtensionPath(extensionBase);
+
+let tempDir: string | null = null;
+
+function createDatabaseWithMigrations(): string {
+  tempDir = mkdtempSync(join(tmpdir(), "absurd-sqlite-"));
+  const dbPath = join(tempDir, "absurd.db");
+  const db = new sqlite(dbPath);
+  db.loadExtension(extensionPath);
+  db.prepare("select absurd_apply_migrations()").get();
+  db.close();
+  return dbPath;
+}
+
+afterEach(() => {
+  if (tempDir) {
+    rmSync(tempDir, { recursive: true, force: true });
+    tempDir = null;
+  }
+});
+
+describe("Absurd", () => {
+  it("creates and lists queues using the sqlite extension", async () => {
+    const dbPath = createDatabaseWithMigrations();
+    const db = new sqlite(dbPath) as unknown as SQLiteDatabase;
+    const absurd = new Absurd(db, extensionPath);
+
+    await absurd.createQueue("alpha");
+    await absurd.createQueue("beta");
+
+    const queues = await absurd.listQueues();
+    expect(queues).toContain("alpha");
+    expect(queues).toContain("beta");
+
+    await absurd.dropQueue("alpha");
+    const remaining = await absurd.listQueues();
+    expect(remaining).not.toContain("alpha");
+
+    const db2 = new sqlite(dbPath);
+    const { count } = db2
+      .prepare("select count(*) as count from absurd_queues")
+      .get() as { count: number };
+    expect(count).toBe(1);
+    db.close();
+
+    await absurd.close();
+  });
+
+  it("closes the sqlite database on close()", async () => {
+    const dbPath = createDatabaseWithMigrations();
+    const db = new sqlite(dbPath) as unknown as SQLiteDatabase;
+    const absurd = new Absurd(db, extensionPath);
+
+    await absurd.close();
+
+    const db2 = new sqlite(dbPath);
+    const { ok } = db2.prepare("select 1 as ok").get() as { ok: number };
+    expect(ok).toBe(1);
+    db.close();
+  });
+});