release: 0.4.0

Author: mattrltrent

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.4.0
+
+- Adds optimistic updates.
+
 ## 0.3.0
 
 - Adds `cancelableAsyncOp` to `Trent` class, allowing for the cancellation of optional async operations via `void reset({bool cancelInFlightAsyncOps = true})` or `cancelInFlightAsyncOps`. This helps prevent state leaking across sessions.

README.md

@@ -16,6 +16,7 @@
 
 - Ease of use:
   - Built-in dependency injection and service locators.
+  - Built-in optimistic update functionality.
   - Boasts simple `Alerter` and `Digester` widgets for managing UI layer reactively.
 - Fine-grained control:
   - Includes special shorthand `watch<T>`, `watchMap<T, S>`, and `get<T>` functions for reduced-boilerplate managing of UI layer.
@@ -438,6 +439,91 @@ class CalculatorTrent extends Trent<CalculatorStates> {
   }
   ```
 
+### Optimistic Updates
+
+Optimistic updates let you immediately reflect a change in your UI before an async operation (like a network request) completes. This makes your app feel faster and more responsive. If the async operation fails, the optimistic update can be reverted.
+
+Trent provides a built-in API for optimistic updates via the `optimisticUpdate<T>(...)` method, available on any Trent instance. Optimistic updates are tracked by tag, can be explicitly accepted or rejected, and are automatically cleaned up on `reset()`.
+
+#### Tags
+A tag is a string that identifies the optimistic update. If you run multiple optimistic updates with the same tag, only the latest effect for that tag is present; previous effects are fully reverted before the new one is applied. This ensures repeated or colliding updates don't stack up and cause state confusion. If you don't provide a tag, Trent will generate a universally unique tag for you.
+
+```dart
+// In your Trent subclass:
+optimisticUpdate<int>(
+  tag: "counter",
+  forward: (state, value) => state.copyWith(value: state.value + value),
+  reverse: (state, value) => state.copyWith(value: state.value - value),
+).execute(5); // Immediately applies +5 optimistically
+```
+
+#### Resolving Optimistic Updates
+There are three main ways to resolve an optimistic update:
+
+1. **Accept**: Call `accept()` on the attempt to confirm the optimistic update (e.g., after a successful async operation). This makes the update permanent and removes it from the pending list.
+2. **Accept As**: Call `acceptAs(newValue)` to accept the update but with a new value (runs revert, then applies the new value as a new optimistic update).
+3. **Reject**: Call `reject()` to revert the optimistic update (e.g., if the async operation fails). This will undo the effect and remove it from the pending list.
+
+All of these methods are available on the returned `OptimisticAttempt`:
+
+```dart
+final attempt = optimisticUpdate<int>(
+  tag: "counter",
+  forward: (state, value) => state.copyWith(value: state.value + value),
+  reverse: (state, value) => state.copyWith(value: state.value - value),
+);
+attempt.execute(10); // Apply +10 optimistically
+
+// Later, after async completes:
+attempt.accept(); // Accepts and finalizes
+// or
+attempt.reject(); // Reverts the update
+// or
+attempt.acceptAs(42); // Reverts +10, then applies +42
+```
+
+Optimistic updates are async-safe: if you run multiple with the same tag before accepting, acceptingAs, or rejecting, only the latest is kept and previous ones are reverted before the new one is applied. This prevents flooding/collision issues.
+
+If you always resolve each optimistic attempt (by calling `accept()`, `acceptAs(...)`, or `reject()` on every attempt you create), you will not leak memory or state. The additional cleanup methods (like `rejectAllUnresolvedOptimisticUpdates`) are provided as extra safety for cases where you might forget to resolve, or for bulk cleanup after network failures, app suspends, or other edge cases.
+
+#### Cleanup
+
+To prevent memory leaks or stale updates, Trent provides a cleanup method:
+
+- `rejectAllUnresolvedOptimisticUpdates({Duration? olderThan})`: Rejects all unresolved optimistic updates, or only those older than a given duration. This is useful for cleaning up after network failures, app suspends, or just to ensure your state is fresh.
+
+```dart
+// Reject all unresolved optimistic updates
+trent.rejectAllUnresolvedOptimisticUpdates();
+
+// Reject only those older than 30 seconds
+trent.rejectAllUnresolvedOptimisticUpdates(olderThan: Duration(seconds: 30));
+```
+
+Optimistic updates are also automatically cleaned up on a Trent's `reset(...)` being called.
+
+**Example:**
+
+```dart
+final attempt = optimisticUpdate<int>(
+  tag: "saveDraft",
+  forward: (state, value) => state.copyWith(value: value),
+  reverse: (state, value) => state.copyWith(value: state.value - value),
+);
+attempt.execute(123);
+
+// If the save fails after 10 seconds
+Future.delayed(Duration(seconds: 10), () {
+  attempt.reject();
+});
+
+// Or, to clean up all stale attempts after a while
+trent.rejectAllUnresolvedOptimisticUpdates(olderThan: Duration(seconds: 10));
+```
+
+This system ensures your UI remains responsive, your state stays consistent, and you have full control over optimistic updates and their lifecycle.
+
+
 ## How to Use
 
 ### 1. Define Your State Types

example/pubspec.lock

@@ -278,7 +278,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "0.1.1"
+    version: "0.3.0"
   typed_data:
     dependency: transitive
     description:

lib/src/logic/optimism.dart

@@ -1,50 +1,57 @@
 import 'package:trent/trent.dart';
+import 'package:meta/meta.dart';
 
 class OptimisticAttempt<TState extends EquatableCopyable<TState>, TValue> {
-  final TState Function(TState, TValue) forward;
-  final TState Function(TState, TValue) reverse;
-  final Trent<TState> trent;
+  final TState Function(TState, TValue) _forward;
+  final TState Function(TState, TValue) _reverse;
+  final Trent<TState> _trent;
   final String tag;
-  final String compositeKey;
+  final String _compositeKey;
 
   bool _started = false;
   bool _finished = false;
 
   late TValue? _value;
 
+  DateTime? _createdAt;
+
   OptimisticAttempt({
-    required this.trent,
+    required Trent<TState> trent,
     required this.tag,
-    required this.forward,
-    required this.reverse,
-  }) : compositeKey = "${trent.runtimeType}_$tag";
+    required TState Function(TState, TValue) forward,
+    required TState Function(TState, TValue) reverse,
+  })  : _trent = trent,
+        _reverse = reverse,
+        _forward = forward,
+        _compositeKey = "${trent.runtimeType}_$tag";
 
   /// Call this to apply the optimistic update with a value.
   void execute([TValue? value]) {
     if (_started) return;
     _started = true;
     _value = value;
+    _createdAt = DateTime.now();
 
     // Revert previous attempt with the same tag if it exists and is not this
-    final prev = registry[compositeKey];
+    final prev = registry[_compositeKey];
     if (prev != null && prev != this && prev._started && !prev._finished) {
       final typedPrev = prev as OptimisticAttempt<TState, TValue>;
-      trent.emit(typedPrev.reverse(trent.state, typedPrev._value as TValue));
+      _trent.emit(typedPrev._reverse(_trent.state, typedPrev._value as TValue));
       typedPrev._finish();
     }
 
-    trent.emit(forward(trent.state, value as TValue));
-    registry[compositeKey] = this;
+    _trent.emit(_forward(_trent.state, value as TValue));
+    registry[_compositeKey] = this;
   }
 
   /// Accept the optimistic update with a new value (runs reverse then forward with new value).
   void acceptAs(TValue value) {
     if (!_started || _finished) return;
     if (_isLatest()) {
       // revert optimistic
-      trent.emit(reverse(trent.state, _value as TValue));
+      _trent.emit(_reverse(_trent.state, _value as TValue));
       // apply new value
-      trent.emit(forward(trent.state, value));
+      _trent.emit(_forward(_trent.state, value));
       _finish();
     }
   }
@@ -53,7 +60,7 @@ class OptimisticAttempt<TState extends EquatableCopyable<TState>, TValue> {
   void reject() {
     if (!_started || _finished) return;
     if (_isLatest()) {
-      trent.emit(reverse(trent.state, _value as TValue));
+      _trent.emit(_reverse(_trent.state, _value as TValue));
       _finish();
     }
   }
@@ -68,10 +75,18 @@ class OptimisticAttempt<TState extends EquatableCopyable<TState>, TValue> {
 
   void _finish() {
     _finished = true;
-    registry.remove(compositeKey);
+    registry.remove(_compositeKey);
   }
 
-  bool _isLatest() => registry[compositeKey] == this;
+  bool _isLatest() => registry[_compositeKey] == this;
 
   static final Map<String, OptimisticAttempt> registry = {};
+
+  bool get isFinished => _finished;
+
+  /// For internal use by Trent only. Not for public consumption.
+  DateTime? get createdAtForTrent => _createdAt;
+
+  @visibleForTesting
+  set createdAtForTest(DateTime dt) => _createdAt = dt;
 }

lib/src/logic/trent.dart

@@ -60,7 +60,8 @@ abstract class Trents<Base> extends ChangeNotifier {
   ///
   /// All last states are cleared.
   ///
-  /// Optionally, cancels all in-flight async ops and resets the session token (further ensuring in-flight async ops get suppressed).
+  /// Also cancels all in-flight async ops and resets the session token (further ensuring in-flight async ops get suppressed).
+  /// Additionally, all unresolved optimistic attempts are rejected and cleared.
   void reset({bool cancelInFlightAsyncOps = true}) {
     if (cancelInFlightAsyncOps) {
       for (var op in _ops) {
@@ -69,6 +70,14 @@ abstract class Trents<Base> extends ChangeNotifier {
       _ops.clear();
       _sessionToken = const Uuid().v4();
     }
+    // --- Reject and clear all unresolved optimistic attempts ---
+    final optimisticRegistry = OptimisticAttempt.registry;
+    for (final attempt in optimisticRegistry.values.toList()) {
+      // Only reject if not finished; _finished is private, so use public API
+      attempt.reject();
+    }
+    optimisticRegistry.clear();
+    // --- END NEW ---
     clearAllExes();
     emit(_initialState);
     _updateLastState(_initialState);
@@ -89,7 +98,8 @@ abstract class Trents<Base> extends ChangeNotifier {
   /// This ensures no "leakage" of async operations that are not cancelled
   /// across Trent resets, and the result is wrapped in an [AsyncCompleted]
   /// to safely distinguish between completed and cancelled/stale executions.
-  Future<AsyncCompleted<T>> cancelableAsyncOp<T>(Future<T> Function() work) async {
+  Future<AsyncCompleted<T>> cancelableAsyncOp<T>(
+      Future<T> Function() work) async {
     final captured = _sessionToken;
     final op = CancelableOperation<T>.fromFuture(work());
     _ops.add(op);
@@ -150,15 +160,18 @@ abstract class Trents<Base> extends ChangeNotifier {
   /// to return to D(value: 10) instead of D(value: some_value_you_must_define).
   Option<T> getExStateAs<T extends Base>() {
     return _lastStates[T] != null
-        ? _lastStates[T]!.match(some: (v) => Option.some(v as T), none: () => Option<T>.none())
+        ? _lastStates[T]!.match(
+            some: (v) => Option.some(v as T), none: () => Option<T>.none())
         : Option<T>.none();
   }
 
   /// Retrieve the current state as a specific type.
   ///
   /// Will return None if the current state is not of the specified type.
   Option<T> getCurrStateAs<T extends Base>() {
-    return _state.runtimeType == T ? Option.some(_state as T) : Option<T>.none();
+    return _state.runtimeType == T
+        ? Option.some(_state as T)
+        : Option<T>.none();
   }
 
   /// Dispose of the Trent.
@@ -183,7 +196,8 @@ abstract class Copyable<T> {
 }
 
 /// A generic Trent that manages state transitions.
-abstract class Trent<Base extends EquatableCopyable<Base>> extends Trents<Base> {
+abstract class Trent<Base extends EquatableCopyable<Base>>
+    extends Trents<Base> {
   Trent(super.state);
 
   /// Optimistic update helper, available on all Trent instances.
@@ -203,4 +217,29 @@ abstract class Trent<Base extends EquatableCopyable<Base>> extends Trents<Base>
     // Do NOT register the attempt here; registration happens in execute().
     return attempt;
   }
+
+  /// Rejects all unresolved optimistic attempts. If [olderThan] is supplied,
+  /// only attempts pending longer than [olderThan] are rejected.
+  void rejectAllUnresolvedOptimisticUpdates({Duration? olderThan}) {
+    final now = DateTime.now();
+    final optimisticRegistry = OptimisticAttempt.registry;
+    for (final attempt in optimisticRegistry.values.toList()) {
+      if (olderThan == null) {
+        attempt.reject();
+      } else {
+        final created = attempt.createdAtForTrent;
+        if (created != null && now.difference(created) > olderThan) {
+          attempt.reject();
+        }
+      }
+    }
+    if (olderThan == null) {
+      optimisticRegistry.clear();
+    } else {
+      // Remove only those that were rejected above
+      optimisticRegistry.removeWhere((_, attempt) =>
+          attempt.createdAtForTrent != null &&
+          now.difference(attempt.createdAtForTrent!) > olderThan);
+    }
+  }
 }

pubspec.yaml

@@ -1,6 +1,6 @@
 name: trent
 description: A Flutter package for simple, scalable, and reactive state management with built-in dependency injection and efficient stream-based state handling.
-version: 0.3.0
+version: 0.4.0
 
 homepage: https://matthewtrent.me
 repository: https://github.com/mattrltrent/trent
@@ -20,6 +20,7 @@ dependencies:
   get_it: ^8.0.3
   async: ^2.12.0
   uuid: ^4.5.1
+  meta: ^1.16.0
 
 dev_dependencies:
   flutter_test: