@multiplier-labs/stepflow 0.3.1

package/src/storage/memory.test.ts

@@ -0,0 +1,399 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { MemoryStorageAdapter } from "./memory";
+import type { WorkflowRunRecord, WorkflowRunStepRecord } from "./types";
+
+describe("MemoryStorageAdapter", () => {
+  let storage: MemoryStorageAdapter;
+
+  beforeEach(() => {
+    storage = new MemoryStorageAdapter();
+  });
+
+  describe("createRun / getRun", () => {
+    it("should create and retrieve a run", async () => {
+      const run = await storage.createRun({
+        kind: "test.workflow",
+        status: "queued",
+        input: { x: 1 },
+        metadata: { userId: "u1" },
+        context: {},
+      });
+
+      expect(run.id).toBeDefined();
+      expect(run.kind).toBe("test.workflow");
+      expect(run.createdAt).toBeInstanceOf(Date);
+
+      const fetched = await storage.getRun(run.id);
+      expect(fetched).toEqual(run);
+    });
+
+    it("should return null for non-existent run", async () => {
+      const run = await storage.getRun("nonexistent");
+      expect(run).toBeNull();
+    });
+  });
+
+  describe("updateRun", () => {
+    it("should update run fields", async () => {
+      const run = await storage.createRun({
+        kind: "test",
+        status: "queued",
+        input: {},
+        metadata: {},
+        context: {},
+      });
+
+      await storage.updateRun(run.id, {
+        status: "running",
+        startedAt: new Date(),
+      });
+
+      const updated = await storage.getRun(run.id);
+      expect(updated?.status).toBe("running");
+      expect(updated?.startedAt).toBeInstanceOf(Date);
+    });
+
+    it("should do nothing for non-existent run", async () => {
+      await expect(
+        storage.updateRun("nonexistent", { status: "failed" }),
+      ).resolves.not.toThrow();
+    });
+  });
+
+  describe("listRuns", () => {
+    beforeEach(async () => {
+      await storage.createRun({
+        kind: "a",
+        status: "queued",
+        input: {},
+        metadata: {},
+        context: {},
+      });
+      await storage.createRun({
+        kind: "a",
+        status: "running",
+        input: {},
+        metadata: {},
+        context: {},
+      });
+      await storage.createRun({
+        kind: "b",
+        status: "succeeded",
+        input: {},
+        metadata: {},
+        context: {},
+      });
+      await storage.createRun({
+        kind: "a",
+        status: "failed",
+        input: {},
+        metadata: {},
+        context: {},
+        parentRunId: "parent-1",
+      });
+    });
+
+    it("should list all runs with default pagination", async () => {
+      const result = await storage.listRuns();
+      expect(result.items).toHaveLength(4);
+      expect(result.total).toBe(4);
+    });
+
+    it("should filter by kind", async () => {
+      const result = await storage.listRuns({ kind: "a" });
+      expect(result.items).toHaveLength(3);
+      expect(result.items.every((r) => r.kind === "a")).toBe(true);
+    });
+
+    it("should filter by single status", async () => {
+      const result = await storage.listRuns({ status: "queued" });
+      expect(result.items).toHaveLength(1);
+      expect(result.items[0].status).toBe("queued");
+    });
+
+    it("should filter by multiple statuses", async () => {
+      const result = await storage.listRuns({ status: ["queued", "running"] });
+      expect(result.items).toHaveLength(2);
+    });
+
+    it("should filter by parentRunId", async () => {
+      const result = await storage.listRuns({ parentRunId: "parent-1" });
+      expect(result.items).toHaveLength(1);
+      expect(result.items[0].parentRunId).toBe("parent-1");
+    });
+
+    it("should apply limit and offset", async () => {
+      const result = await storage.listRuns({ limit: 2, offset: 1 });
+      expect(result.items).toHaveLength(2);
+      expect(result.total).toBe(4);
+      expect(result.limit).toBe(2);
+      expect(result.offset).toBe(1);
+    });
+
+    it("should sort by createdAt ascending", async () => {
+      const result = await storage.listRuns({
+        orderBy: "createdAt",
+        orderDirection: "asc",
+      });
+      const times = result.items.map((r) => r.createdAt.getTime());
+      for (let i = 1; i < times.length; i++) {
+        expect(times[i]).toBeGreaterThanOrEqual(times[i - 1]);
+      }
+    });
+  });
+
+  describe("createStep / getStep / updateStep", () => {
+    it("should create and retrieve a step", async () => {
+      const step = await storage.createStep({
+        runId: "run-1",
+        stepKey: "step1",
+        stepName: "Step 1",
+        status: "running",
+        attempt: 1,
+        startedAt: new Date(),
+      });
+
+      expect(step.id).toBeDefined();
+      expect(step.stepKey).toBe("step1");
+
+      const fetched = await storage.getStep(step.id);
+      expect(fetched).toEqual(step);
+    });
+
+    it("should return null for non-existent step", async () => {
+      const step = await storage.getStep("nonexistent");
+      expect(step).toBeNull();
+    });
+
+    it("should update step fields", async () => {
+      const step = await storage.createStep({
+        runId: "run-1",
+        stepKey: "step1",
+        stepName: "Step 1",
+        status: "running",
+        attempt: 1,
+      });
+
+      await storage.updateStep(step.id, {
+        status: "succeeded",
+        result: { output: "done" },
+        finishedAt: new Date(),
+      });
+
+      const updated = await storage.getStep(step.id);
+      expect(updated?.status).toBe("succeeded");
+      expect(updated?.result).toEqual({ output: "done" });
+    });
+
+    it("should do nothing when updating non-existent step", async () => {
+      await expect(
+        storage.updateStep("nonexistent", { status: "failed" }),
+      ).resolves.not.toThrow();
+    });
+  });
+
+  describe("getStepsForRun", () => {
+    it("should return steps for a specific run sorted by startedAt", async () => {
+      const now = Date.now();
+      await storage.createStep({
+        runId: "run-1",
+        stepKey: "b",
+        stepName: "B",
+        status: "succeeded",
+        attempt: 1,
+        startedAt: new Date(now + 100),
+      });
+      await storage.createStep({
+        runId: "run-1",
+        stepKey: "a",
+        stepName: "A",
+        status: "succeeded",
+        attempt: 1,
+        startedAt: new Date(now),
+      });
+      await storage.createStep({
+        runId: "run-2",
+        stepKey: "c",
+        stepName: "C",
+        status: "running",
+        attempt: 1,
+      });
+
+      const steps = await storage.getStepsForRun("run-1");
+      expect(steps).toHaveLength(2);
+      expect(steps[0].stepKey).toBe("a");
+      expect(steps[1].stepKey).toBe("b");
+    });
+  });
+
+  describe("saveEvent / getEventsForRun", () => {
+    it("should save and retrieve events", async () => {
+      await storage.saveEvent({
+        runId: "run-1",
+        eventType: "step.started",
+        level: "info",
+        timestamp: new Date(),
+      });
+      await storage.saveEvent({
+        runId: "run-1",
+        stepKey: "step1",
+        eventType: "step.completed",
+        level: "info",
+        timestamp: new Date(),
+      });
+      await storage.saveEvent({
+        runId: "run-2",
+        eventType: "run.started",
+        level: "info",
+        timestamp: new Date(),
+      });
+
+      const events = await storage.getEventsForRun("run-1");
+      expect(events).toHaveLength(2);
+    });
+
+    it("should filter events by stepKey", async () => {
+      await storage.saveEvent({
+        runId: "run-1",
+        eventType: "run.started",
+        level: "info",
+        timestamp: new Date(),
+      });
+      await storage.saveEvent({
+        runId: "run-1",
+        stepKey: "step1",
+        eventType: "step.started",
+        level: "info",
+        timestamp: new Date(),
+      });
+
+      const events = await storage.getEventsForRun("run-1", {
+        stepKey: "step1",
+      });
+      expect(events).toHaveLength(1);
+      expect(events[0].stepKey).toBe("step1");
+    });
+
+    it("should filter events by level", async () => {
+      await storage.saveEvent({
+        runId: "run-1",
+        eventType: "info-event",
+        level: "info",
+        timestamp: new Date(),
+      });
+      await storage.saveEvent({
+        runId: "run-1",
+        eventType: "error-event",
+        level: "error",
+        timestamp: new Date(),
+      });
+
+      const events = await storage.getEventsForRun("run-1", { level: "error" });
+      expect(events).toHaveLength(1);
+      expect(events[0].level).toBe("error");
+    });
+
+    it("should paginate events", async () => {
+      for (let i = 0; i < 5; i++) {
+        await storage.saveEvent({
+          runId: "run-1",
+          eventType: `event-${i}`,
+          level: "info",
+          timestamp: new Date(Date.now() + i),
+        });
+      }
+
+      const events = await storage.getEventsForRun("run-1", {
+        limit: 2,
+        offset: 1,
+      });
+      expect(events).toHaveLength(2);
+    });
+  });
+
+  describe("deleteOldRuns", () => {
+    it("should delete runs older than the cutoff date", async () => {
+      const oldDate = new Date("2020-01-01");
+      const newDate = new Date("2025-01-01");
+
+      // Create an old run with steps and events
+      const oldRun = await storage.createRun({
+        kind: "test",
+        status: "succeeded",
+        input: {},
+        metadata: {},
+        context: {},
+      });
+      // Manually set createdAt to old date
+      (await storage.getRun(oldRun.id))!.createdAt = oldDate;
+
+      await storage.createStep({
+        runId: oldRun.id,
+        stepKey: "s1",
+        stepName: "S1",
+        status: "succeeded",
+        attempt: 1,
+      });
+      await storage.saveEvent({
+        runId: oldRun.id,
+        eventType: "run.completed",
+        level: "info",
+        timestamp: new Date(),
+      });
+
+      // Create a recent run
+      const newRun = await storage.createRun({
+        kind: "test",
+        status: "succeeded",
+        input: {},
+        metadata: {},
+        context: {},
+      });
+
+      const deleted = await storage.deleteOldRuns(new Date("2024-01-01"));
+
+      expect(deleted).toBe(1);
+      expect(await storage.getRun(oldRun.id)).toBeNull();
+      expect(await storage.getRun(newRun.id)).not.toBeNull();
+
+      // Steps and events should also be cleaned up
+      const steps = await storage.getStepsForRun(oldRun.id);
+      expect(steps).toHaveLength(0);
+      const events = await storage.getEventsForRun(oldRun.id);
+      expect(events).toHaveLength(0);
+    });
+  });
+
+  describe("clear / getStats", () => {
+    it("should clear all data", async () => {
+      await storage.createRun({
+        kind: "a",
+        status: "queued",
+        input: {},
+        metadata: {},
+        context: {},
+      });
+      await storage.createStep({
+        runId: "r",
+        stepKey: "s",
+        stepName: "S",
+        status: "running",
+        attempt: 1,
+      });
+      await storage.saveEvent({
+        runId: "r",
+        eventType: "e",
+        level: "info",
+        timestamp: new Date(),
+      });
+
+      expect(storage.getStats().runs).toBe(1);
+      expect(storage.getStats().steps).toBe(1);
+      expect(storage.getStats().events).toBe(1);
+
+      storage.clear();
+
+      expect(storage.getStats()).toEqual({ runs: 0, steps: 0, events: 0 });
+    });
+  });
+});

package/src/storage/memory.ts

@@ -0,0 +1,248 @@
+/**
+ * In-memory storage adapter for development and testing.
+ * All data is lost when the process exits.
+ *
+ * NOTE: This adapter is intended for development and testing only. It stores
+ * all state in-process with no persistence or multi-process safety guarantees.
+ */
+
+import { generateId } from "../utils/id";
+import type {
+  StorageAdapter,
+  WorkflowRunRecord,
+  WorkflowRunStepRecord,
+  WorkflowEventRecord,
+  ListRunsOptions,
+  ListEventsOptions,
+  PaginatedResult,
+} from "./types";
+
+/**
+ * In-memory implementation of StorageAdapter.
+ * Useful for development, testing, and lightweight deployments.
+ *
+ * @example
+ * ```typescript
+ * import { WorkflowEngine } from 'stepflow';
+ * import { MemoryStorageAdapter } from 'stepflow/storage';
+ *
+ * const storage = new MemoryStorageAdapter();
+ * const engine = new WorkflowEngine({ storage });
+ * ```
+ */
+export class MemoryStorageAdapter implements StorageAdapter {
+  private runs = new Map<string, WorkflowRunRecord>();
+  private steps = new Map<string, WorkflowRunStepRecord>();
+  private events = new Map<string, WorkflowEventRecord>();
+
+  // ============================================================================
+  // Run Operations
+  // ============================================================================
+
+  /** Create and persist a new workflow run record. */
+  async createRun(
+    run: Omit<WorkflowRunRecord, "id" | "createdAt">,
+  ): Promise<WorkflowRunRecord> {
+    const record: WorkflowRunRecord = {
+      ...run,
+      id: generateId(),
+      createdAt: new Date(),
+    };
+    this.runs.set(record.id, record);
+    return record;
+  }
+
+  /** Retrieve a workflow run by ID, or null if not found. */
+  async getRun(runId: string): Promise<WorkflowRunRecord | null> {
+    return this.runs.get(runId) ?? null;
+  }
+
+  /** Apply partial updates to an existing workflow run. No-op if the run does not exist. */
+  async updateRun(
+    runId: string,
+    updates: Partial<WorkflowRunRecord>,
+  ): Promise<void> {
+    const run = this.runs.get(runId);
+    if (run) {
+      Object.assign(run, updates);
+    }
+  }
+
+  /** List workflow runs with optional filtering, sorting, and pagination. */
+  async listRuns(
+    options: ListRunsOptions = {},
+  ): Promise<PaginatedResult<WorkflowRunRecord>> {
+    let items = Array.from(this.runs.values());
+
+    // Filter by kind
+    if (options.kind) {
+      items = items.filter((r) => r.kind === options.kind);
+    }
+
+    // Filter by status
+    if (options.status) {
+      const statuses = Array.isArray(options.status)
+        ? options.status
+        : [options.status];
+      items = items.filter((r) => statuses.includes(r.status));
+    }
+
+    // Filter by parentRunId
+    if (options.parentRunId !== undefined) {
+      items = items.filter((r) => r.parentRunId === options.parentRunId);
+    }
+
+    // Sort
+    const orderBy = options.orderBy ?? "createdAt";
+    const direction = options.orderDirection ?? "desc";
+    items.sort((a, b) => {
+      const aVal = a[orderBy]?.getTime() ?? 0;
+      const bVal = b[orderBy]?.getTime() ?? 0;
+      return direction === "asc" ? aVal - bVal : bVal - aVal;
+    });
+
+    const total = items.length;
+    const offset = options.offset ?? 0;
+    const limit = options.limit ?? 50;
+
+    items = items.slice(offset, offset + limit);
+
+    return { items, total, limit, offset };
+  }
+
+  // ============================================================================
+  // Step Operations
+  // ============================================================================
+
+  /** Create and persist a new step execution record. */
+  async createStep(
+    step: Omit<WorkflowRunStepRecord, "id">,
+  ): Promise<WorkflowRunStepRecord> {
+    const record: WorkflowRunStepRecord = {
+      ...step,
+      id: generateId(),
+    };
+    this.steps.set(record.id, record);
+    return record;
+  }
+
+  /** Retrieve a step record by ID, or null if not found. */
+  async getStep(stepId: string): Promise<WorkflowRunStepRecord | null> {
+    return this.steps.get(stepId) ?? null;
+  }
+
+  /** Apply partial updates to an existing step record. No-op if the step does not exist. */
+  async updateStep(
+    stepId: string,
+    updates: Partial<WorkflowRunStepRecord>,
+  ): Promise<void> {
+    const step = this.steps.get(stepId);
+    if (step) {
+      Object.assign(step, updates);
+    }
+  }
+
+  /** Retrieve all step records for a workflow run, ordered by start time ascending. */
+  async getStepsForRun(runId: string): Promise<WorkflowRunStepRecord[]> {
+    return Array.from(this.steps.values())
+      .filter((s) => s.runId === runId)
+      .sort(
+        (a, b) => (a.startedAt?.getTime() ?? 0) - (b.startedAt?.getTime() ?? 0),
+      );
+  }
+
+  // ============================================================================
+  // Event Operations
+  // ============================================================================
+
+  /** Persist a workflow event record. */
+  async saveEvent(event: Omit<WorkflowEventRecord, "id">): Promise<void> {
+    const record: WorkflowEventRecord = {
+      ...event,
+      id: generateId(),
+    };
+    this.events.set(record.id, record);
+  }
+
+  /** Retrieve events for a workflow run with optional filtering and pagination. */
+  async getEventsForRun(
+    runId: string,
+    options: ListEventsOptions = {},
+  ): Promise<WorkflowEventRecord[]> {
+    let items = Array.from(this.events.values()).filter(
+      (e) => e.runId === runId,
+    );
+
+    // Filter by step
+    if (options.stepKey) {
+      items = items.filter((e) => e.stepKey === options.stepKey);
+    }
+
+    // Filter by level
+    if (options.level) {
+      items = items.filter((e) => e.level === options.level);
+    }
+
+    // Sort by timestamp
+    items.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+
+    // Apply pagination
+    const offset = options.offset ?? 0;
+    const limit = options.limit ?? 100;
+
+    return items.slice(offset, offset + limit);
+  }
+
+  // ============================================================================
+  // Optional Operations
+  // ============================================================================
+
+  /** Delete runs (and their associated steps and events) created before the given date. Returns the number of deleted runs. */
+  async deleteOldRuns(olderThan: Date): Promise<number> {
+    let deleted = 0;
+    for (const [id, run] of this.runs) {
+      if (run.createdAt < olderThan) {
+        // Delete associated steps
+        for (const [stepId, step] of this.steps) {
+          if (step.runId === id) {
+            this.steps.delete(stepId);
+          }
+        }
+        // Delete associated events
+        for (const [eventId, event] of this.events) {
+          if (event.runId === id) {
+            this.events.delete(eventId);
+          }
+        }
+        // Delete run
+        this.runs.delete(id);
+        deleted++;
+      }
+    }
+    return deleted;
+  }
+
+  // ============================================================================
+  // Testing Utilities
+  // ============================================================================
+
+  /**
+   * Clear all stored data. Useful for testing.
+   */
+  clear(): void {
+    this.runs.clear();
+    this.steps.clear();
+    this.events.clear();
+  }
+
+  /**
+   * Get counts of stored records. Useful for testing.
+   */
+  getStats(): { runs: number; steps: number; events: number } {
+    return {
+      runs: this.runs.size,
+      steps: this.steps.size,
+      events: this.events.size,
+    };
+  }
+}