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.

• 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.

Add the package to your pubspec.yaml:

dependencies:
  upper_flutter_stores: ^0.1.15

Run:

flutter pub get

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
}

Check the Example for more details.

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

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

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

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

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

Wrap your app with StoreLifecycleManager to automatically manage listeners:

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

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.

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.

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

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

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

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

flutter test

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

• 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.

• 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.

• 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.

• 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.

• 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.

--

Check the full documentation for more details and advanced examples.

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