[go_router] Return a value on pop

packages/go_router/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 4.3.0
+
+- Adds a promise option to `push` and `pushNamed` making it posible to await results from a `pop`.
+- Adds an optional parameter to the `pop` method, allowing to return values from a `pop`.
+
 ## 4.2.7
 
 - Update README

packages/go_router/README.md

@@ -134,6 +134,20 @@ methods:
 onTap: () => context.go('/page2')
 ```
 
+
+To wait for values when the screen pops:
+
+```dart
+onTap: () {
+  // In the new page you can do 'context.pop<bool>(someValue)' to return a value.
+  final bool? result = await context.push<bool>('/page2');
+
+  WidgetsBinding.instance.addPostFrameCallback((_) {
+    if(result ?? false)...
+  });
+}
+```
+
 ### Still not sure how to proceed?
 See [examples](https://github.com/flutter/packages/tree/main/packages/go_router/example) for complete runnable examples or visit [API documentation](https://pub.dev/documentation/go_router/latest/go_router/go_router-library.html)
 

packages/go_router/lib/src/delegate.dart

@@ -44,13 +44,21 @@ class GoRouterDelegate extends RouterDelegate<RouteMatchList>
 
   final GlobalKey<NavigatorState> _key = GlobalKey<NavigatorState>();
 
+  /// The list of completers for the promises when pushing asynchronous routes.
+  final Map<String, Completer<dynamic>> _completers =
+      <String, Completer<dynamic>>{};
   RouteMatchList _matches = RouteMatchList.empty();
   final Map<String, int> _pushCounts = <String, int>{};
 
-  /// Pushes the given location onto the page stack
-  void push(RouteMatch match) {
-    // Remap the pageKey to allow any number of the same page on the stack
+  /// Pushes the given location onto the page stack with an optional promise.
+  Future<T?> push<T extends Object?>(RouteMatch match) {
+    // Remap the pageKey to allow any number of the same page on the stack.
     final String fullPath = match.fullpath;
+
+    // Create a completer for the promise and store it in the completers map.
+    final Completer<T> completer = Completer<T>();
+    _completers[fullPath] = completer;
+
     final int count = (_pushCounts[fullPath] ?? 0) + 1;
     _pushCounts[fullPath] = count;
     final ValueKey<String> pageKey = ValueKey<String>('$fullPath-p$count');
@@ -67,15 +75,27 @@ class GoRouterDelegate extends RouterDelegate<RouteMatchList>
 
     _matches.push(newPageKeyMatch);
     notifyListeners();
+    return completer.future;
   }
 
   /// Returns `true` if there is more than 1 page on the stack.
   bool canPop() {
     return _matches.canPop();
   }
 
-  /// Pop the top page off the GoRouter's page stack.
-  void pop() {
+  /// Pop the top page off the GoRouter's page stack and complete a promise if
+  /// there is one.
+  void pop<T extends Object?>([T? value]) {
+    final RouteMatch last = _matches.last;
+
+    // If there is a promise for this page, complete it.
+    final Completer<T>? completer = _completers[last.fullpath] as Completer<T>?;
+    if (completer != null) {
+      completer.complete(value);
+    }
+
+    // Remove promise from completers map.
+    _completers.remove(last.fullpath);
     _matches.pop();
     notifyListeners();
   }
@@ -85,7 +105,17 @@ class GoRouterDelegate extends RouterDelegate<RouteMatchList>
   /// See also:
   /// * [push] which pushes the given location onto the page stack.
   void replace(RouteMatch match) {
+    final String lastPath = _matches.last.fullpath;
+    final Completer<dynamic>? completer = _completers[lastPath];
+
+    // If there's a promise for the last page, we update it to make it point to
+    // the new page.
+    if (completer != null) {
+      _completers[match.fullpath] = completer;
+      _completers.remove(lastPath);
+    }
     _matches.matches.last = match;
+
     notifyListeners();
   }
 

packages/go_router/lib/src/misc/extensions.dart

@@ -36,18 +36,18 @@ extension GoRouterHelper on BuildContext {
         extra: extra,
       );
 
-  /// Push a location onto the page stack.
-  void push(String location, {Object? extra}) =>
+  /// Push a location onto the page stack with an optional promise.
+  Future<T?> push<T extends Object?>(String location, {Object? extra}) =>
       GoRouter.of(this).push(location, extra: extra);
 
-  /// Navigate to a named route onto the page stack.
-  void pushNamed(
+  /// Navigate to a named route onto the page stack with an optional promise.
+  Future<T?> pushNamed<T extends Object?>(
     String name, {
     Map<String, String> params = const <String, String>{},
     Map<String, String> queryParams = const <String, String>{},
     Object? extra,
   }) =>
-      GoRouter.of(this).pushNamed(
+      GoRouter.of(this).pushNamed<T>(
         name,
         params: params,
         queryParams: queryParams,
@@ -59,7 +59,7 @@ extension GoRouterHelper on BuildContext {
 
   /// Pop the top page off the Navigator's page stack by calling
   /// [Navigator.pop].
-  void pop() => GoRouter.of(this).pop();
+  void pop<T extends Object?>([T? value]) => GoRouter.of(this).pop<T>(value);
 
   /// Replaces the top-most page of the page stack with the given URL location
   /// w/ optional query parameters, e.g. `/family/f2/person/p1?color=blue`.

packages/go_router/lib/src/router.dart

@@ -175,34 +175,44 @@ class GoRouter extends ChangeNotifier with NavigatorObserver {
         extra: extra,
       );
 
-  /// Push a URI location onto the page stack w/ optional query parameters, e.g.
-  /// `/family/f2/person/p1?color=blue`
-  void push(String location, {Object? extra}) {
+  /// Push a URI location onto the page stack w/ optional query parameters
+  /// and promise, e.g. `/family/f2/person/p1?color=blue`.
+  Future<T?> push<T extends Object?>(String location, {Object? extra}) async {
     assert(() {
       log.info('pushing $location');
       return true;
     }());
-    _routeInformationParser
-        .parseRouteInformation(
-            DebugGoRouteInformation(location: location, state: extra))
-        .then<void>((RouteMatchList matches) {
-      _routerDelegate.push(matches.last);
-    });
+    final RouteMatchList matches =
+        await _routeInformationParser.parseRouteInformation(
+            DebugGoRouteInformation(location: location, state: extra));
+    return _routerDelegate.push<T>(matches.last);
   }
 
-  /// Push a named route onto the page stack w/ optional parameters, e.g.
-  /// `name='person', params={'fid': 'f2', 'pid': 'p1'}`
-  void pushNamed(
+  /// Push a named route asynchronously onto the page stack w/ optional
+  /// parameters and promise.
+  Future<T?> pushNamed<T extends Object?>(
     String name, {
     Map<String, String> params = const <String, String>{},
     Map<String, String> queryParams = const <String, String>{},
     Object? extra,
   }) =>
-      push(
+      push<T>(
         namedLocation(name, params: params, queryParams: queryParams),
         extra: extra,
       );
 
+  /// Returns `true` if there is more than 1 page on the stack.
+  bool canPop() => _routerDelegate.canPop();
+
+  /// Pop the top page off the GoRouter's page stack.
+  void pop<T extends Object?>([T? result]) {
+    assert(() {
+      log.info('popping $location');
+      return true;
+    }());
+    routerDelegate.pop(result);
+  }
+
   /// Replaces the top-most page of the page stack with the given URL location
   /// w/ optional query parameters, e.g. `/family/f2/person/p1?color=blue`.
   ///
@@ -238,18 +248,6 @@ class GoRouter extends ChangeNotifier with NavigatorObserver {
     );
   }
 
-  /// Returns `true` if there is more than 1 page on the stack.
-  bool canPop() => _routerDelegate.canPop();
-
-  /// Pop the top page off the GoRouter's page stack.
-  void pop() {
-    assert(() {
-      log.info('popping $location');
-      return true;
-    }());
-    _routerDelegate.pop();
-  }
-
   /// Refresh the route.
   void refresh() {
     assert(() {

packages/go_router/pubspec.yaml

@@ -1,7 +1,7 @@
 name: go_router
 description: A declarative router for Flutter based on Navigation 2 supporting
   deep linking, data-driven routes and more
-version: 4.2.7
+version: 4.3.0
 repository: https://github.com/flutter/packages/tree/main/packages/go_router
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+go_router%22
 

packages/go_router/test/go_router_test.dart

@@ -1676,7 +1676,7 @@ void main() {
           title: 'GoRouter Example',
         ),
       );
-      key.currentContext!.namedLocation(
+      key.currentContext?.namedLocation(
         name,
         params: params,
         queryParams: queryParams,
@@ -1696,7 +1696,7 @@ void main() {
           title: 'GoRouter Example',
         ),
       );
-      key.currentContext!.go(
+      key.currentContext?.go(
         location,
         extra: extra,
       );
@@ -1715,7 +1715,7 @@ void main() {
           title: 'GoRouter Example',
         ),
       );
-      key.currentContext!.goNamed(
+      key.currentContext?.goNamed(
         name,
         params: params,
         queryParams: queryParams,
@@ -1738,14 +1738,34 @@ void main() {
           title: 'GoRouter Example',
         ),
       );
-      key.currentContext!.push(
+      await key.currentContext?.push(
         location,
         extra: extra,
       );
       expect(router.myLocation, location);
       expect(router.extra, extra);
     });
 
+    testWidgets('calls [push] on closest GoRouter with a promise',
+        (WidgetTester tester) async {
+      final GoRouterPushAsyncSpy router = GoRouterPushAsyncSpy(routes: routes);
+      await tester.pumpWidget(
+        MaterialApp.router(
+          routeInformationProvider: router.routeInformationProvider,
+          routeInformationParser: router.routeInformationParser,
+          routerDelegate: router.routerDelegate,
+          title: 'GoRouter Example',
+        ),
+      );
+      final String? result = await key.currentContext?.push<String>(
+        location,
+        extra: extra,
+      );
+      expect(result, extra);
+      expect(router.myLocation, location);
+      expect(router.extra, extra);
+    });
+
     testWidgets('calls [pushNamed] on closest GoRouter',
         (WidgetTester tester) async {
       final GoRouterPushNamedSpy router = GoRouterPushNamedSpy(routes: routes);
@@ -1757,16 +1777,41 @@ void main() {
           title: 'GoRouter Example',
         ),
       );
-      key.currentContext!.pushNamed(
+      await key.currentContext?.pushNamed(
         name,
         params: params,
         queryParams: queryParams,
         extra: extra,
       );
+      expect(router.extra, extra);
       expect(router.name, name);
       expect(router.params, params);
       expect(router.queryParams, queryParams);
+    });
+
+    testWidgets('calls [pushNamed] on closest GoRouter with a promise',
+        (WidgetTester tester) async {
+      final GoRouterPushNamedAsyncSpy router =
+          GoRouterPushNamedAsyncSpy(routes: routes);
+      await tester.pumpWidget(
+        MaterialApp.router(
+          routeInformationProvider: router.routeInformationProvider,
+          routeInformationParser: router.routeInformationParser,
+          routerDelegate: router.routerDelegate,
+          title: 'GoRouter Example',
+        ),
+      );
+      final String? result = await key.currentContext?.pushNamed<String>(
+        name,
+        params: params,
+        queryParams: queryParams,
+        extra: extra,
+      );
+      expect(result, extra);
       expect(router.extra, extra);
+      expect(router.name, name);
+      expect(router.params, params);
+      expect(router.queryParams, queryParams);
     });
 
     testWidgets('calls [pop] on closest GoRouter', (WidgetTester tester) async {
@@ -1779,7 +1824,7 @@ void main() {
           title: 'GoRouter Example',
         ),
       );
-      key.currentContext!.pop();
+      key.currentContext?.pop();
       expect(router.popped, true);
     });
   });

packages/go_router/test/inherited_test.dart

@@ -129,10 +129,11 @@ class MockGoRouter extends GoRouter {
   late String latestPushedName;
 
   @override
-  void pushNamed(String name,
+  Future<T?> pushNamed<T extends Object?>(String name,
       {Map<String, String> params = const <String, String>{},
       Map<String, String> queryParams = const <String, String>{},
       Object? extra}) {
     latestPushedName = name;
+    return Future<T>.value();
   }
 }