@multiplier-labs/stepflow 0.3.1 → 0.3.4

package/src/storage/types.ts

@@ -3,12 +3,7 @@
  * Implement StorageAdapter to use your preferred database.
  */
 
-import type {
-  WorkflowKind,
-  RunStatus,
-  StepStatus,
-  WorkflowError,
-} from "../core/types";
+import type { WorkflowKind, RunStatus, StepStatus, WorkflowError } from '../core/types';
 
 // ============================================================================
 // Extended Status Types (New)
@@ -19,25 +14,25 @@ import type {
  * Adds 'pending' and 'timeout' to the core statuses.
  */
 export type ExtendedRunStatus =
-  | "pending"
-  | "queued"
-  | "running"
-  | "succeeded"
-  | "failed"
-  | "canceled"
-  | "timeout";
+  | '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";
+  | 'pending'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'skipped'
+  | 'canceled';
 
 // ============================================================================
 // Legacy Record Types (Backward Compatible)
@@ -53,6 +48,7 @@ export interface WorkflowRunRecord {
   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>;
@@ -87,7 +83,7 @@ export interface WorkflowEventRecord {
   runId: string;
   stepKey?: string;
   eventType: string;
-  level: "info" | "warn" | "error";
+  level: 'info' | 'warn' | 'error';
   payload?: unknown;
   timestamp: Date;
 }
@@ -189,8 +185,8 @@ export interface ListRunsOptions {
   parentRunId?: string;
   limit?: number;
   offset?: number;
-  orderBy?: "createdAt" | "startedAt" | "finishedAt";
-  orderDirection?: "asc" | "desc";
+  orderBy?: 'createdAt' | 'startedAt' | 'finishedAt';
+  orderDirection?: 'asc' | 'desc';
 }
 
 /**
@@ -201,8 +197,8 @@ export interface ExtendedListRunsOptions {
   status?: ExtendedRunStatus | ExtendedRunStatus[];
   limit?: number;
   offset?: number;
-  orderBy?: "createdAt" | "startedAt" | "finishedAt";
-  orderDir?: "asc" | "desc";
+  orderBy?: 'createdAt' | 'startedAt' | 'finishedAt';
+  orderDir?: 'asc' | 'desc';
 }
 
 /**
@@ -210,7 +206,7 @@ export interface ExtendedListRunsOptions {
  */
 export interface ListEventsOptions {
   stepKey?: string;
-  level?: "info" | "warn" | "error";
+  level?: 'info' | 'warn' | 'error';
   limit?: number;
   offset?: number;
 }
@@ -238,30 +234,21 @@ export interface WorkflowStorage {
   createRun(run: CreateRunInput): Promise<ExtendedWorkflowRunRecord>;
   getRun(id: string): Promise<ExtendedWorkflowRunRecord | null>;
   updateRun(id: string, updates: UpdateRunInput): Promise<void>;
-  listRuns(
-    options?: ExtendedListRunsOptions,
-  ): Promise<PaginatedResult<ExtendedWorkflowRunRecord>>;
+  listRuns(options?: ExtendedListRunsOptions): Promise<PaginatedResult<ExtendedWorkflowRunRecord>>;
   deleteRun(id: string): Promise<void>;
 
   // Atomic dequeue for concurrency control
-  dequeueRun(
-    workflowKinds: string[],
-  ): Promise<ExtendedWorkflowRunRecord | null>;
+  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>;
+  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>;
+  saveStepResult(result: Omit<StepResult, 'id'> & { id?: string }): Promise<void>;
 
   // Lifecycle
   initialize(): Promise<void>;
@@ -278,32 +265,20 @@ export interface WorkflowStorage {
  */
 export interface StorageAdapter {
   // Run operations
-  createRun(
-    run: Omit<WorkflowRunRecord, "id" | "createdAt">,
-  ): Promise<WorkflowRunRecord>;
+  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>>;
+  listRuns(options?: ListRunsOptions): Promise<PaginatedResult<WorkflowRunRecord>>;
 
   // Step operations
-  createStep(
-    step: Omit<WorkflowRunStepRecord, "id">,
-  ): Promise<WorkflowRunStepRecord>;
+  createStep(step: Omit<WorkflowRunStepRecord, 'id'>): Promise<WorkflowRunStepRecord>;
   getStep(stepId: string): Promise<WorkflowRunStepRecord | null>;
-  updateStep(
-    stepId: string,
-    updates: Partial<WorkflowRunStepRecord>,
-  ): Promise<void>;
+  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[]>;
+  saveEvent(event: Omit<WorkflowEventRecord, 'id'>): Promise<void>;
+  getEventsForRun(runId: string, options?: ListEventsOptions): Promise<WorkflowEventRecord[]>;
 
   /**
    * Optional transaction support.
@@ -363,6 +338,6 @@ export interface StepflowStepResultsTable {
  * Combined database schema for Stepflow.
  */
 export interface StepflowDatabase {
-  "stepflow.runs": StepflowRunsTable;
-  "stepflow.step_results": StepflowStepResultsTable;
+  'stepflow.runs': StepflowRunsTable;
+  'stepflow.step_results': StepflowStepResultsTable;
 }

package/src/utils/errors.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect } from 'vitest';
 import {
   WorkflowEngineError,
   WorkflowNotFoundError,
@@ -8,145 +8,143 @@ import {
   StepTimeoutError,
   WorkflowCanceledError,
   WorkflowTimeoutError,
-} from "./errors";
+} from './errors';
 
-describe("WorkflowEngineError", () => {
-  it("should store code, message, and details", () => {
-    const err = new WorkflowEngineError("TEST_CODE", "test message", {
-      key: "val",
-    });
+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.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 });
+  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.code).toBe('CODE');
+    expect(record.message).toBe('msg');
     expect(record.details).toEqual({ x: 1 });
-    expect(record.stack).toBeDefined();
+    expect(record.stack).toBeUndefined();
   });
 
-  describe("fromError", () => {
-    it("should convert WorkflowEngineError to record", () => {
-      const err = new WorkflowEngineError("MY_CODE", "my msg");
+  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");
+      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");
+    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();
+      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");
+    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");
+      expect(record.code).toBe('CUSTOM_CODE');
     });
 
-    it("should convert non-Error value to record", () => {
-      const record = WorkflowEngineError.fromError("string error");
+    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.code).toBe('UNKNOWN_ERROR');
+      expect(record.message).toBe('string error');
       expect(record.stack).toBeUndefined();
     });
 
-    it("should convert number to record", () => {
+    it('should convert number to record', () => {
       const record = WorkflowEngineError.fromError(42);
 
-      expect(record.message).toBe("42");
+      expect(record.message).toBe('42');
     });
   });
 });
 
-describe("WorkflowNotFoundError", () => {
-  it("should have correct code and message", () => {
-    const err = new WorkflowNotFoundError("my.workflow");
+describe('WorkflowNotFoundError', () => {
+  it('should have correct code and message', () => {
+    const err = new WorkflowNotFoundError('my.workflow');
 
-    expect(err.code).toBe("WORKFLOW_NOT_FOUND");
+    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" });
+    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");
+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");
+    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");
+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");
+    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);
+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.code).toBe('STEP_ERROR');
+    expect(err.stepKey).toBe('step1');
     expect(err.attempt).toBe(3);
     expect(err.cause).toBe(cause);
-    expect(err.name).toBe("StepError");
+    expect(err.name).toBe('StepError');
   });
 });
 
-describe("StepTimeoutError", () => {
-  it("should store step key and timeout", () => {
-    const err = new StepTimeoutError("slow_step", 5000);
+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.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");
+    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");
+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");
+    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);
+describe('WorkflowTimeoutError', () => {
+  it('should store timeout value', () => {
+    const err = new WorkflowTimeoutError('run-789', 30000);
 
-    expect(err.code).toBe("WORKFLOW_TIMEOUT");
+    expect(err.code).toBe('WORKFLOW_TIMEOUT');
     expect(err.timeoutMs).toBe(30000);
-    expect(err.message).toContain("30000ms");
-    expect(err.name).toBe("WorkflowTimeoutError");
+    expect(err.message).toContain('30000ms');
+    expect(err.name).toBe('WorkflowTimeoutError');
   });
 });

package/src/utils/errors.ts

@@ -2,7 +2,7 @@
  * Custom error classes for the workflow engine.
  */
 
-import type { WorkflowError } from "../core/types";
+import type { WorkflowError } from '../core/types';
 
 /**
  * Base error class for workflow-related errors.
@@ -11,13 +11,9 @@ export class WorkflowEngineError extends Error {
   readonly code: string;
   readonly details?: Record<string, unknown>;
 
-  constructor(
-    code: string,
-    message: string,
-    details?: Record<string, unknown>,
-  ) {
+  constructor(code: string, message: string, details?: Record<string, unknown>) {
     super(message);
-    this.name = "WorkflowEngineError";
+    this.name = 'WorkflowEngineError';
     this.code = code;
     this.details = details;
   }
@@ -29,7 +25,6 @@ export class WorkflowEngineError extends Error {
     return {
       code: this.code,
       message: this.message,
-      stack: this.stack,
       details: this.details,
     };
   }
@@ -37,10 +32,7 @@ export class WorkflowEngineError extends Error {
   /**
    * Create a WorkflowError record from any error.
    */
-  static fromError(
-    error: unknown,
-    defaultCode = "UNKNOWN_ERROR",
-  ): WorkflowError {
+  static fromError(error: unknown, defaultCode = 'UNKNOWN_ERROR'): WorkflowError {
     if (error instanceof WorkflowEngineError) {
       return error.toRecord();
     }
@@ -49,7 +41,6 @@ export class WorkflowEngineError extends Error {
       return {
         code: defaultCode,
         message: error.message,
-        stack: error.stack,
       };
     }
 
@@ -65,10 +56,8 @@ export class WorkflowEngineError extends Error {
  */
 export class WorkflowNotFoundError extends WorkflowEngineError {
   constructor(kind: string) {
-    super("WORKFLOW_NOT_FOUND", `Workflow "${kind}" is not registered`, {
-      kind,
-    });
-    this.name = "WorkflowNotFoundError";
+    super('WORKFLOW_NOT_FOUND', `Workflow "${kind}" is not registered`, { kind });
+    this.name = 'WorkflowNotFoundError';
   }
 }
 
@@ -77,12 +66,8 @@ export class WorkflowNotFoundError extends WorkflowEngineError {
  */
 export class WorkflowAlreadyRegisteredError extends WorkflowEngineError {
   constructor(kind: string) {
-    super(
-      "WORKFLOW_ALREADY_REGISTERED",
-      `Workflow "${kind}" is already registered`,
-      { kind },
-    );
-    this.name = "WorkflowAlreadyRegisteredError";
+    super('WORKFLOW_ALREADY_REGISTERED', `Workflow "${kind}" is already registered`, { kind });
+    this.name = 'WorkflowAlreadyRegisteredError';
   }
 }
 
@@ -91,8 +76,8 @@ export class WorkflowAlreadyRegisteredError extends WorkflowEngineError {
  */
 export class RunNotFoundError extends WorkflowEngineError {
   constructor(runId: string) {
-    super("RUN_NOT_FOUND", `Run "${runId}" not found`, { runId });
-    this.name = "RunNotFoundError";
+    super('RUN_NOT_FOUND', `Run "${runId}" not found`, { runId });
+    this.name = 'RunNotFoundError';
   }
 }
 
@@ -104,14 +89,9 @@ export class StepError extends WorkflowEngineError {
   readonly attempt: number;
   readonly cause?: Error;
 
-  constructor(
-    stepKey: string,
-    message: string,
-    attempt: number,
-    cause?: Error,
-  ) {
-    super("STEP_ERROR", message, { stepKey, attempt });
-    this.name = "StepError";
+  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;
@@ -126,11 +106,11 @@ export class StepTimeoutError extends WorkflowEngineError {
   readonly timeoutMs: number;
 
   constructor(stepKey: string, timeoutMs: number) {
-    super("STEP_TIMEOUT", `Step "${stepKey}" timed out after ${timeoutMs}ms`, {
+    super('STEP_TIMEOUT', `Step "${stepKey}" timed out after ${timeoutMs}ms`, {
       stepKey,
       timeoutMs,
     });
-    this.name = "StepTimeoutError";
+    this.name = 'StepTimeoutError';
     this.stepKey = stepKey;
     this.timeoutMs = timeoutMs;
   }
@@ -141,10 +121,8 @@ export class StepTimeoutError extends WorkflowEngineError {
  */
 export class WorkflowCanceledError extends WorkflowEngineError {
   constructor(runId: string) {
-    super("WORKFLOW_CANCELED", `Workflow run "${runId}" was canceled`, {
-      runId,
-    });
-    this.name = "WorkflowCanceledError";
+    super('WORKFLOW_CANCELED', `Workflow run "${runId}" was canceled`, { runId });
+    this.name = 'WorkflowCanceledError';
   }
 }
 
@@ -156,15 +134,11 @@ export class WaitForRunTimeoutError extends WorkflowEngineError {
   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";
+    super('WAIT_FOR_RUN_TIMEOUT', `Timeout waiting for run ${runId} after ${timeoutMs}ms`, {
+      runId,
+      timeoutMs,
+    });
+    this.name = 'WaitForRunTimeoutError';
     this.runId = runId;
     this.timeoutMs = timeoutMs;
   }
@@ -177,15 +151,11 @@ 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";
+    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,7 +1,8 @@
 /**
  * ID generation utilities for the workflow engine.
  */
-import { randomBytes } from "node:crypto";
+
+import { randomBytes } from 'node:crypto';
 
 /**
  * Generate a unique ID for database records.
@@ -10,12 +11,11 @@ import { randomBytes } from "node:crypto";
  * - Rough time-ordering (useful for debugging)
  * - High collision resistance
  * - URL-safe characters
- * - Cryptographically secure random component
  *
  * @returns A unique identifier string (approx 16 characters)
  */
 export function generateId(): string {
   const timestamp = Date.now().toString(36);
-  const randomPart = randomBytes(6).toString("base64url");
+  const randomPart = randomBytes(6).toString('base64url');
   return `${timestamp}${randomPart}`;
 }

package/src/utils/index.ts

@@ -2,7 +2,9 @@
  * Utilities module exports.
  */
 
-export * from "./id";
-export * from "./errors";
-export * from "./logger";
-export * from "./retry";
+export * from './id';
+export * from './errors';
+export * from './logger';
+export * from './retry';
+export * from './safe-json';
+export * from './webhook-signature';