feat(core): migrate ExperimentalPendingTasks to PendingTasks (angular#57533)

This commit promotes the `ExperimentalPendingTasks` service from experimental to developer preview and includes a migration schematic for the rename. BREAKING CHANGE: `ExperimentalPendingTasks` has been renamed to `PendingTasks`. PR Close angular#57533

Author: atscott

adev/shared-docs/components/viewers/docs-viewer/docs-viewer.component.ts

@@ -84,16 +84,16 @@ export class DocViewer implements OnChanges {
 
  // tslint:disable-next-line:no-unused-variable
  private animateContent = false;
- private readonly pendingRenderTasks = inject(PendingTasks);
+ private readonly pendingTasks = inject(PendingTasks);
 
  private countOfExamples = 0;
 
  async ngOnChanges(changes: SimpleChanges): Promise<void> {
- const taskId = this.pendingRenderTasks.add();
+ const taskId = this.pendingTasks.add();
  if ('docContent' in changes) {
  await this.renderContentsAndRunClientSetup(this.docContent!);
  }
- this.pendingRenderTasks.remove(taskId);
+ this.pendingTasks.remove(taskId);
  }
 
  async renderContentsAndRunClientSetup(content?: string): Promise<void> {
@@ -195,7 +195,7 @@ export class DocViewer implements OnChanges {
  const preview = Boolean(placeholder.getAttribute('preview'));
  const title = placeholder.getAttribute('header') ?? undefined;
  const firstCodeSnippetTitle =
- snippets.length > 0 ? snippets[0].title ?? snippets[0].name : undefined;
+ snippets.length > 0 ? (snippets[0].title ?? snippets[0].name) : undefined;
  const exampleRef = this.viewContainer.createComponent(ExampleViewer);
 
  this.countOfExamples++;

adev/src/content/guide/zoneless.md

@@ -81,15 +81,15 @@ Zoneless applications. In fact, removing these calls can lead to performance reg
 are used in applications that still rely on ZoneJS.
 </docs-callout>
 
-### `ExperimentalPendingTasks` for Server Side Rendering (SSR)
+### `PendingTasks` for Server Side Rendering (SSR)
 
 If you are using SSR with Angular, you may know that it relies on ZoneJS to help determine when the application
 is "stable" and can be serialized. If there are asynchronous tasks that should prevent serialization, an application
-not using ZoneJS will need to make Angular aware of these with the `ExperimentalPendingTasks` service. Serialization
+not using ZoneJS will need to make Angular aware of these with the `PendingTasks` service. Serialization
 will wait for the first moment that all pending tasks have been removed.
 
 ```typescript
-const taskService = inject(ExperimentalPendingTasks);
+const taskService = inject(PendingTasks);
 const taskCleanup = taskService.add();
 await doSomeWorkThatNeedsToBeRendered();
 taskCleanup();

adev/src/content/reference/errors/NG0506.md

@@ -78,4 +78,4 @@ class SimpleComponent {
 
 In zoneless scenarios, stability might be delayed by an application code inside of an `effect` running in an infinite loop (potentially because signals used in effect functions keep changing) or a pending HTTP request.
 
-Developers may also explicitly contribute to indicating the application's stability by using the experimental [`PendingTasks`](/api/core/ExperimentalPendingTasks) service. If you use the mentioned APIs in your application, make sure you invoke a function to mark the task as completed.
+Developers may also explicitly contribute to indicating the application's stability by using the [`PendingTasks`](/api/core/PendingTasks) service. If you use the mentioned APIs in your application, make sure you invoke a function to mark the task as completed.

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

@@ -710,14 +710,6 @@ export interface ExistingSansProvider {
  useExisting: any;
 }
 
-// @public
-export class ExperimentalPendingTasks {
- add(): () => void;
- run<T>(fn: () => Promise<T>): Promise<T>;
- // (undocumented)
- static ɵprov: unknown;
-}
-
 // @public
 export interface FactoryProvider extends FactorySansProvider {
  multi?: boolean;
@@ -1351,6 +1343,14 @@ export interface OutputRefSubscription {
 // @public @deprecated
 export const PACKAGE_ROOT_URL: InjectionToken<string>;
 
+// @public
+export class PendingTasks {
+ add(): () => void;
+ run<T>(fn: () => Promise<T>): Promise<T>;
+ // (undocumented)
+ static ɵprov: unknown;
+}
+
 // @public
 export interface Pipe {
  name: string;

packages/core/schematics/BUILD.bazel

@@ -36,6 +36,7 @@ rollup_bundle(
  "//packages/core/schematics/ng-generate/standalone-migration:index.ts": "standalone-migration",
  "//packages/core/schematics/ng-generate/signal-input-migration:index.ts": "signal-input-migration",
  "//packages/core/schematics/migrations/explicit-standalone-flag:index.ts": "explicit-standalone-flag",
+ "//packages/core/schematics/migrations/pending-tasks:index.ts": "pending-tasks",
  },
  format = "cjs",
  link_workspace_root = True,
@@ -46,6 +47,7 @@ rollup_bundle(
  ],
  deps = [
  "//packages/core/schematics/migrations/explicit-standalone-flag",
+ "//packages/core/schematics/migrations/pending-tasks",
  "//packages/core/schematics/ng-generate/control-flow-migration",
  "//packages/core/schematics/ng-generate/inject-migration",
  "//packages/core/schematics/ng-generate/route-lazy-loading",

packages/core/schematics/migrations.json

@@ -4,6 +4,11 @@
  "version": "19.0.0",
  "description": "Updates non-standalone Directives, Component and Pipes to standalone:false",
  "factory": "./bundles/explicit-standalone-flag#migrate"
+ },
+ "pending-tasks": {
+ "version": "19.0.0",
+ "description": "Updates ExperimentalPendingTasks to PendingTasks",
+ "factory": "./bundles/pending-tasks#migrate"
  }
  }
 }

packages/core/schematics/migrations/pending-tasks/BUILD.bazel

@@ -0,0 +1,21 @@
+load("//tools:defaults.bzl", "ts_library")
+
+package(
+ default_visibility = [
+ "//packages/core/schematics:__pkg__",
+ "//packages/core/schematics/migrations/google3:__pkg__",
+ "//packages/core/schematics/test:__pkg__",
+ ],
+)
+
+ts_library(
+ name = "pending-tasks",
+ srcs = glob(["**/*.ts"]),
+ tsconfig = "//packages/core/schematics:tsconfig.json",
+ deps = [
+ "//packages/core/schematics/utils",
+ "@npm//@angular-devkit/schematics",
+ "@npm//@types/node",
+ "@npm//typescript",
+ ],
+)

packages/core/schematics/migrations/pending-tasks/index.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.io/license
+ */
+
+import {Rule, SchematicsException, Tree, UpdateRecorder} from '@angular-devkit/schematics';
+import {relative} from 'path';
+import {getProjectTsConfigPaths} from '../../utils/project_tsconfig_paths';
+import {canMigrateFile, createMigrationProgram} from '../../utils/typescript/compiler_host';
+import {migrateFile} from './migration';
+
+export function migrate(): Rule {
+ return async (tree: Tree) => {
+ const {buildPaths, testPaths} = await getProjectTsConfigPaths(tree);
+ const basePath = process.cwd();
+ const allPaths = [...buildPaths, ...testPaths];
+
+ if (!allPaths.length) {
+ throw new SchematicsException(
+ 'Could not find any tsconfig file. Cannot run the afterRender phase migration.',
+ );
+ }
+
+ for (const tsconfigPath of allPaths) {
+ runMigration(tree, tsconfigPath, basePath);
+ }
+ };
+}
+
+function runMigration(tree: Tree, tsconfigPath: string, basePath: string) {
+ const program = createMigrationProgram(tree, tsconfigPath, basePath);
+ const sourceFiles = program
+ .getSourceFiles()
+ .filter((sourceFile) => canMigrateFile(basePath, sourceFile, program));
+
+ for (const sourceFile of sourceFiles) {
+ let update: UpdateRecorder | null = null;
+
+ const rewriter = (startPos: number, width: number, text: string | null) => {
+ if (update === null) {
+ // Lazily initialize update, because most files will not require migration.
+ update = tree.beginUpdate(relative(basePath, sourceFile.fileName));
+ }
+ update.remove(startPos, width);
+ if (text !== null) {
+ update.insertLeft(startPos, text);
+ }
+ };
+ migrateFile(sourceFile, program.getTypeChecker(), rewriter);
+
+ if (update !== null) {
+ tree.commitUpdate(update);
+ }
+ }
+}

packages/core/schematics/migrations/pending-tasks/migration.ts

@@ -0,0 +1,67 @@
+/**
+ * @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.io/license
+ */
+
+import ts from 'typescript';
+import {ChangeTracker} from '../../utils/change_tracker';
+import {
+ getImportOfIdentifier,
+ getImportSpecifier,
+ getNamedImports,
+} from '../../utils/typescript/imports';
+
+const CORE = '@angular/core';
+const EXPERIMENTAL_PENDING_TASKS = 'ExperimentalPendingTasks';
+
+type RewriteFn = (startPos: number, width: number, text: string) => void;
+
+export function migrateFile(
+ sourceFile: ts.SourceFile,
+ typeChecker: ts.TypeChecker,
+ rewriteFn: RewriteFn,
+) {
+ const changeTracker = new ChangeTracker(ts.createPrinter());
+ // Check if there are any imports of the `AfterRenderPhase` enum.
+ const coreImports = getNamedImports(sourceFile, CORE);
+ if (!coreImports) {
+ return;
+ }
+ const importSpecifier = getImportSpecifier(sourceFile, CORE, EXPERIMENTAL_PENDING_TASKS);
+ if (!importSpecifier) {
+ return;
+ }
+ const nodeToReplace = importSpecifier.propertyName ?? importSpecifier.name;
+ if (!ts.isIdentifier(nodeToReplace)) {
+ return;
+ }
+
+ changeTracker.replaceNode(nodeToReplace, ts.factory.createIdentifier('PendingTasks'));
+
+ ts.forEachChild(sourceFile, function visit(node: ts.Node) {
+ // import handled above
+ if (ts.isImportDeclaration(node)) {
+ return;
+ }
+
+ if (
+ ts.isIdentifier(node) &&
+ node.text === EXPERIMENTAL_PENDING_TASKS &&
+ getImportOfIdentifier(typeChecker, node)?.name === EXPERIMENTAL_PENDING_TASKS
+ ) {
+ changeTracker.replaceNode(node, ts.factory.createIdentifier('PendingTasks'));
+ }
+
+ ts.forEachChild(node, visit);
+ });
+
+ // Write the changes.
+ for (const changesInFile of changeTracker.recordChanges().values()) {
+ for (const change of changesInFile) {
+ rewriteFn(change.start, change.removeLength ?? 0, change.text);
+ }
+ }
+}

packages/core/schematics/test/pending_tasks_spec.ts

@@ -0,0 +1,101 @@
+/**
+ * @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.io/license
+ */
+
+import {getSystemPath, normalize, virtualFs} from '@angular-devkit/core';
+import {TempScopedNodeJsSyncHost} from '@angular-devkit/core/node/testing';
+import {HostTree} from '@angular-devkit/schematics';
+import {SchematicTestRunner, UnitTestTree} from '@angular-devkit/schematics/testing';
+import {runfiles} from '@bazel/runfiles';
+import shx from 'shelljs';
+
+describe('experimental pending tasks migration', () => {
+ let runner: SchematicTestRunner;
+ let host: TempScopedNodeJsSyncHost;
+ let tree: UnitTestTree;
+ let tmpDirPath: string;
+
+ function writeFile(filePath: string, contents: string) {
+ host.sync.write(normalize(filePath), virtualFs.stringToFileBuffer(contents));
+ }
+
+ function runMigration() {
+ return runner.runSchematic('pending-tasks', {}, tree);
+ }
+
+ beforeEach(() => {
+ runner = new SchematicTestRunner('test', runfiles.resolvePackageRelative('../migrations.json'));
+ host = new TempScopedNodeJsSyncHost();
+ tree = new UnitTestTree(new HostTree(host));
+
+ writeFile(
+ '/tsconfig.json',
+ JSON.stringify({
+ compilerOptions: {
+ lib: ['es2015'],
+ strictNullChecks: true,
+ },
+ }),
+ );
+
+ writeFile(
+ '/angular.json',
+ JSON.stringify({
+ version: 1,
+ projects: {t: {root: '', architect: {build: {options: {tsConfig: './tsconfig.json'}}}}},
+ }),
+ );
+
+ tmpDirPath = getSystemPath(host.root);
+
+ // Switch into the temporary directory path. This allows us to run
+ // the schematic against our custom unit test tree.
+ shx.cd(tmpDirPath);
+ });
+
+ it('should update ExperimentalPendingTasks', async () => {
+ writeFile(
+ '/index.ts',
+ `
+ import {ExperimentalPendingTasks, Directive} from '@angular/core';
+
+ @Directive({
+ selector: '[someDirective]'
+ })
+ export class SomeDirective {
+ x = inject(ExperimentalPendingTasks);
+ }`,
+ );
+
+ await runMigration();
+
+ const content = tree.readContent('/index.ts').replace(/\s+/g, ' ');
+ expect(content).toContain("import {PendingTasks, Directive} from '@angular/core';");
+ expect(content).toContain('x = inject(PendingTasks);');
+ });
+
+ it('should update import alias', async () => {
+ writeFile(
+ '/index.ts',
+ `
+ import {ExperimentalPendingTasks as Y, Directive} from '@angular/core';
+
+ @Directive({
+ selector: '[someDirective]'
+ })
+ export class SomeDirective {
+ x = inject(Y);
+ }`,
+ );
+
+ await runMigration();
+
+ const content = tree.readContent('/index.ts').replace(/\s+/g, ' ');
+ expect(content).toContain("import {PendingTasks as Y, Directive} from '@angular/core';");
+ expect(content).toContain('x = inject(Y);');
+ });
+});