@drej/sqlite 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @drej/sqlite
 
+## 0.2.0
+
+### Minor Changes
+
+- 2fd33e0: feat: run management API
+
+  Add `RunStatus` enum, `RunDetails` type, and `ListRunsOptions` for filtering. Replace `listRuns()` with `listRunDetails()`, `listAllRunDetails()`, `getRunDetails()`, and `deleteRun()` on both `IStorageAdapter` and `DrejClient`. Add `WorkflowRun.status` property that tracks execution state as events are consumed.
+
+### Patch Changes
+
+- Updated dependencies [22b8a32]
+- Updated dependencies [799b6dd]
+- Updated dependencies [8d9d8bb]
+- Updated dependencies [2fd33e0]
+- Updated dependencies [0d94c2a]
+  - @drej/core@0.3.0
+
 ## 0.1.2
 
 ### Patch Changes

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "@drej/sqlite",
-  "version": "0.1.2",
-  "publishConfig": { "access": "public" },
+  "version": "0.2.0",
+  "publishConfig": {
+    "access": "public"
+  },
   "main": "./src/index.ts",
   "dependencies": {
     "@drej/core": "workspace:*"
   },
+  "scripts": {
+    "test": "bun test"
+  },
   "devDependencies": {
-    "bun-types": "latest",
-    "typescript": "latest"
+    "bun-types": "1.3.14",
+    "typescript": "6.0.3"
   }
 }

package/src/adapter.ts

@@ -1,5 +1,6 @@
 import { Database } from "bun:sqlite";
-import type { IStorageAdapter, LedgerEntry, LedgerEvent } from "@drej/core";
+import type { IStorageAdapter, LedgerEntry, LedgerEvent, RunDetails, ListRunsOptions } from "@drej/core";
+import { RunStatus } from "@drej/core";
 import { MIGRATION_SQL } from "./migrations";
 
 type Row = {
@@ -13,6 +14,59 @@ type Row = {
   ts: number;
 };
 
+type AggRow = {
+  wf_name: string;
+  run_id: string;
+  started_at: number | null;
+  completed_at: number | null;
+  terminal_event: string | null;
+  error_msg: string | null;
+  step_count: number;
+};
+
+const AGG_SQL = (whereClause: string) => `
+  WITH agg AS (
+    SELECT
+      wf_name,
+      run_id,
+      MIN(CASE WHEN event = 'run_started' THEN ts END) AS started_at,
+      MAX(CASE WHEN event IN ('workflow_complete', 'workflow_failed') THEN ts END) AS completed_at,
+      MAX(CASE WHEN event IN ('workflow_complete', 'workflow_failed') THEN event END) AS terminal_event,
+      MAX(CASE WHEN event = 'workflow_failed' THEN error END) AS error_msg,
+      CAST(COUNT(CASE WHEN event = 'step_complete' THEN 1 END) AS INTEGER) AS step_count
+    FROM drej_events
+    ${whereClause}
+    GROUP BY wf_name, run_id
+  )
+  SELECT * FROM agg WHERE started_at IS NOT NULL ORDER BY started_at DESC
+`;
+
+function terminalToStatus(event: string | null): RunStatus {
+  if (event === "workflow_complete") return RunStatus.Completed;
+  if (event === "workflow_failed") return RunStatus.Failed;
+  return RunStatus.Running;
+}
+
+function aggRowToDetails(row: AggRow): RunDetails {
+  return {
+    workflowName: row.wf_name,
+    runId: row.run_id,
+    status: terminalToStatus(row.terminal_event),
+    startedAt: row.started_at!,
+    completedAt: row.completed_at ?? undefined,
+    stepCount: row.step_count,
+    error: row.error_msg ?? undefined,
+  };
+}
+
+function applyOpts(details: RunDetails[], opts?: ListRunsOptions): RunDetails[] {
+  let result = details;
+  if (opts?.before != null) result = result.filter((d) => d.startedAt < opts.before!);
+  if (opts?.status != null) result = result.filter((d) => d.status === opts.status);
+  if (opts?.limit != null) result = result.slice(0, opts.limit);
+  return result;
+}
+
 function rowToEntry(row: Row): LedgerEntry {
   return {
     runId: row.run_id,
@@ -86,12 +140,28 @@ export class SQLiteAdapter implements IStorageAdapter {
     return row ? rowToEntry(row) : null;
   }
 
-  async listRuns(workflowName: string): Promise<string[]> {
+  async listRunDetails(workflowName: string, opts?: ListRunsOptions): Promise<RunDetails[]> {
     const rows = this.db
-      .prepare<{ run_id: string }, [string]>(
-        `SELECT DISTINCT run_id FROM drej_events WHERE wf_name = ?`,
-      )
+      .prepare<AggRow, [string]>(AGG_SQL("WHERE wf_name = ?"))
       .all(workflowName);
-    return rows.map((r) => r.run_id);
+    return applyOpts(rows.map(aggRowToDetails), opts);
+  }
+
+  async listAllRunDetails(opts?: ListRunsOptions): Promise<RunDetails[]> {
+    const rows = this.db.prepare<AggRow, []>(AGG_SQL("")).all();
+    return applyOpts(rows.map(aggRowToDetails), opts);
+  }
+
+  async getRunDetails(workflowName: string, runId: string): Promise<RunDetails | null> {
+    const row = this.db
+      .prepare<AggRow, [string, string]>(AGG_SQL("WHERE wf_name = ? AND run_id = ?"))
+      .get(workflowName, runId);
+    return row ? aggRowToDetails(row) : null;
+  }
+
+  async deleteRun(workflowName: string, runId: string): Promise<void> {
+    this.db
+      .prepare<void, [string, string]>(`DELETE FROM drej_events WHERE wf_name = ? AND run_id = ?`)
+      .run(workflowName, runId);
   }
 }

package/test/adapter.test.ts

@@ -0,0 +1,189 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { LedgerEvent, RunStatus, type LedgerEntry } from "@drej/core";
+import { SQLiteAdapter } from "../src/adapter.ts";
+
+function entry(overrides?: Partial<LedgerEntry>): LedgerEntry {
+  return {
+    ts: Date.now(),
+    workflowName: "test-wf",
+    runId: "run-1",
+    stepIndex: 0,
+    event: LedgerEvent.StepStart,
+    ...overrides,
+  };
+}
+
+describe("SQLiteAdapter", () => {
+  let db: SQLiteAdapter;
+
+  beforeEach(async () => {
+    db = new SQLiteAdapter(":memory:");
+    await db.connect();
+  });
+
+  afterEach(async () => {
+    await db.close();
+  });
+
+  // ── append / readAll ────────────────────────────────────────────────────────
+
+  describe("append / readAll", () => {
+    it("stores and retrieves an entry", async () => {
+      await db.append(entry({ event: LedgerEvent.StepStart }));
+      const rows = await db.readAll("test-wf", "run-1");
+      expect(rows).toHaveLength(1);
+      expect(rows[0].event).toBe(LedgerEvent.StepStart);
+    });
+
+    it("returns entries in ascending timestamp order", async () => {
+      await db.append(entry({ ts: 2000, event: LedgerEvent.StepComplete }));
+      await db.append(entry({ ts: 1000, event: LedgerEvent.StepStart }));
+      const rows = await db.readAll("test-wf", "run-1");
+      expect(rows[0].ts).toBe(1000);
+      expect(rows[1].ts).toBe(2000);
+    });
+
+    it("scopes to the given workflow name and run id", async () => {
+      await db.append(entry({ workflowName: "wf-a", runId: "r1" }));
+      await db.append(entry({ workflowName: "wf-b", runId: "r2" }));
+      expect(await db.readAll("wf-a", "r1")).toHaveLength(1);
+      expect(await db.readAll("wf-b", "r2")).toHaveLength(1);
+      expect(await db.readAll("wf-a", "r2")).toHaveLength(0);
+    });
+
+    it("serialises and deserialises JSON payload", async () => {
+      await db.append(entry({ payload: { key: "value", n: 42 } }));
+      const rows = await db.readAll("test-wf", "run-1");
+      expect(rows[0].payload).toEqual({ key: "value", n: 42 });
+    });
+
+    it("preserves null payload as undefined", async () => {
+      await db.append(entry({ payload: undefined }));
+      const rows = await db.readAll("test-wf", "run-1");
+      expect(rows[0].payload).toBeUndefined();
+    });
+
+    it("preserves the branch field", async () => {
+      await db.append(entry({ branch: 2 }));
+      const rows = await db.readAll("test-wf", "run-1");
+      expect(rows[0].branch).toBe(2);
+    });
+
+    it("returns undefined branch when not set", async () => {
+      await db.append(entry());
+      const rows = await db.readAll("test-wf", "run-1");
+      expect(rows[0].branch).toBeUndefined();
+    });
+  });
+
+  // ── lastCheckpoint ──────────────────────────────────────────────────────────
+
+  describe("lastCheckpoint", () => {
+    it("returns null when no checkpoint exists", async () => {
+      expect(await db.lastCheckpoint("test-wf", "run-1")).toBeNull();
+    });
+
+    it("returns the most recent checkpoint", async () => {
+      await db.append(entry({ ts: 1000, event: LedgerEvent.Checkpoint, payload: { step: 1 } }));
+      await db.append(entry({ ts: 2000, event: LedgerEvent.Checkpoint, payload: { step: 2 } }));
+      const cp = await db.lastCheckpoint("test-wf", "run-1");
+      expect((cp!.payload as any).step).toBe(2);
+    });
+
+    it("ignores non-checkpoint events", async () => {
+      await db.append(entry({ event: LedgerEvent.StepStart }));
+      expect(await db.lastCheckpoint("test-wf", "run-1")).toBeNull();
+    });
+  });
+
+  // ── run details ─────────────────────────────────────────────────────────────
+
+  async function seedRun(wf: string, runId: string, terminal: LedgerEvent.WorkflowComplete | LedgerEvent.WorkflowFailed, error?: string) {
+    const ts = Date.now();
+    await db.append(entry({ workflowName: wf, runId, ts, stepIndex: -1, event: LedgerEvent.RunStarted }));
+    await db.append(entry({ workflowName: wf, runId, ts: ts + 1, stepIndex: 0, event: LedgerEvent.StepComplete }));
+    await db.append(entry({ workflowName: wf, runId, ts: ts + 2, stepIndex: -1, event: terminal, error }));
+  }
+
+  describe("getRunDetails", () => {
+    it("returns null for an unknown run", async () => {
+      expect(await db.getRunDetails("wf", "no-such-run")).toBeNull();
+    });
+
+    it("returns Completed status", async () => {
+      await seedRun("wf", "run-1", LedgerEvent.WorkflowComplete);
+      const d = await db.getRunDetails("wf", "run-1");
+      expect(d?.status).toBe(RunStatus.Completed);
+      expect(d?.stepCount).toBe(1);
+    });
+
+    it("returns Failed status with error message", async () => {
+      await seedRun("wf", "run-1", LedgerEvent.WorkflowFailed, "boom");
+      const d = await db.getRunDetails("wf", "run-1");
+      expect(d?.status).toBe(RunStatus.Failed);
+      expect(d?.error).toBe("boom");
+    });
+
+    it("returns Running when no terminal event present", async () => {
+      await db.append(entry({ stepIndex: -1, event: LedgerEvent.RunStarted }));
+      const d = await db.getRunDetails("test-wf", "run-1");
+      expect(d?.status).toBe(RunStatus.Running);
+    });
+  });
+
+  describe("listRunDetails", () => {
+    it("scopes to a single workflow", async () => {
+      await seedRun("wf-a", "r1", LedgerEvent.WorkflowComplete);
+      await seedRun("wf-b", "r2", LedgerEvent.WorkflowComplete);
+      const results = await db.listRunDetails("wf-a");
+      expect(results).toHaveLength(1);
+      expect(results[0].workflowName).toBe("wf-a");
+    });
+
+    it("filters by status", async () => {
+      await seedRun("wf", "r1", LedgerEvent.WorkflowComplete);
+      await seedRun("wf", "r2", LedgerEvent.WorkflowFailed);
+      const completed = await db.listRunDetails("wf", { status: RunStatus.Completed });
+      expect(completed).toHaveLength(1);
+      expect(completed[0].runId).toBe("r1");
+    });
+
+    it("respects the limit option", async () => {
+      await seedRun("wf", "r1", LedgerEvent.WorkflowComplete);
+      await seedRun("wf", "r2", LedgerEvent.WorkflowComplete);
+      expect(await db.listRunDetails("wf", { limit: 1 })).toHaveLength(1);
+    });
+  });
+
+  describe("listAllRunDetails", () => {
+    it("returns runs across all workflows", async () => {
+      await seedRun("wf-a", "r1", LedgerEvent.WorkflowComplete);
+      await seedRun("wf-b", "r2", LedgerEvent.WorkflowComplete);
+      expect(await db.listAllRunDetails()).toHaveLength(2);
+    });
+
+    it("filters by status across workflows", async () => {
+      await seedRun("wf-a", "r1", LedgerEvent.WorkflowComplete);
+      await seedRun("wf-b", "r2", LedgerEvent.WorkflowFailed);
+      const failed = await db.listAllRunDetails({ status: RunStatus.Failed });
+      expect(failed).toHaveLength(1);
+      expect(failed[0].workflowName).toBe("wf-b");
+    });
+  });
+
+  describe("deleteRun", () => {
+    it("removes all entries for the run", async () => {
+      await seedRun("wf", "run-1", LedgerEvent.WorkflowComplete);
+      await db.deleteRun("wf", "run-1");
+      expect(await db.readAll("wf", "run-1")).toHaveLength(0);
+      expect(await db.getRunDetails("wf", "run-1")).toBeNull();
+    });
+
+    it("does not affect other runs", async () => {
+      await seedRun("wf", "r1", LedgerEvent.WorkflowComplete);
+      await seedRun("wf", "r2", LedgerEvent.WorkflowComplete);
+      await db.deleteRun("wf", "r1");
+      expect(await db.getRunDetails("wf", "r2")).not.toBeNull();
+    });
+  });
+});