refactor(@angular-devkit/build-angular): consolidate result file writes in esbuild builder

As a preparation step to allow for in-memory build outputs to support the development server,
The output result files of the build are now written to the file system in one location. This
includes the generated files from the bundling steps as well as any assets and service worker
files.

Author: clydin

packages/angular_devkit/build_angular/src/builders/browser-esbuild/index.ts

@@ -9,8 +9,9 @@
 import { BuilderContext, BuilderOutput, createBuilder } from '@angular-devkit/architect';
 import type { BuildOptions, OutputFile } from 'esbuild';
 import assert from 'node:assert';
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
+import { constants as fsConstants } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
 import { deleteOutputDir } from '../../utils';
 import { copyAssets } from '../../utils/copy-assets';
 import { assertIsError } from '../../utils/error';
@@ -205,38 +206,41 @@ async function execute(
   }
 
   // Copy assets
+  let assetFiles;
   if (assets) {
-    await copyAssets(assets, [outputPath], workspaceRoot);
+    // The webpack copy assets helper is used with no base paths defined. This prevents the helper
+    // from directly writing to disk. This should eventually be replaced with a more optimized helper.
+    assetFiles = await copyAssets(assets, [], workspaceRoot);
   }
 
-  // Write output files
-  await Promise.all(
-    outputFiles.map((file) => fs.writeFile(path.join(outputPath, file.path), file.contents)),
-  );
-
   // Write metafile if stats option is enabled
   if (options.stats) {
-    await fs.writeFile(path.join(outputPath, 'stats.json'), JSON.stringify(metafile, null, 2));
+    outputFiles.push(createOutputFileFromText('stats.json', JSON.stringify(metafile, null, 2)));
   }
 
   // Extract and write licenses for used packages
   if (options.extractLicenses) {
-    await fs.writeFile(
-      path.join(outputPath, '3rdpartylicenses.txt'),
-      await extractLicenses(metafile, workspaceRoot),
+    outputFiles.push(
+      createOutputFileFromText(
+        '3rdpartylicenses.txt',
+        await extractLicenses(metafile, workspaceRoot),
+      ),
     );
   }
 
   // Augment the application with service worker support
-  // TODO: This should eventually operate on the in-memory files prior to writing the output files
   if (serviceWorkerOptions) {
     try {
-      await augmentAppWithServiceWorkerEsbuild(
+      const serviceWorkerResult = await augmentAppWithServiceWorkerEsbuild(
         workspaceRoot,
         serviceWorkerOptions,
-        outputPath,
         options.baseHref || '/',
+        outputFiles,
+        assetFiles || [],
       );
+      outputFiles.push(createOutputFileFromText('ngsw.json', serviceWorkerResult.manifest));
+      assetFiles ??= [];
+      assetFiles.push(...serviceWorkerResult.assetFiles);
     } catch (error) {
       context.logger.error(error instanceof Error ? error.message : `${error}`);
 
@@ -249,12 +253,55 @@ async function execute(
     }
   }
 
+  // Write output files
+  await writeResultFiles(outputFiles, assetFiles, outputPath);
+
   const buildTime = Number(process.hrtime.bigint() - startTime) / 10 ** 9;
   context.logger.info(`Complete. [${buildTime.toFixed(3)} seconds]`);
 
   return new ExecutionResult(true, codeBundleContext, globalStylesBundleContext, codeBundleCache);
 }
 
+async function writeResultFiles(
+  outputFiles: OutputFile[],
+  assetFiles: { source: string; destination: string }[] | undefined,
+  outputPath: string,
+) {
+  const directoryExists = new Set<string>();
+  await Promise.all(
+    outputFiles.map(async (file) => {
+      // Ensure output subdirectories exist
+      const basePath = path.dirname(file.path);
+      if (basePath && !directoryExists.has(basePath)) {
+        await fs.mkdir(path.join(outputPath, basePath), { recursive: true });
+        directoryExists.add(basePath);
+      }
+      // Write file contents
+      await fs.writeFile(path.join(outputPath, file.path), file.contents);
+    }),
+  );
+
+  if (assetFiles?.length) {
+    await Promise.all(
+      assetFiles.map(async ({ source, destination }) => {
+        // Ensure output subdirectories exist
+        const basePath = path.dirname(destination);
+        if (basePath && !directoryExists.has(basePath)) {
+          await fs.mkdir(path.join(outputPath, basePath), { recursive: true });
+          directoryExists.add(basePath);
+        }
+        // Copy file contents
+        await fs.copyFile(
+          source,
+          path.join(outputPath, destination),
+          // This is not yet available from `fs/promises` in Node.js v16.13
+          fsConstants.COPYFILE_FICLONE,
+        );
+      }),
+    );
+  }
+}
+
 function createOutputFileFromText(path: string, text: string): OutputFile {
   return {
     path,

packages/angular_devkit/build_angular/src/utils/copy-assets.ts

@@ -28,6 +28,8 @@ export async function copyAssets(
 ) {
   const defaultIgnore = ['.gitkeep', '**/.DS_Store', '**/Thumbs.db'];
 
+  const outputFiles: { source: string; destination: string }[] = [];
+
   for (const entry of entries) {
     const cwd = path.resolve(root, entry.input);
     const files = await globPromise(entry.glob, {
@@ -49,6 +51,9 @@ export async function copyAssets(
       }
 
       const filePath = entry.flatten ? path.basename(file) : file;
+
+      outputFiles.push({ source: src, destination: path.join(entry.output, filePath) });
+
       for (const base of basePaths) {
         const dest = path.join(base, entry.output, filePath);
         const dir = path.dirname(dest);
@@ -62,4 +67,6 @@ export async function copyAssets(
       }
     }
   }
+
+  return outputFiles;
 }

packages/angular_devkit/build_angular/src/utils/service-worker.ts

@@ -8,7 +8,8 @@
 
 import type { Config, Filesystem } from '@angular/service-worker/config';
 import * as crypto from 'crypto';
-import { constants as fsConstants, promises as fsPromises } from 'fs';
+import type { OutputFile } from 'esbuild';
+import { existsSync, constants as fsConstants, promises as fsPromises } from 'node:fs';
 import * as path from 'path';
 import { assertIsError } from './error';
 import { loadEsmModule } from './load-esm';
@@ -61,6 +62,49 @@ class CliFilesystem implements Filesystem {
   }
 }
 
+class ResultFilesystem implements Filesystem {
+  private readonly fileReaders = new Map<string, () => Promise<string>>();
+
+  constructor(outputFiles: OutputFile[], assetFiles: { source: string; destination: string }[]) {
+    for (const file of outputFiles) {
+      this.fileReaders.set('/' + file.path.replace(/\\/g, '/'), async () => file.text);
+    }
+    for (const file of assetFiles) {
+      this.fileReaders.set('/' + file.destination.replace(/\\/g, '/'), () =>
+        fsPromises.readFile(file.source, 'utf-8'),
+      );
+    }
+  }
+
+  async list(dir: string): Promise<string[]> {
+    if (dir !== '/') {
+      throw new Error('Serviceworker manifest generator should only list files from root.');
+    }
+
+    return [...this.fileReaders.keys()];
+  }
+
+  read(file: string): Promise<string> {
+    const reader = this.fileReaders.get(file);
+    if (reader === undefined) {
+      throw new Error('File does not exist.');
+    }
+
+    return reader();
+  }
+
+  async hash(file: string): Promise<string> {
+    return crypto
+      .createHash('sha1')
+      .update(await this.read(file))
+      .digest('hex');
+  }
+
+  write(): never {
+    throw new Error('Serviceworker manifest generator should not attempted to write.');
+  }
+}
+
 export async function augmentAppWithServiceWorker(
   appRoot: string,
   workspaceRoot: string,
@@ -93,22 +137,37 @@ export async function augmentAppWithServiceWorker(
     }
   }
 
-  return augmentAppWithServiceWorkerCore(
+  const result = await augmentAppWithServiceWorkerCore(
     config,
-    outputPath,
+    new CliFilesystem(outputFileSystem, outputPath),
     baseHref,
-    inputputFileSystem,
-    outputFileSystem,
   );
+
+  const copy = async (src: string, dest: string): Promise<void> => {
+    const resolvedDest = path.join(outputPath, dest);
+
+    return inputputFileSystem === outputFileSystem
+      ? // Native FS (Builder).
+        inputputFileSystem.copyFile(src, resolvedDest, fsConstants.COPYFILE_FICLONE)
+      : // memfs (Webpack): Read the file from the input FS (disk) and write it to the output FS (memory).
+        outputFileSystem.writeFile(resolvedDest, await inputputFileSystem.readFile(src));
+  };
+
+  await outputFileSystem.writeFile(path.join(outputPath, 'ngsw.json'), result.manifest);
+
+  for (const { source, destination } of result.assetFiles) {
+    await copy(source, destination);
+  }
 }
 
 // This is currently used by the esbuild-based builder
 export async function augmentAppWithServiceWorkerEsbuild(
   workspaceRoot: string,
   configPath: string,
-  outputPath: string,
   baseHref: string,
-): Promise<void> {
+  outputFiles: OutputFile[],
+  assetFiles: { source: string; destination: string }[],
+): Promise<{ manifest: string; assetFiles: { source: string; destination: string }[] }> {
   // Read the configuration file
   let config: Config | undefined;
   try {
@@ -128,17 +187,18 @@ export async function augmentAppWithServiceWorkerEsbuild(
     }
   }
 
-  // TODO: Return the output files and any errors/warnings
-  return augmentAppWithServiceWorkerCore(config, outputPath, baseHref);
+  return augmentAppWithServiceWorkerCore(
+    config,
+    new ResultFilesystem(outputFiles, assetFiles),
+    baseHref,
+  );
 }
 
 export async function augmentAppWithServiceWorkerCore(
   config: Config,
-  outputPath: string,
+  serviceWorkerFilesystem: Filesystem,
   baseHref: string,
-  inputputFileSystem = fsPromises,
-  outputFileSystem = fsPromises,
-): Promise<void> {
+): Promise<{ manifest: string; assetFiles: { source: string; destination: string }[] }> {
   // Load ESM `@angular/service-worker/config` using the TypeScript dynamic import workaround.
   // Once TypeScript provides support for keeping the dynamic import this workaround can be
   // changed to a direct dynamic import.
@@ -149,41 +209,27 @@ export async function augmentAppWithServiceWorkerCore(
   ).Generator;
 
   // Generate the manifest
-  const generator = new GeneratorConstructor(
-    new CliFilesystem(outputFileSystem, outputPath),
-    baseHref,
-  );
+  const generator = new GeneratorConstructor(serviceWorkerFilesystem, baseHref);
   const output = await generator.process(config);
 
   // Write the manifest
   const manifest = JSON.stringify(output, null, 2);
-  await outputFileSystem.writeFile(path.join(outputPath, 'ngsw.json'), manifest);
 
   // Find the service worker package
   const workerPath = require.resolve('@angular/service-worker/ngsw-worker.js');
 
-  const copy = async (src: string, dest: string): Promise<void> => {
-    const resolvedDest = path.join(outputPath, dest);
-
-    return inputputFileSystem === outputFileSystem
-      ? // Native FS (Builder).
-        inputputFileSystem.copyFile(src, resolvedDest, fsConstants.COPYFILE_FICLONE)
-      : // memfs (Webpack): Read the file from the input FS (disk) and write it to the output FS (memory).
-        outputFileSystem.writeFile(resolvedDest, await inputputFileSystem.readFile(src));
+  const result = {
+    manifest,
+    // Main worker code
+    assetFiles: [{ source: workerPath, destination: 'ngsw-worker.js' }],
   };
 
-  // Write the worker code
-  await copy(workerPath, 'ngsw-worker.js');
-
   // If present, write the safety worker code
-  try {
-    const safetyPath = path.join(path.dirname(workerPath), 'safety-worker.js');
-    await copy(safetyPath, 'worker-basic.min.js');
-    await copy(safetyPath, 'safety-worker.js');
-  } catch (error) {
-    assertIsError(error);
-    if (error.code !== 'ENOENT') {
-      throw error;
-    }
+  const safetyPath = path.join(path.dirname(workerPath), 'safety-worker.js');
+  if (existsSync(safetyPath)) {
+    result.assetFiles.push({ source: safetyPath, destination: 'worker-basic.min.js' });
+    result.assetFiles.push({ source: safetyPath, destination: 'safety-worker.js' });
   }
+
+  return result;
 }