jakesgordon/javascript-state-machine
Javascript State Machine
This library is a finite state machine framework for JavaScript designed to manage application states and valid transitions. It provides a system for executing state changes with lifecycle hooks, conditional guards, and transition cancellation.
The project is distinguished by its ability to inject state machine logic and transition capabilities directly into existing JavaScript class instances or objects. It also includes a visualization tool that exports state configurations into Graphviz DOT language for auditing system logic.
The framework covers asynchronous transition execution and pausing via promises, dynamic target state resolution, and state history tracking. It supports the creation of multiple independent machine instances from shared templates and provides mechanisms for attaching custom data and defining reusable methods.
Lifecycle management is handled through automatic callbacks triggered during the entry, exit, and observation phases of a transition.
Features
- Finite State Machine Engines - Provides a general-purpose finite state machine engine for managing application states and valid transitions in JavaScript.
- State-Transition Execution - Provides the core runtime logic to execute a change from one state to another after validating the transition.
- Application State Management - Manages the current state of a JavaScript application and controls valid transitions for predictable behavior.
- Lifecycle Hook Executions - Executes user-defined functions automatically before or after state transitions to handle side effects.
- State Transition Lifecycle Hooks - Triggers callback functions automatically before and after state transitions to handle side effects and validation.
- Asynchronous State Transition Orchestration - Handles state transitions that require asynchronous operations, promises, and lifecycle hooks.
- State Logic Injection - Provides the ability to inject state machine capabilities and transition logic into existing JavaScript object instances.
- Behavioral Logic Injection - Injects state machine logic and transition capabilities directly into existing JavaScript objects or class prototypes.
- FSM Behavior Injectors - Attaches state machine logic and transition capabilities directly to existing JavaScript class instances.
- Object Behavior Injection - Injects finite state machine capabilities into existing JavaScript objects or classes to control their operational modes.
- Class-Based State Integration - Allows state machine functionality to be baked into class definitions so every instance manages its own state.
- Dynamic State Resolution - Calculates the next target state at runtime using a function instead of a static destination name.
- State Transition Event Triggers - Runs custom callbacks automatically upon entering or leaving specific states during the transition process.
- Dynamic State Resolution - Allows the next target state to be determined dynamically at runtime via a function.
- State Mapping - Implements a mechanism to map trigger names to destination states using static configuration objects.
- State Transition Mapping - Maps trigger names to source and destination states to control the movement between different operational modes.
- Asynchronous Transition Control - Implements runtime logic to control movement between states using events, no-op transitions, and wildcard triggers.
- Conditional Transition Logic - Defines conditional movements between states using runtime arguments and validation logic to prevent illegal transitions.
- Custom State Transition Hooks - Triggers observer methods automatically during state entry, exit, or transitions to perform necessary side effects.
- Conditional Transition Guards - Evaluates custom conditions before allowing a state transition to ensure the change is valid for the context.
- Asynchronous State Transition Frameworks - Provides a system for executing asynchronous state changes with lifecycle hooks, conditional guards, and transition cancellation.
- State Transition Validation - Implements checks to determine if a requested state transition is valid based on the current state.
- State Graph Export - Converts state configurations into DOT language to produce visual directed graphs of states and transitions.
- Graphviz-Based Graph Renderers - Exports internal transition maps into Graphviz DOT language for visual representation of state flow.
- State Logic Visualizers - Generates a visual map of states and transitions to audit system logic and communicate flow.
- State Machine Instance Factories - Provides a mechanism to create multiple independent state machine instances based on a single shared template.
- State Machine Templating - Generates reusable constructors that produce independent instances sharing the same state logic and configuration.
- Transition Cancellations - Provides a mechanism to prevent state changes by returning false during lifecycle events.
- State Machine Instance Factories - Provides a constructor-based factory to generate multiple independent state machine instances from a shared configuration.
- State Activation Deferral - Allows state transitions to be paused by returning a promise that must resolve before entering the next state.
