@multiplier-labs/stepflow 0.3.4 → 0.3.8

package/src/storage/types.ts

@@ -1,343 +0,0 @@
-/**
- * Storage interface types for the workflow engine.
- * Implement StorageAdapter to use your preferred database.
- */
-
-import type { WorkflowKind, RunStatus, StepStatus, WorkflowError } from '../core/types';
-
-// ============================================================================
-// Extended Status Types (New)
-// ============================================================================
-
-/**
- * Extended status of a workflow run.
- * Adds 'pending' and 'timeout' to the core statuses.
- */
-export type ExtendedRunStatus =
-  | 'pending'
-  | 'queued'
-  | 'running'
-  | 'succeeded'
-  | 'failed'
-  | 'canceled'
-  | 'timeout';
-
-/**
- * Extended status of a workflow step.
- * Uses 'completed' instead of 'succeeded' for consistency.
- */
-export type ExtendedStepStatus =
-  | 'pending'
-  | 'running'
-  | 'completed'
-  | 'failed'
-  | 'skipped'
-  | 'canceled';
-
-// ============================================================================
-// Legacy Record Types (Backward Compatible)
-// ============================================================================
-
-/**
- * Stored representation of a workflow run.
- */
-export interface WorkflowRunRecord {
-  id: string;
-  kind: string;
-  status: RunStatus;
-  parentRunId?: string;
-  input: Record<string, unknown>;
-  context: Record<string, unknown>;
-  completedSteps?: string[];
-  output?: Record<string, unknown>;
-  error?: { code: string; message: string };
-  metadata?: Record<string, unknown>;
-  priority?: number;
-  timeoutMs?: number;
-  createdAt: Date;
-  startedAt?: Date;
-  finishedAt?: Date;
-}
-
-/**
- * Stored representation of a workflow step execution.
- */
-export interface WorkflowRunStepRecord {
-  id: string;
-  runId: string;
-  stepKey: string;
-  stepName: string;
-  status: StepStatus;
-  attempt: number;
-  result?: unknown;
-  error?: WorkflowError;
-  startedAt?: Date;
-  finishedAt?: Date;
-}
-
-/**
- * Stored workflow event.
- */
-export interface WorkflowEventRecord {
-  id: string;
-  runId: string;
-  stepKey?: string;
-  eventType: string;
-  level: 'info' | 'warn' | 'error';
-  payload?: unknown;
-  timestamp: Date;
-}
-
-// ============================================================================
-// New Extended Record Types
-// ============================================================================
-
-/**
- * Extended workflow run record with additional fields.
- * Used by new WorkflowStorage implementations.
- */
-export interface ExtendedWorkflowRunRecord {
-  id: string;
-  kind: string;
-  status: ExtendedRunStatus;
-  input: Record<string, unknown>;
-  context: Record<string, unknown>;
-  output?: Record<string, unknown>;
-  error?: { code: string; message: string };
-  metadata?: Record<string, unknown>;
-  priority: number;
-  timeoutMs?: number;
-  createdAt: Date;
-  startedAt?: Date;
-  finishedAt?: Date;
-}
-
-/**
- * Step result representation.
- */
-export interface StepResult {
-  id: string;
-  runId: string;
-  stepName: string;
-  status: ExtendedStepStatus;
-  output?: Record<string, unknown>;
-  error?: Record<string, unknown>;
-  attempt: number;
-  startedAt?: Date;
-  completedAt?: Date;
-}
-
-/**
- * Step record for workflow steps.
- */
-export interface StepRecord {
-  stepKey: string;
-  stepName: string;
-  status: ExtendedStepStatus;
-  result?: Record<string, unknown>;
-  error?: Record<string, unknown>;
-  attempt: number;
-  startedAt?: Date;
-  finishedAt?: Date;
-}
-
-// ============================================================================
-// Input Types (New)
-// ============================================================================
-
-/**
- * Input for creating a new workflow run.
- */
-export interface CreateRunInput {
-  id?: string;
-  kind: string;
-  status: ExtendedRunStatus;
-  parentRunId?: string;
-  input: Record<string, unknown>;
-  context?: Record<string, unknown>; // Optional with default {}
-  metadata?: Record<string, unknown>;
-  priority?: number;
-  timeoutMs?: number;
-}
-
-/**
- * Input for updating a workflow run.
- */
-export interface UpdateRunInput {
-  status?: ExtendedRunStatus;
-  context?: Record<string, unknown>;
-  output?: Record<string, unknown>;
-  error?: { code: string; message: string };
-  startedAt?: Date;
-  finishedAt?: Date;
-}
-
-// ============================================================================
-// Query Options
-// ============================================================================
-
-/**
- * Options for listing runs.
- */
-export interface ListRunsOptions {
-  kind?: WorkflowKind;
-  status?: RunStatus | RunStatus[];
-  parentRunId?: string;
-  limit?: number;
-  offset?: number;
-  orderBy?: 'createdAt' | 'startedAt' | 'finishedAt';
-  orderDirection?: 'asc' | 'desc';
-}
-
-/**
- * Extended options for listing runs.
- */
-export interface ExtendedListRunsOptions {
-  kind?: string;
-  status?: ExtendedRunStatus | ExtendedRunStatus[];
-  limit?: number;
-  offset?: number;
-  orderBy?: 'createdAt' | 'startedAt' | 'finishedAt';
-  orderDir?: 'asc' | 'desc';
-}
-
-/**
- * Options for listing events.
- */
-export interface ListEventsOptions {
-  stepKey?: string;
-  level?: 'info' | 'warn' | 'error';
-  limit?: number;
-  offset?: number;
-}
-
-/**
- * Paginated result wrapper.
- */
-export interface PaginatedResult<T> {
-  items: T[];
-  total: number;
-  limit?: number;
-  offset?: number;
-}
-
-// ============================================================================
-// WorkflowStorage Interface (New)
-// ============================================================================
-
-/**
- * New storage interface for workflow persistence.
- * Implement this interface for new implementations.
- */
-export interface WorkflowStorage {
-  // Run operations
-  createRun(run: CreateRunInput): Promise<ExtendedWorkflowRunRecord>;
-  getRun(id: string): Promise<ExtendedWorkflowRunRecord | null>;
-  updateRun(id: string, updates: UpdateRunInput): Promise<void>;
-  listRuns(options?: ExtendedListRunsOptions): Promise<PaginatedResult<ExtendedWorkflowRunRecord>>;
-  deleteRun(id: string): Promise<void>;
-
-  // Atomic dequeue for concurrency control
-  dequeueRun(workflowKinds: string[]): Promise<ExtendedWorkflowRunRecord | null>;
-
-  // Stale workflow cleanup
-  cleanupStaleRuns(defaultTimeoutMs?: number): Promise<number>;
-  markRunsAsFailed(runIds: string[], reason: string): Promise<void>;
-
-  // Step operations
-  getStepResult(runId: string, stepName: string): Promise<StepResult | undefined>;
-  getStepResults(runId: string): Promise<StepResult[]>;
-  getStepsForRun(runId: string): Promise<StepRecord[]>;
-  saveStepResult(result: Omit<StepResult, 'id'> & { id?: string }): Promise<void>;
-
-  // Lifecycle
-  initialize(): Promise<void>;
-  close(): Promise<void>;
-}
-
-// ============================================================================
-// Legacy Storage Adapter Interface
-// ============================================================================
-
-/**
- * Abstract storage adapter interface.
- * Implement this interface to use your preferred database.
- */
-export interface StorageAdapter {
-  // Run operations
-  createRun(run: Omit<WorkflowRunRecord, 'id' | 'createdAt'>): Promise<WorkflowRunRecord>;
-  getRun(runId: string): Promise<WorkflowRunRecord | null>;
-  updateRun(runId: string, updates: Partial<WorkflowRunRecord>): Promise<void>;
-  listRuns(options?: ListRunsOptions): Promise<PaginatedResult<WorkflowRunRecord>>;
-
-  // Step operations
-  createStep(step: Omit<WorkflowRunStepRecord, 'id'>): Promise<WorkflowRunStepRecord>;
-  getStep(stepId: string): Promise<WorkflowRunStepRecord | null>;
-  updateStep(stepId: string, updates: Partial<WorkflowRunStepRecord>): Promise<void>;
-  getStepsForRun(runId: string): Promise<WorkflowRunStepRecord[]>;
-
-  // Event operations
-  saveEvent(event: Omit<WorkflowEventRecord, 'id'>): Promise<void>;
-  getEventsForRun(runId: string, options?: ListEventsOptions): Promise<WorkflowEventRecord[]>;
-
-  /**
-   * Optional transaction support.
-   * @deprecated Transaction support is deprecated and will be removed in a future release.
-   */
-  transaction?<T>(fn: (tx: StorageAdapter) => Promise<T>): Promise<T>;
-
-  // Optional: Cleanup
-  deleteOldRuns?(olderThan: Date): Promise<number>;
-
-  // Optional: Lifecycle (required for adapters that need async setup, e.g. PostgreSQL)
-  initialize?(): Promise<void>;
-  close?(): void | Promise<void>;
-}
-
-// ============================================================================
-// Database Schema Types
-// ============================================================================
-
-/**
- * Database table schema for workflow runs.
- * Note: When used with Kysely, wrap auto-generated fields with Generated<T>.
- */
-export interface StepflowRunsTable {
-  id: string;
-  kind: string;
-  status: ExtendedRunStatus;
-  input: Record<string, unknown>;
-  context: Record<string, unknown>;
-  output: Record<string, unknown> | null;
-  error: { code: string; message: string } | null;
-  metadata: Record<string, unknown> | null;
-  priority: number;
-  timeout_ms: number | null;
-  created_at: Date;
-  started_at: Date | null;
-  finished_at: Date | null;
-}
-
-/**
- * Database table schema for step results.
- * Note: When used with Kysely, wrap auto-generated fields with Generated<T>.
- */
-export interface StepflowStepResultsTable {
-  id: string;
-  run_id: string;
-  step_name: string;
-  status: ExtendedStepStatus;
-  output: Record<string, unknown> | null;
-  error: Record<string, unknown> | null;
-  attempt: number;
-  started_at: Date | null;
-  completed_at: Date | null;
-}
-
-/**
- * Combined database schema for Stepflow.
- */
-export interface StepflowDatabase {
-  'stepflow.runs': StepflowRunsTable;
-  'stepflow.step_results': StepflowStepResultsTable;
-}

package/src/utils/errors.test.ts

@@ -1,150 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import {
-  WorkflowEngineError,
-  WorkflowNotFoundError,
-  WorkflowAlreadyRegisteredError,
-  RunNotFoundError,
-  StepError,
-  StepTimeoutError,
-  WorkflowCanceledError,
-  WorkflowTimeoutError,
-} from './errors';
-
-describe('WorkflowEngineError', () => {
-  it('should store code, message, and details', () => {
-    const err = new WorkflowEngineError('TEST_CODE', 'test message', { key: 'val' });
-
-    expect(err.code).toBe('TEST_CODE');
-    expect(err.message).toBe('test message');
-    expect(err.details).toEqual({ key: 'val' });
-    expect(err.name).toBe('WorkflowEngineError');
-    expect(err).toBeInstanceOf(Error);
-  });
-
-  it('should convert to record', () => {
-    const err = new WorkflowEngineError('CODE', 'msg', { x: 1 });
-    const record = err.toRecord();
-
-    expect(record.code).toBe('CODE');
-    expect(record.message).toBe('msg');
-    expect(record.details).toEqual({ x: 1 });
-    expect(record.stack).toBeUndefined();
-  });
-
-  describe('fromError', () => {
-    it('should convert WorkflowEngineError to record', () => {
-      const err = new WorkflowEngineError('MY_CODE', 'my msg');
-      const record = WorkflowEngineError.fromError(err);
-
-      expect(record.code).toBe('MY_CODE');
-      expect(record.message).toBe('my msg');
-    });
-
-    it('should convert regular Error to record with default code', () => {
-      const err = new Error('regular error');
-      const record = WorkflowEngineError.fromError(err);
-
-      expect(record.code).toBe('UNKNOWN_ERROR');
-      expect(record.message).toBe('regular error');
-      expect(record.stack).toBeUndefined();
-    });
-
-    it('should convert regular Error with custom code', () => {
-      const err = new Error('oops');
-      const record = WorkflowEngineError.fromError(err, 'CUSTOM_CODE');
-
-      expect(record.code).toBe('CUSTOM_CODE');
-    });
-
-    it('should convert non-Error value to record', () => {
-      const record = WorkflowEngineError.fromError('string error');
-
-      expect(record.code).toBe('UNKNOWN_ERROR');
-      expect(record.message).toBe('string error');
-      expect(record.stack).toBeUndefined();
-    });
-
-    it('should convert number to record', () => {
-      const record = WorkflowEngineError.fromError(42);
-
-      expect(record.message).toBe('42');
-    });
-  });
-});
-
-describe('WorkflowNotFoundError', () => {
-  it('should have correct code and message', () => {
-    const err = new WorkflowNotFoundError('my.workflow');
-
-    expect(err.code).toBe('WORKFLOW_NOT_FOUND');
-    expect(err.message).toBe('Workflow "my.workflow" is not registered');
-    expect(err.name).toBe('WorkflowNotFoundError');
-    expect(err.details).toEqual({ kind: 'my.workflow' });
-  });
-});
-
-describe('WorkflowAlreadyRegisteredError', () => {
-  it('should have correct code and message', () => {
-    const err = new WorkflowAlreadyRegisteredError('dup.workflow');
-
-    expect(err.code).toBe('WORKFLOW_ALREADY_REGISTERED');
-    expect(err.message).toContain('dup.workflow');
-    expect(err.name).toBe('WorkflowAlreadyRegisteredError');
-  });
-});
-
-describe('RunNotFoundError', () => {
-  it('should have correct code and message', () => {
-    const err = new RunNotFoundError('run-123');
-
-    expect(err.code).toBe('RUN_NOT_FOUND');
-    expect(err.message).toContain('run-123');
-    expect(err.name).toBe('RunNotFoundError');
-  });
-});
-
-describe('StepError', () => {
-  it('should store step key, attempt, and cause', () => {
-    const cause = new Error('root cause');
-    const err = new StepError('step1', 'step failed', 3, cause);
-
-    expect(err.code).toBe('STEP_ERROR');
-    expect(err.stepKey).toBe('step1');
-    expect(err.attempt).toBe(3);
-    expect(err.cause).toBe(cause);
-    expect(err.name).toBe('StepError');
-  });
-});
-
-describe('StepTimeoutError', () => {
-  it('should store step key and timeout', () => {
-    const err = new StepTimeoutError('slow_step', 5000);
-
-    expect(err.code).toBe('STEP_TIMEOUT');
-    expect(err.stepKey).toBe('slow_step');
-    expect(err.timeoutMs).toBe(5000);
-    expect(err.message).toContain('5000ms');
-    expect(err.name).toBe('StepTimeoutError');
-  });
-});
-
-describe('WorkflowCanceledError', () => {
-  it('should have correct code and message', () => {
-    const err = new WorkflowCanceledError('run-456');
-
-    expect(err.code).toBe('WORKFLOW_CANCELED');
-    expect(err.message).toContain('run-456');
-    expect(err.name).toBe('WorkflowCanceledError');
-  });
-});
-
-describe('WorkflowTimeoutError', () => {
-  it('should store timeout value', () => {
-    const err = new WorkflowTimeoutError('run-789', 30000);
-
-    expect(err.code).toBe('WORKFLOW_TIMEOUT');
-    expect(err.timeoutMs).toBe(30000);
-    expect(err.message).toContain('30000ms');
-    expect(err.name).toBe('WorkflowTimeoutError');
-  });
-});

package/src/utils/errors.ts

@@ -1,161 +0,0 @@
-/**
- * Custom error classes for the workflow engine.
- */
-
-import type { WorkflowError } from '../core/types';
-
-/**
- * Base error class for workflow-related errors.
- */
-export class WorkflowEngineError extends Error {
-  readonly code: string;
-  readonly details?: Record<string, unknown>;
-
-  constructor(code: string, message: string, details?: Record<string, unknown>) {
-    super(message);
-    this.name = 'WorkflowEngineError';
-    this.code = code;
-    this.details = details;
-  }
-
-  /**
-   * Convert to a WorkflowError record for storage.
-   */
-  toRecord(): WorkflowError {
-    return {
-      code: this.code,
-      message: this.message,
-      details: this.details,
-    };
-  }
-
-  /**
-   * Create a WorkflowError record from any error.
-   */
-  static fromError(error: unknown, defaultCode = 'UNKNOWN_ERROR'): WorkflowError {
-    if (error instanceof WorkflowEngineError) {
-      return error.toRecord();
-    }
-
-    if (error instanceof Error) {
-      return {
-        code: defaultCode,
-        message: error.message,
-      };
-    }
-
-    return {
-      code: defaultCode,
-      message: String(error),
-    };
-  }
-}
-
-/**
- * Error thrown when a workflow is not found in the registry.
- */
-export class WorkflowNotFoundError extends WorkflowEngineError {
-  constructor(kind: string) {
-    super('WORKFLOW_NOT_FOUND', `Workflow "${kind}" is not registered`, { kind });
-    this.name = 'WorkflowNotFoundError';
-  }
-}
-
-/**
- * Error thrown when a workflow is already registered.
- */
-export class WorkflowAlreadyRegisteredError extends WorkflowEngineError {
-  constructor(kind: string) {
-    super('WORKFLOW_ALREADY_REGISTERED', `Workflow "${kind}" is already registered`, { kind });
-    this.name = 'WorkflowAlreadyRegisteredError';
-  }
-}
-
-/**
- * Error thrown when a run is not found.
- */
-export class RunNotFoundError extends WorkflowEngineError {
-  constructor(runId: string) {
-    super('RUN_NOT_FOUND', `Run "${runId}" not found`, { runId });
-    this.name = 'RunNotFoundError';
-  }
-}
-
-/**
- * Error thrown when a step fails.
- */
-export class StepError extends WorkflowEngineError {
-  readonly stepKey: string;
-  readonly attempt: number;
-  readonly cause?: Error;
-
-  constructor(stepKey: string, message: string, attempt: number, cause?: Error) {
-    super('STEP_ERROR', message, { stepKey, attempt });
-    this.name = 'StepError';
-    this.stepKey = stepKey;
-    this.attempt = attempt;
-    this.cause = cause;
-  }
-}
-
-/**
- * Error thrown when a step times out.
- */
-export class StepTimeoutError extends WorkflowEngineError {
-  readonly stepKey: string;
-  readonly timeoutMs: number;
-
-  constructor(stepKey: string, timeoutMs: number) {
-    super('STEP_TIMEOUT', `Step "${stepKey}" timed out after ${timeoutMs}ms`, {
-      stepKey,
-      timeoutMs,
-    });
-    this.name = 'StepTimeoutError';
-    this.stepKey = stepKey;
-    this.timeoutMs = timeoutMs;
-  }
-}
-
-/**
- * Error thrown when a workflow is canceled.
- */
-export class WorkflowCanceledError extends WorkflowEngineError {
-  constructor(runId: string) {
-    super('WORKFLOW_CANCELED', `Workflow run "${runId}" was canceled`, { runId });
-    this.name = 'WorkflowCanceledError';
-  }
-}
-
-/**
- * Error thrown when waitForRun times out polling for a terminal status.
- */
-export class WaitForRunTimeoutError extends WorkflowEngineError {
-  readonly runId: string;
-  readonly timeoutMs: number;
-
-  constructor(runId: string, timeoutMs: number) {
-    super('WAIT_FOR_RUN_TIMEOUT', `Timeout waiting for run ${runId} after ${timeoutMs}ms`, {
-      runId,
-      timeoutMs,
-    });
-    this.name = 'WaitForRunTimeoutError';
-    this.runId = runId;
-    this.timeoutMs = timeoutMs;
-  }
-}
-
-/**
- * Error thrown when a workflow times out.
- */
-export class WorkflowTimeoutError extends WorkflowEngineError {
-  readonly timeoutMs: number;
-
-  constructor(runId: string, timeoutMs: number) {
-    super('WORKFLOW_TIMEOUT', `Workflow run "${runId}" timed out after ${timeoutMs}ms`, {
-      runId,
-      timeoutMs,
-    });
-    this.name = 'WorkflowTimeoutError';
-    this.timeoutMs = timeoutMs;
-  }
-}

package/src/utils/id.ts

@@ -1,21 +0,0 @@
-/**
- * ID generation utilities for the workflow engine.
- */
-
-import { randomBytes } from 'node:crypto';
-
-/**
- * Generate a unique ID for database records.
- * Uses a ULID-like format: base36 timestamp + random suffix.
- * This provides:
- * - Rough time-ordering (useful for debugging)
- * - High collision resistance
- * - URL-safe characters
- *
- * @returns A unique identifier string (approx 16 characters)
- */
-export function generateId(): string {
-  const timestamp = Date.now().toString(36);
-  const randomPart = randomBytes(6).toString('base64url');
-  return `${timestamp}${randomPart}`;
-}

package/src/utils/index.ts

@@ -1,10 +0,0 @@
-/**
- * Utilities module exports.
- */
-
-export * from './id';
-export * from './errors';
-export * from './logger';
-export * from './retry';
-export * from './safe-json';
-export * from './webhook-signature';