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", ""
];

/**
 * The FSM state configuration — a recursive, hierarchical structure.
 * This is the exact shape the `@statewalker/fsm` engine reads. Only three
 * fields are meaningful to the engine; everything else is optional metadata.
 */
type FsmStateConfig = {
  /**
   * Unique identifier for the state (mandatory), unique among its siblings.
   * Convention: PascalCase, action-oriented — "ProcessingOrder", "WaitingForInput".
   */
  key: StateKey;

  /**
   * Transition rules between this state's DIRECT sub-states (optional).
   * Each transition is a triple: [sourceState, event, targetState].
   */
  transitions?: Transition[];

  /**
   * Nested sub-states with the identical structure (optional).
   * Each sub-state follows the same FsmStateConfig shape recursively.
   */
  states?: FsmStateConfig[];
} & {
  /**
   * The index signature lets you attach arbitrary metadata — a display name,
   * a description, documentation for a viewer or an LLM generator, etc.
   * The engine ignores these fields; they simply travel with the config.
   */
  [key: string]: unknown;
};

Configuration Example

/**
 * Example usage demonstrating the FSM structure:
 */
const telephoneExample: FsmStateConfig = {
  key: "Telephone",
  name: "Telephone System",                 // optional metadata, ignored by the engine
  description: "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