StatePulse

A lightweight, reactive, hydrated state-management library for Flutter — inspired by Provider + Hydrated Bloc, but 10× simpler.

🚀 Features #

• 🌊 Simple API — only a few core classes
• 🔥 Ultra-fast UI updates (InheritedNotifier + AnimatedBuilder)
• 💾 Built-in hydration using HydratedStatePulse
• 🎯 Selectors, Listeners, and Consumers (like Bloc/Provider)
• 🧩 Supports local store instances (per-widget state)
• ⚡ Zero boilerplate
• 🟦 Zero dependencies (only shared_preferences for persistence)
• 🧠 Designed for small → large production apps

📦 Install #

dependencies:
  state_pulse: ^1.1.0

🔄 Migration Guide (0.0.8 → 1.0.0) #

Before (0.0.8) #

class CounterStore extends ChangeNotifier with HydratedStatePulse {
  int value = 0;

  void increment() {
    value++;
    notifyListeners();
  }

  @override
  Map<String, dynamic> toJson() => {'value': value};

  @override
  void fromJson(Map<String, dynamic> json) {
    value = json['value'] ?? 0;
  }
}

Now Breaking Change(1.0.0) #

1. Required initialization

void main() async {
  WidgetsFlutterBinding.ensureInitialized(); // REQUIRED
  await StatePulse.initialize(); // REQUIRED
  runApp(MyApp());
}

2. Store inheritance change

class CounterStore extends HydratedStatePulse {
  int value = 0;

  void increment() {
    value++;
    notifyListeners();
  }

  @override
  Map<String, dynamic> toJson() => {'value': value};

  @override
  void fromJson(Map<String, dynamic> json) {
    value = json['value'] ?? 0;
  }
}

🧩 Quick Start Example #

Create a Store #

  class CounterStore extends HydratedStatePulse {
  int value = 0;

  void increment() {
    value++;
    notifyListeners();
  }

  @override
  Map<String, dynamic> toJson() => {'value': value};

  @override
  void fromJson(Map<String, dynamic> json) {
    value = json['value'] ?? 0;
  }
}

Provide the Store #

   StatePulseProvider(
      store: CounterStore(),
      child: MyApp(),
    );

Use With Builder #

StatePulseBuilder<CounterStore>(
      builder: (_, store) => Text('${store.value}'),
    );

🎯 Selector Example (High Performance Rebuilds) #

Only rebuilds when the selected value changes.

StatePulseSelector<CounterStore, int>(
      selector: (store) => store.value,
      builder: (_, value) => Text('$value'),
    );

👂 Listener Example (Side-effects — No UI Rebuild) #

StatePulseListener<CounterStore>(
      listener: (_, store) {
        if (store.value == 10) {
          print("Reached 10!");
        }
      },
      child: SomeWidget(),
    );

🔀 Consumer Example (Listener + Builder) #

StatePulseConsumer<CounterStore>(
      listener: (_, store) => print("Changed!"),
      builder: (_, store) => Text("${store.value}"),
    );

🧪 Local Store Instance (Widget-Scoped State) #

Each widget has its own isolated store:

 final localStore = CounterStore();

    return StatePulseBuilder<CounterStore>(
      store: localStore,
      builder: (_, store) => Text("${store.value}"),
    );

🔧 Advanced Example — Hydrated User Store #

class UserStore extends HydratedStatePulse {
  UserModel? user;
  bool loading = false;

  Future<void> fetchUser() async {
    loading = true;
    notifyListeners();
    await Future.delayed(Duration(seconds: 1));
    user = UserModel(id: "1", name: "Alex", email: "alex@mail.com");
    loading = false;
    notifyListeners();
  }

  @override
  Map<String, dynamic> toJson() => user == null ? {} : {"user": user!.toJson()};

  @override
  void fromJson(Map<String, dynamic> json) {
    if (json["user"] != null) {
      user = UserModel.fromJson(json["user"]);
    }
  }
}