Skip to content
pubscout

hierarchical_state_machine

2.4.0, released 5 months ago by mcdole.org

Performant hierarchical state machine framework inspired by UML.

WASM-ready
$ flutter pub add hierarchical_state_machine
Source repository

What it does

Implements type-safe hierarchical state machines using static blueprints and runtime instances. Supports advanced features like orthogonal regions, history semantics, pseudo-states, event deferral, and serialization.

AI-written summary of version 2.4.0, based on the package's README and metadata. Report an inaccuracy

Use it when

  • You have complex state logic that suffers from state explosion in flat state machines
  • You need UML-compliant statecharts with hierarchy, concurrency, and history

Skip it when

  • You only need simple UI state holding or basic widget rebuilding
  • You prefer stream-based or simple bloc/cubit patterns for your application logic

Strengths

  • Prevents state explosion with hierarchical parent/child states
  • Immutable blueprints validated during compilation
  • Supports orthogonal regions, history semantics, and serialization

Weaknesses

  • Steeper learning curve compared to standard state management packages
  • Requires careful definition of states, events, and transitions

Setup

Kind
Pure Dart
Effort
Low
Code generation
No
Direct dependencies
3

not documented

enum States { root, locked, unlocked, blinking }
enum Events { coin, push, timer }

final blueprint = MachineBlueprint<States, Events>(
  name: 'Turnstile',
  root: .composite(
    id: .root,
    initial: .locked,
    children: [
      .composite(
        id: .locked,
        on: { .coin: .to(guard: (e, d) => d == 0.25, target: .unlocked) },
      ),
      .composite(
        id: .unlocked,
        on: { .push: .to(target: .locked) },
      ),
    ],
  ),
);

final (hsm, errors) = blueprint.compile();
hsm!.start();

Alternatives

Packages that do the same job and could replace hierarchical_state_machine.

  • yx_state

    A state management library for Dart and Flutter applications.

  • refena

    A state management and dependency injection library inspired by Riverpod and async_redux.

  • cached_query

    Library for caching, background fetching, and managing server state in Dart and Flutter.

  • refena_flutter

    A state management and dependency injection library for Dart and Flutter.

Works with

Packages commonly used together with hierarchical_state_machine: ones it builds on, ones built on it, and its own family.