🌊 Blue Whale: Intuitive State Management for Flutter #

Blue Whale is a clean, scalable, and refreshingly intuitive state management, dependency injection, and navigation plugin for Flutter. Designed to be more intuitive than GetX, it aims for an easy learning curve, rapid implementation, and the flexibility needed for real-world applications. Dive into a smoother development experience!

✨ Why Blue Whale? #

• 🌊 Intuitive & Thematic: Ocean-inspired naming (Pod, Tank, Reef, Surface, Current) makes concepts memorable and easy to grasp.
• 🚀 Fast to Implement: Get up and running quickly with minimal boilerplate.
• 🌟 Clear Separation of Concerns: Distinct roles for state (Pod), logic (Tank), UI (Surface), and DI (Reef).
• ⚓️ Robust Dependency Injection: Simple yet powerful DI with Reef.i.put(), lazyPut(), and find() (or use<T>()).
• 🛝 Effortless Navigation: Contextless named routes, argument passing, and route-aware capabilities.
• 💬 Simplified Overlays: Easy API for showing dialogs, snackbars, and bottom sheets via BlueWhale.overlays.
• 🌐 Built-in i18n: Simple internationalization setup with reactive locale changes.
• 💧 Reactive Primitives: WhalePod for reactive state and WhaleCurrent for streams, integrating seamlessly with Flutter.
• 🛠️ Developer-Friendly: Designed with Developer Experience (DX) as a top priority.

🧱 Core Concepts #

The Analogy: Pods (state units) are managed by Tanks (logic containers). Tanks and Pods are registered in the global Reef. UI Surfaces display what's happening. Data flows through Currents.

📦 Installation #

Add blue_whale to your pubspec.yaml dependencies:

dependencies:
  flutter:
    sdk: flutter
  blue_whale: ^0.0.2 # Replace with latest version

Or use a Git reference (before publishing):

dependencies:
  blue_whale:
    git:
      url: https://github.com/your-username/blue_whale.git

Then:

flutter pub get

Import:

import 'package:blue_whale/blue_whale.dart';

🚀 Getting Started #

See a complete main.dart, CounterPod, and HomePage example in the description above.

📖 Features Overview #

State Management #

• WhalePod<T>: Reactive state.
• watch(context): Widget rebuild on change.
• WhaleTank: Business logic abstraction.
• WhaleBuilder<P, V>: Fine-grained rebuilds.
• WhaleCurrent<T>: Stream integration.

Dependency Injection (Reef) #

• Reef.i.put(obj) / lazyPut() / factory()
• use<T>(): Retrieve dependencies easily.
• Auto-dispose with WhaleTank/WhaleDisposable

Navigation #

• Named routes with no context needed.
• to(), off(), offAll(), back().
• WhaleRouteAwareTank: Lifecycle-aware tanks.

UI Overlays #

• showDialog(), showSnackbar(), showBottomSheet()

Internationalization (i18n) #

• WhaleTranslations
• "key".bwTr(context)
• WhaleLocalePod().setLocale()

🔮 Future Possibilities #

• WhaleScope: Scoped state/DI.
• DevTools integration.
• CLI for codegen and scaffolding.
• Route guards & middleware.
• Forms & local persistence.

🤝 Contributing #

1. Fork the repo
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit (git commit -m 'Add feature')
4. Push (git push origin feature/AmazingFeature)
5. Open a PR

📜 License #

Distributed under the MIT License. See LICENSE for details.

Happy Fluttering with Blue Whale! 🐳