@multiplier-labs/stepflow 0.3.4 → 0.3.8

package/src/index.ts

@@ -1,270 +0,0 @@
-/**
- * Stepflow - Workflow Engine
- *
- * A framework-agnostic workflow engine that provides:
- * - Workflow Definition & Registration
- * - Async Execution Engine (non-blocking, fire-and-forget)
- * - State Management (run/step status tracking with checkpointing)
- * - Event System (real-time events for monitoring and UI updates)
- * - Pluggable Storage (bring your own database/persistence layer)
- * - Retry & Error Handling (configurable per-step error strategies)
- *
- * @example
- * ```typescript
- * import { WorkflowEngine, MemoryStorageAdapter } from 'stepflow';
- *
- * const engine = new WorkflowEngine({
- *   storage: new MemoryStorageAdapter(),
- * });
- *
- * engine.registerWorkflow({
- *   kind: 'email.send_campaign',
- *   name: 'Send Email Campaign',
- *   steps: [
- *     {
- *       key: 'load_recipients',
- *       name: 'Load Recipients',
- *       handler: async (ctx) => {
- *         const recipients = await loadRecipients(ctx.input.campaignId);
- *         return { recipients };
- *       },
- *     },
- *     {
- *       key: 'send_emails',
- *       name: 'Send Emails',
- *       handler: async (ctx) => {
- *         const { recipients } = ctx.results.load_recipients;
- *         // Send emails...
- *         return { sent: recipients.length };
- *       },
- *       onError: 'retry',
- *       maxRetries: 3,
- *     },
- *   ],
- * });
- *
- * const runId = await engine.startRun({
- *   kind: 'email.send_campaign',
- *   input: { campaignId: '123' },
- * });
- *
- * // Subscribe to events
- * engine.subscribeToRun(runId, (event) => {
- *   console.log(`${event.eventType}: ${event.stepKey ?? 'run'}`);
- * });
- * ```
- */
-
-// ============================================================================
-// Core Types and Classes
-// ============================================================================
-
-export {
-  // Types
-  type WorkflowKind,
-  type RunStatus,
-  type StepStatus,
-  type StepErrorStrategy,
-  type WorkflowError,
-  type RunResult,
-  type Logger,
-  type SpawnChildOptions,
-  type WorkflowContext,
-  type WorkflowStep,
-  type WorkflowHooks,
-  type WorkflowDefinition,
-} from './core/types';
-
-export {
-  // Main Engine
-  WorkflowEngine,
-  type WorkflowEngineConfig,
-  type StartRunOptions,
-} from './core/engine';
-
-// ============================================================================
-// Storage
-// ============================================================================
-
-export {
-  // Types
-  type StorageAdapter,
-  type WorkflowStorage,
-  type WorkflowRunRecord,
-  type WorkflowRunStepRecord,
-  type WorkflowEventRecord,
-  type ListRunsOptions,
-  type ListEventsOptions,
-  type PaginatedResult,
-  type CreateRunInput,
-  type UpdateRunInput,
-  type StepResult,
-  type StepRecord,
-  // Extended types for new WorkflowStorage implementations
-  type ExtendedWorkflowRunRecord,
-  type ExtendedRunStatus,
-  type ExtendedStepStatus,
-  type ExtendedListRunsOptions,
-  type StepflowRunsTable,
-  type StepflowStepResultsTable,
-  type StepflowDatabase,
-} from './storage/types';
-
-export {
-  // In-Memory Storage
-  MemoryStorageAdapter,
-} from './storage/memory';
-
-export {
-  // SQLite Storage
-  SQLiteStorageAdapter,
-  type SQLiteStorageConfig,
-} from './storage/sqlite';
-
-export {
-  // PostgreSQL Storage
-  PostgresStorageAdapter,
-  PostgresStorageAdapter as PostgresStorage,
-  type PostgresStorageConfig,
-} from './storage/postgres';
-
-// ============================================================================
-// Events
-// ============================================================================
-
-export {
-  // Types
-  type EventTransport,
-  type WorkflowEvent,
-  type WorkflowEventType,
-  type BuiltInEventType,
-  type EventCallback,
-  type Unsubscribe,
-} from './events/types';
-
-export {
-  // In-Memory Event Transport
-  MemoryEventTransport,
-} from './events/memory';
-
-export {
-  // Socket.IO Event Transport
-  SocketIOEventTransport,
-  type SocketIOEventTransportConfig,
-  type SocketIOServer,
-  type SocketIOSocket,
-  type SocketIOAuthorizeFn,
-} from './events/socketio';
-
-export {
-  // Webhook Event Transport
-  WebhookEventTransport,
-  type WebhookEventTransportConfig,
-  type WebhookEndpoint,
-  type WebhookPayload,
-} from './events/webhook';
-
-// ============================================================================
-// Scheduler
-// ============================================================================
-
-export {
-  type TriggerType,
-  type WorkflowSchedule,
-  type Scheduler,
-} from './scheduler/types';
-
-export {
-  CronScheduler,
-  type CronSchedulerConfig,
-  type SchedulePersistence,
-} from './scheduler/cron';
-
-export {
-  SQLiteSchedulePersistence,
-  type SQLiteSchedulePersistenceConfig,
-} from './scheduler/sqlite-persistence';
-
-export {
-  PostgresSchedulePersistence,
-  type PostgresSchedulePersistenceConfig,
-} from './scheduler/postgres-persistence';
-
-// ============================================================================
-// Utilities
-// ============================================================================
-
-export {
-  // ID Generation
-  generateId,
-} from './utils/id';
-
-export {
-  // Errors
-  WorkflowEngineError,
-  WorkflowNotFoundError,
-  WorkflowAlreadyRegisteredError,
-  RunNotFoundError,
-  StepError,
-  StepTimeoutError,
-  WaitForRunTimeoutError,
-  WorkflowCanceledError,
-  WorkflowTimeoutError,
-} from './utils/errors';
-
-export {
-  // Logger
-  ConsoleLogger,
-  SilentLogger,
-  createScopedLogger,
-  sanitizeErrorForStorage,
-  type LogLevel,
-} from './utils/logger';
-
-export {
-  // Retry
-  type RetryOptions,
-  DEFAULT_RETRY_OPTIONS,
-  sleep,
-  withRetry,
-  calculateRetryDelay,
-} from './utils/retry';
-
-// ============================================================================
-// Planning
-// ============================================================================
-
-export {
-  // Types
-  type ConditionOperator,
-  type RecipeCondition,
-  type RecipeDefaults,
-  type StepHandlerRef,
-  type RecipeStep,
-  type Recipe,
-  type PlanModificationType,
-  type PlanModification,
-  type PlannedStep,
-  type ChildWorkflowPlan,
-  type ResourceEstimate,
-  type Plan,
-  type PlanningPriority,
-  type PlanningConstraints,
-  type PlanningHints,
-  type PlanningContext,
-  type RecipeSelectionResult,
-  type PlanValidationResult,
-  type Planner,
-  type RegisteredStepHandler,
-  type StepHandlerRegistry,
-  type RecipeQueryOptions,
-  type RecipeRegistry,
-
-  // Implementations
-  MemoryStepHandlerRegistry,
-  MemoryRecipeRegistry,
-  createRegistry,
-  type CombinedRegistry,
-  RuleBasedPlanner,
-  type RuleBasedPlannerConfig,
-} from './planning';

package/src/planning/evaluate-condition.test.ts

@@ -1,153 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import {
-  evaluateCondition,
-  getNestedValue,
-  MAX_REGEX_PATTERN_LENGTH,
-} from './evaluate-condition';
-
-describe('getNestedValue', () => {
-  it('returns top-level values', () => {
-    expect(getNestedValue({ a: 1 }, 'a')).toBe(1);
-  });
-
-  it('returns nested values via dot notation', () => {
-    expect(getNestedValue({ a: { b: { c: 'deep' } } }, 'a.b.c')).toBe('deep');
-  });
-
-  it('returns undefined for missing paths', () => {
-    expect(getNestedValue({ a: 1 }, 'b')).toBeUndefined();
-    expect(getNestedValue({ a: { b: 1 } }, 'a.c')).toBeUndefined();
-    expect(getNestedValue({ a: { b: 1 } }, 'a.b.c')).toBeUndefined();
-  });
-
-  it('returns undefined when traversing through a non-object', () => {
-    expect(getNestedValue({ a: 5 }, 'a.b')).toBeUndefined();
-    expect(getNestedValue({ a: null }, 'a.b')).toBeUndefined();
-  });
-
-  it('preserves falsy values (0, false, empty string)', () => {
-    expect(getNestedValue({ a: 0 }, 'a')).toBe(0);
-    expect(getNestedValue({ a: false }, 'a')).toBe(false);
-    expect(getNestedValue({ a: '' }, 'a')).toBe('');
-  });
-});
-
-describe('evaluateCondition', () => {
-  describe('eq / neq', () => {
-    it('uses strict equality', () => {
-      expect(evaluateCondition('eq', 1, 1)).toBe(true);
-      expect(evaluateCondition('eq', 1, '1')).toBe(false);
-      expect(evaluateCondition('eq', 'a', 'a')).toBe(true);
-      expect(evaluateCondition('neq', 1, 2)).toBe(true);
-      expect(evaluateCondition('neq', 'a', 'a')).toBe(false);
-    });
-  });
-
-  describe('numeric comparisons', () => {
-    it('gt / gte / lt / lte work for numbers', () => {
-      expect(evaluateCondition('gt', 5, 3)).toBe(true);
-      expect(evaluateCondition('gt', 3, 5)).toBe(false);
-      expect(evaluateCondition('gt', 5, 5)).toBe(false);
-      expect(evaluateCondition('gte', 5, 5)).toBe(true);
-      expect(evaluateCondition('lt', 3, 5)).toBe(true);
-      expect(evaluateCondition('lt', 5, 5)).toBe(false);
-      expect(evaluateCondition('lte', 5, 5)).toBe(true);
-    });
-
-    it('returns false when either side is not a number', () => {
-      expect(evaluateCondition('gt', '5', 3)).toBe(false);
-      expect(evaluateCondition('gt', 5, '3')).toBe(false);
-      expect(evaluateCondition('gte', null, 0)).toBe(false);
-      expect(evaluateCondition('lt', undefined, 1)).toBe(false);
-      expect(evaluateCondition('lte', true, 0)).toBe(false);
-    });
-  });
-
-  describe('contains', () => {
-    it('matches substrings in strings', () => {
-      expect(evaluateCondition('contains', 'hello world', 'world')).toBe(true);
-      expect(evaluateCondition('contains', 'hello world', 'xyz')).toBe(false);
-    });
-
-    it('matches elements in arrays', () => {
-      expect(evaluateCondition('contains', [1, 2, 3], 2)).toBe(true);
-      expect(evaluateCondition('contains', ['a', 'b'], 'c')).toBe(false);
-    });
-
-    it('returns false for unsupported types', () => {
-      expect(evaluateCondition('contains', 42, 4)).toBe(false);
-      expect(evaluateCondition('contains', { a: 1 }, 'a')).toBe(false);
-    });
-  });
-
-  describe('matches', () => {
-    it('returns true for matching regex', () => {
-      expect(evaluateCondition('matches', 'hello world', '^hello')).toBe(true);
-      expect(evaluateCondition('matches', 'foo123', '\\d+')).toBe(true);
-    });
-
-    it('returns false for non-matching regex', () => {
-      expect(evaluateCondition('matches', 'hello', '^world')).toBe(false);
-    });
-
-    it('returns false on invalid regex (does not throw)', () => {
-      expect(evaluateCondition('matches', 'hello', '[invalid')).toBe(false);
-    });
-
-    it('returns false when either side is not a string', () => {
-      expect(evaluateCondition('matches', 123, '\\d+')).toBe(false);
-      expect(evaluateCondition('matches', 'abc', /abc/)).toBe(false);
-    });
-
-    it('rejects unsafe RE2-incompatible patterns rather than throwing', () => {
-      // Backreferences are unsupported in RE2 — verify we degrade gracefully.
-      expect(evaluateCondition('matches', 'aa', '(a)\\1')).toBe(false);
-    });
-
-    it('rejects patterns longer than MAX_REGEX_PATTERN_LENGTH without compiling', () => {
-      // A pattern equal to the limit should still compile and match.
-      const atLimit = 'a'.repeat(MAX_REGEX_PATTERN_LENGTH);
-      expect(evaluateCondition('matches', atLimit, atLimit)).toBe(true);
-
-      // One character over the limit should be rejected (returns false, no throw).
-      const overLimit = 'a'.repeat(MAX_REGEX_PATTERN_LENGTH + 1);
-      expect(evaluateCondition('matches', overLimit, overLimit)).toBe(false);
-    });
-  });
-
-  describe('exists / notExists', () => {
-    it('exists is true for any non-empty value', () => {
-      expect(evaluateCondition('exists', 'value', undefined)).toBe(true);
-      expect(evaluateCondition('exists', 0, undefined)).toBe(true);
-      expect(evaluateCondition('exists', false, undefined)).toBe(true);
-      expect(evaluateCondition('exists', [], undefined)).toBe(true);
-    });
-
-    it('exists is false for undefined, null, or empty string', () => {
-      expect(evaluateCondition('exists', undefined, undefined)).toBe(false);
-      expect(evaluateCondition('exists', null, undefined)).toBe(false);
-      expect(evaluateCondition('exists', '', undefined)).toBe(false);
-    });
-
-    it('notExists mirrors exists', () => {
-      expect(evaluateCondition('notExists', undefined, undefined)).toBe(true);
-      expect(evaluateCondition('notExists', null, undefined)).toBe(true);
-      expect(evaluateCondition('notExists', '', undefined)).toBe(true);
-      expect(evaluateCondition('notExists', 'value', undefined)).toBe(false);
-      expect(evaluateCondition('notExists', 0, undefined)).toBe(false);
-    });
-  });
-
-  describe('unknown operator', () => {
-    it('returns false for an unrecognized operator', () => {
-      // Cast through unknown to test the default branch.
-      expect(
-        evaluateCondition(
-          'bogus' as unknown as Parameters<typeof evaluateCondition>[0],
-          1,
-          1
-        )
-      ).toBe(false);
-    });
-  });
-});

package/src/planning/evaluate-condition.ts

@@ -1,105 +0,0 @@
-/**
- * Shared condition evaluation helpers used by the planner and registry.
- *
- * Extracted to a single module so the planner's recipe scoring and the
- * registry's `query({ matchConditions })` filter cannot drift apart.
- */
-
-import RE2 from 're2';
-import type { ConditionOperator } from './types';
-
-/**
- * Maximum length (in characters) accepted for a `matches` regex pattern.
- *
- * Recipe conditions can come from user-supplied configuration; even with RE2's
- * linear-time guarantee, very large patterns waste CPU/memory at compile time
- * and inflate the per-evaluation cost. Cap the source length so a pathological
- * recipe cannot hand the planner a megabyte of regex.
- */
-export const MAX_REGEX_PATTERN_LENGTH = 512;
-
-/**
- * Get a nested value from an object using dot notation.
- */
-export function getNestedValue(
-  obj: Record<string, unknown>,
-  path: string
-): unknown {
-  return path.split('.').reduce<unknown>((current, key) => {
-    if (current && typeof current === 'object' && key in current) {
-      return (current as Record<string, unknown>)[key];
-    }
-    return undefined;
-  }, obj);
-}
-
-/**
- * Evaluate a single condition against a value.
- *
- * The `matches` operator uses RE2 (not the JS RegExp engine) to avoid
- * catastrophic-backtracking DoS from untrusted recipe inputs.
- */
-export function evaluateCondition(
-  operator: ConditionOperator,
-  fieldValue: unknown,
-  conditionValue: unknown
-): boolean {
-  switch (operator) {
-    case 'eq':
-      return fieldValue === conditionValue;
-
-    case 'neq':
-      return fieldValue !== conditionValue;
-
-    case 'gt':
-      return typeof fieldValue === 'number' && typeof conditionValue === 'number'
-        ? fieldValue > conditionValue
-        : false;
-
-    case 'gte':
-      return typeof fieldValue === 'number' && typeof conditionValue === 'number'
-        ? fieldValue >= conditionValue
-        : false;
-
-    case 'lt':
-      return typeof fieldValue === 'number' && typeof conditionValue === 'number'
-        ? fieldValue < conditionValue
-        : false;
-
-    case 'lte':
-      return typeof fieldValue === 'number' && typeof conditionValue === 'number'
-        ? fieldValue <= conditionValue
-        : false;
-
-    case 'contains':
-      if (typeof fieldValue === 'string' && typeof conditionValue === 'string') {
-        return fieldValue.includes(conditionValue);
-      }
-      if (Array.isArray(fieldValue)) {
-        return fieldValue.includes(conditionValue);
-      }
-      return false;
-
-    case 'matches':
-      if (typeof fieldValue === 'string' && typeof conditionValue === 'string') {
-        if (conditionValue.length > MAX_REGEX_PATTERN_LENGTH) {
-          return false;
-        }
-        try {
-          return new RE2(conditionValue).test(fieldValue);
-        } catch {
-          return false;
-        }
-      }
-      return false;
-
-    case 'exists':
-      return fieldValue !== undefined && fieldValue !== null && fieldValue !== '';
-
-    case 'notExists':
-      return fieldValue === undefined || fieldValue === null || fieldValue === '';
-
-    default:
-      return false;
-  }
-}

package/src/planning/index.ts

@@ -1,55 +0,0 @@
-/**
- * Planning module for the workflow engine.
- * Provides recipes, plans, and planners for dynamic workflow orchestration.
- */
-
-// Types
-export type {
-  // Condition types
-  ConditionOperator,
-  RecipeCondition,
-
-  // Recipe types
-  RecipeDefaults,
-  StepHandlerRef,
-  RecipeStep,
-  Recipe,
-
-  // Plan types
-  PlanModificationType,
-  PlanModification,
-  PlannedStep,
-  ChildWorkflowPlan,
-  ResourceEstimate,
-  Plan,
-
-  // Planning context types
-  PlanningPriority,
-  PlanningConstraints,
-  PlanningHints,
-  PlanningContext,
-
-  // Planner types
-  RecipeSelectionResult,
-  PlanValidationResult,
-  Planner,
-
-  // Registry types
-  RegisteredStepHandler,
-  StepHandlerRegistry,
-  RecipeQueryOptions,
-  RecipeRegistry,
-} from './types';
-
-// Implementations
-export {
-  MemoryStepHandlerRegistry,
-  MemoryRecipeRegistry,
-  createRegistry,
-  type CombinedRegistry,
-} from './registry';
-
-export {
-  RuleBasedPlanner,
-  type RuleBasedPlannerConfig,
-} from './planner';