zeba_academy_state_machine 0.0.1

Lightweight finite state machine for Flutter with validation and debugging.

🚀 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!

---

📜 Changelog

0.0.1 Initial Release

🎉 First stable release of zeba_academy_state_machine

✨ Features

• Add ZState for defining states
• Add ZTransition for state transitions
• Implement ZStateMachine core engine
• Support for adding states and transitions
• Prevent invalid transitions with runtime checks
• canTransition() helper method
• onTransition callback support

🧪 Debugging

• Built-in ZDebugger for logging transitions
• Logs for successful transitions
• Logs for invalid transitions

🛡 Safety

• Enforces state registration before transitions
• Throws exceptions for invalid transitions

⚡ Performance

• Lightweight architecture
• Minimal dependencies

📦 Developer Experience

• Simple and clean API
• Easy integration with Flutter apps
• Test-friendly design

---

❤️ Support

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

---

Thank you for visiting! 🙌