@multiplier-labs/stepflow 0.3.1 → 0.3.4

package/src/index.ts

@@ -73,14 +73,14 @@ export {
   type WorkflowStep,
   type WorkflowHooks,
   type WorkflowDefinition,
-} from "./core/types";
+} from './core/types';
 
 export {
   // Main Engine
   WorkflowEngine,
   type WorkflowEngineConfig,
   type StartRunOptions,
-} from "./core/engine";
+} from './core/engine';
 
 // ============================================================================
 // Storage
@@ -108,25 +108,25 @@ export {
   type StepflowRunsTable,
   type StepflowStepResultsTable,
   type StepflowDatabase,
-} from "./storage/types";
+} from './storage/types';
 
 export {
   // In-Memory Storage
   MemoryStorageAdapter,
-} from "./storage/memory";
+} from './storage/memory';
 
 export {
   // SQLite Storage
   SQLiteStorageAdapter,
   type SQLiteStorageConfig,
-} from "./storage/sqlite";
+} from './storage/sqlite';
 
 export {
   // PostgreSQL Storage
   PostgresStorageAdapter,
   PostgresStorageAdapter as PostgresStorage,
   type PostgresStorageConfig,
-} from "./storage/postgres";
+} from './storage/postgres';
 
 // ============================================================================
 // Events
@@ -140,12 +140,12 @@ export {
   type BuiltInEventType,
   type EventCallback,
   type Unsubscribe,
-} from "./events/types";
+} from './events/types';
 
 export {
   // In-Memory Event Transport
   MemoryEventTransport,
-} from "./events/memory";
+} from './events/memory';
 
 export {
   // Socket.IO Event Transport
@@ -154,7 +154,7 @@ export {
   type SocketIOServer,
   type SocketIOSocket,
   type SocketIOAuthorizeFn,
-} from "./events/socketio";
+} from './events/socketio';
 
 export {
   // Webhook Event Transport
@@ -162,7 +162,7 @@ export {
   type WebhookEventTransportConfig,
   type WebhookEndpoint,
   type WebhookPayload,
-} from "./events/webhook";
+} from './events/webhook';
 
 // ============================================================================
 // Scheduler
@@ -172,23 +172,23 @@ export {
   type TriggerType,
   type WorkflowSchedule,
   type Scheduler,
-} from "./scheduler/types";
+} from './scheduler/types';
 
 export {
   CronScheduler,
   type CronSchedulerConfig,
   type SchedulePersistence,
-} from "./scheduler/cron";
+} from './scheduler/cron';
 
 export {
   SQLiteSchedulePersistence,
   type SQLiteSchedulePersistenceConfig,
-} from "./scheduler/sqlite-persistence";
+} from './scheduler/sqlite-persistence';
 
 export {
   PostgresSchedulePersistence,
   type PostgresSchedulePersistenceConfig,
-} from "./scheduler/postgres-persistence";
+} from './scheduler/postgres-persistence';
 
 // ============================================================================
 // Utilities
@@ -197,7 +197,7 @@ export {
 export {
   // ID Generation
   generateId,
-} from "./utils/id";
+} from './utils/id';
 
 export {
   // Errors
@@ -210,7 +210,7 @@ export {
   WaitForRunTimeoutError,
   WorkflowCanceledError,
   WorkflowTimeoutError,
-} from "./utils/errors";
+} from './utils/errors';
 
 export {
   // Logger
@@ -219,7 +219,7 @@ export {
   createScopedLogger,
   sanitizeErrorForStorage,
   type LogLevel,
-} from "./utils/logger";
+} from './utils/logger';
 
 export {
   // Retry
@@ -228,7 +228,7 @@ export {
   sleep,
   withRetry,
   calculateRetryDelay,
-} from "./utils/retry";
+} from './utils/retry';
 
 // ============================================================================
 // Planning
@@ -267,4 +267,4 @@ export {
   type CombinedRegistry,
   RuleBasedPlanner,
   type RuleBasedPlannerConfig,
-} from "./planning";
+} from './planning';

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

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

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

@@ -39,7 +39,7 @@ export type {
   StepHandlerRegistry,
   RecipeQueryOptions,
   RecipeRegistry,
-} from "./types";
+} from './types';
 
 // Implementations
 export {
@@ -47,6 +47,9 @@ export {
   MemoryRecipeRegistry,
   createRegistry,
   type CombinedRegistry,
-} from "./registry";
+} from './registry';
 
-export { RuleBasedPlanner, type RuleBasedPlannerConfig } from "./planner";
+export {
+  RuleBasedPlanner,
+  type RuleBasedPlannerConfig,
+} from './planner';