feat(core): move provideExperimentalCheckNoChangesForDebug to provideCheckNoChangesConfig (angular#60906)

This commit makes several changes changes to the
`provideExperimentalCheckNoChangesForDebug` API:

* Rename it
* Promote to dev preview
* Apply the exhaustive behavior to _all_ checkNoChanges runs
* Remove `useNgZoneOnStable` option. This wasn't found to be generally
  more useful than `interval`

fixes angular#45612

BREAKING CHANGE: `provideExperimentalCheckNoChangesForDebug` has several
breaking changes:
* It is renamed to `provideCheckNoChangesConfig`
* The behavior applies to _all_ checkNoChanges runs
* The `useNgZoneOnStable` option is removed. This wasn't found to be generally
  more useful than `interval`

PR Close angular#60906

Author: atscott

adev/src/content/guide/zoneless.md

@@ -161,7 +161,7 @@ it is acceptable to use `fixture.changeDetectorRef.markForCheck()`.
 ### Debug-mode check to ensure updates are detected
 
 Angular also provides an additional tool to help verify that an application is making
-updates to state in a zoneless-compatible way. `provideExperimentalCheckNoChangesForDebug`
+updates to state in a zoneless-compatible way. `provideCheckNoChangesConfig({exhaustive: true, interval: <milliseconds>})`
 can be used to periodically check to ensure that no bindings have been updated
 without a notification. Angular throws `ExpressionChangedAfterItHasBeenCheckedError`
 if there is an updated binding that would not have refreshed by the zoneless change

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

@@ -4,7 +4,6 @@
 
 ```ts
 
-import * as _angular_core from '@angular/core';
 import { Observable } from 'rxjs';
 import { Subject } from 'rxjs';
 import { Subscription } from 'rxjs';
@@ -1450,14 +1449,18 @@ export function provideAppInitializer(initializerFn: () => Observable<unknown> |
 export function provideBrowserGlobalErrorListeners(): EnvironmentProviders;
 
 // @public
-export function provideEnvironmentInitializer(initializerFn: () => void): EnvironmentProviders;
+export function provideCheckNoChangesConfig(options: {
+    exhaustive: false;
+}): EnvironmentProviders;
 
 // @public
-export function provideExperimentalCheckNoChangesForDebug(options: {
+export function provideCheckNoChangesConfig(options: {
     interval?: number;
-    useNgZoneOnStable?: boolean;
-    exhaustive?: boolean;
-}): _angular_core.EnvironmentProviders;
+    exhaustive: true;
+}): EnvironmentProviders;
+
+// @public
+export function provideEnvironmentInitializer(initializerFn: () => void): EnvironmentProviders;
 
 // @public
 export function provideNgReflectAttributes(): EnvironmentProviders;

packages/core/src/change_detection/change_detection.ts

@@ -36,6 +36,7 @@ export {
   KeyValueDifferFactory,
   KeyValueDiffers,
 } from './differs/keyvalue_differs';
+
 export {PipeTransform} from './pipe_transform';
 
 /**

packages/core/src/change_detection/provide_check_no_changes_config.ts

@@ -0,0 +1,58 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {EnvironmentProviders, makeEnvironmentProviders} from '../di';
+import {UseExhaustiveCheckNoChanges} from './use_exhaustive_check_no_changes';
+import {exhaustiveCheckNoChangesInterval} from './scheduling/exhaustive_check_no_changes';
+
+/**
+ * Used to disable exhaustive checks when verifying no expressions changed after they were checked.
+ *
+ * This means that `OnPush` components that are not marked for check will not be checked.
+ * This behavior is the current default behavior in Angular. When running change detection
+ * on a view tree, views marked for check are refreshed and the flag to check it is removed.
+ * When Angular checks views a second time to ensure nothing has changed, `OnPush` components
+ * will no longer be marked and not be checked.
+ *
+ * @developerPreview
+ * @publicApi
+ */
+export function provideCheckNoChangesConfig(options: {exhaustive: false}): EnvironmentProviders;
+/**
+ * - `interval` will periodically run `checkNoChanges` on application views. This can be useful
+ *   in zoneless applications to periodically ensure no changes have been made without notifying
+ *   Angular that templates need to be refreshed.
+ * - The exhaustive option will treat all application views as if they were `ChangeDetectionStrategy.Default` when verifying
+ *   no expressions have changed. All views attached to `ApplicationRef` and all the descendants of
+ *   those views will be checked for changes (excluding those subtrees which are detached via `ChangeDetectorRef.detach()`).
+ *   This is useful because the check that runs after regular change detection does not work for components using `ChangeDetectionStrategy.OnPush`.
+ *   This check is will surface any existing errors hidden by `OnPush` components.
+ *
+ * @developerPreview
+ * @publicApi
+ */
+export function provideCheckNoChangesConfig(options: {
+  interval?: number;
+  exhaustive: true;
+}): EnvironmentProviders;
+export function provideCheckNoChangesConfig(options: {
+  interval?: number;
+  exhaustive: boolean;
+}): EnvironmentProviders {
+  return makeEnvironmentProviders(
+    typeof ngDevMode === 'undefined' || ngDevMode
+      ? [
+          {
+            provide: UseExhaustiveCheckNoChanges,
+            useValue: options.exhaustive,
+          },
+          options?.interval !== undefined ? exhaustiveCheckNoChangesInterval(options.interval) : [],
+        ]
+      : [],
+  );
+}

packages/core/src/change_detection/scheduling/exhaustive_check_no_changes.ts

@@ -9,162 +9,42 @@
 import {ApplicationRef} from '../../application/application_ref';
 import {ChangeDetectionSchedulerImpl} from './zoneless_scheduling_impl';
 import {inject} from '../../di/injector_compatibility';
-import {makeEnvironmentProviders} from '../../di/provider_collection';
+import {provideEnvironmentInitializer} from '../../di/provider_collection';
 import {NgZone} from '../../zone/ng_zone';
 
-import {EnvironmentInjector} from '../../di/r3_injector';
-import {ENVIRONMENT_INITIALIZER} from '../../di/initializer_token';
-import {CheckNoChangesMode} from '../../render3/state';
 import {ErrorHandler} from '../../error_handler';
 import {checkNoChangesInternal} from '../../render3/instructions/change_detection';
-import {ZONELESS_ENABLED} from './zoneless_scheduling';
 
-/**
- * Used to periodically verify no expressions have changed after they were checked.
- *
- * @param options Used to configure when the check will execute.
- *   - `interval` will periodically run exhaustive `checkNoChanges` on application views
- *   - `useNgZoneOnStable` will use ZoneJS to determine when change detection might have run
- *      in an application using ZoneJS to drive change detection. When the `NgZone.onStable` would
- *      have emitted, all views attached to the `ApplicationRef` are checked for changes.
- *   - 'exhaustive' means that all views attached to `ApplicationRef` and all the descendants of those views will be
- *     checked for changes (excluding those subtrees which are detached via `ChangeDetectorRef.detach()`).
- *     This is useful because the check that runs after regular change detection does not work for components using `ChangeDetectionStrategy.OnPush`.
- *     This check is will surface any existing errors hidden by `OnPush` components. By default, this check is exhaustive
- *     and will always check all views, regardless of their "dirty" state and `ChangeDetectionStrategy`.
- *
- * When the `useNgZoneOnStable` option is `true`, this function will provide its own `NgZone` implementation and needs
- * to come after any other `NgZone` provider, including `provideZoneChangeDetection()` and `provideZonelessChangeDetection()`.
- *
- * @experimental
- * @publicApi
- */
-export function provideExperimentalCheckNoChangesForDebug(options: {
-  interval?: number;
-  useNgZoneOnStable?: boolean;
-  exhaustive?: boolean;
-}) {
-  if (typeof ngDevMode === 'undefined' || ngDevMode) {
-    if (options.interval === undefined && !options.useNgZoneOnStable) {
-      throw new Error('Must provide one of `useNgZoneOnStable` or `interval`');
-    }
-    const checkNoChangesMode =
-      options?.exhaustive === false
-        ? CheckNoChangesMode.OnlyDirtyViews
-        : CheckNoChangesMode.Exhaustive;
-    return makeEnvironmentProviders([
-      options?.useNgZoneOnStable
-        ? {provide: NgZone, useFactory: () => new DebugNgZoneForCheckNoChanges(checkNoChangesMode)}
-        : [],
-      options?.interval !== undefined
-        ? exhaustiveCheckNoChangesInterval(options.interval, checkNoChangesMode)
-        : [],
-      {
-        provide: ENVIRONMENT_INITIALIZER,
-        multi: true,
-        useValue: () => {
-          if (
-            options?.useNgZoneOnStable &&
-            !(inject(NgZone) instanceof DebugNgZoneForCheckNoChanges)
-          ) {
-            throw new Error(
-              '`provideExperimentalCheckNoChangesForDebug` with `useNgZoneOnStable` must be after any other provider for `NgZone`.',
-            );
+export function exhaustiveCheckNoChangesInterval(interval: number) {
+  return provideEnvironmentInitializer(() => {
+    const applicationRef = inject(ApplicationRef);
+    const errorHandler = inject(ErrorHandler);
+    const scheduler = inject(ChangeDetectionSchedulerImpl);
+    const ngZone = inject(NgZone);
+
+    function scheduleCheckNoChanges() {
+      ngZone.runOutsideAngular(() => {
+        setTimeout(() => {
+          if (applicationRef.destroyed) {
+            return;
+          }
+          if (scheduler.pendingRenderTaskId || scheduler.runningTick) {
+            scheduleCheckNoChanges();
+            return;
           }
-        },
-      },
-    ]);
-  } else {
-    return makeEnvironmentProviders([]);
-  }
-}
-
-export class DebugNgZoneForCheckNoChanges extends NgZone {
-  private applicationRef?: ApplicationRef;
-  private scheduler?: ChangeDetectionSchedulerImpl;
-  private errorHandler?: ErrorHandler;
-  private readonly injector = inject(EnvironmentInjector);
 
-  constructor(private readonly checkNoChangesMode: CheckNoChangesMode) {
-    const zonelessEnabled = inject(ZONELESS_ENABLED);
-    // Use coalescing to ensure we aren't ever running this check synchronously
-    super({
-      shouldCoalesceEventChangeDetection: true,
-      shouldCoalesceRunChangeDetection: zonelessEnabled,
-    });
+          for (const view of applicationRef.allViews) {
+            try {
+              checkNoChangesInternal(view._lView, true /** exhaustive */);
+            } catch (e) {
+              errorHandler.handleError(e);
+            }
+          }
 
-    if (zonelessEnabled) {
-      // prevent emits to ensure code doesn't rely on these
-      this.onMicrotaskEmpty.emit = () => {};
-      this.onStable.emit = () => {
-        this.scheduler ||= this.injector.get(ChangeDetectionSchedulerImpl);
-        if (this.scheduler.pendingRenderTaskId || this.scheduler.runningTick) {
-          return;
-        }
-        this.checkApplicationViews();
-      };
-      this.onUnstable.emit = () => {};
-    } else {
-      this.runOutsideAngular(() => {
-        this.onStable.subscribe(() => {
-          this.checkApplicationViews();
-        });
+          scheduleCheckNoChanges();
+        }, interval);
       });
     }
-  }
-
-  private checkApplicationViews() {
-    this.applicationRef ||= this.injector.get(ApplicationRef);
-    for (const view of this.applicationRef.allViews) {
-      try {
-        checkNoChangesInternal(view._lView, this.checkNoChangesMode);
-      } catch (e) {
-        this.errorHandler ||= this.injector.get(ErrorHandler);
-        this.errorHandler.handleError(e);
-      }
-    }
-  }
-}
-
-function exhaustiveCheckNoChangesInterval(
-  interval: number,
-  checkNoChangesMode: CheckNoChangesMode,
-) {
-  return {
-    provide: ENVIRONMENT_INITIALIZER,
-    multi: true,
-    useFactory: () => {
-      const applicationRef = inject(ApplicationRef);
-      const errorHandler = inject(ErrorHandler);
-      const scheduler = inject(ChangeDetectionSchedulerImpl);
-      const ngZone = inject(NgZone);
-
-      return () => {
-        function scheduleCheckNoChanges() {
-          ngZone.runOutsideAngular(() => {
-            setTimeout(() => {
-              if (applicationRef.destroyed) {
-                return;
-              }
-              if (scheduler.pendingRenderTaskId || scheduler.runningTick) {
-                scheduleCheckNoChanges();
-                return;
-              }
-
-              for (const view of applicationRef.allViews) {
-                try {
-                  checkNoChangesInternal(view._lView, checkNoChangesMode);
-                } catch (e) {
-                  errorHandler.handleError(e);
-                }
-              }
-
-              scheduleCheckNoChanges();
-            }, interval);
-          });
-        }
-        scheduleCheckNoChanges();
-      };
-    },
-  };
+    scheduleCheckNoChanges();
+  });
 }

packages/core/src/change_detection/use_exhaustive_check_no_changes.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {InjectionToken} from '../di';
+
+export const USE_EXHAUSTIVE_CHECK_NO_CHANGES_DEFAULT = false;
+
+export const UseExhaustiveCheckNoChanges = new InjectionToken<boolean>(
+  ngDevMode ? 'exhaustive checkNoChanges' : '',
+);

packages/core/src/core.ts

@@ -49,7 +49,7 @@ export {
   provideZonelessChangeDetection as provideExperimentalZonelessChangeDetection,
 } from './change_detection/scheduling/zoneless_scheduling_impl';
 export {PendingTasks} from './pending_tasks';
-export {provideExperimentalCheckNoChangesForDebug} from './change_detection/scheduling/exhaustive_check_no_changes';
+export {provideCheckNoChangesConfig} from './change_detection/provide_check_no_changes_config';
 export {enableProdMode, isDevMode} from './util/is_dev_mode';
 export {
   APP_ID,

packages/core/src/render3/instructions/change_detection.ts

@@ -137,8 +137,10 @@ function detectChangesInViewWhileDirty(lView: LView, mode: ChangeDetectionMode)
   }
 }
 
-export function checkNoChangesInternal(lView: LView, mode: CheckNoChangesMode) {
-  setIsInCheckNoChangesMode(mode);
+export function checkNoChangesInternal(lView: LView, exhaustive: boolean) {
+  setIsInCheckNoChangesMode(
+    exhaustive ? CheckNoChangesMode.Exhaustive : CheckNoChangesMode.OnlyDirtyViews,
+  );
   try {
     detectChangesInternal(lView);
   } finally {

packages/core/src/render3/view_ref.ts

@@ -6,6 +6,10 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import {
+  USE_EXHAUSTIVE_CHECK_NO_CHANGES_DEFAULT,
+  UseExhaustiveCheckNoChanges,
+} from '../change_detection/use_exhaustive_check_no_changes';
 import type {ChangeDetectorRef} from '../change_detection/change_detector_ref';
 import {NotificationSource} from '../change_detection/scheduling/zoneless_scheduling';
 import type {ApplicationRef} from '../core';
@@ -23,6 +27,7 @@ import {
   CONTEXT,
   DECLARATION_LCONTAINER,
   FLAGS,
+  INJECTOR,
   LView,
   LViewFlags,
   PARENT,
@@ -46,6 +51,7 @@ interface ChangeDetectorRefInterface extends ChangeDetectorRef {}
 export class ViewRef<T> implements EmbeddedViewRef<T>, ChangeDetectorRefInterface {
   private _appRef: ApplicationRef | null = null;
   private _attachedToViewContainer = false;
+  private readonly exhaustive: boolean = USE_EXHAUSTIVE_CHECK_NO_CHANGES_DEFAULT;
 
   get rootNodes(): any[] {
     const lView = this._lView;
@@ -74,7 +80,14 @@ export class ViewRef<T> implements EmbeddedViewRef<T>, ChangeDetectorRefInterfac
      * This may be different from `_lView` if the `_cdRefInjectingView` is an embedded view.
      */
     private _cdRefInjectingView?: LView,
-  ) {}
+  ) {
+    if (typeof ngDevMode === 'undefined' || ngDevMode) {
+      this.exhaustive = this._lView[INJECTOR].get(
+        UseExhaustiveCheckNoChanges,
+        USE_EXHAUSTIVE_CHECK_NO_CHANGES_DEFAULT,
+      );
+    }
+  }
 
   get context(): T {
     return this._lView[CONTEXT] as unknown as T;
@@ -320,9 +333,8 @@ export class ViewRef<T> implements EmbeddedViewRef<T>, ChangeDetectorRefInterfac
    * introduce other changes.
    */
   checkNoChanges(): void {
-    if (ngDevMode) {
-      checkNoChangesInternal(this._lView, CheckNoChangesMode.OnlyDirtyViews);
-    }
+    if (!ngDevMode) return;
+    checkNoChangesInternal(this._lView, this.exhaustive);
   }
 
   attachToViewContainerRef() {