@multiplier-labs/stepflow 0.3.4 → 0.3.8

package/src/scheduler/sqlite-persistence.test.ts

@@ -1,235 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import Database from 'better-sqlite3';
-import { SQLiteSchedulePersistence } from './sqlite-persistence';
-import type { WorkflowSchedule } from './types';
-
-describe('SQLiteSchedulePersistence', () => {
-  let db: Database.Database;
-  let persistence: SQLiteSchedulePersistence;
-
-  beforeEach(() => {
-    // Use in-memory database for testing
-    db = new Database(':memory:');
-    persistence = new SQLiteSchedulePersistence({ db });
-  });
-
-  afterEach(() => {
-    db.close();
-  });
-
-  describe('saveSchedule', () => {
-    it('should save a cron schedule', async () => {
-      const schedule: WorkflowSchedule = {
-        id: 'test-1',
-        workflowKind: 'test.workflow',
-        triggerType: 'cron',
-        cronExpression: '0 * * * *',
-        timezone: 'UTC',
-        enabled: true,
-        input: { foo: 'bar' },
-        metadata: { user: 'test' },
-      };
-
-      await persistence.saveSchedule(schedule);
-
-      const loaded = await persistence.loadSchedules();
-      expect(loaded).toHaveLength(1);
-      expect(loaded[0].id).toBe('test-1');
-      expect(loaded[0].cronExpression).toBe('0 * * * *');
-      expect(loaded[0].input).toEqual({ foo: 'bar' });
-    });
-
-    it('should save a workflow completion trigger', async () => {
-      const schedule: WorkflowSchedule = {
-        id: 'test-2',
-        workflowKind: 'notification.send',
-        triggerType: 'workflow_completed',
-        triggerOnWorkflowKind: 'order.process',
-        triggerOnStatus: ['succeeded', 'failed'],
-        enabled: true,
-      };
-
-      await persistence.saveSchedule(schedule);
-
-      const loaded = await persistence.loadSchedules();
-      expect(loaded).toHaveLength(1);
-      expect(loaded[0].triggerType).toBe('workflow_completed');
-      expect(loaded[0].triggerOnWorkflowKind).toBe('order.process');
-      expect(loaded[0].triggerOnStatus).toEqual(['succeeded', 'failed']);
-    });
-
-    it('should save schedule with dates', async () => {
-      const lastRunAt = new Date('2024-01-01T12:00:00Z');
-      const nextRunAt = new Date('2024-01-01T13:00:00Z');
-
-      const schedule: WorkflowSchedule = {
-        id: 'test-3',
-        workflowKind: 'test.workflow',
-        triggerType: 'cron',
-        cronExpression: '0 * * * *',
-        enabled: true,
-        lastRunAt,
-        lastRunId: 'run-123',
-        nextRunAt,
-      };
-
-      await persistence.saveSchedule(schedule);
-
-      const loaded = await persistence.loadSchedules();
-      expect(loaded[0].lastRunAt).toEqual(lastRunAt);
-      expect(loaded[0].lastRunId).toBe('run-123');
-      expect(loaded[0].nextRunAt).toEqual(nextRunAt);
-    });
-  });
-
-  describe('loadSchedules', () => {
-    it('should return empty array when no schedules', async () => {
-      const schedules = await persistence.loadSchedules();
-      expect(schedules).toHaveLength(0);
-    });
-
-    it('should load multiple schedules', async () => {
-      await persistence.saveSchedule({
-        id: 'schedule-1',
-        workflowKind: 'workflow.a',
-        triggerType: 'cron',
-        cronExpression: '0 * * * *',
-        enabled: true,
-      });
-
-      await persistence.saveSchedule({
-        id: 'schedule-2',
-        workflowKind: 'workflow.b',
-        triggerType: 'manual',
-        enabled: false,
-      });
-
-      const schedules = await persistence.loadSchedules();
-      expect(schedules).toHaveLength(2);
-    });
-  });
-
-  describe('updateSchedule', () => {
-    it('should update enabled status', async () => {
-      await persistence.saveSchedule({
-        id: 'update-1',
-        workflowKind: 'test.workflow',
-        triggerType: 'cron',
-        cronExpression: '0 * * * *',
-        enabled: true,
-      });
-
-      await persistence.updateSchedule('update-1', { enabled: false });
-
-      const loaded = await persistence.loadSchedules();
-      expect(loaded[0].enabled).toBe(false);
-    });
-
-    it('should update cron expression', async () => {
-      await persistence.saveSchedule({
-        id: 'update-2',
-        workflowKind: 'test.workflow',
-        triggerType: 'cron',
-        cronExpression: '0 * * * *',
-        enabled: true,
-      });
-
-      await persistence.updateSchedule('update-2', {
-        cronExpression: '30 * * * *',
-      });
-
-      const loaded = await persistence.loadSchedules();
-      expect(loaded[0].cronExpression).toBe('30 * * * *');
-    });
-
-    it('should update lastRunAt and lastRunId', async () => {
-      await persistence.saveSchedule({
-        id: 'update-3',
-        workflowKind: 'test.workflow',
-        triggerType: 'cron',
-        cronExpression: '0 * * * *',
-        enabled: true,
-      });
-
-      const now = new Date();
-      await persistence.updateSchedule('update-3', {
-        lastRunAt: now,
-        lastRunId: 'run-456',
-      });
-
-      const loaded = await persistence.loadSchedules();
-      expect(loaded[0].lastRunAt).toEqual(now);
-      expect(loaded[0].lastRunId).toBe('run-456');
-    });
-
-    it('should throw for non-existent schedule', async () => {
-      await expect(
-        persistence.updateSchedule('nonexistent', { enabled: false })
-      ).rejects.toThrow('Schedule not found');
-    });
-  });
-
-  describe('deleteSchedule', () => {
-    it('should delete a schedule', async () => {
-      await persistence.saveSchedule({
-        id: 'delete-1',
-        workflowKind: 'test.workflow',
-        triggerType: 'cron',
-        cronExpression: '0 * * * *',
-        enabled: true,
-      });
-
-      await persistence.deleteSchedule('delete-1');
-
-      const loaded = await persistence.loadSchedules();
-      expect(loaded).toHaveLength(0);
-    });
-
-    it('should handle deleting non-existent schedule gracefully', async () => {
-      // This should not throw
-      await persistence.deleteSchedule('nonexistent');
-    });
-  });
-
-  describe('data integrity', () => {
-    it('should preserve all fields through save/load cycle', async () => {
-      const schedule: WorkflowSchedule = {
-        id: 'integrity-1',
-        workflowKind: 'complex.workflow',
-        triggerType: 'workflow_completed',
-        triggerOnWorkflowKind: 'parent.workflow',
-        triggerOnStatus: ['succeeded'],
-        input: { nested: { value: 123 } },
-        metadata: { tags: ['a', 'b'] },
-        enabled: true,
-        lastRunAt: new Date('2024-06-15T10:30:00Z'),
-        lastRunId: 'run-789',
-        nextRunAt: new Date('2024-06-15T11:00:00Z'),
-      };
-
-      await persistence.saveSchedule(schedule);
-
-      const loaded = await persistence.loadSchedules();
-      expect(loaded[0]).toEqual(schedule);
-    });
-
-    it('should handle null/undefined values correctly', async () => {
-      const schedule: WorkflowSchedule = {
-        id: 'nullable-1',
-        workflowKind: 'test.workflow',
-        triggerType: 'manual',
-        enabled: false,
-        // All other optional fields are undefined
-      };
-
-      await persistence.saveSchedule(schedule);
-
-      const loaded = await persistence.loadSchedules();
-      expect(loaded[0].cronExpression).toBeUndefined();
-      expect(loaded[0].timezone).toBeUndefined();
-      expect(loaded[0].input).toBeUndefined();
-      expect(loaded[0].metadata).toBeUndefined();
-      expect(loaded[0].lastRunAt).toBeUndefined();
-    });
-  });
-});

package/src/scheduler/sqlite-persistence.ts

@@ -1,286 +0,0 @@
-/**
- * SQLite persistence adapter for schedules.
- *
- * Stores workflow schedules in a SQLite database table.
- */
-
-import type { Database, Statement } from 'better-sqlite3';
-import type { WorkflowSchedule } from './types';
-import type { SchedulePersistence } from './cron';
-import type { Logger, RunStatus } from '../core/types';
-import { generateId } from '../utils/id';
-import { safeJsonParse as sharedSafeJsonParse } from '../utils/safe-json';
-
-// ============================================================================
-// Configuration Types
-// ============================================================================
-
-/**
- * Configuration for SQLiteSchedulePersistence.
- */
-export interface SQLiteSchedulePersistenceConfig {
-  /** SQLite database instance */
-  db: Database;
-
-  /** Table name for schedules (default: workflow_schedules) */
-  tableName?: string;
-
-  /**
-   * Optional structured logger used to surface JSON corruption events.
-   * Without one, parse failures still increment the corruption counter
-   * exposed via `getJsonParseCorruptionCount()` but produce no log output.
-   */
-  logger?: Logger;
-}
-
-// ============================================================================
-// SQLiteSchedulePersistence Class
-// ============================================================================
-
-/**
- * SQLite-based persistence for workflow schedules.
- *
- * @example
- * ```typescript
- * import Database from 'better-sqlite3';
- *
- * const db = new Database('workflow.db');
- * const persistence = new SQLiteSchedulePersistence({ db });
- *
- * const scheduler = new CronScheduler({
- *   engine,
- *   persistence,
- * });
- * ```
- */
-export class SQLiteSchedulePersistence implements SchedulePersistence {
-  private db: Database;
-  private tableName: string;
-  private logger: Logger | undefined;
-  private stmts: {
-    insert: Statement;
-    update: Statement;
-    delete: Statement;
-    getAll: Statement;
-    getById: Statement;
-  } | null = null;
-
-  constructor(config: SQLiteSchedulePersistenceConfig) {
-    this.db = config.db;
-    this.tableName = config.tableName ?? 'workflow_schedules';
-    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(this.tableName)) {
-      throw new Error(`Invalid table name: ${this.tableName}`);
-    }
-    this.logger = config.logger;
-    this.initializeDatabase();
-  }
-
-  // ============================================================================
-  // Database Initialization
-  // ============================================================================
-
-  private initializeDatabase(): void {
-    // Create schedules table.
-    // Schema layout:
-    //   id               — unique schedule identifier (TEXT PK)
-    //   workflow_kind     — target workflow type to spawn
-    //   trigger_type      — 'cron', 'workflow_completed', or 'manual'
-    //   cron_expression   — cron expression for time-based triggers (nullable)
-    //   timezone          — IANA timezone for cron evaluation (nullable)
-    //   trigger_on_*      — fields for workflow-completion triggers
-    //   input / metadata  — JSON-serialized payloads for spawned runs
-    //   enabled           — whether this schedule is active (0/1)
-    //   last_run_at/id    — most recent execution tracking
-    //   next_run_at       — next scheduled execution time
-    //   created_at/updated_at — audit timestamps
-    // No migration strategy is currently implemented; table is created idempotently.
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS ${this.tableName} (
-        id TEXT PRIMARY KEY,
-        workflow_kind TEXT NOT NULL,
-        trigger_type TEXT NOT NULL,
-        cron_expression TEXT,
-        timezone TEXT,
-        trigger_on_workflow_kind TEXT,
-        trigger_on_status TEXT,
-        input TEXT,
-        metadata TEXT,
-        enabled INTEGER NOT NULL DEFAULT 1,
-        last_run_at TEXT,
-        last_run_id TEXT,
-        next_run_at TEXT,
-        created_at TEXT NOT NULL DEFAULT (datetime('now')),
-        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
-      )
-    `);
-
-    // Create indexes
-    this.db.exec(`
-      CREATE INDEX IF NOT EXISTS idx_${this.tableName}_workflow_kind
-      ON ${this.tableName}(workflow_kind);
-
-      CREATE INDEX IF NOT EXISTS idx_${this.tableName}_enabled
-      ON ${this.tableName}(enabled);
-
-      CREATE INDEX IF NOT EXISTS idx_${this.tableName}_trigger_type
-      ON ${this.tableName}(trigger_type);
-    `);
-
-    // Prepare statements
-    this.stmts = {
-      insert: this.db.prepare(`
-        INSERT INTO ${this.tableName} (
-          id, workflow_kind, trigger_type, cron_expression, timezone,
-          trigger_on_workflow_kind, trigger_on_status, input, metadata,
-          enabled, last_run_at, last_run_id, next_run_at
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `),
-      update: this.db.prepare(`
-        UPDATE ${this.tableName}
-        SET workflow_kind = COALESCE(?, workflow_kind),
-            trigger_type = COALESCE(?, trigger_type),
-            cron_expression = ?,
-            timezone = ?,
-            trigger_on_workflow_kind = ?,
-            trigger_on_status = ?,
-            input = ?,
-            metadata = ?,
-            enabled = COALESCE(?, enabled),
-            last_run_at = ?,
-            last_run_id = ?,
-            next_run_at = ?,
-            updated_at = datetime('now')
-        WHERE id = ?
-      `),
-      delete: this.db.prepare(`
-        DELETE FROM ${this.tableName} WHERE id = ?
-      `),
-      getAll: this.db.prepare(`
-        SELECT * FROM ${this.tableName}
-      `),
-      getById: this.db.prepare(`
-        SELECT * FROM ${this.tableName} WHERE id = ?
-      `),
-    };
-  }
-
-  // ============================================================================
-  // SchedulePersistence Interface Implementation
-  // ============================================================================
-
-  async loadSchedules(): Promise<WorkflowSchedule[]> {
-    const rows = this.stmts!.getAll.all() as ScheduleRow[];
-    return rows.map(row => this.rowToSchedule(row));
-  }
-
-  async saveSchedule(schedule: WorkflowSchedule): Promise<void> {
-    this.stmts!.insert.run(
-      schedule.id,
-      schedule.workflowKind,
-      schedule.triggerType,
-      schedule.cronExpression ?? null,
-      schedule.timezone ?? null,
-      schedule.triggerOnWorkflowKind ?? null,
-      schedule.triggerOnStatus ? JSON.stringify(schedule.triggerOnStatus) : null,
-      schedule.input ? JSON.stringify(schedule.input) : null,
-      schedule.metadata ? JSON.stringify(schedule.metadata) : null,
-      schedule.enabled ? 1 : 0,
-      schedule.lastRunAt?.toISOString() ?? null,
-      schedule.lastRunId ?? null,
-      schedule.nextRunAt?.toISOString() ?? null
-    );
-  }
-
-  async updateSchedule(scheduleId: string, updates: Partial<WorkflowSchedule>): Promise<void> {
-    // Get existing schedule to merge with updates
-    const existing = this.stmts!.getById.get(scheduleId) as ScheduleRow | undefined;
-    if (!existing) {
-      throw new Error(`Schedule not found: ${scheduleId}`);
-    }
-
-    const merged = {
-      ...this.rowToSchedule(existing),
-      ...updates,
-    };
-
-    this.stmts!.update.run(
-      updates.workflowKind ?? null,
-      updates.triggerType ?? null,
-      merged.cronExpression ?? null,
-      merged.timezone ?? null,
-      merged.triggerOnWorkflowKind ?? null,
-      merged.triggerOnStatus ? JSON.stringify(merged.triggerOnStatus) : null,
-      merged.input ? JSON.stringify(merged.input) : null,
-      merged.metadata ? JSON.stringify(merged.metadata) : null,
-      updates.enabled !== undefined ? (updates.enabled ? 1 : 0) : null,
-      merged.lastRunAt?.toISOString() ?? null,
-      merged.lastRunId ?? null,
-      merged.nextRunAt?.toISOString() ?? null,
-      scheduleId
-    );
-  }
-
-  async deleteSchedule(scheduleId: string): Promise<void> {
-    this.stmts!.delete.run(scheduleId);
-  }
-
-  // ============================================================================
-  // Helper Methods
-  // ============================================================================
-
-  private safeJsonParse(
-    json: string,
-    fallback: unknown,
-    rowId: string,
-    column: string,
-  ): unknown {
-    return sharedSafeJsonParse(json, fallback, {
-      component: 'SQLiteSchedulePersistence',
-      rowId,
-      column,
-      logger: this.logger,
-    });
-  }
-
-  private rowToSchedule(row: ScheduleRow): WorkflowSchedule {
-    return {
-      id: row.id,
-      workflowKind: row.workflow_kind,
-      triggerType: row.trigger_type as WorkflowSchedule['triggerType'],
-      cronExpression: row.cron_expression ?? undefined,
-      timezone: row.timezone ?? undefined,
-      triggerOnWorkflowKind: row.trigger_on_workflow_kind ?? undefined,
-      triggerOnStatus: row.trigger_on_status
-        ? this.safeJsonParse(row.trigger_on_status, undefined, row.id, 'trigger_on_status') as RunStatus[] | undefined
-        : undefined,
-      input: row.input ? this.safeJsonParse(row.input, undefined, row.id, 'input') as Record<string, unknown> | undefined : undefined,
-      metadata: row.metadata ? this.safeJsonParse(row.metadata, undefined, row.id, 'metadata') as Record<string, unknown> | undefined : undefined,
-      enabled: row.enabled === 1,
-      lastRunAt: row.last_run_at ? new Date(row.last_run_at) : undefined,
-      lastRunId: row.last_run_id ?? undefined,
-      nextRunAt: row.next_run_at ? new Date(row.next_run_at) : undefined,
-    };
-  }
-}
-
-// ============================================================================
-// Types
-// ============================================================================
-
-interface ScheduleRow {
-  id: string;
-  workflow_kind: string;
-  trigger_type: string;
-  cron_expression: string | null;
-  timezone: string | null;
-  trigger_on_workflow_kind: string | null;
-  trigger_on_status: string | null;
-  input: string | null;
-  metadata: string | null;
-  enabled: number;
-  last_run_at: string | null;
-  last_run_id: string | null;
-  next_run_at: string | null;
-  created_at: string;
-  updated_at: string;
-}

package/src/scheduler/types.ts

@@ -1,73 +0,0 @@
-/**
- * Scheduler types for the workflow engine.
- * Defines the type contracts for the cron and workflow-completion trigger
- * scheduler, implemented by {@link CronScheduler}, {@link SQLiteSchedulePersistence},
- * and {@link PostgresSchedulePersistence}.
- */
-
-import type { WorkflowKind, RunStatus } from '../core/types';
-
-/**
- * Schedule trigger types.
- */
-export type TriggerType = 'cron' | 'workflow_completed' | 'manual';
-
-/**
- * Schedule definition.
- */
-export interface WorkflowSchedule {
-  id: string;
-  workflowKind: WorkflowKind;
-  triggerType: TriggerType;
-
-  /** Cron expression for time-based triggers (e.g. `0 0 * * *` for daily). Only used when triggerType is 'cron'. */
-  cronExpression?: string;
-  /** IANA timezone for cron evaluation (e.g. 'America/New_York'). Defaults to 'UTC'. */
-  timezone?: string;
-
-  /** Workflow kind that triggers this schedule on completion. Only used when triggerType is 'workflow_completed'. */
-  triggerOnWorkflowKind?: WorkflowKind;
-  /** Run statuses that activate the completion trigger. If empty, any terminal status triggers. */
-  triggerOnStatus?: RunStatus[];
-
-  /** Input payload passed to the spawned workflow run. */
-  input?: Record<string, unknown>;
-  /** Arbitrary metadata attached to the spawned workflow run. */
-  metadata?: Record<string, unknown>;
-
-  /** Whether this schedule is active. Disabled schedules are not evaluated. */
-  enabled: boolean;
-  /** Timestamp of the most recent run spawned by this schedule. */
-  lastRunAt?: Date;
-  /** Run ID of the most recent run spawned by this schedule. */
-  lastRunId?: string;
-  /** Next scheduled execution time, computed from the cron expression and timezone. */
-  nextRunAt?: Date;
-}
-
-/**
- * Scheduler interface.
- * Implement this to create custom schedulers.
- */
-export interface Scheduler {
-  /** Start the scheduler */
-  start(): Promise<void>;
-
-  /** Stop the scheduler */
-  stop(): Promise<void>;
-
-  /** Add a schedule */
-  addSchedule(schedule: Omit<WorkflowSchedule, 'id'>): Promise<WorkflowSchedule>;
-
-  /** Remove a schedule */
-  removeSchedule(scheduleId: string): Promise<void>;
-
-  /** Update a schedule */
-  updateSchedule(scheduleId: string, updates: Partial<WorkflowSchedule>): Promise<void>;
-
-  /** Get all schedules */
-  getSchedules(): Promise<WorkflowSchedule[]>;
-
-  /** Manually trigger a scheduled workflow */
-  triggerNow(scheduleId: string): Promise<string>;
-}

package/src/storage/index.ts

@@ -1,27 +0,0 @@
-/**
- * Storage module exports.
- */
-
-export * from './types';
-export * from './memory';
-export * from './sqlite';
-export * from './postgres';
-
-// Re-export specific types for convenience
-export type {
-  WorkflowStorage,
-  WorkflowRunRecord,
-  CreateRunInput,
-  UpdateRunInput,
-  ListRunsOptions,
-  PaginatedResult,
-  StepResult,
-  StepRecord,
-  ExtendedWorkflowRunRecord,
-  ExtendedRunStatus,
-  ExtendedStepStatus,
-  ExtendedListRunsOptions,
-  StepflowRunsTable,
-  StepflowStepResultsTable,
-  StepflowDatabase,
-} from './types';