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

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.

Author: clydin

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);
       }

packages/angular/build/src/tools/esbuild/persistent-load-result-cache.ts

@@ -0,0 +1,301 @@
+/**
+ * @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 { readFile, stat } from 'node:fs/promises';
+import type { Cache as PersistentCacheStore } from './cache';
+import { LoadResultCache, MemoryLoadResultCache } from './load-result-cache';
+
+/**
+ * Metadata for a single watch file dependency.
+ */
+export interface CachedDependencyMetadata {
+  hash: string;
+  mtimeMs: number;
+  size: number;
+}
+
+/**
+ * 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 dependency metadata */
+  watchFilesMetadata: Record<string, CachedDependencyMetadata>;
+
+  /** 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('\0')
+    .update(path)
+    .update('\0')
+    .update(content)
+    .digest('hex');
+}
+
+/**
+ * Validates that all imported watch files exist on disk and their contents match.
+ * Performs a fast-path metadata check (mtime + size) first, falling back to content hashing.
+ * Heals/updates the cached metadata on disk if the content hash was valid but the metadata changed.
+ */
+async function validateAndHealCacheEntry(
+  watchFilesMetadata: Record<string, CachedDependencyMetadata>,
+  store: PersistentCacheStore<CachedLoadResultEntry>,
+  cacheKey: string,
+  cached: CachedLoadResultEntry,
+  targetFilePath?: string,
+): Promise<boolean> {
+  const watchFiles = Object.keys(watchFilesMetadata);
+  const concurrencyLimit = 8;
+  let healed = false;
+
+  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) => {
+        try {
+          const stats = await stat(filePath);
+          const expected = watchFilesMetadata[filePath];
+          if (!expected) {
+            return false;
+          }
+
+          // 1. Fast Path: size and mtime match
+          if (stats.size === expected.size && stats.mtimeMs === expected.mtimeMs) {
+            return true;
+          }
+
+          // 2. Target File Path: content hash was already verified by cacheKey lookup, heal metadata if mtime changed
+          if (targetFilePath && filePath === targetFilePath) {
+            watchFilesMetadata[filePath] = {
+              ...expected,
+              mtimeMs: stats.mtimeMs,
+              size: stats.size,
+            };
+            healed = true;
+
+            return true;
+          }
+
+          // 3. Slow Path for dependencies: content hash fallback
+          const currentContent = await readFile(filePath);
+          const currentHash = hashContent(currentContent);
+          if (currentHash === expected.hash) {
+            // Heal cache entry with new metadata
+            watchFilesMetadata[filePath] = {
+              ...expected,
+              mtimeMs: stats.mtimeMs,
+              size: stats.size,
+            };
+            healed = true;
+
+            return true;
+          }
+
+          return false;
+        } catch {
+          return false;
+        }
+      }),
+    );
+
+    if (results.some((isValid) => !isValid)) {
+      return false;
+    }
+  }
+
+  if (healed) {
+    try {
+      await store.put(cacheKey, cached);
+    } catch {
+      // Ignore errors writing healed entries
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Computes metadata (content hashes, mtime, size) for an array of watch file paths.
+ * Processes files in parallel chunks of 8 to avoid exhausting file descriptors.
+ */
+async function computeMetadataForWatchFiles(
+  watchFiles: string[],
+  knownContents?: Map<string, string | Uint8Array>,
+): Promise<Record<string, CachedDependencyMetadata>> {
+  const watchFilesMetadata: Record<string, CachedDependencyMetadata> = {};
+  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) => {
+        try {
+          const knownContent = knownContents?.get(filePath);
+          const [content, stats] = await Promise.all([
+            knownContent !== undefined ? knownContent : readFile(filePath),
+            stat(filePath),
+          ]);
+          watchFilesMetadata[filePath] = {
+            hash: hashContent(content),
+            mtimeMs: stats.mtimeMs,
+            size: stats.size,
+          };
+        } catch {
+          // Ignore unreadable files
+        }
+      }),
+    );
+  }
+
+  return watchFilesMetadata;
+}
+
+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 metadata.
+   */
+  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;
+    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 validateAndHealCacheEntry(
+        cached.watchFilesMetadata,
+        this.persistentStore,
+        cacheKey,
+        cached,
+        filePath,
+      ))
+    ) {
+      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);
+
+    // Persist to L2 store if persistentStore is configured and contents exist (including empty strings/buffers)
+    if (this.persistentStore && result.contents !== undefined) {
+      let content: string | Uint8Array;
+      const filePath = path.startsWith('file:') ? path.slice(5) : path;
+      try {
+        content = await readFile(filePath);
+      } catch {
+        content = '';
+      }
+
+      const cacheKey = calculateCacheKey(this.globalConfigHash, path, content);
+
+      // Reuse the target file's pre-read content buffer to avoid redundant disk reads (readFile)
+      // during dependency watch file metadata computation.
+      const knownContents = new Map<string, string | Uint8Array>([[filePath, content]]);
+      const watchFilesMetadata = await computeMetadataForWatchFiles(
+        result.watchFiles ?? [],
+        knownContents,
+      );
+
+      await this.persistentStore.put(cacheKey, {
+        contents: result.contents,
+        loader: result.loader,
+        watchFiles: result.watchFiles ?? [],
+        watchFilesMetadata,
+        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 metadata verification (`validateAndHealCacheEntry`).
+   */
+  invalidate(path: string): boolean {
+    return this.memoryCache.invalidate(path);
+  }
+
+  get watchFiles(): ReadonlyArray<string> {
+    return this.memoryCache.watchFiles;
+  }
+}