GitHub - upperdo/upper_flutter_stores: A lightweight, super-friendly, and non-verbose state management solution for Flutter inspired by Svelte stores.

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

Run:

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

💡 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}");
  }
});

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

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

4. Lifecycle Management with `StoreLifecycleManager`

Wrap your app with StoreLifecycleManager to automatically manage listeners:

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

📋 List of Features

State Management:
- Reactive state updates.
- Built-in tracing for debugging.
Persistence:
- Save and restore state with SharedPreferences.
Undo/Redo:
- Built-in undo/redo stack for state transitions.
Snapshots:
- Take, replay, and clear state snapshots.
Async Operations:
- Manage loading, success, and error states with ease.
Dynamic Key-Value State:
- Flexible state management for dynamic structures.
Middleware:
- Add middleware to intercept and process state changes.
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:

Pending Features Checklist for upper_flutter_stores

This checklist outlines planned features for the upper_flutter_stores package to enhance functionality, usability, and appeal to both beginner and advanced users.

Core Enhancements

Multi-Store Sync
- Enable seamless synchronization of shared states across multiple stores.
- Provide middleware and event-based synchronization options.
Caching Support
- Middleware to automatically cache API responses based on rules.
- Configurable TTL (time-to-live) and cache invalidation options.
DevTools Event Integration
- Log and expose store events to DevTools using the dart:developer timeline.
- Enable visualization of store changes in a DevTools custom panel.
Custom Event Viewer
- Create a dedicated DevTools extension for monitoring upper_flutter_stores.* events.
- Display events like state changes, middleware logs, and snapshots in a table format.

Developer Experience

Enhanced Debugging Panel
- In-app debugging widget to visualize state, undo/redo history, and snapshots.
- Filter and search states by keywords for quick analysis.
Type Safety Enhancements
- Integrate stricter type definitions for common store patterns.
- Provide TypedStore examples for common use cases like models, lists, and maps.
Error Boundary Middleware
- Capture and gracefully handle errors within store state transitions.
- Prevent application crashes due to unexpected errors in state updates.

Advanced Features

Immutable State Helpers
- Introduce immutable state utilities for performance optimization.
- Automatically handle deep copies during state updates.
Lazy Store Initialization
- Load specific stores only when accessed, reducing initial memory footprint.
State Export and Import
- Add support for exporting and importing states as JSON for testing or migration.
- Useful for replicating bugs or transferring states between environments.

Ecosystem Expansion

CLI Integration
- Command-line tools to scaffold stores, generate models, and manage configurations.
Enhanced Documentation
- Add more examples, including real-world use cases.
- Provide dedicated guides for advanced features like computed stores and multi-store setups.
Community Marketplace
- Allow publishing and sharing custom middlewares, adapters, or store patterns.

Performance Improvements

Batch State Updates
- Optimize state updates by batching multiple changes into a single notification cycle.
Selective Store Listeners
- Enable widgets to listen to specific parts of the state for improved performance.

📚 Documentation

Check the full documentation for more details and advanced examples.

Contribution

If you’re interested in contributing or suggesting additional features, please refer to the CONTRIBUTING.md.