refactor(@angular/build): implement generic persistent load result cache infrastructure for build pipeline

clydin · clydin · commit edabae0701d8 · 2026-07-24T10:10:02.000-04:00
This change implements a unified, generic persistent caching system for the esbuild builder pipeline. It introduces a two-tier caching mechanism combining in-memory caching with a persistent disk store.
Integration into various aspects of the build system will be performed in future changes.
diff --git a/packages/angular/build/src/tools/esbuild/load-result-cache.ts b/packages/angular/build/src/tools/esbuild/load-result-cache.ts
@@ -10,7 +10,7 @@ import type { OnLoadResult, PluginBuild } from 'esbuild';
 import { normalize } from 'node:path';
 
 export interface LoadResultCache {
-  get(path: string): OnLoadResult | undefined;
+  get(path: string): OnLoadResult | Promise<OnLoadResult | undefined> | undefined;
   put(path: string, result: OnLoadResult): Promise<void>;
   readonly watchFiles: ReadonlyArray<string>;
 }
@@ -25,7 +25,7 @@ export function createCachedLoad(
 
   return async (args) => {
     const loadCacheKey = `${args.namespace}:${args.path}`;
-    let result: OnLoadResult | null | undefined = cache.get(loadCacheKey);
+    let result: OnLoadResult | null | undefined = await cache.get(loadCacheKey);
 
     if (result === undefined) {
       result = await callback(args);
@@ -35,7 +35,9 @@ export function createCachedLoad(
         // Ensure requested path is included if it was a resolved file
         if (args.namespace === 'file') {
           result.watchFiles ??= [];
-          result.watchFiles.push(args.path);
+          if (!result.watchFiles.includes(args.path)) {
+            result.watchFiles.push(args.path);
+          }
         }
         await cache.put(loadCacheKey, result);
       }
diff --git a/packages/angular/build/src/tools/esbuild/persistent-load-result-cache.ts b/packages/angular/build/src/tools/esbuild/persistent-load-result-cache.ts
@@ -0,0 +1,216 @@
+/**
+ * @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 type { Loader, OnLoadResult, PartialMessage } from 'esbuild';
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import type { Cache as PersistentCacheStore } from './cache';
+import { LoadResultCache, MemoryLoadResultCache } from './load-result-cache';
+
+/**
+ * Serialized representation of any esbuild load result stored in persistent cache.
+ */
+export interface CachedLoadResultEntry {
+  /** Compiled output string or binary data */
+  contents: string | Uint8Array;
+
+  /** esbuild loader type */
+  loader?: Loader;
+
+  /** Absolute paths of all imported/watched dependency files */
+  watchFiles: string[];
+
+  /** Map of watchFile absolute paths to content hashes */
+  watchFilesHashes: Record<string, string>;
+
+  /** Warnings emitted during load processing */
+  warnings?: PartialMessage[];
+
+  /** Errors emitted during load processing */
+  errors?: PartialMessage[];
+}
+
+function hashContent(content: string | Uint8Array): string {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Calculates a unique cache key by updating the hash incrementally.
+ * This prevents implicit string coercion of large binary content buffers.
+ */
+function calculateCacheKey(
+  globalConfigHash: string,
+  path: string,
+  content: string | Uint8Array,
+): string {
+  return createHash('sha256').update(globalConfigHash).update(path).update(content).digest('hex');
+}
+
+/**
+ * Validates that all imported watch files exist on disk and their content hashes match.
+ * Processes files in parallel chunks of 8 to avoid exhausting file descriptors.
+ */
+async function isCacheEntryValid(watchFilesHashes: Record<string, string>): Promise<boolean> {
+  const watchFiles = Object.keys(watchFilesHashes);
+  const concurrencyLimit = 8;
+
+  for (let i = 0; i < watchFiles.length; i += concurrencyLimit) {
+    const chunk = watchFiles.slice(i, i + concurrencyLimit);
+    const results = await Promise.all(
+      chunk.map(async (filePath) => {
+        if (!existsSync(filePath)) {
+          return false;
+        }
+        try {
+          const currentContent = await readFile(filePath);
+
+          return hashContent(currentContent) === watchFilesHashes[filePath];
+        } catch {
+          return false;
+        }
+      }),
+    );
+
+    if (results.some((isValid) => !isValid)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Computes hashes for an array of watch file paths.
+ * Processes files in parallel chunks of 8 to avoid exhausting file descriptors.
+ */
+async function computeHashesForWatchFiles(watchFiles: string[]): Promise<Record<string, string>> {
+  const watchFilesHashes: Record<string, string> = {};
+  const concurrencyLimit = 8;
+
+  for (let i = 0; i < watchFiles.length; i += concurrencyLimit) {
+    const chunk = watchFiles.slice(i, i + concurrencyLimit);
+    await Promise.all(
+      chunk.map(async (filePath) => {
+        if (existsSync(filePath)) {
+          try {
+            const content = await readFile(filePath);
+            watchFilesHashes[filePath] = hashContent(content);
+          } catch {
+            // Ignore unreadable files
+          }
+        }
+      }),
+    );
+  }
+
+  return watchFilesHashes;
+}
+
+export class PersistentLoadResultCache implements LoadResultCache {
+  private readonly memoryCache = new MemoryLoadResultCache();
+
+  constructor(
+    private readonly persistentStore?: PersistentCacheStore<CachedLoadResultEntry>,
+    private readonly globalConfigHash: string = '',
+  ) {}
+
+  /**
+   * Retrieves a load result from cache.
+   * Checks L1 memory cache first for immediate watch-mode speed, falling back to L2 persistent disk
+   * store on L1 cache miss. L2 persistent cache entries are validated against dependency content hashes.
+   */
+  async get(path: string): Promise<OnLoadResult | undefined> {
+    // 1. Check L1 Memory Cache
+    const memoryResult = this.memoryCache.get(path);
+    if (memoryResult) {
+      return memoryResult;
+    }
+
+    if (!this.persistentStore) {
+      return undefined;
+    }
+
+    // 2. Check L2 Persistent Disk Cache
+    let content: string | Uint8Array = '';
+    const filePath = path.startsWith('file:') ? path.slice(5) : path;
+    if (existsSync(filePath)) {
+      try {
+        content = await readFile(filePath);
+      } catch {
+        return undefined;
+      }
+    }
+
+    const cacheKey = calculateCacheKey(this.globalConfigHash, path, content);
+    const cached = await this.persistentStore.get(cacheKey);
+
+    if (cached && (await isCacheEntryValid(cached.watchFilesHashes))) {
+      const result: OnLoadResult = {
+        contents: cached.contents,
+        loader: cached.loader,
+        watchFiles: cached.watchFiles,
+        warnings: cached.warnings,
+        errors: cached.errors,
+      };
+
+      // Populate L1 Memory Cache for subsequent lookups
+      await this.memoryCache.put(path, result);
+
+      return result;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Stores a load result in both L1 memory cache and L2 persistent disk store.
+   */
+  async put(path: string, result: OnLoadResult): Promise<void> {
+    await this.memoryCache.put(path, result);
+
+    if (this.persistentStore && result.contents) {
+      let content: string | Uint8Array = '';
+      const filePath = path.startsWith('file:') ? path.slice(5) : path;
+      if (existsSync(filePath)) {
+        try {
+          content = await readFile(filePath);
+        } catch {
+          // ignore
+        }
+      }
+
+      const cacheKey = calculateCacheKey(this.globalConfigHash, path, content);
+      const watchFilesHashes = await computeHashesForWatchFiles(result.watchFiles ?? []);
+
+      await this.persistentStore.put(cacheKey, {
+        contents: result.contents,
+        loader: result.loader,
+        watchFiles: result.watchFiles ?? [],
+        watchFilesHashes,
+        warnings: result.warnings,
+        errors: result.errors,
+      });
+    }
+  }
+
+  /**
+   * Invalidates cached entries affected by a modified dependency file during watch mode.
+   *
+   * Note: Invalidation of L1 memory cache is sufficient for active watch mode.
+   * Cross-process/cold start stale entries in L2 persistent store are automatically handled
+   * during `get()` via dependency content hash verification (`isCacheEntryValid`).
+   */
+  invalidate(path: string): boolean {
+    return this.memoryCache.invalidate(path);
+  }
+
+  get watchFiles(): ReadonlyArray<string> {
+    return this.memoryCache.watchFiles;
+  }
+}
diff --git a/packages/angular/build/src/tools/esbuild/persistent-load-result-cache_spec.ts b/packages/angular/build/src/tools/esbuild/persistent-load-result-cache_spec.ts
@@ -0,0 +1,88 @@
+/**
+ * @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 type { OnLoadResult } from 'esbuild';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import type { Cache as PersistentCacheStore } from './cache';
+import {
+  type CachedLoadResultEntry,
+  PersistentLoadResultCache,
+} from './persistent-load-result-cache';
+
+describe('PersistentLoadResultCache', () => {
+  let mockStore: Map<string, CachedLoadResultEntry>;
+  let persistentStore: PersistentCacheStore<CachedLoadResultEntry>;
+  let tmpDir: string;
+  let file1: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), 'persistent-cache-test-'));
+    file1 = path.join(tmpDir, 'test.js');
+    fs.writeFileSync(file1, 'console.log("hello");');
+
+    mockStore = new Map();
+    persistentStore = {
+      async get(key: string) {
+        return mockStore.get(key);
+      },
+      async put(key: string, value: CachedLoadResultEntry) {
+        mockStore.set(key, value);
+      },
+    } as unknown as PersistentCacheStore<CachedLoadResultEntry>;
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('should return undefined on L1 and L2 cache miss', async () => {
+    const cache = new PersistentLoadResultCache(persistentStore, 'global-hash');
+    const result = await cache.get(file1);
+    expect(result).toBeUndefined();
+  });
+
+  it('should hit L2 persistent store and return cached output when dependencies are valid', async () => {
+    const cache = new PersistentLoadResultCache(persistentStore, 'global-hash');
+    const sampleResult: OnLoadResult = {
+      contents: 'console.log("hello");',
+      loader: 'js',
+      watchFiles: [file1],
+    };
+
+    await cache.put(file1, sampleResult);
+
+    // Create a second cache instance (simulating cold start)
+    const coldCache = new PersistentLoadResultCache(persistentStore, 'global-hash');
+    const hit = await coldCache.get(file1);
+
+    expect(hit).toBeDefined();
+    expect(hit?.contents).toBe('console.log("hello");');
+    expect(hit?.loader).toBe('js');
+  });
+
+  it('should invalidate L2 persistent cache hit if a watch dependency file is modified', async () => {
+    const cache = new PersistentLoadResultCache(persistentStore, 'global-hash');
+    const sampleResult: OnLoadResult = {
+      contents: 'console.log("hello");',
+      loader: 'js',
+      watchFiles: [file1],
+    };
+
+    await cache.put(file1, sampleResult);
+
+    // Modify dependency file
+    fs.writeFileSync(file1, 'console.log("world");');
+
+    const coldCache = new PersistentLoadResultCache(persistentStore, 'global-hash');
+    const hit = await coldCache.get(file1);
+
+    expect(hit).toBeUndefined();
+  });
+});
diff --git a/packages/angular/build/src/tools/esbuild/stylesheets/stylesheet-cache-key.ts b/packages/angular/build/src/tools/esbuild/stylesheets/stylesheet-cache-key.ts
@@ -0,0 +1,64 @@
+/**
+ * @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 { createHash } from 'node:crypto';
+import type { BundleStylesheetOptions } from './bundle-options';
+
+/**
+ * Generates a global hash based on all build options that affect stylesheet compilation.
+ *
+ * IMPORTANT: This hash acts as the root cache key prefix for all persistent stylesheet cache
+ * entries. Any change in the values hashed below will invalidate all cached stylesheet outputs
+ * across the entire application.
+ *
+ * Included build options and their rationale:
+ * - `optimization`: Affects CSS minification, dead code elimination, and whitespace stripping.
+ * - `sourcemap`: Toggles inline/external source map generation and comment insertion.
+ * - `includePaths`: Changes Sass/Less `@import` and `@use` path resolution search directories.
+ * - `sassOptions`: Changes Sass compiler deprecations and behavior flags.
+ * - `target`: Affects CSS property lowering and browser vendor prefixing in esbuild.
+ * - `publicPath`: Affects relative asset URL rewriting (`url('...')`) inside CSS output.
+ * - `outputNames`: Affects asset output filename hashing schemes.
+ * - `inlineFonts`: Controls whether external web font `@import` / `<link>` directives are inlined.
+ * - `preserveSymlinks`: Controls symlink realpath resolution in monorepos/pnpm workspace packages.
+ * - `externalDependencies`: Controls which CSS modules/urls are excluded from bundling.
+ * - `postcssConfig`: Path to custom PostCSS configuration file.
+ * - `tailwindConfig`: Path to Tailwind CSS configuration file.
+ * - `packageVersion`: Invalidates cache across `@angular/build` compiler toolchain updates.
+ *
+ * @note Maintainers: If any new build option is added to `BundleStylesheetOptions` or `@angular/build`
+ * that alters generated stylesheet code or asset outputs, it MUST be added to this hash object.
+ */
+export function calculateGlobalStylesheetConfigHash(
+  options: BundleStylesheetOptions,
+  packageVersion: string = '',
+): string {
+  return createHash('sha256')
+    .update(
+      JSON.stringify({
+        optimization: options.optimization,
+        sourcemap: options.sourcemap,
+        includePaths: options.includePaths,
+        sassOptions: options.sass,
+        target: options.target,
+        publicPath: options.publicPath,
+        outputNames: options.outputNames,
+        inlineFonts: options.inlineFonts,
+        preserveSymlinks: options.preserveSymlinks,
+        externalDependencies: options.externalDependencies,
+        postcssConfig: options.postcssConfiguration?.configPath
+          ? options.postcssConfiguration.configPath
+          : '',
+        tailwindConfig: options.tailwindConfiguration?.file
+          ? options.tailwindConfiguration.file
+          : '',
+        packageVersion,
+      }),
+    )
+    .digest('hex');
+}
diff --git a/packages/angular/build/src/tools/esbuild/stylesheets/stylesheet-cache-key_spec.ts b/packages/angular/build/src/tools/esbuild/stylesheets/stylesheet-cache-key_spec.ts
