@higher.archi/boe 1.0.0

package/src/engines/state-machine/strategy.ts

@@ -0,0 +1,634 @@
+/**
+ * State Machine Engine Strategy
+ *
+ * Manages state machine instances and executes transitions.
+ * Each instance tracks its own state, context, and history.
+ */
+
+import {
+  CompiledStateMachineDefinition,
+  CompiledStateDefinition,
+  CompiledTransition,
+  CompiledStateMachineAction,
+  StateMachineOptions,
+  MachineSnapshot,
+  TransitionRecord,
+  TransitionResult,
+  IStateMachineInstance
+} from './types';
+
+// ========================================
+// Guard Evaluation Context
+// ========================================
+
+interface GuardEvalContext {
+  context: Record<string, any>;
+  state: string;
+  history: TransitionRecord[];
+  definition: CompiledStateMachineDefinition;
+  canCheck: (event: string) => boolean;
+}
+
+// ========================================
+// Guard Evaluation
+// ========================================
+
+/**
+ * Evaluate a compiled guard condition for state machines.
+ * State machines use a simpler context (just context and state) rather than facts.
+ * Includes state-machine-specific operators: can, inState, isFinal, historyContains
+ */
+function evaluateGuardCondition(condition: any, evalContext: GuardEvalContext): boolean {
+  if (!condition) return true;
+
+  const { op, operands, children } = condition;
+
+  // Logical operators
+  if (op === 'and') {
+    return children.every((child: any) => evaluateGuardCondition(child, evalContext));
+  }
+  if (op === 'or') {
+    return children.some((child: any) => evaluateGuardCondition(child, evalContext));
+  }
+  if (op === 'not') {
+    return !evaluateGuardCondition(children[0], evalContext);
+  }
+
+  // Resolve operands
+  const resolveOperand = (operand: any): any => {
+    if (operand.type === 'constant') {
+      return operand.value;
+    }
+    if (operand.type === 'property') {
+      const { param, path } = operand.ref;
+      let value: any;
+      if (param === 'context') {
+        value = evalContext.context;
+      } else if (param === 'state') {
+        return evalContext.state;
+      } else {
+        // Try to find in context
+        value = evalContext.context[param];
+      }
+      for (const key of path) {
+        value = value?.[key];
+      }
+      return value;
+    }
+    return undefined;
+  };
+
+  const left = operands?.[0] ? resolveOperand(operands[0]) : undefined;
+  const right = operands?.[1] ? resolveOperand(operands[1]) : undefined;
+
+  // State-machine-specific operators
+  switch (op) {
+    // ['can', 'EVENT_NAME'] - Check if an event can trigger a transition
+    case 'can': {
+      const eventName = left;
+      if (typeof eventName !== 'string') return false;
+      return evalContext.canCheck(eventName);
+    }
+
+    // ['inState', 'stateName'] - Check if current state matches or is child of stateName
+    case 'inState': {
+      const targetState = left;
+      if (typeof targetState !== 'string') return false;
+      // Exact match
+      if (evalContext.state === targetState) return true;
+      // Hierarchical match: 'active' matches 'active.running', 'active.paused', etc.
+      if (evalContext.state.startsWith(targetState + '.')) return true;
+      return false;
+    }
+
+    // ['isFinal'] - Check if current state is a final state
+    case 'isFinal': {
+      const currentStateDef = evalContext.definition.stateMap.get(evalContext.state);
+      return currentStateDef?.type === 'final';
+    }
+
+    // ['historyContains', 'stateName'] - Check if a state was ever visited
+    case 'historyContains': {
+      const stateName = left;
+      if (typeof stateName !== 'string') return false;
+      // Check if any transition went to or from this state
+      return evalContext.history.some(
+        record => record.to === stateName || record.from === stateName ||
+                  record.to.startsWith(stateName + '.') || record.from.startsWith(stateName + '.')
+      );
+    }
+
+    // ['historyContainsEvent', 'EVENT_NAME'] - Check if an event was ever fired
+    case 'historyContainsEvent': {
+      const eventName = left;
+      if (typeof eventName !== 'string') return false;
+      return evalContext.history.some(record => record.event === eventName);
+    }
+  }
+
+  // Standard comparison operators
+  switch (op) {
+    case 'equals': return left === right;
+    case 'notEquals': return left !== right;
+    case 'greaterThan': return left > right;
+    case 'greaterThanOrEquals': return left >= right;
+    case 'lessThan': return left < right;
+    case 'lessThanOrEquals': return left <= right;
+    case 'isNull': return left === null || left === undefined;
+    case 'isNotNull': return left !== null && left !== undefined;
+    case 'includes': return Array.isArray(left) ? left.includes(right) : false;
+    case 'startsWith': return typeof left === 'string' ? left.startsWith(right) : false;
+    case 'endsWith': return typeof left === 'string' ? left.endsWith(right) : false;
+    case 'contains': return typeof left === 'string' ? left.includes(right) : false;
+    case 'between': {
+      const third = operands?.[2] ? resolveOperand(operands[2]) : undefined;
+      return left >= right && left <= third;
+    }
+    default:
+      return true;
+  }
+}
+
+// ========================================
+// Helper Functions
+// ========================================
+
+function setValueAtPath(obj: Record<string, any>, path: string[], value: any): void {
+  let current = obj;
+  for (let i = 0; i < path.length - 1; i++) {
+    const key = path[i];
+    if (!(key in current)) {
+      current[key] = {};
+    }
+    current = current[key];
+  }
+  current[path[path.length - 1]] = value;
+}
+
+function resolveValue(value: any, context: Record<string, any>, event: any): any {
+  if (typeof value === 'string') {
+    // Handle context references like '$context.foo'
+    if (value.startsWith('$context.')) {
+      const path = value.slice(9).split('.');
+      let current: any = context;
+      for (const key of path) {
+        current = current?.[key];
+      }
+      return current;
+    }
+    // Handle event references like '$event.amount'
+    if (value.startsWith('$event.')) {
+      const path = value.slice(7).split('.');
+      let current: any = event;
+      for (const key of path) {
+        current = current?.[key];
+      }
+      return current;
+    }
+    // Handle special values
+    if (value === '$timestamp') {
+      return Date.now();
+    }
+    if (value === '$now') {
+      return new Date().toISOString();
+    }
+  }
+  return value;
+}
+
+// ========================================
+// State Machine Instance
+// ========================================
+
+class StateMachineInstance implements IStateMachineInstance {
+  private _state: string;
+  private _context: Record<string, any>;
+  private _history: TransitionRecord[];
+  private definition: CompiledStateMachineDefinition;
+  private options: StateMachineOptions;
+
+  constructor(
+    definition: CompiledStateMachineDefinition,
+    initialSnapshot?: MachineSnapshot,
+    options: StateMachineOptions = {}
+  ) {
+    this.definition = definition;
+    this.options = options;
+
+    if (initialSnapshot) {
+      // Restore from snapshot
+      this._state = initialSnapshot.state;
+      this._context = { ...initialSnapshot.context };
+      this._history = [...initialSnapshot.history];
+    } else {
+      // Initialize fresh
+      this._state = definition.initial;
+      this._context = { ...definition.initialContext };
+      this._history = [];
+
+      // Execute onEnter for initial state
+      this.executeOnEnter(this._state);
+    }
+  }
+
+  get state(): string {
+    return this._state;
+  }
+
+  get context(): Record<string, any> {
+    return { ...this._context };
+  }
+
+  /**
+   * Check if an event can trigger a transition from current state
+   */
+  can(event: string): boolean {
+    const currentState = this.getCurrentStateDefinition();
+    if (!currentState) return false;
+
+    // Check if any transition matches this event and passes guard
+    for (const transition of currentState.transitions) {
+      if (transition.event === event) {
+        if (this.evaluateGuard(transition)) {
+          return true;
+        }
+      }
+    }
+
+    // Check parent state transitions (for hierarchical)
+    const parentTransition = this.findParentTransition(event);
+    return parentTransition !== null;
+  }
+
+  /**
+   * Get all valid events from current state
+   */
+  nextEvents(): string[] {
+    const events = new Set<string>();
+    const currentState = this.getCurrentStateDefinition();
+
+    if (currentState) {
+      for (const transition of currentState.transitions) {
+        if (this.evaluateGuard(transition)) {
+          events.add(transition.event);
+        }
+      }
+    }
+
+    // Include parent state events
+    const parentState = this.getParentStateDefinition();
+    if (parentState) {
+      for (const transition of parentState.transitions) {
+        if (this.evaluateGuard(transition)) {
+          events.add(transition.event);
+        }
+      }
+    }
+
+    return Array.from(events);
+  }
+
+  /**
+   * Send an event to trigger a transition
+   */
+  send(event: string, payload?: any): TransitionResult {
+    const fromState = this._state;
+    const actionsExecuted: string[] = [];
+
+    // Find matching transition
+    const transition = this.findTransition(event);
+
+    if (!transition) {
+      if (this.definition.config.strict) {
+        return {
+          success: false,
+          from: fromState,
+          to: fromState,
+          event,
+          error: `No valid transition for event '${event}' from state '${fromState}'`,
+          actionsExecuted
+        };
+      }
+      // Non-strict mode: ignore invalid events
+      return {
+        success: false,
+        from: fromState,
+        to: fromState,
+        event,
+        actionsExecuted
+      };
+    }
+
+    // Resolve target state
+    let targetState = transition.target;
+    if (targetState.startsWith('#')) {
+      // Absolute reference to root state
+      targetState = targetState.slice(1);
+    } else if (!this.definition.stateMap.has(targetState)) {
+      // Try relative to current state's parent
+      const parentName = this.getCurrentStateDefinition()?.parent;
+      if (parentName) {
+        const relativePath = `${parentName}.${targetState}`;
+        if (this.definition.stateMap.has(relativePath)) {
+          targetState = relativePath;
+        }
+      }
+    }
+
+    // Execute onExit for current state
+    this.executeOnExit(this._state, actionsExecuted);
+
+    // Execute transition actions
+    this.executeActions(transition.actions, { type: event, payload }, actionsExecuted);
+
+    // Update state
+    const previousState = this._state;
+    this._state = targetState;
+
+    // Execute onEnter for new state
+    this.executeOnEnter(this._state, actionsExecuted);
+
+    // Handle compound states - enter initial sub-state
+    this.enterInitialSubState(actionsExecuted);
+
+    // Record transition
+    const record: TransitionRecord = {
+      from: previousState,
+      to: this._state,
+      event,
+      timestamp: new Date().toISOString(),
+      payload
+    };
+    this._history.push(record);
+
+    // Trim history if needed
+    if (this._history.length > this.definition.config.maxHistory) {
+      this._history = this._history.slice(-this.definition.config.maxHistory);
+    }
+
+    // Notify listener
+    this.options.onTransition?.(previousState, this._state, event);
+
+    return {
+      success: true,
+      from: previousState,
+      to: this._state,
+      event,
+      actionsExecuted
+    };
+  }
+
+  /**
+   * Check if machine is in a final state
+   */
+  isFinal(): boolean {
+    const currentState = this.getCurrentStateDefinition();
+    return currentState?.type === 'final';
+  }
+
+  /**
+   * Get serializable snapshot for persistence
+   */
+  snapshot(): MachineSnapshot {
+    return {
+      state: this._state,
+      context: { ...this._context },
+      history: [...this._history]
+    };
+  }
+
+  /**
+   * Get transition history
+   */
+  history(): TransitionRecord[] {
+    return [...this._history];
+  }
+
+  // ========================================
+  // Private Helper Methods
+  // ========================================
+
+  private getCurrentStateDefinition(): CompiledStateDefinition | undefined {
+    return this.definition.stateMap.get(this._state);
+  }
+
+  private getParentStateDefinition(): CompiledStateDefinition | undefined {
+    const current = this.getCurrentStateDefinition();
+    if (current?.parent) {
+      return this.definition.stateMap.get(current.parent);
+    }
+    return undefined;
+  }
+
+  private findTransition(event: string): CompiledTransition | null {
+    // Check current state transitions first
+    const currentState = this.getCurrentStateDefinition();
+    if (currentState) {
+      for (const transition of currentState.transitions) {
+        if (transition.event === event && this.evaluateGuard(transition)) {
+          return transition;
+        }
+      }
+    }
+
+    // Check parent state transitions
+    return this.findParentTransition(event);
+  }
+
+  private findParentTransition(event: string): CompiledTransition | null {
+    const parentState = this.getParentStateDefinition();
+    if (parentState) {
+      for (const transition of parentState.transitions) {
+        if (transition.event === event && this.evaluateGuard(transition)) {
+          return transition;
+        }
+      }
+    }
+    return null;
+  }
+
+  private evaluateGuard(transition: CompiledTransition, checkingEvents: Set<string> = new Set()): boolean {
+    if (!transition.guard) return true;
+
+    // Build context for guard evaluation with state-machine-specific operators
+    const evalContext: GuardEvalContext = {
+      context: this._context,
+      state: this._state,
+      history: this._history,
+      definition: this.definition,
+      // canCheck is used by the 'can' operator - prevents infinite recursion
+      canCheck: (event: string) => {
+        // Prevent infinite recursion: if we're already checking this event, return false
+        if (checkingEvents.has(event)) {
+          return false;
+        }
+        return this.canWithRecursionGuard(event, checkingEvents);
+      }
+    };
+
+    try {
+      return evaluateGuardCondition(transition.guard, evalContext);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Internal can() check with recursion guard for use in guard evaluation
+   */
+  private canWithRecursionGuard(event: string, checkingEvents: Set<string>): boolean {
+    const newCheckingEvents = new Set(checkingEvents);
+    newCheckingEvents.add(event);
+
+    const currentState = this.getCurrentStateDefinition();
+    if (!currentState) return false;
+
+    // Check if any transition matches this event and passes guard
+    for (const transition of currentState.transitions) {
+      if (transition.event === event) {
+        if (this.evaluateGuard(transition, newCheckingEvents)) {
+          return true;
+        }
+      }
+    }
+
+    // Check parent state transitions (for hierarchical)
+    const parentState = this.getParentStateDefinition();
+    if (parentState) {
+      for (const transition of parentState.transitions) {
+        if (transition.event === event) {
+          if (this.evaluateGuard(transition, newCheckingEvents)) {
+            return true;
+          }
+        }
+      }
+    }
+
+    return false;
+  }
+
+  private executeActions(
+    actions: CompiledStateMachineAction[],
+    event: { type: string; payload?: any },
+    executed: string[]
+  ): void {
+    for (const action of actions) {
+      this.executeAction(action, event, executed);
+    }
+  }
+
+  private executeAction(
+    action: CompiledStateMachineAction,
+    event: { type: string; payload?: any },
+    executed: string[]
+  ): void {
+    switch (action.type) {
+      case 'set':
+        if (action.assignments) {
+          for (const { path, value } of action.assignments) {
+            const resolvedValue = resolveValue(value, this._context, event.payload);
+            setValueAtPath(this._context, path, resolvedValue);
+            executed.push(`set:${path.join('.')}`);
+          }
+        }
+        break;
+
+      case 'emit':
+        if (action.event && this.options.onEmit) {
+          const data = action.data ?? {};
+          // Resolve any references in data
+          const resolvedData: Record<string, any> = {};
+          for (const [key, value] of Object.entries(data)) {
+            resolvedData[key] = resolveValue(value, this._context, event.payload);
+          }
+          this.options.onEmit(action.event, resolvedData, this.snapshot());
+          executed.push(`emit:${action.event}`);
+        }
+        break;
+
+      case 'call':
+        if (action.handler && this.options.actions) {
+          const handler = this.options.actions[action.handler];
+          if (handler) {
+            handler(
+              this._context,
+              event,
+              { from: this._state, to: this._state }
+            );
+            executed.push(`call:${action.handler}`);
+          } else if (this.definition.config.strict) {
+            throw new Error(`Action handler not found: ${action.handler}`);
+          }
+        }
+        break;
+
+      case 'log':
+        if (action.message) {
+          // Resolve any references in message
+          let message = action.message;
+          message = message.replace(/\$context\.(\w+)/g, (_, key) => {
+            return String(this._context[key] ?? '');
+          });
+          message = message.replace(/\$state/g, this._state);
+          console.log(`[StateMachine:${this.definition.id}] ${message}`);
+          executed.push(`log`);
+        }
+        break;
+    }
+  }
+
+  private executeOnEnter(stateName: string, executed: string[] = []): void {
+    const state = this.definition.stateMap.get(stateName);
+    if (state?.onEnter) {
+      this.executeActions(state.onEnter, { type: 'enter' }, executed);
+    }
+  }
+
+  private executeOnExit(stateName: string, executed: string[] = []): void {
+    const state = this.definition.stateMap.get(stateName);
+    if (state?.onExit) {
+      this.executeActions(state.onExit, { type: 'exit' }, executed);
+    }
+  }
+
+  private enterInitialSubState(executed: string[]): void {
+    const currentState = this.getCurrentStateDefinition();
+    if (currentState?.states && currentState.initial) {
+      const subStateName = `${this._state}.${currentState.initial}`;
+      this._state = subStateName;
+      this.executeOnEnter(subStateName, executed);
+      // Recursively handle nested compound states
+      this.enterInitialSubState(executed);
+    }
+  }
+}
+
+// ========================================
+// Strategy Class
+// ========================================
+
+export class StateMachineStrategy {
+  /**
+   * Create a new state machine instance
+   */
+  create(
+    definition: CompiledStateMachineDefinition,
+    options: StateMachineOptions = {}
+  ): IStateMachineInstance {
+    return new StateMachineInstance(definition, undefined, options);
+  }
+
+  /**
+   * Restore a state machine instance from a snapshot
+   */
+  restore(
+    definition: CompiledStateMachineDefinition,
+    snapshot: MachineSnapshot,
+    options: StateMachineOptions = {}
+  ): IStateMachineInstance {
+    return new StateMachineInstance(definition, snapshot, options);
+  }
+}
+
+// Export singleton for convenience
+export const stateMachineStrategy = new StateMachineStrategy();