[go_router] Add MapRouteResultCallback and PipeRouteCompleterCallback

Both are used to resolve the current route completer when it is replaced.
Both are added to `RouteInformationState` and `ImperativeRouteMatch`.

Author: nouvist

packages/go_router/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 15.3.0
+
+- Resolves an issue where `replace` and `pushReplacement` caused the originating
+  route's completer to hang by adding `mapReplacementResult` to
+  `RouteInformationState` and `ImperativeRouteMatch`.
+  [flutter#141251](https://github.com/flutter/flutter/issues/141251)
+
 ## 15.2.3
 
 - Updates Type-safe routes topic documentation to use the mixin from `go_router_builder` 3.0.0.
@@ -8,16 +15,16 @@
 
 ## 15.2.1
 
-* Fixes Popping state and re-rendering scaffold at the same time doesn't update the URL on web.
+- Fixes Popping state and re-rendering scaffold at the same time doesn't update the URL on web.
 
 ## 15.2.0
 
-* `GoRouteData` now defines `.location`, `.go(context)`, `.push(context)`, `.pushReplacement(context)`, and `replace(context)` to be used for [Type-safe routing](https://pub.dev/documentation/go_router/latest/topics/Type-safe%20routes-topic.html). **Requires go_router_builder >= 3.0.0**.
+- `GoRouteData` now defines `.location`, `.go(context)`, `.push(context)`, `.pushReplacement(context)`, and `replace(context)` to be used for [Type-safe routing](https://pub.dev/documentation/go_router/latest/topics/Type-safe%20routes-topic.html). **Requires go_router_builder >= 3.0.0**.
 
 ## 15.1.3
 
-* Updates minimum supported SDK version to Flutter 3.27/Dart 3.6.
-* Fixes typo in API docs.
+- Updates minimum supported SDK version to Flutter 3.27/Dart 3.6.
+- Fixes typo in API docs.
 
 ## 15.1.2
 
@@ -41,7 +48,7 @@
 ## 14.8.1
 
 - Secured canPop method for the lack of matches in routerDelegate's configuration.
- 
+
 ## 14.8.0
 
 - Adds `preload` parameter to `StatefulShellBranchData.$branch`.
@@ -1205,4 +1212,3 @@
 ## 0.1.0
 
 - squatting on the package name (I'm not too proud to admit it)
-

packages/go_router/example/devtools_options.yaml

@@ -0,0 +1,3 @@
+description: This file stores settings for Dart & Flutter DevTools.
+documentation: https://docs.flutter.dev/tools/devtools/extensions#configure-extension-enablement-states
+extensions:

packages/go_router/lib/src/configuration.dart

@@ -319,10 +319,12 @@ class RouteConfiguration {
     for (final ImperativeRouteMatch imperativeMatch
         in matchList.matches.whereType<ImperativeRouteMatch>()) {
       final ImperativeRouteMatch match = ImperativeRouteMatch(
-          pageKey: imperativeMatch.pageKey,
-          matches: findMatch(imperativeMatch.matches.uri,
-              extra: imperativeMatch.matches.extra),
-          completer: imperativeMatch.completer);
+        pageKey: imperativeMatch.pageKey,
+        matches: findMatch(imperativeMatch.matches.uri,
+            extra: imperativeMatch.matches.extra),
+        completer: imperativeMatch.completer,
+        pipeCompleter: imperativeMatch.pipeCompleter,
+      );
       result = result.push(match);
     }
     return result;

packages/go_router/lib/src/information_provider.dart

@@ -36,6 +36,13 @@ enum NavigatingType {
   restore,
 }
 
+/// Maps the replacement route result to the correct generic type.
+typedef MapRouteResultCallback<T extends Object?> = T Function(Object? result);
+
+/// Pipe completer to the last route match completer.
+typedef PipeRouteCompleterCallback = Completer<Next?>
+    Function<Next extends Object?>(Completer<Next?> next);
+
 /// The data class to be stored in [RouteInformation.state] to be used by
 /// [GoRouteInformationParser].
 ///
@@ -49,9 +56,16 @@ class RouteInformationState<T> {
     this.completer,
     this.baseRouteMatchList,
     required this.type,
+    MapRouteResultCallback<T?>? mapReplacementResult,
   })  : assert((type == NavigatingType.go || type == NavigatingType.restore) ==
             (completer == null)),
-        assert((type != NavigatingType.go) == (baseRouteMatchList != null));
+        assert((type != NavigatingType.go) == (baseRouteMatchList != null)),
+        mapReplacementResult =
+            mapReplacementResult ?? _defaultMapReplacementResult;
+
+  static T? _defaultMapReplacementResult<T>(Object? result) {
+    return null;
+  }
 
   /// The extra object used when navigating with [GoRouter].
   final Object? extra;
@@ -63,13 +77,30 @@ class RouteInformationState<T> {
   /// [NavigatingType.restore].
   final Completer<T?>? completer;
 
+  /// Maps the replacement result to the appropriate type, to resolve the
+  /// [completer].
+  final MapRouteResultCallback<T?> mapReplacementResult;
+
   /// The base route match list to push on top to.
   ///
   /// This is only null if [type] is [NavigatingType.go].
   final RouteMatchList? baseRouteMatchList;
 
   /// The type of navigation.
   final NavigatingType type;
+
+  /// Pipes the completer to the next completer in the chain.
+  Completer<Next?> pipeCompleter<Next extends Object?>(Completer<Next?> next) {
+    if (completer == null) {
+      return next;
+    }
+
+    return _PipeCompleter<T?, Next?>(
+      next: next,
+      current: completer!,
+      mapReplacementResult: mapReplacementResult,
+    );
+  }
 }
 
 /// The [RouteInformationProvider] created by go_router.
@@ -156,8 +187,12 @@ class GoRouteInformationProvider extends RouteInformationProvider
   }
 
   /// Pushes the `location` as a new route on top of `base`.
-  Future<T?> push<T>(String location,
-      {required RouteMatchList base, Object? extra}) {
+  Future<T?> push<T>(
+    String location, {
+    required RouteMatchList base,
+    Object? extra,
+    MapRouteResultCallback<T?>? mapReplacementResult,
+  }) {
     final Completer<T?> completer = Completer<T?>();
     _setValue(
       location,
@@ -166,6 +201,7 @@ class GoRouteInformationProvider extends RouteInformationProvider
         baseRouteMatchList: base,
         completer: completer,
         type: NavigatingType.push,
+        mapReplacementResult: mapReplacementResult,
       ),
     );
     return completer.future;
@@ -196,8 +232,12 @@ class GoRouteInformationProvider extends RouteInformationProvider
 
   /// Removes the top-most route match from `base` and pushes the `location` as a
   /// new route on top.
-  Future<T?> pushReplacement<T>(String location,
-      {required RouteMatchList base, Object? extra}) {
+  Future<T?> pushReplacement<T>(
+    String location, {
+    required RouteMatchList base,
+    Object? extra,
+    MapRouteResultCallback<T?>? mapReplacementResult,
+  }) {
     final Completer<T?> completer = Completer<T?>();
     _setValue(
       location,
@@ -206,14 +246,19 @@ class GoRouteInformationProvider extends RouteInformationProvider
         baseRouteMatchList: base,
         completer: completer,
         type: NavigatingType.pushReplacement,
+        mapReplacementResult: mapReplacementResult,
       ),
     );
     return completer.future;
   }
 
   /// Replaces the top-most route match from `base` with the `location`.
-  Future<T?> replace<T>(String location,
-      {required RouteMatchList base, Object? extra}) {
+  Future<T?> replace<T>(
+    String location, {
+    required RouteMatchList base,
+    Object? extra,
+    MapRouteResultCallback<T?>? mapReplacementResult,
+  }) {
     final Completer<T?> completer = Completer<T?>();
     _setValue(
       location,
@@ -290,3 +335,42 @@ class GoRouteInformationProvider extends RouteInformationProvider
     return SynchronousFuture<bool>(true);
   }
 }
+
+/// Ensures the replacement routes can resolve the originating route completer.
+/// Mainly used by [RouteInformationState.pipeCompleter]
+class _PipeCompleter<Current extends Object?, Next extends Object?>
+    implements Completer<Next> {
+  _PipeCompleter({
+    required Completer<Next> next,
+    required Completer<Current> current,
+    required MapRouteResultCallback<Current> mapReplacementResult,
+  })  : _next = next,
+        _current = current,
+        _mapReplacementResult = mapReplacementResult;
+
+  final Completer<Next> _next;
+  final Completer<Current> _current;
+  final MapRouteResultCallback<Current> _mapReplacementResult;
+
+  @override
+  void complete([FutureOr<Next>? value]) {
+    _next.complete(value);
+    if (!_current.isCompleted) {
+      _current.complete(_mapReplacementResult(value));
+    }
+  }
+
+  @override
+  void completeError(Object error, [StackTrace? stackTrace]) {
+    _next.completeError(error, stackTrace);
+    if (!_current.isCompleted) {
+      _current.completeError(error, stackTrace);
+    }
+  }
+
+  @override
+  Future<Next> get future => _next.future;
+
+  @override
+  bool get isCompleted => _next.isCompleted;
+}

packages/go_router/lib/src/match.dart

@@ -12,6 +12,7 @@ import 'package:logging/logging.dart';
 import 'package:meta/meta.dart' as meta;
 
 import 'configuration.dart';
+import 'information_provider.dart';
 import 'logging.dart';
 import 'misc/errors.dart';
 import 'path_utils.dart';
@@ -432,9 +433,12 @@ class ShellRouteMatch extends RouteMatchBase {
 /// The route match that represent route pushed through [GoRouter.push].
 class ImperativeRouteMatch extends RouteMatch {
   /// Constructor for [ImperativeRouteMatch].
-  ImperativeRouteMatch(
-      {required super.pageKey, required this.matches, required this.completer})
-      : super(
+  ImperativeRouteMatch({
+    required super.pageKey,
+    required this.matches,
+    required this.completer,
+    required this.pipeCompleter,
+  }) : super(
           route: _getsLastRouteFromMatches(matches),
           matchedLocation: _getsMatchedLocationFromMatches(matches),
         );
@@ -460,6 +464,9 @@ class ImperativeRouteMatch extends RouteMatch {
   /// The completer for the future returned by [GoRouter.push].
   final Completer<Object?> completer;
 
+  /// Pipes the completer to the next completer in the chain.
+  final PipeRouteCompleterCallback pipeCompleter;
+
   /// Called when the corresponding [Route] associated with this route match is
   /// completed.
   void complete([dynamic value]) {
@@ -967,6 +974,8 @@ class _RouteMatchListDecoder
           // https://github.com/flutter/flutter/issues/128122.
           completer: Completer<Object?>(),
           matches: imperativeMatchList,
+          // TODO(nouvist): Sorry, I don't know what convert does.
+          pipeCompleter: <Next>(Completer<Next?> next) => next,
         );
         matchList = matchList.push(imperativeMatch);
       }

packages/go_router/lib/src/parser.dart

@@ -117,6 +117,7 @@ class GoRouteInformationParser extends RouteInformationParser<RouteMatchList> {
         baseRouteMatchList: state.baseRouteMatchList,
         completer: state.completer,
         type: state.type,
+        pipeCompleter: state.pipeCompleter,
       );
     });
   }
@@ -168,11 +169,24 @@ class GoRouteInformationParser extends RouteInformationParser<RouteMatchList> {
     return redirectedFuture;
   }
 
+  /// Ensures the replacement routes can resolve the originating route completer.
+  Completer<T?> _pipeCompleter<T extends Object?>(
+    Completer<T?> currentCompleter,
+    RouteMatch lastRouteMatch,
+  ) {
+    if (lastRouteMatch is ImperativeRouteMatch) {
+      return lastRouteMatch.pipeCompleter(currentCompleter);
+    } else {
+      return currentCompleter;
+    }
+  }
+
   RouteMatchList _updateRouteMatchList(
     RouteMatchList newMatchList, {
     required RouteMatchList? baseRouteMatchList,
     required Completer<Object?>? completer,
     required NavigatingType type,
+    required PipeRouteCompleterCallback pipeCompleter,
   }) {
     switch (type) {
       case NavigatingType.push:
@@ -181,32 +195,37 @@ class GoRouteInformationParser extends RouteInformationParser<RouteMatchList> {
             pageKey: _getUniqueValueKey(),
             completer: completer!,
             matches: newMatchList,
+            pipeCompleter: pipeCompleter,
           ),
         );
       case NavigatingType.pushReplacement:
         final RouteMatch routeMatch = baseRouteMatchList!.last;
+        completer = _pipeCompleter(completer!, routeMatch);
         baseRouteMatchList = baseRouteMatchList.remove(routeMatch);
         if (baseRouteMatchList.isEmpty) {
           return newMatchList;
         }
         return baseRouteMatchList.push(
           ImperativeRouteMatch(
             pageKey: _getUniqueValueKey(),
-            completer: completer!,
+            completer: completer,
             matches: newMatchList,
+            pipeCompleter: pipeCompleter,
           ),
         );
       case NavigatingType.replace:
         final RouteMatch routeMatch = baseRouteMatchList!.last;
+        completer = _pipeCompleter(completer!, routeMatch);
         baseRouteMatchList = baseRouteMatchList.remove(routeMatch);
         if (baseRouteMatchList.isEmpty) {
           return newMatchList;
         }
         return baseRouteMatchList.push(
           ImperativeRouteMatch(
             pageKey: routeMatch.pageKey,
-            completer: completer!,
+            completer: completer,
             matches: newMatchList,
+            pipeCompleter: pipeCompleter,
           ),
         );
       case NavigatingType.go: