🚀 zeba_academy_state_machine

A lightweight, powerful Finite State Machine (FSM) for Flutter.

Designed to help you manage application states safely, prevent invalid transitions, and debug state flows easily — without unnecessary complexity.

✨ Features

  • 🔄 Define states and transitions
  • 🛑 Prevent invalid state changes
  • 🧠 Lightweight & simple architecture
  • 🧪 Fully testable
  • 🧾 Built-in debug logging
  • ⚡ High performance with minimal overhead

📦 Installation

Add this to your pubspec.yaml:

dependencies:
  zeba_academy_state_machine: ^0.0.1

Then run:

flutter pub get

🚀 Quick Start

import 'package:zeba_academy_state_machine/zeba_academy_state_machine.dart';

final idle = ZState('idle');
final loading = ZState('loading');
final success = ZState('success');

final machine = ZStateMachine(initialState: idle)
  ..addState(loading)
  ..addState(success)
  ..addTransition(idle, loading)
  ..addTransition(loading, success);

machine.transitionTo(loading);
machine.transitionTo(success);

🧠 Core Concepts

🔹 State

Represents a condition of your app.

final idle = ZState('idle');

🔹 Transition

Defines valid movement between states.

machine.addTransition(idle, loading);

🔹 State Machine

Controls the flow and ensures only valid transitions occur.

machine.transitionTo(loading);

🛡 Prevent Invalid Transitions

machine.transitionTo(success); // ❌ Throws exception if invalid

🧪 Debugging

Built-in debugger logs all transitions:

machine.debugger.logs.forEach(print);

Example output:

✅ idle → loading
❌ INVALID: loading → idle

🎯 Use Cases

  • UI state management
  • Authentication flows
  • API request lifecycle
  • Form validation flows
  • Game logic
  • Workflow engines

🔥 Advanced Usage

Listen to Transitions

machine.onTransition = (from, to) {
  print('Transitioned from $from to $to');
};

Check Before Transition

if (machine.canTransition(success)) {
  machine.transitionTo(success);
}

🧪 Testing

Run tests using:

flutter test

🛣 Roadmap

  • 📊 Visual state graph
  • 🔁 Undo / redo transitions
  • ⏳ Async transitions support
  • 🔌 Integration with Bloc / Riverpod
  • 🧰 DevTools extension

📄 License

This project is licensed under the GNU General Public License v3.0.

👨‍💻 About Me

✨ I’m Sufyan bin Uzayr, an open-source developer passionate about building and sharing meaningful projects. You can learn more about me and my work at sufyanism.com or connect with me on Linkedin

🌐 Your all-in-one no-bloat hub!

🚀 Explore cutting-edge resources in coding, tech, and development at zeba.academy and code.zeba.academy. Empower yourself with practical skills through curated directives, real-world projects, and hands-on experience. Level up your tech game today! 💻✨

Zeba Academy is a learning platform dedicated to coding, technology, and development. ➡ Visit our main site: zeba.academy ➡ Explore hands-on courses and resources at: code.zeba.academy ➡ Check out our YouTube for more tutorials: zeba.academy ➡ Follow us on Instagram: zeba.academy

❤️ Support

If you like this package, consider giving it a ⭐ on GitHub and sharing it with the community!

Thank you for visiting! 🙌

Libraries

zeba_academy_state_machine