feat: improve hmr conditions around routing

Author: NathanWalker

packages/angular/src/lib/application.ts

@@ -20,9 +20,12 @@ import {
   getAngularCoreForHmrReset,
   rememberAngularCoreForHmr,
   resetAngularHmrCompiledComponents,
+  setAngularCoreForHmr,
 } from './hmr-compiled-components-core';
 import { NativeScriptLoadingService } from './loading.service';
 import { clearAngularHmrRouteConfigCaches } from './legacy/router/hmr-route-cache-core';
+import { NSLocationStrategy } from './legacy/router/ns-location-strategy';
+import { NSRouteReuseStrategy } from './legacy/router/ns-route-reuse-strategy';
 import { createAngularRootTransitionGuard } from './root-transition-guard';
 import { APP_ROOT_VIEW, DISABLE_ROOT_VIEW_HANDLING, NATIVESCRIPT_ROOT_MODULE_ID } from './tokens';
 import { NativeScriptDebug } from './trace';
@@ -32,6 +35,9 @@ import { NativeScriptDebug } from './trace';
 // We need to use the original one that has the registered LViews
 rememberAngularCoreForHmr(AngularCore as any, globalThis as any);
 
+const angularHmrGlobal = globalThis as any;
+angularHmrGlobal.__NS_REMEMBER_ANGULAR_CORE__ = (core: any) => setAngularCoreForHmr(core, angularHmrGlobal);
+
 export interface AppLaunchView extends LayoutBase {
   // called when the animation is to begin
   startAnimation?: () => void;
@@ -234,18 +240,43 @@ export interface ApplicationConfig {
 }
 
 export function runNativeScriptAngularApp<T, K>(options: AppRunOptions<T, K>) {
+  const hmrGlobal = globalThis as any;
+
+  if (hmrGlobal.__NS_ANGULAR_HMR_REGISTER_ONLY__ && typeof hmrGlobal.__NS_UPDATE_ANGULAR_APP_OPTIONS__ === 'function') {
+    hmrGlobal.__NS_UPDATE_ANGULAR_APP_OPTIONS__(options);
+    return;
+  }
+
+  let currentOptions = options;
   let mainModuleRef: NgModuleRef<T> | ApplicationRef = null;
   let loadingModuleRef: NgModuleRef<K> | ApplicationRef;
   let platformRef: PlatformRef = null;
   let bootstrapId = -1;
+
+  hmrGlobal.__NS_UPDATE_ANGULAR_APP_OPTIONS__ = (nextOptions: AppRunOptions<T, K>) => {
+    currentOptions = nextOptions;
+  };
+
   const clearAngularHmrRouteCaches = () => {
     try {
       const injector = (mainModuleRef as any)?.injector;
+      const reuseStrategy = injector?.get?.(NSRouteReuseStrategy, null);
+      const locationStrategy = injector?.get?.(NSLocationStrategy, null);
       const router = injector?.get?.(Router, null);
+      const clearedDetached = reuseStrategy?.clearAllCaches?.() ?? 0;
+      const clearedLocation = locationStrategy?.resetForHmr?.() ?? null;
       const cleared = clearAngularHmrRouteConfigCaches(router?.config);
 
-      if (cleared > 0) {
-        console.log('[ng-hmr] cleared Angular route caches before reboot:', cleared);
+      if (
+        clearedDetached > 0 ||
+        cleared > 0 ||
+        (clearedLocation && (clearedLocation.outlets > 0 || clearedLocation.states > 0 || clearedLocation.callbacks > 0 || clearedLocation.hadUrlTree))
+      ) {
+        console.log('[ng-hmr] cleared Angular route caches before reboot:', {
+          detachedViews: clearedDetached,
+          locationState: clearedLocation,
+          routeFields: cleared,
+        });
       }
     } catch {}
   };
@@ -299,7 +330,7 @@ export function runNativeScriptAngularApp<T, K>(options: AppRunOptions<T, K>) {
       if (NativeScriptDebug.isLogEnabled()) {
         NativeScriptDebug.bootstrapLog(`Setting RootView to ${ref}`);
       }
-      if (options.embedded) {
+      if (currentOptions.embedded) {
         Application.run({ create: () => ref });
       } else if (launchEventDone) {
         rootTransitionGuard.runApplicationResetRootView(Application, () => ref, ref?.constructor?.name || 'View');
@@ -317,11 +348,11 @@ export function runNativeScriptAngularApp<T, K>(options: AppRunOptions<T, K>) {
       'newRoot:',
       newRoot?.constructor?.name,
     );
-    console.log('[ng-hmr] setRootView: launchEventDone:', launchEventDone, 'embedded:', options.embedded);
+    console.log('[ng-hmr] setRootView: launchEventDone:', launchEventDone, 'embedded:', currentOptions.embedded);
     if (NativeScriptDebug.isLogEnabled()) {
       NativeScriptDebug.bootstrapLog(`Setting RootView to ${newRoot}`);
     }
-    if (options.embedded) {
+    if (currentOptions.embedded) {
       console.log('[ng-hmr] setRootView: calling Application.run (embedded)');
       Application.run({ create: () => newRoot });
     } else if (launchEventDone) {
@@ -372,7 +403,7 @@ export function runNativeScriptAngularApp<T, K>(options: AppRunOptions<T, K>) {
       };
       runSynchronously(
         () =>
-          options.appModuleBootstrap(reason).then(
+          currentOptions.appModuleBootstrap(reason).then(
             (ref) => {
               console.log('[ng-hmr] appModuleBootstrap resolved, ref:', ref?.constructor?.name);
               console.log('[ng-hmr] currentBootstrapId:', currentBootstrapId, 'bootstrapId:', bootstrapId);
@@ -482,9 +513,9 @@ export function runNativeScriptAngularApp<T, K>(options: AppRunOptions<T, K>) {
             return;
           }
           if (!bootstrapped) {
-            if (options.loadingModule) {
+            if (currentOptions.loadingModule) {
               runSynchronously(() =>
-                options.loadingModule(reason).then(
+                currentOptions.loadingModule(reason).then(
                   (loadingRef) => {
                     if (currentBootstrapId !== bootstrapId) {
                       // this module is old and not needed anymore
@@ -536,8 +567,8 @@ export function runNativeScriptAngularApp<T, K>(options: AppRunOptions<T, K>) {
                   },
                 ),
               );
-            } else if (options.launchView) {
-              let launchView = options.launchView(reason);
+            } else if (currentOptions.launchView) {
+              let launchView = currentOptions.launchView(reason);
               setRootView(launchView);
               if (launchView.startAnimation) {
                 setTimeout(() => {
@@ -606,7 +637,7 @@ export function runNativeScriptAngularApp<T, K>(options: AppRunOptions<T, K>) {
     global.NativeScriptGlobals.events.addEventListener =
       global.NativeScriptGlobals.events[Zone.__symbol__('addEventListener')];
   }
-  if (!options.embedded) {
+  if (!currentOptions.embedded) {
     Application.on(Application.launchEvent, launchCallback);
   }
   Application.on(Application.exitEvent, exitCallback);
@@ -681,7 +712,7 @@ export function runNativeScriptAngularApp<T, K>(options: AppRunOptions<T, K>) {
     return;
   }
 
-  if (options.embedded) {
+  if (currentOptions.embedded) {
     bootstrapRoot('applaunch');
   } else {
     Application.run();

packages/angular/src/lib/hmr-compiled-components-core.spec.ts

@@ -2,6 +2,7 @@ import {
   getAngularCoreForHmrReset,
   rememberAngularCoreForHmr,
   resetAngularHmrCompiledComponents,
+  setAngularCoreForHmr,
 } from './hmr-compiled-components-core';
 
 describe('Angular HMR compiled component reset', () => {
@@ -57,4 +58,19 @@ describe('Angular HMR compiled component reset', () => {
     expect(rememberAngularCoreForHmr(replacementCore, globalObj)).toBe(originalCore);
     expect(globalObj.__NS_ANGULAR_CORE__).toBe(originalCore);
   });
+
+  it('allows the active Angular core realm to be updated explicitly for HMR resets', () => {
+    const originalCore = {
+      ɵresetCompiledComponents: jest.fn(),
+    };
+    const replacementCore = {
+      ɵresetCompiledComponents: jest.fn(),
+    };
+    const globalObj: any = {
+      __NS_ANGULAR_CORE__: originalCore,
+    };
+
+    expect(setAngularCoreForHmr(replacementCore, globalObj)).toBe(replacementCore);
+    expect(globalObj.__NS_ANGULAR_CORE__).toBe(replacementCore);
+  });
 });

packages/angular/src/lib/hmr-compiled-components-core.ts

@@ -6,6 +6,17 @@ type AngularCoreHolder = {
   __NS_ANGULAR_CORE__?: AngularCoreWithCompiledComponentReset | null;
 };
 
+export function setAngularCoreForHmr(
+  core: AngularCoreWithCompiledComponentReset | null | undefined,
+  globalObj: AngularCoreHolder = globalThis as AngularCoreHolder,
+): AngularCoreWithCompiledComponentReset | null | undefined {
+  if (core) {
+    globalObj.__NS_ANGULAR_CORE__ = core;
+  }
+
+  return getAngularCoreForHmrReset(core, globalObj);
+}
+
 export function getAngularCoreForHmrReset(
   core: AngularCoreWithCompiledComponentReset | null | undefined,
   globalObj: AngularCoreHolder = globalThis as AngularCoreHolder,

packages/angular/src/lib/legacy/router/hmr-route-bootstrap-core.ts

@@ -0,0 +1,55 @@
+type AngularBootstrapRouteLike = {
+  children?: AngularBootstrapRouteLike[];
+};
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function shouldStripRouteKey(key: string): boolean {
+  return key.startsWith('_') || key.startsWith('ɵ');
+}
+
+function cloneRouteValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.slice();
+  }
+
+  if (isPlainObject(value)) {
+    return { ...value };
+  }
+
+  return value;
+}
+
+function cloneBootstrapRoute<T extends object>(route: T): T {
+  const next: AngularBootstrapRouteLike = {};
+
+  for (const [key, value] of Object.entries(route as Record<string, unknown>)) {
+    if (shouldStripRouteKey(key)) {
+      continue;
+    }
+
+    if (key === 'children' && Array.isArray(value)) {
+      next.children = cloneRoutesForBootstrap(value);
+      continue;
+    }
+
+    next[key] = cloneRouteValue(value);
+  }
+
+  return next as T;
+}
+
+export function cloneRoutesForBootstrap<T extends object>(routes: T[] | undefined | null): T[] {
+  if (!Array.isArray(routes)) {
+    return [];
+  }
+
+  return routes.map((route) => cloneBootstrapRoute(route));
+}

packages/angular/src/lib/legacy/router/hmr-route-bootstrap.spec.ts

@@ -0,0 +1,58 @@
+import { cloneRoutesForBootstrap } from './hmr-route-bootstrap-core';
+
+describe('cloneRoutesForBootstrap', () => {
+  it('drops private Angular router cache fields while preserving public route config', () => {
+    const loadComponent = jest.fn();
+    const canActivate = [jest.fn()];
+    const routes = [
+      {
+        path: 'signup-landing',
+        loadComponent,
+        canActivate,
+        data: { source: 'signup' },
+        _loadedComponent: { stale: true },
+        _loadedInjector: { stale: true },
+        _loadedRoutes: [{ stale: true }],
+        _injector: { stale: true },
+        _loadedNgModuleFactory: { stale: true },
+        ɵrouterPageId: 'stale',
+        children: [
+          {
+            path: 'child',
+            loadChildren: jest.fn(),
+            _loadedComponent: { nested: true },
+          },
+        ],
+      },
+    ] as any;
+
+    const cloned = cloneRoutesForBootstrap(routes);
+
+    expect(cloned).not.toBe(routes);
+    expect(cloned[0]).not.toBe(routes[0]);
+    expect(cloned[0].loadComponent).toBe(loadComponent);
+    expect(cloned[0].canActivate).toEqual(canActivate);
+    expect(cloned[0].canActivate).not.toBe(canActivate);
+    expect(cloned[0].data).toEqual({ source: 'signup' });
+    expect(cloned[0].data).not.toBe(routes[0].data);
+    expect(cloned[0]._loadedComponent).toBeUndefined();
+    expect(cloned[0]._loadedInjector).toBeUndefined();
+    expect(cloned[0]._loadedRoutes).toBeUndefined();
+    expect(cloned[0]._injector).toBeUndefined();
+    expect(cloned[0]._loadedNgModuleFactory).toBeUndefined();
+    expect(cloned[0]['ɵrouterPageId']).toBeUndefined();
+    expect(cloned[0].children).toEqual([
+      {
+        path: 'child',
+        loadChildren: routes[0].children[0].loadChildren,
+      },
+    ]);
+    expect(cloned[0].children).not.toBe(routes[0].children);
+    expect(cloned[0].children[0]).not.toBe(routes[0].children[0]);
+  });
+
+  it('returns an empty array when routes are missing', () => {
+    expect(cloneRoutesForBootstrap(undefined)).toEqual([]);
+    expect(cloneRoutesForBootstrap(null)).toEqual([]);
+  });
+});

packages/angular/src/lib/legacy/router/hmr-route-cache-core.ts

@@ -3,16 +3,34 @@ type AngularHmrRouteLike = {
   _injector?: unknown;
   _loadedComponent?: unknown;
   _loadedInjector?: unknown;
+  _loadedNgModuleFactory?: unknown;
   _loadedRoutes?: AngularHmrRouteLike[];
 };
 
-const ROUTE_CACHE_KEYS = ['_loadedComponent', '_loadedInjector', '_loadedRoutes', '_injector'] as const;
+const ROUTE_CACHE_KEYS = ['_loadedComponent', '_loadedInjector', '_loadedNgModuleFactory', '_loadedRoutes', '_injector'] as const;
+
+function destroyRouteCacheValue(value: unknown): void {
+  if (!value || typeof value !== 'object') {
+    return;
+  }
+
+  const destroy = (value as { destroy?: () => void }).destroy;
+  if (typeof destroy === 'function') {
+    try {
+      destroy.call(value);
+    } catch {}
+  }
+}
 
 function clearRouteCacheField(route: Record<string, unknown>, key: (typeof ROUTE_CACHE_KEYS)[number]): boolean {
   if (!Object.prototype.hasOwnProperty.call(route, key) && route[key] === undefined) {
     return false;
   }
 
+  if (key === '_injector' || key === '_loadedInjector' || key === '_loadedNgModuleFactory') {
+    destroyRouteCacheValue(route[key]);
+  }
+
   try {
     delete route[key];
   } catch {

packages/angular/src/lib/legacy/router/hmr-route-cache.spec.ts

@@ -2,17 +2,22 @@ import { clearAngularHmrRouteConfigCaches } from './hmr-route-cache-core';
 
 describe('Angular HMR route cache clearing', () => {
   it('clears lazy route caches recursively while preserving public route fields', () => {
+    const detailsInjectorDestroy = jest.fn();
+    const surveyInjectorDestroy = jest.fn();
+    const childInjectorDestroy = jest.fn();
+    const loadedFactoryDestroy = jest.fn();
     const grandchild = {
       path: 'details',
       _loadedComponent: { name: 'DetailsComponent' },
-      _loadedInjector: { token: 'details' },
+      _loadedInjector: { token: 'details', destroy: detailsInjectorDestroy },
     };
     const child = {
       path: 'survey',
       children: [grandchild],
       _loadedComponent: { name: 'SurveyComponent' },
-      _loadedInjector: { token: 'survey' },
-      _injector: { token: 'child-injector' },
+      _loadedInjector: { token: 'survey', destroy: surveyInjectorDestroy },
+      _loadedNgModuleFactory: { token: 'survey-factory', destroy: loadedFactoryDestroy },
+      _injector: { token: 'child-injector', destroy: childInjectorDestroy },
     };
     const route = {
       path: 'onboarding-flow',
@@ -33,13 +38,18 @@ describe('Angular HMR route cache clearing', () => {
 
     const cleared = clearAngularHmrRouteConfigCaches([route]);
 
-    expect(cleared).toBe(9);
+    expect(cleared).toBe(10);
     expect(route.path).toBe('onboarding-flow');
     expect(child.path).toBe('survey');
     expect(grandchild.path).toBe('details');
+    expect(detailsInjectorDestroy).toHaveBeenCalledTimes(1);
+    expect(surveyInjectorDestroy).toHaveBeenCalledTimes(1);
+    expect(childInjectorDestroy).toHaveBeenCalledTimes(1);
+    expect(loadedFactoryDestroy).toHaveBeenCalledTimes(1);
     expect((route as any)._loadedRoutes).toBeUndefined();
     expect((child as any)._loadedComponent).toBeUndefined();
     expect((child as any)._loadedInjector).toBeUndefined();
+    expect((child as any)._loadedNgModuleFactory).toBeUndefined();
     expect((child as any)._injector).toBeUndefined();
     expect((grandchild as any)._loadedComponent).toBeUndefined();
     expect((grandchild as any)._loadedInjector).toBeUndefined();