feat(core): provide ExperimentalPendingTasks API (angular#55487)

The new ExperimentalPendingTasks API lets developers to add and remove
tasks that control applications stability: a pending task prevents
application from being stable.

This API is important for all the use-cases that depend on the concept
of stability and SSR serialization is a notable example.

Closes angular#53381

PR Close angular#55487

Author: pkozlowski-opensource

goldens/public-api/core/index.md

@@ -4,6 +4,7 @@
 
 ```ts
 
+import { BehaviorSubject } from 'rxjs';
 import { Observable } from 'rxjs';
 import { SIGNAL } from '@angular/core/primitives/signals';
 import { SignalNode } from '@angular/core/primitives/signals';
@@ -673,6 +674,17 @@ export interface ExistingSansProvider {
     useExisting: any;
 }
 
+// @public
+export class ExperimentalPendingTasks {
+    add(): () => void;
+    // (undocumented)
+    internalPendingTasks: ɵPendingTasks;
+    // (undocumented)
+    static ɵfac: i0.ɵɵFactoryDeclaration<ExperimentalPendingTasks, never>;
+    // (undocumented)
+    static ɵprov: i0.ɵɵInjectableDeclaration<ExperimentalPendingTasks>;
+}
+
 // @public
 export interface FactoryProvider extends FactorySansProvider {
     multi?: boolean;

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

@@ -225,8 +225,8 @@ export class ChangeDetectionSchedulerImpl implements ChangeDetectionScheduler {
  * ```
  *
  * This API is experimental. Neither the shape, nor the underlying behavior is stable and can change
- * in patch versions. There are known feature gaps, including the lack of a public zoneless API
- * which prevents the application from serializing too early with SSR.
+ * in patch versions. There are known feature gaps and API ergonomic considerations. We will iterate
+ * on the exact API based on the feedback and our understanding of the problem and solution space.
  *
  * @publicApi
  * @experimental

packages/core/src/core.ts

@@ -29,6 +29,7 @@ export {PlatformRef} from './platform/platform_ref';
 export {createPlatform, createPlatformFactory, assertPlatform, destroyPlatform, getPlatform} from './platform/platform';
 export {provideZoneChangeDetection, NgZoneOptions} from './change_detection/scheduling/ng_zone_scheduling';
 export {provideExperimentalZonelessChangeDetection} from './change_detection/scheduling/zoneless_scheduling_impl';
+export {ExperimentalPendingTasks} from './pending_tasks';
 export {enableProdMode, isDevMode} from './util/is_dev_mode';
 export {APP_ID, PACKAGE_ROOT_URL, PLATFORM_INITIALIZER, PLATFORM_ID, ANIMATION_MODULE_TYPE, CSP_NONCE} from './application/application_tokens';
 export {APP_INITIALIZER, ApplicationInitStatus} from './application/application_init';

packages/core/src/pending_tasks.ts

@@ -8,20 +8,16 @@
 
 import {BehaviorSubject} from 'rxjs';
 
-import {Injectable} from './di';
+import {inject} from './di';
+import {Injectable} from './di/injectable';
 import {OnDestroy} from './interface/lifecycle_hooks';
 
 /**
- * *Internal* service that keeps track of pending tasks happening in the system.
- *
- * This information is needed to make sure that the serialization on the server
- * is delayed until all tasks in the queue (such as an initial navigation or a
- * pending HTTP request) are completed.
- *
- * Pending tasks continue to contribute to the stableness of `ApplicationRef`
- * throughout the lifetime of the application.
+ * Internal implementation of the pending tasks service.
  */
-@Injectable({providedIn: 'root'})
+@Injectable({
+  providedIn: 'root',
+})
 export class PendingTasks implements OnDestroy {
   private taskId = 0;
   private pendingTasks = new Set<number>();
@@ -53,3 +49,44 @@ export class PendingTasks implements OnDestroy {
     }
   }
 }
+
+/**
+ * Experimental service that keeps track of pending tasks contributing to the stableness of Angular
+ * application. While several existing Angular services (ex.: `HttpClient`) will internally manage
+ * tasks influencing stability, this API gives control over stability to library and application
+ * developers for specific cases not covered by Angular internals.
+ *
+ * The concept of stability comes into play in several important scenarios:
+ * - SSR process needs to wait for the application stability before serializing and sending rendered
+ * HTML;
+ * - tests might want to delay assertions until the application becomes stable;
+ *
+ * @usageNotes
+ * ```typescript
+ * const pendingTasks = inject(ExperimentalPendingTasks);
+ * const taskCleanup = pendingTasks.add();
+ * // do work that should block application's stability and then:
+ * taskCleanup();
+ * ```
+ *
+ * This API is experimental. Neither the shape, nor the underlying behavior is stable and can change
+ * in patch versions. We will iterate on the exact API based on the feedback and our understanding
+ * of the problem and solution space.
+ *
+ * @publicApi
+ * @experimental
+ */
+@Injectable({
+  providedIn: 'root',
+})
+export class ExperimentalPendingTasks {
+  internalPendingTasks = inject(PendingTasks);
+  /**
+   * Adds a new task that should block application's stability.
+   * @returns A cleanup function that removes a task when called.
+   */
+  add(): () => void {
+    const taskId = this.internalPendingTasks.add();
+    return () => this.internalPendingTasks.remove(taskId);
+  }
+}

packages/core/test/acceptance/pending_tasks_spec.ts

@@ -6,11 +6,11 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
+import {ApplicationRef, ExperimentalPendingTasks} from '@angular/core';
 import {TestBed} from '@angular/core/testing';
 import {EMPTY, of} from 'rxjs';
 import {map, take, withLatestFrom} from 'rxjs/operators';
 
-import {ApplicationRef} from '../../src/application/application_ref';
 import {PendingTasks} from '../../src/pending_tasks';
 
 describe('PendingTasks', () => {
@@ -67,6 +67,18 @@ describe('PendingTasks', () => {
   });
 });
 
+describe('public ExperimentalPendingTasks', () => {
+  it('should allow adding and removing tasks influencing stability', async () => {
+    const appRef = TestBed.inject(ApplicationRef);
+    const pendingTasks = TestBed.inject(ExperimentalPendingTasks);
+
+    const taskA = pendingTasks.add();
+    await expectAsync(applicationRefIsStable(appRef)).toBeResolvedTo(false);
+    taskA();
+    await expectAsync(applicationRefIsStable(appRef)).toBeResolvedTo(true);
+  });
+});
+
 function applicationRefIsStable(applicationRef: ApplicationRef) {
   return applicationRef.isStable.pipe(take(1)).toPromise();
 }