Features/store provider

CHANGELOG.md

@@ -58,6 +58,14 @@ All notable changes to this project will be documented in this file.
 ### Added
 - Updated documentation github url
 
+## [0.1.12] - 2025-01-25
+### Added
+- Added StoreProvided
+- Added ConsumerProvider
+- Added MultiStoreProvided
+- Added StoreDefinition
+- Added Documentation
+
 ### Improved
 - Optimized `_notifyListeners` in `BaseStore` for better performance with large subscriber counts.
 - Refactored individual stores to support lifecycle management and debugging seamlessly.

README.md

@@ -206,4 +206,4 @@ flutter test
 
 ## 📚 Documentation
 
-Check the [full documentation](https://github.com/upperdo/upper_flutter_stores) for more details and advanced examples.
+Check the [full documentation](https://github.com/upperdo/upper_flutter_stores/blob/main/docs/README.md) for more details and advanced examples.

docs/API_DEFINITION.md

@@ -0,0 +1,189 @@
+# API Reference: **upper_flutter_stores**
+
+This document provides a comprehensive overview of the API definitions, interfaces, and core components available in the **upper_flutter_stores** package.
+
+---
+
+## Overview
+The **upper_flutter_stores** package provides a structured and flexible API to manage application state efficiently. The package includes key classes, interfaces, and utilities for state management, middleware, persistence, and more.
+
+---
+
+## Core Interfaces and Classes
+
+### 1. `BaseStore<T>`
+#### Description:
+The foundational class for state management, offering basic functionality for handling state and notifying listeners.
+
+#### Key Methods:
+- **`T get state`**: Retrieves the current state.
+- **`void set(T newState)`**: Updates the state and notifies listeners.
+- **`void addListener(void Function() listener)`**: Registers a listener for state changes.
+- **`void removeListener(void Function() listener)`**: Unregisters a listener.
+
+---
+
+### 2. `Store<T>`
+#### Description:
+A unified store that integrates advanced features like undo/redo, persistence, snapshots, and computed values.
+
+#### Key Features:
+- Undo/Redo functionality.
+- Persistence support.
+- Middleware integration.
+- Snapshot and replay support.
+
+#### Key Methods:
+- **`void undo()`**: Reverts to the previous state.
+- **`void redo()`**: Restores the last undone state.
+- **`Future<void> persist()`**: Saves the current state persistently.
+- **`void takeSnapshot()`**: Captures the current state as a snapshot.
+- **`void replaySnapshot(int index)`**: Reverts to a specific snapshot.
+
+---
+
+### 3. `StoreInterface<T>`
+#### Description:
+An abstract base interface for creating custom stores with specific features.
+
+#### Key Methods:
+- **`T get state`**: Retrieves the current state.
+- **`void set(T newState)`**: Updates the state.
+- **`Future<void> initializePersistence()`**: Initializes persistent storage for the state.
+- **`void undo()`**, **`void redo()`**: Undo/redo functionality for state changes.
+- **`void takeSnapshot()`**, **`void replaySnapshot(int index)`**: Snapshot management.
+
+---
+
+### 4. `StoreProvider<T>`
+#### Description:
+An InheritedWidget for injecting a store into the widget tree.
+
+#### Key Methods:
+- **`static T of<T extends BaseStore>(BuildContext context)`**: Retrieves the store of type `T` from the widget tree.
+
+---
+
+### 5. `StoreConsumer<T>`
+#### Description:
+A widget that listens to store changes and rebuilds its child widget.
+
+#### Key Parameters:
+- **`Widget Function(BuildContext context, T store)`**: A builder function that rebuilds on state changes.
+
+---
+
+### 6. `MultiStoreProvider`
+#### Description:
+A utility for injecting multiple stores into the widget tree.
+
+#### Key Parameters:
+- **`List<BaseStoreDefinition> definitions`**: A list of store definitions to provide.
+- **`Widget child`**: The child widget to wrap with providers.
+
+---
+
+### 7. `Middleware<T>`
+#### Description:
+A function that intercepts state transitions, allowing pre-processing or validation.
+
+#### Function Signature:
+```dart
+typedef Middleware<T> = void Function(T oldState, T newState);
+```
+
+---
+
+## Advanced Features
+
+### 1. Persistence
+#### Description:
+Provides a mechanism to persist state using `SharedPreferences` or other storage backends.
+
+#### Key Classes:
+- **`PersistentStore<T>`**: A store that saves and restores state persistently.
+- **`Store<T>`**: Unified store with built-in persistence support.
+
+#### Key Methods:
+- **`Future<void> initialize()`**: Initializes persistent storage.
+- **`Future<void> persist()`**: Saves the current state.
+
+---
+
+### 2. Undo/Redo
+#### Description:
+Tracks state history for reverting or reapplying changes.
+
+#### Key Classes:
+- **`UndoableStore<T>`**: Adds undo/redo capabilities to a store.
+- **`Store<T>`**: Unified store with built-in undo/redo support.
+
+#### Key Methods:
+- **`void undo()`**: Reverts to the previous state.
+- **`void redo()`**: Restores the last undone state.
+
+---
+
+### 3. Snapshots
+#### Description:
+Allows capturing and replaying state snapshots for debugging or time travel.
+
+#### Key Classes:
+- **`SnapshotStore<T>`**: Enables snapshot management.
+- **`Store<T>`**: Unified store with snapshot support.
+
+#### Key Methods:
+- **`void takeSnapshot()`**: Captures the current state as a snapshot.
+- **`void replaySnapshot(int index)`**: Restores a specific snapshot.
+
+---
+
+### 4. Async State Management
+#### Description:
+Manages asynchronous tasks and updates state upon completion.
+
+#### Key Classes:
+- **`AsyncStore<T>`**: Handles async operations.
+- **`Store<T>`**: Unified store with async support.
+
+#### Key Methods:
+- **`Future<void> runAsync(Future<T> Function() task)`**: Runs an async task and updates the state on completion.
+
+---
+
+### 5. Computed State
+#### Description:
+Automatically calculates derived state based on dependencies.
+
+#### Key Classes:
+- **`ComputedStore<T>`**: Computes derived state.
+- **`Store<T>`**: Unified store with computed state support.
+
+#### Key Parameters:
+- **`T Function()`**: A function to compute the derived state.
+- **`List<BaseStore>`**: Dependencies for the computed state.
+
+---
+
+## Store Definitions
+### `BaseStoreDefinition` and `StoreDefinition`
+#### Description:
+Used with `MultiStoreProvider` to define stores and wrap widgets with their respective providers.
+
+#### Example:
+```dart
+final definitions = [
+  StoreDefinition(TodoStore()),
+  StoreDefinition(SampleStore()),
+];
+
+MultiStoreProvider(
+  definitions: definitions,
+  child: MyApp(),
+);
+```
+
+---
+
+## Conclusion
+The **upper_flutter_stores** package offers a flexible and powerful API for state management. With its modular design, advanced features, and intuitive interface, it simplifies building robust Flutter applications.

docs/ARCHITECTURE.md

@@ -0,0 +1,99 @@
+# Architecture: **upper_flutter_stores**
+
+The **upper_flutter_stores** package is designed with flexibility, modularity, and extensibility in mind. It provides a robust foundation for managing application state in Flutter projects, allowing developers to handle complex scenarios while maintaining simplicity.
+
+## Core Principles
+
+1. **Separation of Concerns**:
+   - The architecture separates core functionalities into distinct stores and components.
+   - Unified and separated stores ensure modularity and focus on specific responsibilities.
+
+2. **Scalability**:
+   - The package supports both small-scale and large-scale applications by allowing developers to pick only the features they need.
+
+3. **Reusability**:
+   - Components like middleware and snapshot mechanisms are designed to be reusable across multiple stores.
+
+4. **Developer Experience**:
+   - Minimal boilerplate and intuitive APIs make it easy for developers to integrate and use the package.
+
+---
+
+## Key Components
+
+### 1. Unified Store
+- **Purpose**: Combines multiple features (e.g., persistence, undo/redo, async operations) into a single store for convenience.
+- **Features**:
+  - Supports state persistence using `PersistentStore`.
+  - Allows undo/redo actions via `UndoableStore`.
+  - Handles computed states with `ComputedStore`.
+  - Enables asynchronous operations through `AsyncStore`.
+  - Provides snapshot and replay functionality with `SnapshotStore`.
+- **Usage**: Ideal for most scenarios where multiple features are required in a single store.
+
+### 2. Separated Stores
+- **Purpose**: Provide feature-specific implementations for advanced control and specialization.
+- **Examples**:
+  - `BaseStore`: Core state management.
+  - `UndoableStore`: Adds undo/redo functionality.
+  - `PersistentStore`: Manages state persistence.
+  - `AsyncStore`: Handles asynchronous updates.
+  - `ComputedStore`: Manages derived state calculations.
+  - `SnapshotStore`: Enables state snapshots and replay.
+- **Usage**: Suitable for use cases requiring granular control over individual features.
+
+### 3. Store Providers
+- **`StoreProvider`**:
+  - A generic provider that injects a store into the widget tree.
+  - Allows child widgets to access the store via the context.
+- **`MultiStoreProvider`**:
+  - Enables injecting multiple stores into the widget tree simultaneously.
+  - Simplifies dependency management for widgets requiring multiple stores.
+
+### 4. Middleware
+- **Purpose**: Intercepts state transitions, enabling custom logic (e.g., logging, validation).
+- **Integration**: Middleware can be added to unified stores or specific separated stores.
+
+---
+
+## Data Flow
+
+The package follows a unidirectional data flow pattern:
+
+1. **State Update**:
+   - State changes are triggered via `set` or feature-specific methods (e.g., `undo`, `takeSnapshot`).
+
+2. **Middleware Interception**:
+   - Middleware intercepts state transitions, allowing additional logic to be executed.
+
+3. **Reactivity**:
+   - Changes in state automatically notify listeners, ensuring the UI reflects the updated state.
+
+4. **Persistence** (if enabled):
+   - State changes are saved to local storage, ensuring data is retained across sessions.
+
+---
+
+## Reactivity and Notifications
+
+- Stores inherit from `BaseStore`, which implements `ChangeNotifier` to provide reactivity.
+- Changes to state trigger notifications to listeners, ensuring widgets depending on the state rebuild as needed.
+
+---
+
+## Design Decisions
+
+### Modular Design
+- Stores are designed as independent modules, allowing developers to use them individually or as part of the unified store.
+
+### Extensibility
+- Developers can extend existing stores or create custom implementations by inheriting from `BaseStore` or other specialized stores.
+
+### Lightweight and Efficient
+- The package avoids unnecessary dependencies, focusing on performance and simplicity.
+
+---
+
+## Conclusion
+
+The **upper_flutter_stores** package provides a comprehensive and flexible state management solution tailored to the needs of modern Flutter applications. Its modular architecture and focus on scalability make it a powerful tool for developers, whether building small apps or enterprise-level solutions.