refactor(@angular/build): introduce AngularCompilationContext to manage compiler lifecycle

Refactors the ambient/global sharedTSCompilationState synchronization singleton into an explicit, orchestrator-instantiated AngularCompilationContext. This context encapsulates the AngularCompilation instance and its ready promise/resolver.

The context is instantiated once in executeBuild and passed down to both browser and server compiler plugins, eliminating global state and providing a single cohesive API to manage worker thread lifecycles via context.dispose().

Author: clydin

packages/angular/build/src/builders/application/execute-build.ts

@@ -8,6 +8,7 @@
 
 import { BuilderContext } from '@angular-devkit/architect';
 import { createAngularCompilation } from '../../tools/angular/compilation';
+import { AngularCompilationContext } from '../../tools/esbuild/angular/compilation-state';
 import { SourceFileCache } from '../../tools/esbuild/angular/source-file-cache';
 import { generateBudgetStats } from '../../tools/esbuild/budget-stats';
 import { BundleContextResult, BundlerContext } from '../../tools/esbuild/bundler-context';
@@ -102,13 +103,16 @@ export async function executeBuild(
     if (options.templateUpdates) {
       templateUpdates = new Map<string, string>();
     }
+    const angularCompilation = await createAngularCompilation(
+      !!options.jit,
+      !options.serverEntryPoint,
+    );
     bundlerContexts = setupBundlerContexts(
       options,
       target,
       codeBundleCache,
       componentStyleBundler,
-      // Create new reusable compilation for the appropriate mode based on the `jit` plugin option
-      await createAngularCompilation(!!options.jit, !options.serverEntryPoint),
+      new AngularCompilationContext(angularCompilation),
       templateUpdates,
     );
 

packages/angular/build/src/builders/application/setup-bundling.ts

@@ -6,9 +6,9 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import { AngularCompilation } from '../../tools/angular/compilation';
+import type { AngularCompilationContext } from '../../tools/esbuild/angular/compilation-state';
 import { ComponentStylesheetBundler } from '../../tools/esbuild/angular/component-stylesheets';
-import { SourceFileCache } from '../../tools/esbuild/angular/source-file-cache';
+import type { SourceFileCache } from '../../tools/esbuild/angular/source-file-cache';
 import {
   createBrowserCodeBundleOptions,
   createBrowserPolyfillBundleOptions,
@@ -20,7 +20,7 @@ import { BundlerContext } from '../../tools/esbuild/bundler-context';
 import { createGlobalScriptsBundleOptions } from '../../tools/esbuild/global-scripts';
 import { createGlobalStylesBundleOptions } from '../../tools/esbuild/global-styles';
 import { getSupportedNodeTargets } from '../../tools/esbuild/utils';
-import { NormalizedApplicationBuildOptions } from './options';
+import type { NormalizedApplicationBuildOptions } from './options';
 
 /**
  * Generates one or more BundlerContext instances based on the builder provided
@@ -35,7 +35,7 @@ export function setupBundlerContexts(
   target: string[],
   codeBundleCache: SourceFileCache,
   stylesheetBundler: ComponentStylesheetBundler,
-  angularCompilation: AngularCompilation,
+  angularCompilationContext: AngularCompilationContext,
   templateUpdates: Map<string, string> | undefined,
 ): {
   typescriptContexts: BundlerContext[];
@@ -63,7 +63,7 @@ export function setupBundlerContexts(
         target,
         codeBundleCache,
         stylesheetBundler,
-        angularCompilation,
+        angularCompilationContext,
         templateUpdates,
       ),
     ),

packages/angular/build/src/tools/esbuild/angular/compilation-state.ts

@@ -6,12 +6,23 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-export class SharedTSCompilationState {
+import type { AngularCompilation } from '../../angular/compilation';
+
+export class AngularCompilationContext {
+  #compilation: AngularCompilation;
   #pendingCompilation = true;
   #resolveCompilationReady: ((value: boolean) => void) | undefined;
   #compilationReadyPromise: Promise<boolean> | undefined;
   #hasErrors = true;
 
+  constructor(compilation: AngularCompilation) {
+    this.#compilation = compilation;
+  }
+
+  get compilation(): AngularCompilation {
+    return this.#compilation;
+  }
+
   get waitUntilReady(): Promise<boolean> {
     if (!this.#pendingCompilation) {
       return Promise.resolve(this.#hasErrors);
@@ -35,14 +46,14 @@ export class SharedTSCompilationState {
     this.#pendingCompilation = true;
   }
 
-  dispose(): void {
+  #disposed = false;
+
+  async dispose(): Promise<void> {
+    if (this.#disposed) {
+      return;
+    }
+    this.#disposed = true;
     this.markAsReady(true);
-    globalSharedCompilationState = undefined;
+    await this.#compilation.close?.();
   }
 }
-
-let globalSharedCompilationState: SharedTSCompilationState | undefined;
-
-export function getSharedCompilationState(): SharedTSCompilationState {
-  return (globalSharedCompilationState ??= new SharedTSCompilationState());
-}

packages/angular/build/src/tools/esbuild/angular/compiler-plugin.ts

@@ -27,7 +27,7 @@ import { AngularCompilation, DiagnosticModes, NoopCompilation } from '../../angu
 import { JavaScriptTransformer } from '../javascript-transformer';
 import { LoadResultCache, createCachedLoad } from '../load-result-cache';
 import { logCumulativeDurations, profileAsync, resetCumulativeDurations } from '../profiling';
-import { SharedTSCompilationState, getSharedCompilationState } from './compilation-state';
+import { AngularCompilationContext } from './compilation-state';
 import { ComponentStylesheetBundler } from './component-stylesheets';
 import { FileReferenceTracker } from './file-reference-tracker';
 import { setupJitPluginCallbacks } from './jit-plugin-callbacks';
@@ -61,7 +61,10 @@ export interface CompilerPluginOptions {
 // eslint-disable-next-line max-lines-per-function
 export function createCompilerPlugin(
   pluginOptions: CompilerPluginOptions,
-  compilationOrFactory: AngularCompilation | (() => Promise<AngularCompilation>),
+  compilationContextOrCompilation:
+    | AngularCompilationContext
+    | AngularCompilation
+    | (() => Promise<AngularCompilation>),
   stylesheetBundler: ComponentStylesheetBundler,
 ): Plugin {
   return {
@@ -111,10 +114,15 @@ export function createCompilerPlugin(
 
       // The factory is only relevant for compatibility purposes with the private API.
       // TODO: Update private API in the next major to allow compilation function factory removal here.
-      const compilation =
-        typeof compilationOrFactory === 'function'
-          ? await compilationOrFactory()
-          : compilationOrFactory;
+      const angularCompilationContext =
+        compilationContextOrCompilation instanceof AngularCompilationContext
+          ? compilationContextOrCompilation
+          : new AngularCompilationContext(
+              typeof compilationContextOrCompilation === 'function'
+                ? await compilationContextOrCompilation()
+                : compilationContextOrCompilation,
+            );
+      const compilation = angularCompilationContext.compilation;
 
       // The in-memory cache of TypeScript file outputs will be used during the build in `onLoad` callbacks for TS files.
       // A string value indicates direct TS/NG output and a Uint8Array indicates fully transformed code.
@@ -136,16 +144,13 @@ export function createCompilerPlugin(
       // Determines if transpilation should be handle by TypeScript or esbuild
       let useTypeScriptTranspilation = true;
 
-      let sharedTSCompilationState: SharedTSCompilationState | undefined;
-
       // To fully invalidate files, track resource referenced files and their referencing source
       const referencedFileTracker = new FileReferenceTracker();
 
       // eslint-disable-next-line max-lines-per-function
       build.onStart(async () => {
-        sharedTSCompilationState = getSharedCompilationState();
         if (!(compilation instanceof NoopCompilation)) {
-          sharedTSCompilationState.markAsInProgress();
+          angularCompilationContext.markAsInProgress();
         }
 
         const result: OnStartResult = {
@@ -348,7 +353,7 @@ export function createCompilerPlugin(
         }
 
         if (compilation instanceof NoopCompilation) {
-          hasCompilationErrors = await sharedTSCompilationState.waitUntilReady;
+          hasCompilationErrors = await angularCompilationContext.waitUntilReady;
 
           return result;
         }
@@ -417,7 +422,7 @@ export function createCompilerPlugin(
         // Reset the setup warnings so that they are only shown during the first build.
         setupWarnings = undefined;
 
-        sharedTSCompilationState.markAsReady(hasCompilationErrors);
+        angularCompilationContext.markAsReady(hasCompilationErrors);
 
         return result;
       });
@@ -576,7 +581,7 @@ export function createCompilerPlugin(
 
       build.onEnd((result) => {
         // Ensure other compilations are unblocked if the main compilation throws during start
-        sharedTSCompilationState?.markAsReady(hasCompilationErrors);
+        angularCompilationContext.markAsReady(hasCompilationErrors);
 
         for (const { outputFiles, metafile } of additionalResults.values()) {
           // Add any additional output files to the main output files
@@ -598,8 +603,7 @@ export function createCompilerPlugin(
       });
 
       build.onDispose(() => {
-        sharedTSCompilationState?.dispose();
-        void compilation.close?.();
+        void angularCompilationContext.dispose();
         void javascriptTransformer.close();
         void cacheStore?.close();
       });

packages/angular/build/src/tools/esbuild/application-code-bundle.ts

@@ -20,6 +20,7 @@ import {
   SERVER_GENERATED_EXTERNALS,
 } from '../../utils/server-rendering/manifest';
 import { AngularCompilation, NoopCompilation } from '../angular/compilation';
+import { AngularCompilationContext } from './angular/compilation-state';
 import { createCompilerPlugin } from './angular/compiler-plugin';
 import { ComponentStylesheetBundler } from './angular/component-stylesheets';
 import { SourceFileCache } from './angular/source-file-cache';
@@ -42,7 +43,7 @@ export function createBrowserCodeBundleOptions(
   target: string[],
   sourceFileCache: SourceFileCache,
   stylesheetBundler: ComponentStylesheetBundler,
-  angularCompilation: AngularCompilation,
+  angularCompilationContext: AngularCompilationContext,
   templateUpdates: Map<string, string> | undefined,
 ): BundlerOptionsFactory {
   return (loadCache) => {
@@ -77,7 +78,7 @@ export function createBrowserCodeBundleOptions(
       createCompilerPlugin(
         // JS/TS options
         pluginOptions,
-        angularCompilation,
+        angularCompilationContext,
         // Component stylesheet bundler
         stylesheetBundler,
       ),