@multiplier-labs/stepflow 0.3.4 → 0.3.6

package/src/core/types.ts

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

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

package/src/events/memory.test.ts

@@ -1,107 +0,0 @@
-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

@@ -1,92 +0,0 @@
-/**
- * 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');
-  }
-}