release: v0.2.0

Author: mattrltrent

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.2.0
+
+- Adds `Future<AsyncCompleted<T>> cancelableAsyncOp<T>(Future<T> Function() work)` wrapper function to `Trent` class, allowing for the cancellation of optional async operations via `void reset({bool cancelAsyncOps = true})`. This helps prevent state leaking across sessions.
+
 ## 0.1.1
 
 - Updates `TrentManager`'s `trents` field to be optional.

example/pubspec.lock

@@ -41,6 +41,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.19.1"
+  crypto:
+    dependency: transitive
+    description:
+      name: crypto
+      sha256: "1e445881f28f22d6140f181e07737b22f1e099a5e1ff94b0af2f9e4a463f4855"
+      url: "https://pub.dev"
+    source: hosted
+    version: "3.0.6"
   cupertino_icons:
     dependency: "direct main"
     description:
@@ -65,6 +73,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.3.2"
+  fixnum:
+    dependency: transitive
+    description:
+      name: fixnum
+      sha256: b6dc7065e46c974bc7c5f143080a6764ec7a4be6da1285ececdc37be96de53be
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.1.1"
   flutter:
     dependency: "direct main"
     description: flutter
@@ -208,6 +224,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.10.1"
+  sprintf:
+    dependency: transitive
+    description:
+      name: sprintf
+      sha256: "1fc9ffe69d4df602376b52949af107d8f5703b77cda567c4d7d86a0693120f23"
+      url: "https://pub.dev"
+    source: hosted
+    version: "7.0.0"
   stack_trace:
     dependency: transitive
     description:
@@ -254,7 +278,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "0.0.7"
+    version: "0.1.1"
   typed_data:
     dependency: transitive
     description:
@@ -263,6 +287,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.4.0"
+  uuid:
+    dependency: transitive
+    description:
+      name: uuid
+      sha256: a5be9ef6618a7ac1e964353ef476418026db906c4facdedaa299b7a2e71690ff
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.5.1"
   vector_math:
     dependency: transitive
     description:

lib/src/logic/accessors.dart

@@ -11,9 +11,8 @@ final GetIt _serviceLocator = GetIt.instance;
 /// we'll store typed providers directly:
 final List<SingleChildWidget> _allTrentProviders = [];
 
-ChangeNotifierProvider register<T extends ChangeNotifier>(
-  T trent,
-) {
+ChangeNotifierProvider register<T extends ChangeNotifier>(T trent,
+    {bool debug = false}) {
   if (!_serviceLocator.isRegistered<T>()) {
     _serviceLocator.registerSingleton<T>(trent);
   }
@@ -23,6 +22,13 @@ ChangeNotifierProvider register<T extends ChangeNotifier>(
     ChangeNotifierProvider<T>.value(value: trent),
   );
 
+  // if debug is true, we want to start listening to the trent in my web server?
+  if (debug) {
+    trent.addListener(() {
+      debugPrint('Trent updated: $trent');
+    });
+  }
+
   return ChangeNotifierProvider<T>.value(
     value: _serviceLocator.get<T>(),
   );

lib/src/logic/trent.dart

@@ -3,7 +3,10 @@ import 'package:equatable/equatable.dart';
 import 'package:flutter/widgets.dart';
 import 'package:rxdart/rxdart.dart';
 import 'package:trent/src/logic/mappers.dart';
+import 'package:trent/src/types/async_completed.dart';
 import 'package:trent/src/types/option.dart';
+import 'package:async/async.dart';
+import 'package:uuid/uuid.dart';
 
 /// A generic, abstract Trent that manages state transitions.
 abstract class Trents<Base> extends ChangeNotifier {
@@ -14,6 +17,13 @@ abstract class Trents<Base> extends ChangeNotifier {
     _updateLastState(_state);
   }
 
+  String _sessionToken = const Uuid().v4();
+
+  /// Under-the-hood session token getter incase it's needed for reference.
+  String get sessionToken => _sessionToken;
+
+  final List<CancelableOperation<void>> _ops = [];
+
   /// The current state.
   Base _state;
 
@@ -48,12 +58,45 @@ abstract class Trents<Base> extends ChangeNotifier {
   /// Reset the Trent to its initial state.
   ///
   /// All last states are cleared.
-  void reset() {
+  void reset({bool cancelAsyncOps = true}) {
+    if (cancelAsyncOps) {
+      for (var op in _ops) {
+        op.cancel();
+      }
+      _ops.clear();
+      _sessionToken = const Uuid().v4();
+    }
     clearAllExes();
     emit(_initialState);
     _updateLastState(_initialState);
   }
 
+  /// Wrap any Trent function in this method to ensure it can be
+  /// optionally cancelled if the Trent is reset.
+  ///
+  /// 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 {
+    final captured = _sessionToken;
+    final op = CancelableOperation<T>.fromFuture(work());
+    _ops.add(op);
+
+    try {
+      final result = await op.valueOrCancellation(null);
+      final isStale = captured != _sessionToken;
+
+      if (result == null || isStale) {
+        return AsyncCompleted.withCancelled();
+      } else {
+        return AsyncCompleted.withCompleted(result);
+      }
+    } finally {
+      _ops.remove(op);
+    }
+  }
+
   /// Emit a new state to the stream. This WILL update the UI.
   ///
   /// Does not emit if and only if the new state is the same as the current state (ie: old: A(val: 55), new A(val: 55)).

lib/src/types/async_completed.dart

@@ -0,0 +1,31 @@
+class AsyncCompleted<T> {
+  final T? value;
+  final bool wasCancelled;
+
+  AsyncCompleted._({this.value, required this.wasCancelled});
+
+  static AsyncCompleted<T> withCompleted<T>(T value) =>
+      AsyncCompleted._(value: value, wasCancelled: false);
+
+  static AsyncCompleted<T> withCancelled<T>() =>
+      AsyncCompleted._(wasCancelled: true);
+
+  /// Match on the result.
+  /// - `onCancelled` is called if the operation was cancelled or the value is null.
+  /// - `onCompleted` is called with the value if it was completed successfully.
+  R match<R>(R Function() onCancelled, R Function(T val) onCompleted) {
+    return wasCancelled || value == null
+        ? onCancelled()
+        : onCompleted(value as T);
+  }
+
+  /// Optional helpers
+  bool isNothing() => wasCancelled || value == null;
+
+  T unwrap() {
+    if (isNothing()) {
+      throw StateError('Attempted to access cancelled or stale value');
+    }
+    return value as T;
+  }
+}

lib/trent.dart

@@ -1,7 +1,6 @@
 // Logic
 export 'src/logic/trent.dart';
 export 'src/logic/accessors.dart';
-export 'src/logic/accessors.dart';
 
 // Types
 export 'src/types/option.dart';

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.1.1
+version: 0.2.0
 
 homepage: https://matthewtrent.me
 repository: https://github.com/mattrltrent/trent
@@ -18,6 +18,8 @@ dependencies:
   rxdart: ^0.28.0
   provider: ^6.1.2
   get_it: ^8.0.3
+  async: ^2.12.0
+  uuid: ^4.5.1
 
 dev_dependencies:
   flutter_test:

test/trent_test.dart

@@ -548,4 +548,91 @@ void main() {
 
     expect(handlerCalled, false); // Handler for B should not have been called
   });
+
+  test("dashboard", () {
+    register(SimpleTrent(), debug: true);
+    final trent = get<SimpleTrent>();
+    trent.emit(A(10));
+    expect(trent.state, isA<A>());
+  });
+
+  test('cancelableAsyncOp returns correct AsyncCompleted', () async {
+    final trent = SimpleTrent();
+
+    // Complete normally
+    final result1 = await trent.cancelableAsyncOp(() async {
+      await Future.delayed(Duration(milliseconds: 10));
+      return 'done';
+    });
+
+    expect(result1.isNothing(), false);
+    expect(result1.unwrap(), 'done');
+
+    // Trigger session reset during async op
+    final result2Future = trent.cancelableAsyncOp(() async {
+      await Future.delayed(Duration(milliseconds: 50));
+      return 'should be stale';
+    });
+
+    trent.reset(); // cancels and changes sessionToken
+
+    // should have returned and updated state now
+    await Future.delayed(Duration(milliseconds: 75));
+
+    final result2 = await result2Future;
+    expect(result2.isNothing(), true);
+
+    // Match-style handling
+    final result3 = await trent.cancelableAsyncOp(() async {
+      await Future.delayed(Duration(milliseconds: 10));
+      return 123;
+    });
+
+    final matchOutput = result3.match(
+      () => 'cancelled',
+      (val) => 'value: $val',
+    );
+    expect(matchOutput, 'value: 123');
+  });
+
+  test(
+      'reset(cancelAsyncOps: true) cancels inflight ops and invalidates session',
+      () async {
+    final trent = SimpleTrent();
+
+    final future = trent.cancelableAsyncOp(() async {
+      await Future.delayed(Duration(milliseconds: 50));
+      return 'should not complete';
+    });
+
+    // Trigger reset before the future completes
+    await Future.delayed(Duration(milliseconds: 10));
+    trent.reset(cancelAsyncOps: true);
+
+    final result = await future;
+    expect(result.isNothing(), true); // Result discarded due to session flip
+  });
+
+  test(
+      'reset(cancelAsyncOps: false) preserves session and allows ops to complete',
+      () async {
+    final trent = SimpleTrent();
+
+    final capturedToken = trent.sessionToken; // assume you expose this for test
+    final future = trent.cancelableAsyncOp(() async {
+      await Future.delayed(Duration(milliseconds: 30));
+      return 'survives reset';
+    });
+
+    // Reset WITHOUT canceling ops
+    await Future.delayed(Duration(milliseconds: 10));
+    trent.reset(cancelAsyncOps: false);
+
+    final result = await future;
+    expect(result.isNothing(), false);
+    expect(result.unwrap(), 'survives reset');
+
+    // Ensure session token didn't change
+    expect(trent.sessionToken, capturedToken);
+  });
 }