@multiplier-labs/stepflow 0.3.1

package/src/storage/types.ts

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

@@ -0,0 +1,152 @@
+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).toBeDefined();
+  });
+
+  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).toBeDefined();
+    });
+
+    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

@@ -0,0 +1,191 @@
+/**
+ * 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,
+      stack: this.stack,
+      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,
+        stack: error.stack,
+      };
+    }
+
+    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;
+  }
+}