feat(core): Add a schematic to migrate afterRender phase flag (angular#55648)

Adds an `ng update` migration to move users from using the phase flag with `afterRender` / `afterNextRender` to passing a spec object instead. PR Close angular#55648

Author: mmalerba

packages/core/schematics/BUILD.bazel

@@ -18,6 +18,7 @@ pkg_npm(
  validate = False,
  visibility = ["//packages/core:__pkg__"],
  deps = [
+ "//packages/core/schematics/migrations/after-render-phase:bundle",
  "//packages/core/schematics/migrations/http-providers:bundle",
  "//packages/core/schematics/migrations/invalid-two-way-bindings:bundle",
  "//packages/core/schematics/ng-generate/control-flow-migration:bundle",

packages/core/schematics/migrations.json

@@ -9,6 +9,11 @@
  "version": "18.0.0",
  "description": "Replace deprecated HTTP related modules with provider functions",
  "factory": "./migrations/http-providers/bundle"
+ },
+ "migration-after-render-phase": {
+ "version": "18.1.0",
+ "description": "Updates calls to afterRender with an explicit phase to the new API",
+ "factory": "./migrations/after-render-phase/bundle"
  }
  }
 }

packages/core/schematics/migrations/after-render-phase/BUILD.bazel

@@ -0,0 +1,33 @@
+load("//tools:defaults.bzl", "esbuild", "ts_library")
+
+package(
+ default_visibility = [
+ "//packages/core/schematics:__pkg__",
+ "//packages/core/schematics/migrations/google3:__pkg__",
+ "//packages/core/schematics/test:__pkg__",
+ ],
+)
+
+ts_library(
+ name = "after-render-phase",
+ srcs = glob(["**/*.ts"]),
+ tsconfig = "//packages/core/schematics:tsconfig.json",
+ deps = [
+ "//packages/core/schematics/utils",
+ "@npm//@angular-devkit/schematics",
+ "@npm//@types/node",
+ "@npm//typescript",
+ ],
+)
+
+esbuild(
+ name = "bundle",
+ entry_point = ":index.ts",
+ external = [
+ "@angular-devkit/*",
+ "typescript",
+ ],
+ format = "cjs",
+ platform = "node",
+ deps = [":after-render-phase"],
+)

packages/core/schematics/migrations/after-render-phase/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 default function (): 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/after-render-phase/migration.ts

@@ -0,0 +1,83 @@
+/**
+ * @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} from '../../utils/typescript/imports';
+
+const CORE = '@angular/core';
+const AFTER_RENDER_PHASE_ENUM = 'AfterRenderPhase';
+const AFTER_RENDER_FNS = new Set(['afterRender', 'afterNextRender']);
+
+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());
+ const phaseEnum = getImportSpecifier(sourceFile, CORE, AFTER_RENDER_PHASE_ENUM);
+
+ // Check if there are any imports of the `AfterRenderPhase` enum.
+ if (phaseEnum) {
+ // Remove the `AfterRenderPhase` enum import.
+ changeTracker.removeNode(phaseEnum);
+ ts.forEachChild(sourceFile, function visit(node: ts.Node) {
+ ts.forEachChild(node, visit);
+
+ // Check if this is a function call of `afterRender` or `afterNextRender`.
+ if (
+ ts.isCallExpression(node) &&
+ ts.isIdentifier(node.expression) &&
+ AFTER_RENDER_FNS.has(getImportOfIdentifier(typeChecker, node.expression)?.name || '')
+ ) {
+ let phase: string | undefined;
+ const [callback, options] = node.arguments;
+ // Check if any `AfterRenderOptions` options were specified.
+ if (ts.isObjectLiteralExpression(options)) {
+ const phaseProp = options.properties.find((p) => p.name?.getText() === 'phase');
+ // Check if the `phase` options is set.
+ if (
+ phaseProp &&
+ ts.isPropertyAssignment(phaseProp) &&
+ ts.isPropertyAccessExpression(phaseProp.initializer) &&
+ phaseProp.initializer.expression.getText() === AFTER_RENDER_PHASE_ENUM
+ ) {
+ phaseProp.initializer.expression;
+ phase = phaseProp.initializer.name.getText();
+ // Remove the `phase` option.
+ if (options.properties.length === 1) {
+ changeTracker.removeNode(options);
+ } else {
+ const newOptions = ts.factory.createObjectLiteralExpression(
+ options.properties.filter((p) => p !== phaseProp),
+ );
+ changeTracker.replaceNode(options, newOptions);
+ }
+ }
+ }
+ // If we found a phase, update the callback.
+ if (phase) {
+ phase = phase.substring(0, 1).toLocaleLowerCase() + phase.substring(1);
+ const spec = ts.factory.createObjectLiteralExpression([
+ ts.factory.createPropertyAssignment(ts.factory.createIdentifier(phase), callback),
+ ]);
+ changeTracker.replaceNode(callback, spec);
+ }
+ }
+ });
+ }
+
+ // 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/BUILD.bazel

@@ -19,6 +19,8 @@ jasmine_node_test(
  data = [
  "//packages/core/schematics:collection.json",
  "//packages/core/schematics:migrations.json",
+ "//packages/core/schematics/migrations/after-render-phase",
+ "//packages/core/schematics/migrations/after-render-phase:bundle",
  "//packages/core/schematics/migrations/http-providers",
  "//packages/core/schematics/migrations/http-providers:bundle",
  "//packages/core/schematics/migrations/invalid-two-way-bindings",

packages/core/schematics/test/after_render_phase_spec.ts

@@ -0,0 +1,176 @@
+/**
+ * @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('afterRender phase migration', () => {
+ let runner: SchematicTestRunner;
+ let host: TempScopedNodeJsSyncHost;
+ let tree: UnitTestTree;
+ let tmpDirPath: string;
+ let previousWorkingDir: string;
+
+ function writeFile(filePath: string, contents: string) {
+ host.sync.write(normalize(filePath), virtualFs.stringToFileBuffer(contents));
+ }
+
+ function runMigration() {
+ return runner.runSchematic('migration-after-render-phase', {}, 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'}}}}},
+ }),
+ );
+
+ previousWorkingDir = shx.pwd();
+ 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 afterRender phase flag', async () => {
+ writeFile(
+ '/index.ts',
+ `
+ import { AfterRenderPhase, Directive, afterRender } from '@angular/core';
+
+ @Directive({
+ selector: '[someDirective]'
+ })
+ export class SomeDirective {
+ constructor() {
+ afterRender(() => {
+ console.log('read');
+ }, {phase: AfterRenderPhase.Read});
+ }
+ }`,
+ );
+
+ await runMigration();
+
+ const content = tree.readContent('/index.ts').replace(/\s+/g, ' ');
+ expect(content).not.toContain('AfterRenderPhase');
+ expect(content).toContain(`afterRender({ read: () => { console.log('read'); } }, );`);
+ });
+
+ it('should update afterNextRender phase flag', async () => {
+ writeFile(
+ '/index.ts',
+ `
+ import { AfterRenderPhase, Directive, afterNextRender } from '@angular/core';
+
+ @Directive({
+ selector: '[someDirective]'
+ })
+ export class SomeDirective {
+ constructor() {
+ afterNextRender(() => {
+ console.log('earlyRead');
+ }, {phase: AfterRenderPhase.EarlyRead});
+ }
+ }`,
+ );
+
+ await runMigration();
+
+ const content = tree.readContent('/index.ts').replace(/\s+/g, ' ');
+ expect(content).not.toContain('AfterRenderPhase');
+ expect(content).toContain(
+ `afterNextRender({ earlyRead: () => { console.log('earlyRead'); } }, );`,
+ );
+ });
+
+ it('should not update calls that do not specify phase flag', async () => {
+ const originalContent = `
+ import { Directive, Injector, afterRender, afterNextRender, inject } from '@angular/core';
+
+ @Directive({
+ selector: '[someDirective]'
+ })
+ export class SomeDirective {
+ injector = inject(Injector);
+
+ constructor() {
+ afterRender(() => {
+ console.log('default phase');
+ });
+ afterNextRender(() => {
+ console.log('default phase');
+ });
+ afterRender(() => {
+ console.log('default phase');
+ }, {injector: this.injector});
+ afterNextRender(() => {
+ console.log('default phase');
+ }, {injector: this.injector});
+ }
+ }`;
+ writeFile('/index.ts', originalContent);
+
+ await runMigration();
+
+ const content = tree.readContent('/index.ts').replace(/\s+/g, ' ');
+ expect(content).toEqual(originalContent.replace(/\s+/g, ' '));
+ });
+
+ it('should not change options other than phase', async () => {
+ writeFile(
+ '/index.ts',
+ `
+ import { AfterRenderPhase, Directive, Injector, afterRender, inject } from '@angular/core';
+
+ @Directive({
+ selector: '[someDirective]'
+ })
+ export class SomeDirective {
+ injector = inject(Injector);
+
+ constructor() {
+ afterRender(() => {
+ console.log('earlyRead');
+ }, {
+ phase: AfterRenderPhase.EarlyRead,
+ injector: this.injector
+ });
+ }
+ }`,
+ );
+
+ await runMigration();
+ const content = tree.readContent('/index.ts').replace(/\s+/g, ' ');
+ expect(content).toContain(
+ `afterRender({ earlyRead: () => { console.log('earlyRead'); } }, { injector: this.injector });`,
+ );
+ });
+});