feat(core): support customization of @defer's on idle behavior

thePunderWoman · thePunderWoman · commit a5981b83a605 · 2026-02-24T17:19:09.000-08:00
This commit makes the behavior of `on idle` in `@defer` configurable via DI. It defines an `IdleService` interface that an application can implement and provide to Angular: ```ts @Injectable({providedIn: 'root'}) export class CustomIdleService implements IdleService { requestOnIdle(callback: () => void): number {...} cancelOnIdle(id: number): void {...} } ``` Then the idle service can be used by providing the IDLE_SERVICE token with the custom implementation.
diff --git a/goldens/public-api/core/index.api.md b/goldens/public-api/core/index.api.md
@@ -843,6 +843,12 @@ export interface HostListenerDecorator {
     new (eventName: string, args?: string[]): any;
 }
 
+// @public
+export interface IdleService {
+    cancelOnIdle(id: number): void;
+    requestOnIdle(callback: (deadline?: IdleDeadline) => void): number;
+}
+
 // @public
 export function importProvidersFrom(...sources: ImportProvidersSource[]): EnvironmentProviders;
 
@@ -1489,6 +1495,9 @@ export function provideCheckNoChangesConfig(options: {
 // @public
 export function provideEnvironmentInitializer(initializerFn: () => void): EnvironmentProviders;
 
+// @public
+export function provideIdleServiceWith(useExisting: AbstractType<IdleService> | InjectionToken<IdleService>): EnvironmentProviders;
+
 // @public
 export function provideNgReflectAttributes(): EnvironmentProviders;
 
diff --git a/packages/core/src/core.ts b/packages/core/src/core.ts
@@ -131,6 +131,7 @@ export {
   AnimationFunction,
   MAX_ANIMATION_TIMEOUT,
 } from './animation/interfaces';
+export {IdleService, provideIdleServiceWith} from './defer/idle_service';
 
 import {global} from './util/global';
 if (typeof ngDevMode !== 'undefined' && ngDevMode) {
diff --git a/packages/core/src/defer/idle_scheduler.ts b/packages/core/src/defer/idle_scheduler.ts
@@ -9,6 +9,7 @@
 import type {OnDestroy} from '../core';
 import {Injector, inject, ɵɵdefineInjectable} from '../di';
 import {NgZone} from '../zone';
+import {IDLE_SERVICE} from './idle_service';
 
 /**
  * Helper function to schedule a callback to be invoked when a browser becomes idle.
@@ -23,18 +24,6 @@ export function onIdle(callback: VoidFunction, injector: Injector) {
   return cleanupFn;
 }
 
-/**
- * Use shims for the `requestIdleCallback` and `cancelIdleCallback` functions for
- * environments where those functions are not available (e.g. Node.js and Safari).
- *
- * Note: we wrap the `requestIdleCallback` call into a function, so that it can be
- * overridden/mocked in test environment and picked up by the runtime code.
- */
-const _requestIdleCallback = () =>
-  typeof requestIdleCallback !== 'undefined' ? requestIdleCallback : setTimeout;
-const _cancelIdleCallback = () =>
-  typeof requestIdleCallback !== 'undefined' ? cancelIdleCallback : clearTimeout;
-
 /**
  * Helper service to schedule `requestIdleCallback`s for batches of defer blocks,
  * to avoid calling `requestIdleCallback` for each defer block (e.g. if
@@ -48,9 +37,7 @@ export class IdleScheduler implements OnDestroy {
   queue = new Set<VoidFunction>();
 
   ngZone = inject(NgZone);
-
-  requestIdleCallbackFn = _requestIdleCallback().bind(globalThis);
-  cancelIdleCallbackFn = _cancelIdleCallback().bind(globalThis);
+  private readonly idleService = inject(IDLE_SERVICE);
 
   add(callback: VoidFunction) {
     this.queue.add(callback);
@@ -90,14 +77,14 @@ export class IdleScheduler implements OnDestroy {
     };
     // Ensure that the callback runs in the NgZone since
     // the `requestIdleCallback` is not currently patched by Zone.js.
-    this.idleId = this.requestIdleCallbackFn((deadline) =>
+    this.idleId = this.idleService.requestOnIdle((deadline) =>
       this.ngZone.run(() => callback(deadline)),
     ) as number;
   }
 
   private cancelIdleCallback() {
     if (this.idleId !== null) {
-      this.cancelIdleCallbackFn(this.idleId);
+      this.idleService.cancelOnIdle(this.idleId);
       this.idleId = null;
     }
   }
diff --git a/packages/core/src/defer/idle_service.ts b/packages/core/src/defer/idle_service.ts
@@ -0,0 +1,84 @@
+/**
+ * @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 {AbstractType} from '../interface/type';
+import {InjectionToken} from '../di/injection_token';
+import type {EnvironmentProviders} from '../di/interface/provider';
+import {makeEnvironmentProviders} from '../di/provider_collection';
+
+/**
+ * Use shims for the `requestIdleCallback` and `cancelIdleCallback` functions for
+ * environments where those functions are not available (e.g. Node.js and Safari).
+ *
+ * Note: we wrap the `requestIdleCallback` call into a function, so that it can be
+ * overridden/mocked in test environment and picked up by the runtime code.
+ */
+const _requestIdleCallback = () =>
+  typeof requestIdleCallback !== 'undefined' ? requestIdleCallback.bind(globalThis) : setTimeout;
+const _cancelIdleCallback = () =>
+  typeof requestIdleCallback !== 'undefined' ? cancelIdleCallback.bind(globalThis) : clearTimeout;
+
+/**
+ * Service which configures custom 'on idle' behavior for Angular features like `@defer`.
+ *
+ * @publicApi
+ */
+export interface IdleService {
+  /**
+   * Schedule `callback` to be executed when the current application or browser is considered idle.
+   *
+   * @returns an id which allows the scheduled callback to be cancelled before it executes.
+   */
+  requestOnIdle(callback: (deadline?: IdleDeadline) => void): number;
+
+  /**
+   * Cancel a previously scheduled callback using the id associated with it.
+   */
+  cancelOnIdle(id: number): void;
+}
+
+export const IDLE_SERVICE = new InjectionToken<IdleService>(ngDevMode ? 'IDLE_SERVICE' : '', {
+  providedIn: 'root',
+  factory: () => new RequestIdleCallbackService(),
+});
+
+/**
+ * Configures Angular to use the given DI token as its `IdleService`.
+ *
+ * The given token must be available for injection from the root injector, and the injected value
+ * must implement the `IdleService` interface.
+ *
+ * @publicApi
+ */
+export function provideIdleServiceWith(
+  useExisting: AbstractType<IdleService> | InjectionToken<IdleService>,
+): EnvironmentProviders {
+  return makeEnvironmentProviders([
+    {
+      provide: IDLE_SERVICE,
+      useExisting,
+    },
+  ]);
+}
+
+/**
+ * Default implementation of `IDLE_SERVICE` which uses `requestIdleCallback` when available or
+ * `setTimeout` when not.
+ */
+class RequestIdleCallbackService implements IdleService {
+  private readonly requestIdleCallback = _requestIdleCallback();
+  private readonly cancelIdleCallback = _cancelIdleCallback();
+
+  requestOnIdle(callback: (deadline?: IdleDeadline) => void): number {
+    return this.requestIdleCallback(callback) as unknown as number;
+  }
+
+  cancelOnIdle(id: number): void {
+    return this.cancelIdleCallback(id);
+  }
+}
diff --git a/packages/core/test/acceptance/defer_spec.ts b/packages/core/test/acceptance/defer_spec.ts
@@ -39,6 +39,7 @@ import {
   ViewChildren,
   ɵDEFER_BLOCK_DEPENDENCY_INTERCEPTOR,
 } from '../../src/core';
+import {IDLE_SERVICE, IdleService, provideIdleServiceWith} from '../../src/defer/idle_service';
 import {IdleScheduler} from '../../src/defer/idle_scheduler';
 import {TimerScheduler} from '../../src/defer/timer_scheduler';
 import {formatRuntimeErrorCode, RuntimeErrorCode} from '../../src/errors';
@@ -1814,8 +1815,31 @@ describe('@defer', () => {
         },
       };
 
+      @Injectable({providedIn: 'root'})
+      class CustomIdleService implements IdleService {
+        private callbacks: Array<((deadline?: IdleDeadline) => void) | undefined> = [];
+
+        requestOnIdle(callback: (deadline?: IdleDeadline) => void): number {
+          return this.callbacks.push(callback) - 1;
+        }
+
+        cancelOnIdle(id: number): void {
+          this.callbacks[id] = undefined;
+        }
+
+        trigger(): void {
+          for (const callback of this.callbacks) {
+            callback?.();
+          }
+          this.callbacks.length = 0;
+        }
+      }
+
       TestBed.configureTestingModule({
-        providers: [{provide: ɵDEFER_BLOCK_DEPENDENCY_INTERCEPTOR, useValue: deferDepsInterceptor}],
+        providers: [
+          {provide: ɵDEFER_BLOCK_DEPENDENCY_INTERCEPTOR, useValue: deferDepsInterceptor},
+          provideIdleServiceWith(CustomIdleService),
+        ],
       });
 
       clearDirectiveDefs(RootCmp);
@@ -1828,7 +1852,7 @@ describe('@defer', () => {
       // Make sure loading function is not yet invoked.
       expect(loadingFnInvokedTimes).toBe(0);
 
-      triggerIdleCallbacks();
+      TestBed.inject(CustomIdleService).trigger();
       await allPendingDynamicImports();
       fixture.detectChanges();
 
@@ -4429,8 +4453,23 @@ describe('@defer', () => {
 
 describe('IdleScheduler', () => {
   let scheduler: IdleScheduler;
+  let customIdleService: CustomIdleService;
+
+  class CustomIdleService implements IdleService {
+    requestOnIdleSpy = jasmine.createSpy('requestOnIdleFn');
+
+    requestOnIdle(callback: (deadline?: IdleDeadline) => void): number {
+      return this.requestOnIdleSpy(callback);
+    }
+
+    cancelOnIdle(id: number): void {}
+  }
 
   beforeEach(() => {
+    customIdleService = new CustomIdleService();
+    TestBed.configureTestingModule({
+      providers: [{provide: IDLE_SERVICE, useValue: customIdleService}],
+    });
     scheduler = TestBed.inject(IdleScheduler);
   });
 
@@ -4442,13 +4481,11 @@ describe('IdleScheduler', () => {
     let capturedCb: ((deadline: any) => void) | null = null;
     let ricCount = 0;
 
-    scheduler.requestIdleCallbackFn = jasmine
-      .createSpy('requestIdleCallbackFn')
-      .and.callFake((cb: any) => {
-        ricCount++;
-        capturedCb = cb;
-        return 100 + ricCount;
-      });
+    customIdleService.requestOnIdleSpy.and.callFake((cb: any) => {
+      ricCount++;
+      capturedCb = cb;
+      return 100 + ricCount;
+    });
 
     const cb1 = jasmine.createSpy('cb1');
     const cb2 = jasmine.createSpy('cb2');
@@ -4479,13 +4516,11 @@ describe('IdleScheduler', () => {
     let capturedCb: ((deadline: any) => void) | null = null;
     let ricCount = 0;
 
-    scheduler.requestIdleCallbackFn = jasmine
-      .createSpy('requestIdleCallbackFn')
-      .and.callFake((cb: any) => {
-        ricCount++;
-        capturedCb = cb;
-        return 100 + ricCount;
-      });
+    customIdleService.requestOnIdleSpy.and.callFake((cb: any) => {
+      ricCount++;
+      capturedCb = cb;
+      return 100 + ricCount;
+    });
 
     const cb1 = jasmine.createSpy('cb1');
     const cb2 = jasmine.createSpy('cb2');
@@ -4540,13 +4575,11 @@ describe('IdleScheduler', () => {
     let capturedCb: ((deadline: any) => void) | null = null;
     let ricCount = 0;
 
-    scheduler.requestIdleCallbackFn = jasmine
-      .createSpy('requestIdleCallbackFn')
-      .and.callFake((cb: any) => {
-        ricCount++;
-        capturedCb = cb;
-        return 100 + ricCount;
-      });
+    customIdleService.requestOnIdleSpy.and.callFake((cb: any) => {
+      ricCount++;
+      capturedCb = cb;
+      return 100 + ricCount;
+    });
 
     const cb1 = jasmine.createSpy('cb1');
     const cb2 = jasmine.createSpy('cb2');
@@ -4577,13 +4610,11 @@ describe('IdleScheduler', () => {
     let capturedCb: ((deadline: any) => void) | null = null;
     let ricCount = 0;
 
-    scheduler.requestIdleCallbackFn = jasmine
-      .createSpy('requestIdleCallbackFn')
-      .and.callFake((cb: any) => {
-        ricCount++;
-        capturedCb = cb;
-        return 100 + ricCount;
-      });
+    customIdleService.requestOnIdleSpy.and.callFake((cb: any) => {
+      ricCount++;
+      capturedCb = cb;
+      return 100 + ricCount;
+    });
 
     // Test with undefined (empty arguments, typical of setTimeout)
     let cb1 = jasmine.createSpy('cb1');
