FSM: States Configuration

Formal States and Processes Description

This document contains formal definitions for HFSM processes formats in TypeScript and JSON Schema formats.

TypeScript Declaration

/**
 * Represents different types of keys used in FSM configuration
 * - Use "*" for wildcard matching (any state or event)
 * - Use "" for initial state (source) or termination state (target)
 * - Use any string for specific state keys or event names
 */
type StateKey = string;    // Example: "Off", 
type InitialStateKey = ""; // Used to declare initial transition
type FinalStateKey = "";   // Used to declare final (exit) transition
type WildcardStateKey = "*"; // Declaration of default transitions

type EventKey = string;    // Example: "ok", "ko", "toggle"
type WildcardEventKey = "*"; // Declaration of default transition, matching all event keys

/**
 * A transition triple defining state machine behavior
 * Format: [sourceState, event, targetState]
 * 
 * Transition types:
 * - Initial: ["", event, "TargetState"] - Entry into FSM
 * - Standard: ["SourceState", "event", "TargetState"] - Normal flow
 * - Wildcard: ["*", "event", "TargetState"] - From any state
 * - Termination: ["SourceState", "event", ""] - Exit FSM
 * - Event wildcard: ["SourceState", "*", "TargetState"] - Any event
 */
type Transition = [
  sourceState: StateKey | WildcardStateKey | InitialStateKey, // Example: "SourceKey", "*", ""
  event: EventKey | WildcardEventKey, // Example: "toggle", "*"
  targetState: StateKey | FinalStateKey, // Example: "TargetState", ""
];

/**
 * Core FSM state configuration with hierarchical structure
 * Each state can contain its own sub-states and transitions
 * The structure is recursive - sub-states follow the same pattern
 */
interface FSMState {
  /** 
   * Unique identifier for the state (mandatory)
   * Should follow PascalCase naming convention and be action-oriented
   * Examples: "ProcessingOrder", "WaitingForInput", "HandleError"
   */
  key: StateKey;

  /** 
   * Array of transition rules between direct sub-states (optional)
   * Each transition is a triple: [sourceState, event, targetState]
   * Transitions are only possible between direct sub-states of this parent
   */
  transitions?: Transition[];
  
  /** 
   * Array of nested sub-states with identical structure (optional)
   * Each sub-state follows the same FSMState interface recursively
   * Enables hierarchical state decomposition for complex workflows
   */
  states?: FSMState[];
} & {

  /** 
   * Human-readable name for the state (optional)
   * Provides a friendly display name that can include spaces and special characters
   * Examples: "Processing Order", "Waiting for User Input", "Handle Error Condition"
   */
  name?: string;

  /** 
   * Detailed description of the state (optional but recommended)
   * Explains the state's purpose, behavior, and role within the overall process workflow
   * Examples: "This state handles the initial validation and processing of customer orders"
   */
  description?: string;

  /** 
   * Expected outcome after this stage completes (optional but recommended)
   * Describes what should be achieved when this state finishes execution
   * Should reference corresponding events that will be emitted
   * Examples: "Order validated and ready for processing", "User authentication completed"
   */
  outcome?: string;

  /** 
   * Events generated when this state completes (mandatory for leaf states)
   * Lists all possible events this state can emit based on its outcomes
   * Each event should correspond to a transition defined in the parent state
   * Examples: ["success", "failure"], ["validated", "rejected", "requiresReview"]
   */
  events?: string[];

  /** 
   * Actors participating in this process stage (optional)
   * Lists entities or roles that perform actions in this state
   * Examples: ["User", "System", "Administrator"], ["Customer", "PaymentGateway"]
   */
  actors?: string[];

  /** 
   * Primary object being acted upon in this stage (optional)
   * Identifies the main entity or resource that this state operates on
   * Examples: "Order", "UserAccount", "PaymentTransaction", "DocumentRequest"
   */
  object?: string;
  
} & {
  // Other fields
  [key: string] : unknown;
}

Configuration Example

/**
 * Example usage demonstrating the FSM structure:
 */
const telephoneExample: FSMState = {
  key: "Telephone",
  name: "Telephone System",
  description: "Complete telephone system with integrated fax functionality",
  transitions: [
    ["", "*", "Off"],           // Initial transition
    ["Off", "switch", "On"],    // Power on
    ["On", "switch", "Off"],    // Power off
    ["*", "unplug", ""]         // Emergency termination from any state
  ],
  states: [
    {
      key: "On",
      name: "Telephone Active",
      description: "Active state where the telephone is powered on and ready to handle calls",
      transitions: [
        ["", "*", "Waiting"],
        ["Waiting", "signal", "Ringing"],
        ["Ringing", "hangUp", "Talking"],
        ["Talking", "hangOut", "Waiting"],
        ["Ringing", "timeout", "FaxReceiving"],
        ["FaxReceiving", "done", "Waiting"]
      ]
    }
  ]
};

JSON Schema

This section contains a formal JSON Schema definition for FSM data structures:

Process Generation Prompt