From ca798804b244a380875abc1da5f0cff99164f539 Mon Sep 17 00:00:00 2001
From: Anas Barghoud <abarghoud@gmail.com>
Date: Mon, 15 Jul 2019 23:00:01 +0200
Subject: [PATCH] fix(router): export DefaultRouteReuseStrategy to Router
 public_api (#31575)

export DefaultRouteStrategy class that was used internally and exposed, and add documentation for each one of methods

PR Close #31575
---
 goldens/public-api/router/router.d.ts       |  8 +++++
 packages/router/src/index.ts                |  2 +-
 packages/router/src/route_reuse_strategy.ts | 38 +++++++++++++++++++--
 3 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/goldens/public-api/router/router.d.ts b/goldens/public-api/router/router.d.ts
index 41395ae9bb..8e88ac7b7c 100644
--- a/goldens/public-api/router/router.d.ts
+++ b/goldens/public-api/router/router.d.ts
@@ -51,6 +51,14 @@ export declare class ActivationStart {
     toString(): string;
 }
 
+export declare abstract class BaseRouteReuseStrategy implements RouteReuseStrategy {
+    retrieve(route: ActivatedRouteSnapshot): DetachedRouteHandle | null;
+    shouldAttach(route: ActivatedRouteSnapshot): boolean;
+    shouldDetach(route: ActivatedRouteSnapshot): boolean;
+    shouldReuseRoute(future: ActivatedRouteSnapshot, curr: ActivatedRouteSnapshot): boolean;
+    store(route: ActivatedRouteSnapshot, detachedTree: DetachedRouteHandle): void;
+}
+
 export declare interface CanActivate {
     canActivate(route: ActivatedRouteSnapshot, state: RouterStateSnapshot): Observable<boolean | UrlTree> | Promise<boolean | UrlTree> | boolean | UrlTree;
 }
diff --git a/packages/router/src/index.ts b/packages/router/src/index.ts
index ffd02e06c8..ea41cbd7ac 100644
--- a/packages/router/src/index.ts
+++ b/packages/router/src/index.ts
@@ -13,7 +13,7 @@ export {RouterLinkActive} from './directives/router_link_active';
 export {RouterOutlet} from './directives/router_outlet';
 export {ActivationEnd, ActivationStart, ChildActivationEnd, ChildActivationStart, Event, GuardsCheckEnd, GuardsCheckStart, NavigationCancel, NavigationEnd, NavigationError, NavigationStart, ResolveEnd, ResolveStart, RouteConfigLoadEnd, RouteConfigLoadStart, RouterEvent, RoutesRecognized, Scroll} from './events';
 export {CanActivate, CanActivateChild, CanDeactivate, CanLoad, Resolve} from './interfaces';
-export {DetachedRouteHandle, RouteReuseStrategy} from './route_reuse_strategy';
+export {BaseRouteReuseStrategy, DetachedRouteHandle, RouteReuseStrategy} from './route_reuse_strategy';
 export {Navigation, NavigationExtras, Router} from './router';
 export {ROUTES} from './router_config_loader';
 export {ExtraOptions, InitialNavigation, provideRoutes, ROUTER_CONFIGURATION, ROUTER_INITIALIZER, RouterModule} from './router_module';
diff --git a/packages/router/src/route_reuse_strategy.ts b/packages/router/src/route_reuse_strategy.ts
index 0d2a0241ac..8af9f8d9d7 100644
--- a/packages/router/src/route_reuse_strategy.ts
+++ b/packages/router/src/route_reuse_strategy.ts
@@ -60,20 +60,54 @@ export abstract class RouteReuseStrategy {
 }
 
 /**
- * Does not detach any subtrees. Reuses routes as long as their route config is the same.
+ * @description
+ *
+ * This base route reuse strategy only reuses routes when the matched router configs are
+ * identical. This prevents components from being destroyed and recreated
+ * when just the fragment or query parameters change
+ * (that is, the existing component is _reused_).
+ *
+ * This strategy does not store any routes for later reuse.
+ *
+ * Angular uses this strategy by default.
+ *
+ *
+ * It can be used as a base class for custom route reuse strategies, i.e. you can create your own
+ * class that extends the `BaseRouteReuseStrategy` one.
+ * @publicApi
  */
-export class DefaultRouteReuseStrategy implements RouteReuseStrategy {
+export abstract class BaseRouteReuseStrategy implements RouteReuseStrategy {
+  /**
+   * Whether the given route should detach for later reuse.
+   * Always returns false for `BaseRouteReuseStrategy`.
+   * */
   shouldDetach(route: ActivatedRouteSnapshot): boolean {
     return false;
   }
+
+  /**
+   * A no-op; the route is never stored since this strategy never detaches routes for later re-use.
+   */
   store(route: ActivatedRouteSnapshot, detachedTree: DetachedRouteHandle): void {}
+
+  /** Returns `false`, meaning the route (and its subtree) is never reattached */
   shouldAttach(route: ActivatedRouteSnapshot): boolean {
     return false;
   }
+
+  /** Returns `null` because this strategy does not store routes for later re-use. */
   retrieve(route: ActivatedRouteSnapshot): DetachedRouteHandle|null {
     return null;
   }
+
+  /**
+   * Determines if a route should be reused.
+   * This strategy returns `true` when the future route config and current route config are
+   * identical.
+   */
   shouldReuseRoute(future: ActivatedRouteSnapshot, curr: ActivatedRouteSnapshot): boolean {
     return future.routeConfig === curr.routeConfig;
   }
 }
+
+export class DefaultRouteReuseStrategy extends BaseRouteReuseStrategy {}