feat(router): add urlUpdateStrategy allow updating the browser URL at the beginning of navigation (#24820)

Fixes #24616

PR Close #24820

packages/router/src/router.ts

@@ -285,6 +285,18 @@ export class Router {
    */
   paramsInheritanceStrategy: 'emptyOnly'|'always' = 'emptyOnly';
 
+  /**
+   * Defines when the router updates the browser URL. The default behavior is to update after
+   * successful navigation. However, some applications may prefer a mode where the URL gets
+   * updated at the beginning of navigation. The most common use case would be updating the
+   * URL early so if navigation fails, you can show an error message with the URL that failed.
+   * Available options are:
+   *
+   * - `'deferred'`, the default, updates the browser URL after navigation has finished.
+   * - `'eager'`, updates browser URL at the beginning of navigation.
+   */
+  urlUpdateStrategy: 'deferred'|'eager' = 'deferred';
+
   /**
    * Creates the router service.
    */
@@ -610,6 +622,9 @@ export class Router {
 
     if ((this.onSameUrlNavigation === 'reload' ? true : urlTransition) &&
         this.urlHandlingStrategy.shouldProcessUrl(rawUrl)) {
+      if (this.urlUpdateStrategy === 'eager' && !extras.skipLocationChange) {
+        this.setBrowserUrl(rawUrl, !!extras.replaceUrl, id);
+      }
       (this.events as Subject<Event>)
           .next(new NavigationStart(id, this.serializeUrl(url), source, state));
       Promise.resolve()
@@ -791,13 +806,8 @@ export class Router {
 
           (this as{routerState: RouterState}).routerState = state;
 
-          if (!skipLocationChange) {
+          if (this.urlUpdateStrategy === 'deferred' && !skipLocationChange) {
-            const path = this.urlSerializer.serialize(this.rawUrlTree);
+            this.setBrowserUrl(this.rawUrlTree, replaceUrl, id);
-            if (this.location.isCurrentPathEqualTo(path) || replaceUrl) {
-              this.location.replaceState(path, '', {navigationId: id});
-            } else {
-              this.location.go(path, '', {navigationId: id});
-            }
           }
 
           new ActivateRoutes(
@@ -843,6 +853,15 @@ export class Router {
             });
   }
 
+  private setBrowserUrl(url: UrlTree, replaceUrl: boolean, id: number) {
+    const path = this.urlSerializer.serialize(url);
+    if (this.location.isCurrentPathEqualTo(path) || replaceUrl) {
+      this.location.replaceState(path, '', {navigationId: id});
+    } else {
+      this.location.go(path, '', {navigationId: id});
+    }
+  }
+
   private resetStateAndUrl(storedState: RouterState, storedUrl: UrlTree, rawUrl: UrlTree): void {
     (this as{routerState: RouterState}).routerState = storedState;
     this.currentUrlTree = storedUrl;

packages/router/src/router_module.ts

@@ -405,6 +405,18 @@ export interface ExtraOptions {
    * */
   malformedUriErrorHandler?:
       (error: URIError, urlSerializer: UrlSerializer, url: string) => UrlTree;
+
+  /**
+   * Defines when the router updates the browser URL. The default behavior is to update after
+   * successful navigation. However, some applications may prefer a mode where the URL gets
+   * updated at the beginning of navigation. The most common use case would be updating the
+   * URL early so if navigation fails, you can show an error message with the URL that failed.
+   * Available options are:
+   *
+   * - `'deferred'`, the default, updates the browser URL after navigation has finished.
+   * - `'eager'`, updates browser URL at the beginning of navigation.
+   */
+  urlUpdateStrategy?: 'deferred'|'eager';
 }
 
 export function setupRouter(
@@ -449,6 +461,10 @@ export function setupRouter(
     router.paramsInheritanceStrategy = opts.paramsInheritanceStrategy;
   }
 
+  if (opts.urlUpdateStrategy) {
+    router.urlUpdateStrategy = opts.urlUpdateStrategy;
+  }
+
   return router;
 }
 

packages/router/test/integration.spec.ts

@@ -469,6 +469,31 @@ describe('Integration', () => {
        expect(fixture.nativeElement).toHaveText('team 33 [ , right:  ]');
      })));
 
+  it('should eagerly update the URL with urlUpdateStrategy="eagar"',
+     fakeAsync(inject([Router, Location], (router: Router, location: Location) => {
+       const fixture = TestBed.createComponent(RootCmp);
+       advance(fixture);
+
+       router.resetConfig([{path: 'team/:id', component: TeamCmp}]);
+
+       router.navigateByUrl('/team/22');
+       advance(fixture);
+       expect(location.path()).toEqual('/team/22');
+
+       expect(fixture.nativeElement).toHaveText('team 22 [ , right:  ]');
+
+       router.urlUpdateStrategy = 'eager';
+       (router as any).hooks.beforePreactivation = () => {
+         expect(location.path()).toEqual('/team/33');
+         expect(fixture.nativeElement).toHaveText('team 22 [ , right:  ]');
+         return of (null);
+       };
+       router.navigateByUrl('/team/33');
+
+       advance(fixture);
+       expect(fixture.nativeElement).toHaveText('team 33 [ , right:  ]');
+     })));
+
   it('should navigate back and forward',
      fakeAsync(inject([Router, Location], (router: Router, location: Location) => {
        const fixture = createRoot(router, RootCmp);
@@ -868,6 +893,8 @@ describe('Integration', () => {
        ]);
      })));
 
+  // Errors should behave the same for both deferred and eager URL update strategies
+  ['deferred', 'eager'].forEach((strat: any) => {
     it('should dispatch NavigationError after the url has been reset back', fakeAsync(() => {
          const router: Router = TestBed.get(Router);
          const location: SpyLocation = TestBed.get(Location);
@@ -875,6 +902,7 @@ describe('Integration', () => {
 
          router.resetConfig(
              [{path: 'simple', component: SimpleCmp}, {path: 'throwing', component: ThrowingCmp}]);
+         router.urlUpdateStrategy = strat;
 
          router.navigateByUrl('/simple');
          advance(fixture);
@@ -904,7 +932,7 @@ describe('Integration', () => {
            {path: 'simple1', component: SimpleCmp}, {path: 'simple2', component: SimpleCmp},
            {path: 'throwing', component: ThrowingCmp}
          ]);
-
+         router.urlUpdateStrategy = strat;
 
          let event: NavigationStart;
          router.events.subscribe(e => {
@@ -938,6 +966,7 @@ describe('Integration', () => {
 
          router.resetConfig(
              [{path: 'simple', component: SimpleCmp}, {path: 'throwing', component: ThrowingCmp}]);
+         router.urlUpdateStrategy = strat;
 
          const events: any[] = [];
          router.events.forEach((e: any) => {
@@ -956,6 +985,8 @@ describe('Integration', () => {
          expect(events).toEqual(['/simple', '/throwing']);
        }));
 
+  });
+
   it('should dispatch NavigationCancel after the url has been reset back', fakeAsync(() => {
        TestBed.configureTestingModule(
            {providers: [{provide: 'returnsFalse', useValue: () => false}]});

tools/public_api_guard/router/router.d.ts

@@ -121,6 +121,7 @@ export interface ExtraOptions {
     preloadingStrategy?: any;
     scrollOffset?: [number, number] | (() => [number, number]);
     scrollPositionRestoration?: 'disabled' | 'enabled' | 'top';
+    urlUpdateStrategy?: 'deferred' | 'eager';
     useHash?: boolean;
 }
 
@@ -323,6 +324,7 @@ export declare class Router {
     readonly routerState: RouterState;
     readonly url: string;
     urlHandlingStrategy: UrlHandlingStrategy;
+    urlUpdateStrategy: 'deferred' | 'eager';
     constructor(rootComponentType: Type<any> | null, urlSerializer: UrlSerializer, rootContexts: ChildrenOutletContexts, location: Location, injector: Injector, loader: NgModuleFactoryLoader, compiler: Compiler, config: Routes);
     createUrlTree(commands: any[], navigationExtras?: NavigationExtras): UrlTree;
     dispose(): void;