@multiplier-labs/stepflow 0.3.1 → 0.3.3

package/src/core/orchestrator.ts

@@ -13,18 +13,12 @@ import type {
   RunResult,
   Logger,
   SpawnChildOptions,
-} from "./types";
-import type { StorageAdapter } from "../storage/types";
-import type { EventTransport, WorkflowEvent } from "../events/types";
-import {
-  WorkflowEngineError,
-  StepError,
-  StepTimeoutError,
-  WorkflowCanceledError,
-  WorkflowTimeoutError,
-} from "../utils/errors";
-import { createScopedLogger } from "../utils/logger";
-import { sleep, calculateRetryDelay } from "../utils/retry";
+} from './types';
+import type { StorageAdapter } from '../storage/types';
+import type { EventTransport, WorkflowEvent } from '../events/types';
+import { WorkflowEngineError, StepError, StepTimeoutError, WorkflowCanceledError, WorkflowTimeoutError } from '../utils/errors';
+import { createScopedLogger } from '../utils/logger';
+import { sleep, calculateRetryDelay } from '../utils/retry';
 
 /**
  * Checkpoint data for resuming workflows.
@@ -66,9 +60,7 @@ export interface ExecuteOptions {
  * Execute a workflow definition.
  * This is the main execution logic that runs all steps sequentially.
  */
-export async function executeWorkflow(
-  options: ExecuteOptions,
-): Promise<RunResult> {
+export async function executeWorkflow(options: ExecuteOptions): Promise<RunResult> {
   const {
     runId,
     definition,
@@ -88,24 +80,25 @@ export async function executeWorkflow(
   // Update run status to running (if not already)
   // On resume, don't overwrite the original startedAt
   await storage.updateRun(runId, {
-    status: "running",
+    status: 'running',
     ...(isResume ? {} : { startedAt: new Date() }),
   });
 
   emitEvent(events, logger, {
     runId,
     kind: definition.kind,
-    eventType: isResume ? "run.resumed" : "run.started",
+    eventType: isResume ? 'run.resumed' : 'run.started',
     timestamp: new Date(),
-    payload: isResume
-      ? { resumedFrom: Array.from(checkpoint.completedStepKeys) }
-      : undefined,
+    payload: isResume ? { resumedFrom: Array.from(checkpoint.completedStepKeys) } : undefined,
   });
 
+  // Track completed step keys for checkpoint persistence
+  const completedSteps: string[] = checkpoint ? Array.from(checkpoint.completedStepKeys) : [];
+
   // Build the execution context, using checkpoint results if resuming
   const context: WorkflowContext = {
     runId,
-    stepId: "", // Will be set for each step before handler is called
+    stepId: '',  // Will be set for each step before handler is called
     kind: definition.kind,
     input,
     results: checkpoint?.results ? { ...checkpoint.results } : {},
@@ -130,10 +123,7 @@ export async function executeWorkflow(
 
   if (definition.timeout) {
     workflowTimeoutId = setTimeout(() => {
-      workflowTimeoutError = new WorkflowTimeoutError(
-        runId,
-        definition.timeout!,
-      );
+      workflowTimeoutError = new WorkflowTimeoutError(runId, definition.timeout!);
       abortController.abort();
     }, definition.timeout);
   }
@@ -155,16 +145,14 @@ export async function executeWorkflow(
 
       // Skip already completed steps when resuming
       if (checkpoint?.completedStepKeys.has(step.key)) {
-        logger.info(
-          `Skipping step "${step.key}" (already completed in previous run)`,
-        );
+        logger.info(`Skipping step "${step.key}" (already completed in previous run)`);
         emitEvent(events, logger, {
           runId,
           kind: definition.kind,
-          eventType: "step.skipped",
+          eventType: 'step.skipped',
           stepKey: step.key,
           timestamp: new Date(),
-          payload: { reason: "checkpoint" },
+          payload: { reason: 'checkpoint' },
         });
         continue;
       }
@@ -178,7 +166,7 @@ export async function executeWorkflow(
           emitEvent(events, logger, {
             runId,
             kind: definition.kind,
-            eventType: "step.skipped",
+            eventType: 'step.skipped',
             stepKey: step.key,
             timestamp: new Date(),
           });
@@ -199,9 +187,13 @@ export async function executeWorkflow(
       // Store result in context
       context.results[step.key] = result;
 
-      // Save checkpoint (accumulated results)
+      // Track completed step
+      completedSteps.push(step.key);
+
+      // Save checkpoint (accumulated results + completed steps)
       await storage.updateRun(runId, {
         context: { ...context.results },
+        completedSteps: [...completedSteps],
       });
     }
 
@@ -213,7 +205,7 @@ export async function executeWorkflow(
 
     const duration = Date.now() - startTime;
     const runResult: RunResult = {
-      status: "succeeded",
+      status: 'succeeded',
       results: context.results,
       duration,
     };
@@ -225,7 +217,7 @@ export async function executeWorkflow(
 
     // Update run status
     await storage.updateRun(runId, {
-      status: "succeeded",
+      status: 'succeeded',
       context: context.results,
       finishedAt: new Date(),
     });
@@ -233,12 +225,13 @@ export async function executeWorkflow(
     emitEvent(events, logger, {
       runId,
       kind: definition.kind,
-      eventType: "run.completed",
+      eventType: 'run.completed',
       timestamp: new Date(),
       payload: { results: context.results, duration },
     });
 
     return runResult;
+
   } catch (error) {
     // Clear workflow timeout
     if (workflowTimeoutId) {
@@ -253,14 +246,9 @@ export async function executeWorkflow(
 
     // Determine final status
     const isTimeout = actualError instanceof WorkflowTimeoutError;
-    const isCanceled =
-      !isTimeout && actualError instanceof WorkflowCanceledError;
-    const status = isCanceled ? "canceled" : "failed";
-    const eventType = isTimeout
-      ? "run.timeout"
-      : isCanceled
-        ? "run.canceled"
-        : "run.failed";
+    const isCanceled = !isTimeout && actualError instanceof WorkflowCanceledError;
+    const status = isCanceled ? 'canceled' : 'failed';
+    const eventType = isTimeout ? 'run.timeout' : (isCanceled ? 'run.canceled' : 'run.failed');
 
     const runResult: RunResult = {
       status,
@@ -274,7 +262,7 @@ export async function executeWorkflow(
       try {
         await definition.hooks.afterRun(context, runResult);
       } catch (hookError) {
-        logger.error("afterRun hook failed:", hookError);
+        logger.error('afterRun hook failed for run ' + runId + ':', hookError);
       }
     }
 
@@ -315,12 +303,12 @@ interface StepExecutionOptions<TInput = Record<string, unknown>> {
 async function executeStep<TInput>(
   step: WorkflowStep<TInput>,
   context: WorkflowContext<TInput>,
-  options: StepExecutionOptions<TInput>,
+  options: StepExecutionOptions<TInput>
 ): Promise<unknown> {
   const { definition, storage, events, logger, abortController } = options;
 
   // Determine error strategy
-  const onError = step.onError ?? definition.defaultOnError ?? "fail";
+  const onError = step.onError ?? definition.defaultOnError ?? 'fail';
   const maxRetries = step.maxRetries ?? 3;
   const retryDelay = step.retryDelay ?? 1000;
   const retryBackoff = step.retryBackoff ?? 2;
@@ -341,7 +329,7 @@ async function executeStep<TInput>(
       runId: context.runId,
       stepKey: step.key,
       stepName: step.name,
-      status: "running",
+      status: 'running',
       attempt,
       startedAt: new Date(),
     });
@@ -353,7 +341,7 @@ async function executeStep<TInput>(
     emitEvent(events, logger, {
       runId: context.runId,
       kind: context.kind,
-      eventType: "step.started",
+      eventType: 'step.started',
       stepKey: step.key,
       timestamp: new Date(),
       payload: { attempt },
@@ -374,19 +362,19 @@ async function executeStep<TInput>(
           () => step.handler(context),
           step.timeout,
           abortController.signal,
-          step.key,
+          step.key
         );
       } else {
         // Race step handler against abort signal for workflow-level timeout support
         result = await raceWithAbort(
           step.handler(context),
-          abortController.signal,
+          abortController.signal
         );
       }
 
       // Step succeeded
       await storage.updateStep(stepRecord.id, {
-        status: "succeeded",
+        status: 'succeeded',
         result,
         finishedAt: new Date(),
       });
@@ -399,24 +387,23 @@ async function executeStep<TInput>(
       emitEvent(events, logger, {
         runId: context.runId,
         kind: context.kind,
-        eventType: "step.completed",
+        eventType: 'step.completed',
         stepKey: step.key,
         timestamp: new Date(),
         payload: { result },
       });
 
       return result;
+
     } catch (error) {
       lastError = error instanceof Error ? error : new Error(String(error));
 
       // Check if this is a cancellation (abort signal fired)
-      const isCanceled =
-        error instanceof WorkflowCanceledError ||
-        abortController.signal.aborted;
+      const isCanceled = error instanceof WorkflowCanceledError || abortController.signal.aborted;
 
       // Update step record with error
       await storage.updateStep(stepRecord.id, {
-        status: isCanceled ? "canceled" : "failed",
+        status: isCanceled ? 'canceled' : 'failed',
         error: WorkflowEngineError.fromError(error),
         finishedAt: new Date(),
       });
@@ -426,7 +413,7 @@ async function executeStep<TInput>(
         emitEvent(events, logger, {
           runId: context.runId,
           kind: context.kind,
-          eventType: "step.failed",
+          eventType: 'step.failed',
           stepKey: step.key,
           timestamp: new Date(),
           payload: { error: lastError.message, attempt },
@@ -439,43 +426,41 @@ async function executeStep<TInput>(
         try {
           await definition.hooks.onStepError(context, step, lastError);
         } catch (hookError) {
-          logger.error("onStepError hook failed:", hookError);
+          logger.error('onStepError hook failed for run ' + context.runId + ':', hookError);
         }
       }
 
       emitEvent(events, logger, {
         runId: context.runId,
         kind: context.kind,
-        eventType: "step.failed",
+        eventType: 'step.failed',
         stepKey: step.key,
         timestamp: new Date(),
         payload: { error: lastError.message, attempt },
       });
 
       // Handle error based on strategy
-      if (onError === "skip") {
+      if (onError === 'skip') {
         logger.warn(`Step "${step.key}" failed, skipping (strategy: skip)`);
         emitEvent(events, logger, {
           runId: context.runId,
           kind: context.kind,
-          eventType: "step.skipped",
+          eventType: 'step.skipped',
           stepKey: step.key,
           timestamp: new Date(),
-          payload: { reason: "error", error: lastError.message },
+          payload: { reason: 'error', error: lastError.message },
         });
         return undefined;
       }
 
-      if (onError === "retry" && attempt <= maxRetries) {
+      if (onError === 'retry' && attempt <= maxRetries) {
         const delay = calculateRetryDelay(attempt, retryDelay, retryBackoff);
-        logger.warn(
-          `Step "${step.key}" failed, retrying in ${delay}ms (attempt ${attempt}/${maxRetries})`,
-        );
+        logger.warn(`Step "${step.key}" failed, retrying in ${delay}ms (attempt ${attempt}/${maxRetries})`);
 
         emitEvent(events, logger, {
           runId: context.runId,
           kind: context.kind,
-          eventType: "step.retry",
+          eventType: 'step.retry',
           stepKey: step.key,
           timestamp: new Date(),
           payload: { attempt, maxRetries, delay, error: lastError.message },
@@ -486,7 +471,7 @@ async function executeStep<TInput>(
         } catch (sleepError) {
           if (sleepError instanceof WorkflowCanceledError) {
             await storage.updateStep(stepRecord.id, {
-              status: "canceled",
+              status: 'canceled',
               finishedAt: new Date(),
             });
           }
@@ -513,7 +498,7 @@ async function executeWithTimeout<T>(
   fn: () => Promise<T>,
   timeoutMs: number,
   signal: AbortSignal,
-  stepKey: string,
+  stepKey: string
 ): Promise<T> {
   let timeoutId: ReturnType<typeof setTimeout> | undefined;
   let onAbort: (() => void) | undefined;
@@ -528,14 +513,14 @@ async function executeWithTimeout<T>(
 
         onAbort = () => {
           clearTimeout(timeoutId);
-          reject(new WorkflowCanceledError("run"));
+          reject(new WorkflowCanceledError('run'));
         };
-        signal.addEventListener("abort", onAbort, { once: true });
+        signal.addEventListener('abort', onAbort, { once: true });
       }),
     ]);
   } finally {
     if (timeoutId) clearTimeout(timeoutId);
-    if (onAbort) signal.removeEventListener("abort", onAbort);
+    if (onAbort) signal.removeEventListener('abort', onAbort);
   }
 }
 
@@ -552,10 +537,10 @@ async function executeWithTimeout<T>(
  */
 async function raceWithAbort<T>(
   promise: Promise<T>,
-  signal: AbortSignal,
+  signal: AbortSignal
 ): Promise<T> {
   if (signal.aborted) {
-    throw new WorkflowCanceledError("run");
+    throw new WorkflowCanceledError('run');
   }
 
   let onAbort: (() => void) | undefined;
@@ -564,27 +549,23 @@ async function raceWithAbort<T>(
     return await Promise.race([
       promise,
       new Promise<never>((_, reject) => {
-        onAbort = () => reject(new WorkflowCanceledError("run"));
-        signal.addEventListener("abort", onAbort, { once: true });
+        onAbort = () => reject(new WorkflowCanceledError('run'));
+        signal.addEventListener('abort', onAbort, { once: true });
       }),
     ]);
   } finally {
-    if (onAbort) signal.removeEventListener("abort", onAbort);
+    if (onAbort) signal.removeEventListener('abort', onAbort);
   }
 }
 
 /**
  * Helper to emit an event.
  */
-function emitEvent(
-  events: EventTransport,
-  logger: Logger,
-  event: WorkflowEvent,
-): void {
+function emitEvent(events: EventTransport, logger: Logger, event: WorkflowEvent): void {
   try {
     events.emit(event);
   } catch (error) {
     // Log but don't fail the workflow for event emission errors
-    logger.error("Failed to emit event:", error);
+    logger.error('Failed to emit event:', error);
   }
 }

package/src/core/types.ts

@@ -16,23 +16,12 @@ export type WorkflowKind = string;
 /**
  * Status of a workflow run.
  */
-export type RunStatus =
-  | "queued"
-  | "running"
-  | "succeeded"
-  | "failed"
-  | "canceled";
+export type RunStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled';
 
 /**
  * Status of a workflow step.
  */
-export type StepStatus =
-  | "pending"
-  | "running"
-  | "succeeded"
-  | "failed"
-  | "skipped"
-  | "canceled";
+export type StepStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'skipped' | 'canceled';
 
 /**
  * Error handling strategy for a step.
@@ -40,7 +29,7 @@ export type StepStatus =
  * - 'retry': Retry the step up to maxRetries times
  * - 'skip': Mark as skipped and continue to next step
  */
-export type StepErrorStrategy = "fail" | "retry" | "skip";
+export type StepErrorStrategy = 'fail' | 'retry' | 'skip';
 
 // ============================================================================
 // Error Types
@@ -60,7 +49,7 @@ export interface WorkflowError {
  * Result of a completed workflow run.
  */
 export interface RunResult {
-  status: "succeeded" | "failed" | "canceled";
+  status: 'succeeded' | 'failed' | 'canceled';
   results: Record<string, unknown>;
   error?: WorkflowError;
   duration: number;
@@ -190,24 +179,13 @@ export interface WorkflowHooks<TInput = Record<string, unknown>> {
   afterRun?: (ctx: WorkflowContext<TInput>, result: RunResult) => Promise<void>;
 
   /** Called before each step */
-  beforeStep?: (
-    ctx: WorkflowContext<TInput>,
-    step: WorkflowStep<TInput>,
-  ) => Promise<void>;
+  beforeStep?: (ctx: WorkflowContext<TInput>, step: WorkflowStep<TInput>) => Promise<void>;
 
   /** Called after each step (success only) */
-  afterStep?: (
-    ctx: WorkflowContext<TInput>,
-    step: WorkflowStep<TInput>,
-    result: unknown,
-  ) => Promise<void>;
+  afterStep?: (ctx: WorkflowContext<TInput>, step: WorkflowStep<TInput>, result: unknown) => Promise<void>;
 
   /** Called when a step fails */
-  onStepError?: (
-    ctx: WorkflowContext<TInput>,
-    step: WorkflowStep<TInput>,
-    error: Error,
-  ) => Promise<void>;
+  onStepError?: (ctx: WorkflowContext<TInput>, step: WorkflowStep<TInput>, error: Error) => Promise<void>;
 }
 
 // ============================================================================

package/src/events/index.ts

@@ -2,7 +2,7 @@
  * Events module exports.
  */
 
-export * from "./types";
-export * from "./memory";
-export * from "./socketio";
-export * from "./webhook";
+export * from './types';
+export * from './memory';
+export * from './socketio';
+export * from './webhook';

package/src/events/memory.test.ts

@@ -1,96 +1,94 @@
-import { describe, it, expect, beforeEach, vi } from "vitest";
-import { MemoryEventTransport } from "./memory";
-import type { WorkflowEvent, WorkflowEventType } from "./types";
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { MemoryEventTransport } from './memory';
+import type { WorkflowEvent, WorkflowEventType } from './types';
 
-function createTestEvent(
-  overrides: Partial<WorkflowEvent> = {},
-): WorkflowEvent {
+function createTestEvent(overrides: Partial<WorkflowEvent> = {}): WorkflowEvent {
   return {
-    eventType: "run.started",
-    runId: "run-123",
-    kind: "test.workflow",
-    timestamp: new Date("2024-01-01T12:00:00Z"),
+    eventType: 'run.started',
+    runId: 'run-123',
+    kind: 'test.workflow',
+    timestamp: new Date('2024-01-01T12:00:00Z'),
     ...overrides,
   };
 }
 
-describe("MemoryEventTransport", () => {
+describe('MemoryEventTransport', () => {
   let transport: MemoryEventTransport;
 
   beforeEach(() => {
     transport = new MemoryEventTransport();
   });
 
-  describe("subscribeToType", () => {
-    it("should call callback when event of matching type is emitted", () => {
+  describe('subscribeToType', () => {
+    it('should call callback when event of matching type is emitted', () => {
       const callback = vi.fn();
-      transport.subscribeToType("run.completed", callback);
+      transport.subscribeToType('run.completed', callback);
 
-      const event = createTestEvent({ eventType: "run.completed" });
+      const event = createTestEvent({ eventType: 'run.completed' });
       transport.emit(event);
 
       expect(callback).toHaveBeenCalledWith(event);
     });
 
-    it("should not call callback for events of a different type", () => {
+    it('should not call callback for events of a different type', () => {
       const callback = vi.fn();
-      transport.subscribeToType("run.completed", callback);
+      transport.subscribeToType('run.completed', callback);
 
-      transport.emit(createTestEvent({ eventType: "run.started" }));
+      transport.emit(createTestEvent({ eventType: 'run.started' }));
 
       expect(callback).not.toHaveBeenCalled();
     });
 
-    it("should unsubscribe when calling the returned function", () => {
+    it('should unsubscribe when calling the returned function', () => {
       const callback = vi.fn();
-      const unsubscribe = transport.subscribeToType("run.completed", callback);
+      const unsubscribe = transport.subscribeToType('run.completed', callback);
 
       // Emit once before unsubscribe
-      transport.emit(createTestEvent({ eventType: "run.completed" }));
+      transport.emit(createTestEvent({ eventType: 'run.completed' }));
       expect(callback).toHaveBeenCalledTimes(1);
 
       unsubscribe();
 
       // Emit again after unsubscribe
-      transport.emit(createTestEvent({ eventType: "run.completed" }));
+      transport.emit(createTestEvent({ eventType: 'run.completed' }));
       expect(callback).toHaveBeenCalledTimes(1);
     });
 
-    it("should support multiple type subscriptions independently", () => {
+    it('should support multiple type subscriptions independently', () => {
       const completedCb = vi.fn();
       const failedCb = vi.fn();
-      transport.subscribeToType("run.completed", completedCb);
-      transport.subscribeToType("run.failed", failedCb);
+      transport.subscribeToType('run.completed', completedCb);
+      transport.subscribeToType('run.failed', failedCb);
 
-      transport.emit(createTestEvent({ eventType: "run.completed" }));
+      transport.emit(createTestEvent({ eventType: 'run.completed' }));
 
       expect(completedCb).toHaveBeenCalledTimes(1);
       expect(failedCb).not.toHaveBeenCalled();
     });
   });
 
-  describe("getListenerCount", () => {
-    it("should return 0 when no listeners are registered", () => {
+  describe('getListenerCount', () => {
+    it('should return 0 when no listeners are registered', () => {
       expect(transport.getListenerCount()).toBe(0);
     });
 
-    it("should return global listener count when called without channel", () => {
+    it('should return global listener count when called without channel', () => {
       transport.subscribeAll(vi.fn());
       transport.subscribeAll(vi.fn());
 
       expect(transport.getListenerCount()).toBe(2);
     });
 
-    it("should return channel-specific listener count when called with channel", () => {
-      transport.subscribe("run-1", vi.fn());
-      transport.subscribe("run-1", vi.fn());
-      transport.subscribe("run-2", vi.fn());
+    it('should return channel-specific listener count when called with channel', () => {
+      transport.subscribe('run-1', vi.fn());
+      transport.subscribe('run-1', vi.fn());
+      transport.subscribe('run-2', vi.fn());
 
-      expect(transport.getListenerCount("run:run-1")).toBe(2);
-      expect(transport.getListenerCount("run:run-2")).toBe(1);
+      expect(transport.getListenerCount('run:run-1')).toBe(2);
+      expect(transport.getListenerCount('run:run-2')).toBe(1);
     });
 
-    it("should update count after subscribe and unsubscribe", () => {
+    it('should update count after subscribe and unsubscribe', () => {
       const unsub = transport.subscribeAll(vi.fn());
       expect(transport.getListenerCount()).toBe(1);
 
@@ -98,12 +96,12 @@ describe("MemoryEventTransport", () => {
       expect(transport.getListenerCount()).toBe(0);
     });
 
-    it("should return count for type-based channels", () => {
-      transport.subscribeToType("step.completed", vi.fn());
-      transport.subscribeToType("step.completed", vi.fn());
+    it('should return count for type-based channels', () => {
+      transport.subscribeToType('step.completed', vi.fn());
+      transport.subscribeToType('step.completed', vi.fn());
 
-      expect(transport.getListenerCount("type:step.completed")).toBe(2);
-      expect(transport.getListenerCount("type:step.failed")).toBe(0);
+      expect(transport.getListenerCount('type:step.completed')).toBe(2);
+      expect(transport.getListenerCount('type:step.failed')).toBe(0);
     });
   });
 });