fix: rename dispose to free to avoid collisions

Co-authored-by: MasterMarcoHD <MasterMarcoHD@users.noreply.github.com>

Author: mcquenji

example/routing.dart

@@ -68,7 +68,12 @@ Future<void> main() async {
 
   final router = GetIt.I<RoutingService<String, _Config>>();
 
-  await router.navigate('/test/123we/a', callback: print);
+  await router.navigate(
+    '/test/123we/a',
+    callback: (view, preview) {
+      print('Navigation callback: preview=$preview, view=$view');
+    },
+  );
 
   print(router.currentContext);
 

lib/src/domain/services/routing_service.dart

@@ -15,7 +15,7 @@ abstract class RoutingService<T, Config extends Object> extends Service {
   Future<void> navigate(
     String path, {
     bool skipPreview = false,
-    required void Function(T) callback,
+    required void Function(T, bool) callback,
   });
 
   /// Checks if the specified [path] is currently active.

lib/src/infra/services/noop_telemetry_service.dart

@@ -1,3 +1,5 @@
+import 'dart:async';
+
 import 'package:grumpy/grumpy.dart';
 
 /// A no-operation implementation of [TelemetryService].
@@ -6,4 +8,17 @@ class NoopTelemetryService extends TelemetryService {
   noSuchMethod(Invocation invocation) {
     log('NoopTelemetryService: ${invocation.memberName} called.');
   }
+
+  @override
+  Future<T> runSpan<T>(
+    String name,
+    FutureOr<T> Function() callback, {
+    Map<String, dynamic>? attributes,
+  }) async {
+    log(
+      'NoopTelemetryService: runSpan $name called with attributes: $attributes',
+    );
+
+    return callback();
+  }
 }

lib/src/infra/services/routingkit_routing_service.dart

@@ -9,6 +9,8 @@ class RoutingKitRoutingService<T, Config extends Object>
     with LifecycleMixin {
   RouteContext? _context;
 
+  final Map<Uri, (Future<bool>, LeafRoute<T, Config>)> _pendingNavigations = {};
+
   /// The root module of the application.
   final RootModule<T, Config> rootModule;
 
@@ -30,8 +32,8 @@ class RoutingKitRoutingService<T, Config extends Object>
   RouteContext? get currentContext => _context;
 
   @override
-  FutureOr<void> dispose() {
-    super.dispose();
+  FutureOr<void> free() {
+    super.free();
     _listeners.clear();
   }
 
@@ -116,82 +118,145 @@ class RoutingKitRoutingService<T, Config extends Object>
   Future<void> navigate(
     String path, {
     bool skipPreview = false,
-    required void Function(T) callback,
+    required void Function(T, bool) callback,
   }) async {
     final uri = Uri.parse(path);
 
     if (uri == currentContext?.uri) {
       log('Already at path: $path, skipping navigation.');
+
       return;
     }
 
-    final cleanPath = uri.path;
+    if (_pendingNavigations.containsKey(uri)) {
+      log('Navigation to $path is already in progress, forwarding callback.');
 
-    // find the route
-    final match = _kit.find(null, cleanPath);
+      final (future, leaf) = _pendingNavigations[uri]!;
 
-    if (match == null) {
-      throw ArgumentError.value(
-        path,
-        'path',
-        'No route found for the given path!',
-      );
-    }
+      if (!skipPreview) {
+        callback(leaf.view.preview(RouteContext.fromUri(uri)), true);
+      }
 
-    var leaf = match.data;
+      log('Waiting for pending navigation to $path to complete.');
 
-    if (leaf is ModuleRoute<T, Config>) {
-      leaf =
-          leaf.root ??
-          (throw ArgumentError.value(
-            path,
-            'path',
-            'Resolved ModuleRoute does not have a root LeafRoute defined!',
-          ));
-    }
+      final success = await future;
+
+      if (!success) {
+        log(
+          'Pending navigation to $path failed, not invoking content callback.',
+        );
+        return;
+      }
 
-    // check if leaf (throw if not)
-    if (leaf is! LeafRoute) {
-      throw ArgumentError.value(path, 'path', 'Resolved route is not a leaf!');
+      log('Pending navigation to $path completed, invoking content callback.');
+
+      callback(await leaf.view.content(RouteContext.fromUri(uri)), false);
+
+      return;
     }
 
-    leaf as LeafRoute<T, Config>;
+    try {
+      final cleanPath = uri.path;
+
+      // find the route
+      final match = _kit.find(null, cleanPath);
+
+      if (match == null) {
+        throw ArgumentError.value(
+          path,
+          'path',
+          'No route found for the given path!',
+        );
+      }
+
+      var leaf = match.data;
 
-    // find context
+      if (leaf is ModuleRoute<T, Config>) {
+        leaf =
+            leaf.root ??
+            (throw ArgumentError.value(
+              path,
+              'path',
+              'Resolved ModuleRoute does not have a root LeafRoute defined!',
+            ));
+      }
+
+      // check if leaf (throw if not)
+      if (leaf is! LeafRoute) {
+        throw ArgumentError.value(
+          path,
+          'path',
+          'Resolved route is not a leaf!',
+        );
+      }
+
+      leaf as LeafRoute<T, Config>;
+
+      final future = _navigate(uri, leaf, skipPreview, callback);
+
+      _pendingNavigations[uri] = (future, leaf);
+      await future;
+    } catch (e, s) {
+      log('Navigation to $path failed with error', e, s);
+      rethrow;
+    } finally {
+      _pendingNavigations.remove(uri);
+    }
+  }
+
+  Future<bool> _navigate(
+    Uri uri,
+    LeafRoute<T, Config> leaf,
+    bool skipPreview,
+    void Function(T, bool) callback,
+  ) async {
     var context = RouteContext.fromUri(uri);
+    final cleanPath = uri.path;
 
-    log('Navigating to $path with context: $context');
+    log('Navigating to $cleanPath with context: $context');
 
-    if (!skipPreview) callback(leaf.view.preview(context));
+    if (!skipPreview) callback(leaf.view.preview(context), true);
 
     // activate required modules
     final dependencies = getDependencies(cleanPath);
 
     for (Module<T, Config> module in dependencies) {
-      module.activate();
+      await module.activate();
       log('Activated module: ${module.runtimeType}');
     }
 
     // run middlewares (if any)
     try {
-      for (final middleware in leaf.middleware) {
+      for (var i = 0; i < leaf.middleware.length; i++) {
+        final middleware = leaf.middleware[i];
+        log(
+          'Executing middleware ${i + 1}/${leaf.middleware.length}: ${middleware.runtimeType}',
+        );
         context = await middleware(context);
-        log('Middleware processed context: $context');
       }
+      log(
+        'All ${leaf.middleware.length} middlewares executed successfully for $cleanPath',
+      );
     } catch (e, s) {
-      log('A middleware threw an exception during navigation to $path', e, s);
-      rethrow;
+      log(
+        'A middleware threw an exception during navigation to $cleanPath',
+        e,
+        s,
+      );
+      return false;
     }
 
     _context = context;
 
-    callback(await leaf.view.content(context));
+    callback(await leaf.view.content(context), false);
 
-    log('Activated route at $path');
+    log('Activated route at $cleanPath');
 
     // notify listeners
     for (final listener in _listeners) {
       listener(leaf);
     }
+
+    return true;
   }
 }

lib/src/module.dart

@@ -101,7 +101,7 @@ abstract class Module<RouteType, Config extends Object>
       await _mount(module);
     }
 
-    _di.pushNewScope(scopeName: runtimeType.toString(), dispose: dispose);
+    _di.pushNewScope(scopeName: runtimeType.toString(), dispose: free);
 
     bindExternalDeps(<T extends Object>(builder) {
       _di.registerSingleton<T>(builder(_di.get<Config>(), _di.get));
@@ -128,19 +128,19 @@ abstract class Module<RouteType, Config extends Object>
         },
         dispose: (repo) async {
           await repo.deactivate();
-          await repo.dispose();
+          await repo.free();
         },
       );
     });
   }
 
   @override
   @mustCallSuper
-  FutureOr<void> dispose() async {
+  FutureOr<void> free() async {
     if (_disposed) return;
     _disposed = true;
 
-    await super.dispose();
+    await super.free();
 
     if (_firstImportScope != null) {
       await _di.popScopesTill(_firstImportScope!);
@@ -211,7 +211,7 @@ abstract class RootModule<RouteType, Config extends Object>
   @override
   // if the root module is disposed, something is very wrong.
   // ignore: must_call_super
-  FutureOr<void> dispose() {
+  FutureOr<void> free() {
     throw StateError(
       'RootModule should not be disposed. It lives throughout the application lifecycle.',
     );

lib/src/utils/disposable.dart

@@ -5,9 +5,9 @@ import 'package:meta/meta.dart';
 /// An interface for disposable resources.
 mixin Disposable on Object implements get_it.Disposable {
   /// Disposes of the resource.
-  FutureOr<void> dispose();
+  FutureOr<void> free();
 
   @override
   @nonVirtual
-  FutureOr<dynamic> onDispose() => dispose();
+  FutureOr<dynamic> onDispose() => free();
 }

lib/src/utils/lifecycle_hooks_mixin.dart

@@ -12,26 +12,46 @@ mixin LifecycleHooksMixin on LifecycleMixin, LogMixin {
   final List<FutureOr<void> Function()> _disposeHooks = [];
 
   /// Registers a hook to be called in [initialize].
+  ///
+  /// Note: It is unsafe to access the same variables in multiple hooks
+  /// registered via this method, as the order of execution is not guaranteed.
+  /// Use a single hook to manage shared state.
   void onInitialize(FutureOr<void> Function() hook) {
     _initializeHooks.add(hook);
   }
 
   /// Registers a hook to be called in [activate].
+  ///
+  /// Note: It is unsafe to access the same variables in multiple hooks
+  /// registered via this method, as the order of execution is not guaranteed.
+  /// Use a single hook to manage shared state.
   void onActivate(FutureOr<void> Function() hook) {
     _activateHooks.add(hook);
   }
 
   /// Registers a hook to be called in [deactivate].
+  ///
+  /// Note: It is unsafe to access the same variables in multiple hooks
+  /// registered via this method, as the order of execution is not guaranteed.
+  /// Use a single hook to manage shared state.
   void onDeactivate(FutureOr<void> Function() hook) {
     _deactivateHooks.add(hook);
   }
 
   /// Registers a hook to be called in [dependenciesChanged].
+  ///
+  /// Note: It is unsafe to access the same variables in multiple hooks
+  /// registered via this method, as the order of execution is not guaranteed.
+  /// Use a single hook to manage shared state.
   void onDependenciesChanged(FutureOr<void> Function() hook) {
     _dependenciesChangedHooks.add(hook);
   }
 
-  /// Registers a hook to be called in [dispose].
+  /// Registers a hook to be called in [free].
+  ///
+  /// Note: It is unsafe to access the same variables in multiple hooks
+  /// registered via this method, as the order of execution is not guaranteed.
+  /// Use a single hook to manage shared state.
   void onDisposed(FutureOr<void> Function() hook) {
     _disposeHooks.add(hook);
   }
@@ -75,8 +95,8 @@ mixin LifecycleHooksMixin on LifecycleMixin, LogMixin {
 
   @override
   @mustCallSuper
-  FutureOr<void> dispose() async {
-    await super.dispose();
+  FutureOr<void> free() async {
+    await super.free();
 
     _initializeHooks.clear();
     _activateHooks.clear();

lib/src/utils/lifecycle_mixin.dart

@@ -12,7 +12,7 @@ import 'package:grumpy/grumpy.dart';
 ///   returning from the background).
 /// - [deactivate]: Called when the object is deactivated.
 /// - [dependenciesChanged]: Called when the object's dependencies have changed.
-/// - [dispose]: Called when the object is being disposed of.
+/// - [free]: Called when the object is being disposed of.
 abstract mixin class LifecycleMixin implements Disposable {
   bool _isDisposed = false;
 
@@ -43,16 +43,20 @@ abstract mixin class LifecycleMixin implements Disposable {
   /// Disposes of the object and releases any resources.
   /// This method should be overridden to perform cleanup tasks.
   ///
-  /// You can safely assume that [dispose] will be called only once.
+  /// You can safely assume that [free] will be called only once.
   @override
   @mustCallSuper
-  FutureOr<void> dispose() async {
+  FutureOr<void> free() async {
     if (_isDisposed) {
       throw StateError('Resource has already been disposed.');
     }
 
     _isDisposed = true;
   }
+
+  @override
+  @nonVirtual
+  FutureOr<void> onDispose() => free();
 }
 
 /// Mixin that adds lifecycle callbacks to a [Repo].