@multiplier-labs/stepflow 0.3.4 → 0.3.6

package/src/storage/memory.test.ts

@@ -1,349 +0,0 @@
-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

@@ -1,227 +0,0 @@
-/**
- * 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,
-    };
-  }
-}