upper_flutter_stores 0.1.15

A lightweight, super-friendly, and non-verbose state management solution for Flutter.

UPPER Flutter Stores 📦

UPPER Flutter Stores is a lightweight, powerful, and flexible state management solution designed to simplify your Flutter applications. Inspired by the simplicity of Svelte Stores, it provides a unified store API with specialized independent stores for advanced use cases like persistence, snapshots, undo/redo functionality, middleware, and more.

---

🌟 Features

• Unified API: Manage your application's state in a single store with optional features like persistence, undo/redo, snapshots, and async operations.
• Independent Stores: Modular and specific stores for specialized needs:
  • BaseStore: A minimal store with reactive state.
  • AsyncStore: Manage asynchronous tasks with built-in loading and error states.
  • UndoableStore: Add undo/redo functionality for state transitions.
  • ComputedStore: Automatically derive state based on dependencies.
  • PersistentStore: Save and restore state with SharedPreferences.
  • SnapshotStore: Create and replay snapshots of state.
  • DynamicStore: Manage key-value state dynamically.
  • MiddlewareStore: Add middleware for intercepting state changes.
• Tracing and Debugging: Track state changes, errors, and their context when debugging is enabled.
• Integration Ready: Wrap your application with StoreLifecycleManager for automatic cleanup of listeners and subscriptions.
• No Boilerplate: Minimal setup with extensive functionality out-of-the-box.

---

🔧 Installation

Add the package to your pubspec.yaml:

dependencies:
  upper_flutter_stores: ^0.1.15

copied to clipboard

Run:

flutter pub get

copied to clipboard

---

🚀 Getting Started

Unified Store Example

import 'package:upper_flutter_stores/upper_flutter_stores.dart';

void main() {
  final store = Store<int>(
    0, // Initial state
    enableDebugging: true, // Enable debug logs
    enableUndoRedo: true, // Add undo/redo capability
    enableSnapshots: true, // Enable snapshot functionality
    enablePersistence: true, // Persist state across app restarts
    persistKey: 'counter_store', // Key for persistence
    fromJson: (json) => json['value'] as int,
    toJson: (state) => {'value': state},
  );

  // Listen to state changes
  store.subscribe((state) {
    print('State updated: $state');
  });

  // Perform state updates
  store.set(10); // Update state
  store.undo(); // Undo last change
  store.takeSnapshot(); // Take a snapshot
  store.persist(); // Save state
}

copied to clipboard

💡 Full Demo

Check the Example for more details.

---

💡 Advanced Usage

1. Async Operations

final asyncStore = AsyncStore<String>(enableDebugging: true);

asyncStore.run(() async {
  await Future.delayed(Duration(seconds: 2));
  return "Data Loaded!";
});

asyncStore.subscribe((state) {
  if (state.isLoading) {
    print("Loading...");
  } else if (state.data != null) {
    print("Data: ${state.data}");
  } else if (state.error != null) {
    print("Error: ${state.error}");
  }
});

copied to clipboard

2. Undo/Redo Functionality

final undoableStore = UndoableStore<int>(0, enableDebugging: true);

undoableStore.set(10);
undoableStore.set(20);

undoableStore.undo(); // Reverts to 10
undoableStore.redo(); // Returns to 20

copied to clipboard

3. Middleware Example

final middlewareStore = MiddlewareStore<int>(0, enableDebugging: true);

// Add a middleware to log state transitions
middlewareStore.addMiddleware((oldState, newState) {
  print("State changed from $oldState to $newState");
});

// Add another middleware for validation
middlewareStore.addMiddleware((oldState, newState) {
  if (newState < 0) {
    print("Warning: State is negative");
  }
});

// Update state
middlewareStore.set(10); // Logs: State changed from 0 to 10
middlewareStore.set(-5); // Logs: State changed from 10 to -5 and Warning: State is negative

copied to clipboard

4. Lifecycle Management with StoreLifecycleManager

Wrap your app with StoreLifecycleManager to automatically manage listeners:

StoreLifecycleManager.register(context, () {
  print("Dispose callback executed");
});

copied to clipboard

---

📋 List of Features

1. State Management:
   • Reactive state updates.
   • Built-in tracing for debugging.
2. Persistence:
   • Save and restore state with SharedPreferences.
3. Undo/Redo:
   • Built-in undo/redo stack for state transitions.
4. Snapshots:
   • Take, replay, and clear state snapshots.
5. Async Operations:
   • Manage loading, success, and error states with ease.
6. Dynamic Key-Value State:
   • Flexible state management for dynamic structures.
7. Middleware:
   • Add middleware to intercept and process state changes.
8. Computed State:
   • Automatically calculate state based on dependencies.

---

🛠 Debugging and Tracing

Enable debugging with enableDebugging: true in any store. It provides:

• Logs of state transitions.
• Errors with stack traces.
• Context tracking to locate the source of changes.

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

---

📝 Changelog

See the CHANGELOG.md for the list of updates and improvements.

---

💬 Feedback and Contributions

We’d love your feedback! Feel free to open issues or contribute to the repository.

---

🧪 Tests

This package comes with extensive unit tests to ensure reliability. Run tests with:

flutter test

copied to clipboard

---

📚 Documentation

Check the full documentation for more details and advanced examples.