@multiplier-labs/stepflow 0.3.1

package/src/core/types.ts

@@ -0,0 +1,242 @@
+/**
+ * Core types for the workflow engine.
+ * These are the foundational interfaces used throughout the system.
+ */
+
+// ============================================================================
+// Basic Types
+// ============================================================================
+
+/**
+ * Unique identifier for a workflow type.
+ * Used to register and look up workflow definitions.
+ */
+export type WorkflowKind = string;
+
+/**
+ * Status of a workflow run.
+ */
+export type RunStatus =
+  | "queued"
+  | "running"
+  | "succeeded"
+  | "failed"
+  | "canceled";
+
+/**
+ * Status of a workflow step.
+ */
+export type StepStatus =
+  | "pending"
+  | "running"
+  | "succeeded"
+  | "failed"
+  | "skipped"
+  | "canceled";
+
+/**
+ * Error handling strategy for a step.
+ * - 'fail': Stop the workflow immediately
+ * - 'retry': Retry the step up to maxRetries times
+ * - 'skip': Mark as skipped and continue to next step
+ */
+export type StepErrorStrategy = "fail" | "retry" | "skip";
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+/**
+ * Structured error information stored with runs and steps.
+ */
+export interface WorkflowError {
+  code: string;
+  message: string;
+  stack?: string;
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Result of a completed workflow run.
+ */
+export interface RunResult {
+  status: "succeeded" | "failed" | "canceled";
+  results: Record<string, unknown>;
+  error?: WorkflowError;
+  duration: number;
+}
+
+// ============================================================================
+// Logger Interface
+// ============================================================================
+
+/**
+ * Minimal logger interface that consumers can implement.
+ * Compatible with console, pino, winston, etc.
+ */
+export interface Logger {
+  debug(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+}
+
+// ============================================================================
+// Spawn Child Options
+// ============================================================================
+
+/**
+ * Options for spawning a child workflow from within a step handler.
+ */
+export interface SpawnChildOptions {
+  kind: WorkflowKind;
+  input?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Workflow Context
+// ============================================================================
+
+/**
+ * Runtime context passed to each step handler.
+ * Contains all information a step needs to execute and interact with the engine.
+ */
+export interface WorkflowContext<TInput = Record<string, unknown>> {
+  /** Unique run identifier */
+  runId: string;
+
+  /** Current step identifier (for granular tracking, e.g., token usage) */
+  stepId: string;
+
+  /** Workflow type */
+  kind: WorkflowKind;
+
+  /** Input parameters passed when starting the run */
+  input: TInput;
+
+  /** Accumulated results from previous steps (keyed by step key) */
+  results: Record<string, unknown>;
+
+  /** Optional metadata (topicId, userId, etc.) */
+  metadata: Record<string, unknown>;
+
+  /** Current step key (set during execution) */
+  currentStep?: string;
+
+  /** Logger instance scoped to this run */
+  logger: Logger;
+
+  /** Abort signal for cancellation */
+  signal: AbortSignal;
+
+  /** Helper to spawn child workflows */
+  spawnChild: (options: SpawnChildOptions) => Promise<string>;
+
+  /** Helper to emit custom events */
+  emit: (eventType: string, payload?: unknown) => void;
+}
+
+// ============================================================================
+// Workflow Step
+// ============================================================================
+
+/**
+ * Definition of a single workflow step.
+ * Steps are executed sequentially within a workflow.
+ */
+export interface WorkflowStep<TInput = Record<string, unknown>> {
+  /** Unique step identifier within the workflow */
+  key: string;
+
+  /** Human-readable step name */
+  name: string;
+
+  /** Async function that performs the step's work */
+  handler: (ctx: WorkflowContext<TInput>) => Promise<unknown>;
+
+  /** What to do when the step fails (default: 'fail') */
+  onError?: StepErrorStrategy;
+
+  /** Maximum retry attempts when onError is 'retry' @default 3 */
+  maxRetries?: number;
+
+  /** Delay between retries in ms @default 1000 */
+  retryDelay?: number;
+
+  /** Exponential backoff multiplier @default 2 */
+  retryBackoff?: number;
+
+  /** Timeout for this step in ms (optional) */
+  timeout?: number;
+
+  /** Condition to skip this step */
+  skipIf?: (ctx: WorkflowContext<TInput>) => boolean | Promise<boolean>;
+}
+
+// ============================================================================
+// Workflow Hooks
+// ============================================================================
+
+/**
+ * Lifecycle hooks for workflows.
+ * Allow custom logic at key points in the workflow execution.
+ */
+export interface WorkflowHooks<TInput = Record<string, unknown>> {
+  /** Called before workflow starts */
+  beforeRun?: (ctx: WorkflowContext<TInput>) => Promise<void>;
+
+  /** Called after workflow completes (success or failure) */
+  afterRun?: (ctx: WorkflowContext<TInput>, result: RunResult) => Promise<void>;
+
+  /** Called before each step */
+  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>;
+
+  /** Called when a step fails */
+  onStepError?: (
+    ctx: WorkflowContext<TInput>,
+    step: WorkflowStep<TInput>,
+    error: Error,
+  ) => Promise<void>;
+}
+
+// ============================================================================
+// Workflow Definition
+// ============================================================================
+
+/**
+ * Complete workflow definition.
+ * Registered with the engine to enable starting runs of this type.
+ */
+export interface WorkflowDefinition<TInput = Record<string, unknown>> {
+  /** Unique workflow type identifier */
+  kind: WorkflowKind;
+
+  /** Human-readable workflow name */
+  name: string;
+
+  /** Optional description */
+  description?: string;
+
+  /** Ordered list of steps to execute */
+  steps: WorkflowStep<TInput>[];
+
+  /** Default error strategy for all steps (default: 'fail') */
+  defaultOnError?: StepErrorStrategy;
+
+  /** Global timeout for the entire workflow in ms */
+  timeout?: number;
+
+  /** Hooks for workflow lifecycle */
+  hooks?: WorkflowHooks<TInput>;
+}

package/src/events/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Events module exports.
+ */
+
+export * from "./types";
+export * from "./memory";
+export * from "./socketio";
+export * from "./webhook";

package/src/events/memory.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { MemoryEventTransport } from "./memory";
+import type { WorkflowEvent, WorkflowEventType } from "./types";
+
+function createTestEvent(
+  overrides: Partial<WorkflowEvent> = {},
+): WorkflowEvent {
+  return {
+    eventType: "run.started",
+    runId: "run-123",
+    kind: "test.workflow",
+    timestamp: new Date("2024-01-01T12:00:00Z"),
+    ...overrides,
+  };
+}
+
+describe("MemoryEventTransport", () => {
+  let transport: MemoryEventTransport;
+
+  beforeEach(() => {
+    transport = new MemoryEventTransport();
+  });
+
+  describe("subscribeToType", () => {
+    it("should call callback when event of matching type is emitted", () => {
+      const callback = vi.fn();
+      transport.subscribeToType("run.completed", callback);
+
+      const event = createTestEvent({ eventType: "run.completed" });
+      transport.emit(event);
+
+      expect(callback).toHaveBeenCalledWith(event);
+    });
+
+    it("should not call callback for events of a different type", () => {
+      const callback = vi.fn();
+      transport.subscribeToType("run.completed", callback);
+
+      transport.emit(createTestEvent({ eventType: "run.started" }));
+
+      expect(callback).not.toHaveBeenCalled();
+    });
+
+    it("should unsubscribe when calling the returned function", () => {
+      const callback = vi.fn();
+      const unsubscribe = transport.subscribeToType("run.completed", callback);
+
+      // Emit once before unsubscribe
+      transport.emit(createTestEvent({ eventType: "run.completed" }));
+      expect(callback).toHaveBeenCalledTimes(1);
+
+      unsubscribe();
+
+      // Emit again after unsubscribe
+      transport.emit(createTestEvent({ eventType: "run.completed" }));
+      expect(callback).toHaveBeenCalledTimes(1);
+    });
+
+    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.emit(createTestEvent({ eventType: "run.completed" }));
+
+      expect(completedCb).toHaveBeenCalledTimes(1);
+      expect(failedCb).not.toHaveBeenCalled();
+    });
+  });
+
+  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", () => {
+      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());
+
+      expect(transport.getListenerCount("run:run-1")).toBe(2);
+      expect(transport.getListenerCount("run:run-2")).toBe(1);
+    });
+
+    it("should update count after subscribe and unsubscribe", () => {
+      const unsub = transport.subscribeAll(vi.fn());
+      expect(transport.getListenerCount()).toBe(1);
+
+      unsub();
+      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());
+
+      expect(transport.getListenerCount("type:step.completed")).toBe(2);
+      expect(transport.getListenerCount("type:step.failed")).toBe(0);
+    });
+  });
+});

package/src/events/memory.ts

@@ -0,0 +1,95 @@
+/**
+ * In-memory event transport using Node.js EventEmitter.
+ * Default transport for development and single-process deployments.
+ *
+ * NOTE: This adapter is intended for development and testing only. It stores
+ * all state in-process with no persistence or multi-process safety guarantees.
+ */
+
+import { EventEmitter } from "events";
+import type {
+  EventTransport,
+  WorkflowEvent,
+  WorkflowEventType,
+  EventCallback,
+  Unsubscribe,
+} from "./types";
+
+/**
+ * In-memory event transport implementation using EventEmitter.
+ * Events are emitted to subscribers in the same process.
+ */
+export class MemoryEventTransport implements EventTransport {
+  private emitter = new EventEmitter();
+
+  constructor() {
+    // Increase max listeners to avoid warnings in workflows with many steps
+    this.emitter.setMaxListeners(100);
+  }
+
+  /**
+   * Emit an event to all subscribers.
+   */
+  emit(event: WorkflowEvent): void {
+    // Emit to global subscribers
+    this.emitter.emit("event", event);
+
+    // Emit to run-specific subscribers
+    this.emitter.emit(`run:${event.runId}`, event);
+
+    // Emit to event-type subscribers
+    this.emitter.emit(`type:${event.eventType}`, event);
+  }
+
+  /**
+   * Subscribe to events for a specific run.
+   */
+  subscribe(runId: string, callback: EventCallback): Unsubscribe {
+    const channel = `run:${runId}`;
+    this.emitter.on(channel, callback);
+    return () => {
+      this.emitter.off(channel, callback);
+    };
+  }
+
+  /**
+   * Subscribe to all events.
+   */
+  subscribeAll(callback: EventCallback): Unsubscribe {
+    this.emitter.on("event", callback);
+    return () => {
+      this.emitter.off("event", callback);
+    };
+  }
+
+  /**
+   * Subscribe to events of a specific type.
+   */
+  subscribeToType(
+    eventType: WorkflowEventType,
+    callback: EventCallback,
+  ): Unsubscribe {
+    const channel = `type:${eventType}`;
+    this.emitter.on(channel, callback);
+    return () => {
+      this.emitter.off(channel, callback);
+    };
+  }
+
+  /**
+   * Close the transport and remove all listeners.
+   */
+  close(): void {
+    this.emitter.removeAllListeners();
+  }
+
+  /**
+   * Get the number of listeners for a channel (for testing).
+   */
+  getListenerCount(channel?: string): number {
+    if (channel) {
+      return this.emitter.listenerCount(channel);
+    }
+    return this.emitter.listenerCount("event");
+  }
+}