feat(router): Add partial ActivatedRouteSnapshot information to canMatch params

This commit adds partial `ActivatedRouteSnapshot` information as the
third parameter of the `canMatch` guard.

resolves #49309

Author: atscott

goldens/public-api/router/index.api.md

@@ -151,11 +151,11 @@ export type CanLoadFn = (route: Route, segments: UrlSegment[]) => MaybeAsync<Gua
 // @public
 export interface CanMatch {
     // (undocumented)
-    canMatch(route: Route, segments: UrlSegment[]): MaybeAsync<GuardResult>;
+    canMatch(route: Route, segments: UrlSegment[], currentSnapshot?: PartialMatchRouteSnapshot): MaybeAsync<GuardResult>;
 }
 
 // @public
-export type CanMatchFn = (route: Route, segments: UrlSegment[]) => MaybeAsync<GuardResult>;
+export type CanMatchFn = (route: Route, segments: UrlSegment[], currentSnapshot?: PartialMatchRouteSnapshot) => MaybeAsync<GuardResult>;
 
 // @public
 export class ChildActivationEnd {

packages/core/test/bundling/router/bundle.golden_symbols.json

@@ -520,6 +520,7 @@
       "createOrReusePlatformInjector",
       "createPlatformInjector",
       "createPositionApplyingDoubleDots",
+      "createPreMatchRouteSnapshot",
       "createProvidersConfig",
       "createResultByTNodeType",
       "createResultForNode",

packages/router/src/models.ts

@@ -1151,7 +1151,11 @@ export type CanDeactivateFn<T> = (
  * @see [CanMatch](guide/routing/route-guards#canmatch)
  */
 export interface CanMatch {
-  canMatch(route: Route, segments: UrlSegment[]): MaybeAsync<GuardResult>;
+  canMatch(
+    route: Route,
+    segments: UrlSegment[],
+    currentSnapshot?: PartialMatchRouteSnapshot,
+  ): MaybeAsync<GuardResult>;
 }
 
 /**
@@ -1168,12 +1172,19 @@ export interface CanMatch {
  *
  * @param route The route configuration.
  * @param segments The URL segments that have not been consumed by previous parent route evaluations.
+ * @param currentSnapshot The current route snapshot up to this point in the matching process. While this parameter is optional,
+ * it will always be defined when called by the Router. It is only optional for backwards compatibility with functions defined prior
+ * to the introduction of this parameter.
  *
  * @publicApi
  * @see {@link Route}
  * @see [CanMatch](guide/routing/route-guards#canmatch)
  */
-export type CanMatchFn = (route: Route, segments: UrlSegment[]) => MaybeAsync<GuardResult>;
+export type CanMatchFn = (
+  route: Route,
+  segments: UrlSegment[],
+  currentSnapshot?: PartialMatchRouteSnapshot,
+) => MaybeAsync<GuardResult>;
 
 /**
  * A subset of the `ActivatedRouteSnapshot` interface that includes only the known data

packages/router/src/operators/check_guards.ts

@@ -28,6 +28,7 @@ import {
   CanLoadFn,
   CanMatchFn,
   Route,
+  PartialMatchRouteSnapshot,
 } from '../models';
 import {redirectingNavigationError} from '../navigation_canceling_error';
 import type {NavigationTransition} from '../navigation_transition';
@@ -266,6 +267,7 @@ export function runCanMatchGuards(
   route: Route,
   segments: UrlSegment[],
   urlSerializer: UrlSerializer,
+  currentSnapshot: PartialMatchRouteSnapshot,
   abortSignal: AbortSignal,
 ): Observable<GuardResult> {
   const canMatch = route.canMatch;
@@ -274,8 +276,10 @@ export function runCanMatchGuards(
   const canMatchObservables = canMatch.map((injectionToken) => {
     const guard = getTokenOrFunctionIdentity(injectionToken as ProviderToken<any>, injector);
     const guardVal = isCanMatch(guard)
-      ? guard.canMatch(route, segments)
-      : runInInjectionContext(injector, () => (guard as CanMatchFn)(route, segments));
+      ? guard.canMatch(route, segments, currentSnapshot)
+      : runInInjectionContext(injector, () =>
+          (guard as CanMatchFn)(route, segments, currentSnapshot),
+        );
     return wrapIntoObservable(guardVal).pipe(takeUntilAbort(abortSignal));
   });
 

packages/router/src/recognize.ts

@@ -24,8 +24,10 @@ import {Params, PRIMARY_OUTLET} from './shared';
 import {UrlSegment, UrlSegmentGroup, UrlSerializer, UrlTree} from './url_tree';
 import {getOutlet, sortByMatchingOutlets} from './utils/config';
 import {
+  createPreMatchRouteSnapshot,
   emptyPathMatch,
   match,
+  MatchResult,
   matchWithChecks,
   noLeftoversInUrl,
   split,
@@ -356,7 +358,7 @@ export class Recognizer {
       consumedSegments,
       route.redirectTo!,
       positionalParamSegments,
-      currentSnapshot,
+      createPreMatchRouteSnapshot(currentSnapshot),
       injector,
     );
 
@@ -408,8 +410,19 @@ export class Recognizer {
     if (this.abortSignal.aborted) {
       throw new Error(this.abortSignal.reason);
     }
+
+    const createSnapshot = (result: MatchResult) =>
+      this.createSnapshot(injector, route, result.consumedSegments, result.parameters, parentRoute);
     const result = await firstValueFrom(
-      matchWithChecks(rawSegment, route, segments, injector, this.urlSerializer, this.abortSignal),
+      matchWithChecks(
+        rawSegment,
+        route,
+        segments,
+        injector,
+        this.urlSerializer,
+        createSnapshot,
+        this.abortSignal,
+      ),
     );
     if (route.path === '**') {
       // Prior versions of the route matching algorithm would stop matching at the wildcard route.

packages/router/src/utils/config_matching.ts

@@ -10,8 +10,9 @@ import {EnvironmentInjector} from '@angular/core';
 import {Observable, of} from 'rxjs';
 import {map} from 'rxjs/operators';
 
-import {Route} from '../models';
+import {PartialMatchRouteSnapshot, Route} from '../models';
 import {runCanMatchGuards} from '../operators/check_guards';
+import {ActivatedRouteSnapshot} from '../router_state';
 import {defaultUrlMatcher, PRIMARY_OUTLET} from '../shared';
 import {UrlSegment, UrlSegmentGroup, UrlSerializer} from '../url_tree';
 
@@ -33,25 +34,49 @@ const noMatch: MatchResult = {
   positionalParamSegments: {},
 };
 
+export function createPreMatchRouteSnapshot(
+  snapshot: ActivatedRouteSnapshot,
+): PartialMatchRouteSnapshot {
+  return {
+    routeConfig: snapshot.routeConfig,
+    url: snapshot.url,
+    params: snapshot.params,
+    queryParams: snapshot.queryParams,
+    fragment: snapshot.fragment,
+    data: snapshot.data,
+    outlet: snapshot.outlet,
+    title: snapshot.title,
+    paramMap: snapshot.paramMap,
+    queryParamMap: snapshot.queryParamMap,
+  };
+}
+
 export function matchWithChecks(
   segmentGroup: UrlSegmentGroup,
   route: Route,
   segments: UrlSegment[],
   injector: EnvironmentInjector,
   urlSerializer: UrlSerializer,
+  createSnapshot: (result: MatchResult) => ActivatedRouteSnapshot,
   abortSignal: AbortSignal,
 ): Observable<MatchResult> {
   const result = match(segmentGroup, route, segments);
   if (!result.matched) {
     return of(result);
   }
 
+  const currentSnapshot = createPreMatchRouteSnapshot(createSnapshot(result));
   // Only create the Route's `EnvironmentInjector` if it matches the attempted
   // navigation
   injector = getOrCreateRouteInjectorIfNeeded(route, injector);
-  return runCanMatchGuards(injector, route, segments, urlSerializer, abortSignal).pipe(
-    map((v) => (v === true ? result : {...noMatch})),
-  );
+  return runCanMatchGuards(
+    injector,
+    route,
+    segments,
+    urlSerializer,
+    currentSnapshot,
+    abortSignal,
+  ).pipe(map((v) => (v === true ? result : {...noMatch})));
 }
 
 export function match(

packages/router/test/integration/guards.spec.ts

@@ -26,6 +26,8 @@ import {
   Router,
   NavigationStart,
   RoutesRecognized,
+  Route,
+  UrlSegment,
   GuardsCheckStart,
   ChildActivationStart,
   ActivationStart,
@@ -50,6 +52,7 @@ import {
   CanActivateFn,
   CanActivateChildFn,
   CanDeactivateFn,
+  PartialMatchRouteSnapshot,
 } from '../../src';
 import {wrapIntoObservable} from '../../src/utils/collection';
 import {RouterTestingHarness} from '../../testing';
@@ -2226,6 +2229,61 @@ export function guardsIntegrationSuite() {
         // same time
         expect(delayedGuardSpy.calls.count()).toEqual(1);
       });
+
+      it('receives PreMatchRouteSnapshot as third argument', async () => {
+        const router = TestBed.inject(Router);
+        const fixture = await createRoot(router, RootCmp);
+        let capturedSnapshot: PartialMatchRouteSnapshot | undefined;
+
+        router.resetConfig([
+          {
+            path: 'a/:id',
+            canMatch: [
+              (route: Route, segments: UrlSegment[], snapshot: PartialMatchRouteSnapshot) => {
+                capturedSnapshot = snapshot;
+                return true;
+              },
+            ],
+            component: SimpleCmp,
+          },
+        ]);
+
+        await router.navigateByUrl('/a/1?q=2#f');
+        expect(capturedSnapshot).toBeDefined();
+        expect(capturedSnapshot!.params['id']).toBe('1');
+        expect(capturedSnapshot!.queryParams['q']).toBe('2');
+        expect(capturedSnapshot!.fragment).toBe('f');
+      });
+
+      it('can redirect based on snapshot params', async () => {
+        const router = TestBed.inject(Router);
+        const fixture = await createRoot(router, RootCmp);
+
+        router.resetConfig([
+          {
+            path: 'a/:id',
+            canMatch: [
+              (route: Route, segments: UrlSegment[], snapshot: PartialMatchRouteSnapshot) => {
+                const router = inject(Router);
+                if (snapshot.params['id'] === '1') {
+                  return router.parseUrl('/b');
+                }
+                return true;
+              },
+            ],
+            component: SimpleCmp,
+          },
+          {path: 'b', component: BlankCmp},
+        ]);
+
+        await router.navigateByUrl('/a/1');
+        await advance(fixture);
+        expect(router.url).toEqual('/b');
+
+        await router.navigateByUrl('/a/2');
+        await advance(fixture);
+        expect(router.url).toEqual('/a/2');
+      });
     });
 
     it('should allow guards as functions', async () => {