refactor(@angular-devkit/build-angular): use esbuild 0.17 incremental API in esbuild builder

Due to the update of the experimental esbuild-based browser application builder to use esbuild 0.17,
the watch mode has been changed to use the new incremental API. The previous API has been removed
from esbuild. The new API involves creating a build context object that can then be used to perform
rebuilds of the configured application bundler as needed. All watch mode usage has been updated to
use this new approach. An effort was made to minimize the amount of changes made to support this API
update and limit the changeset. However, further refactoring will be possible as additional capabilities
are added in the future.
esbuild API reference: https://esbuild.github.io/api/#rebuild

Author: clydin

package.json

@@ -141,8 +141,8 @@
     "cross-env": "^7.0.3",
     "css-loader": "6.7.3",
     "debug": "^4.1.1",
-    "esbuild": "0.16.17",
-    "esbuild-wasm": "0.16.17",
+    "esbuild": "0.17.2",
+    "esbuild-wasm": "0.17.2",
     "eslint": "8.31.0",
     "eslint-config-prettier": "8.6.0",
     "eslint-plugin-header": "3.1.1",

packages/angular_devkit/build_angular/package.json

@@ -31,7 +31,7 @@
     "copy-webpack-plugin": "11.0.0",
     "critters": "0.0.16",
     "css-loader": "6.7.3",
-    "esbuild-wasm": "0.16.17",
+    "esbuild-wasm": "0.17.2",
     "glob": "8.0.3",
     "https-proxy-agent": "5.0.1",
     "inquirer": "8.2.4",
@@ -67,7 +67,7 @@
     "webpack-subresource-integrity": "5.1.0"
   },
   "optionalDependencies": {
-    "esbuild": "0.16.17"
+    "esbuild": "0.17.2"
   },
   "peerDependencies": {
     "@angular/compiler-cli": "^15.0.0 || ^15.2.0-next",

packages/angular_devkit/build_angular/src/builders/browser-esbuild/compiler-plugin.ts

@@ -277,7 +277,9 @@ export function createCompilerPlugin(
             );
 
             const { contents, resourceFiles, errors, warnings } = stylesheetResult;
-            (result.errors ??= []).push(...errors);
+            if (errors) {
+              (result.errors ??= []).push(...errors);
+            }
             (result.warnings ??= []).push(...warnings);
             stylesheetResourceFiles.push(...resourceFiles);
             if (stylesheetResult.metafile) {

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

@@ -8,13 +8,15 @@
 
 import { BuilderContext } from '@angular-devkit/architect';
 import {
+  BuildContext,
   BuildFailure,
-  BuildInvalidate,
   BuildOptions,
-  BuildResult,
+  Message,
+  Metafile,
   OutputFile,
   PartialMessage,
   build,
+  context,
   formatMessages,
 } from 'esbuild';
 import { basename, extname, relative } from 'node:path';
@@ -29,76 +31,116 @@ export function isEsBuildFailure(value: unknown): value is BuildFailure {
   return !!value && typeof value === 'object' && 'errors' in value && 'warnings' in value;
 }
 
-/**
- * Executes the esbuild build function and normalizes the build result in the event of a
- * build failure that results in no output being generated.
- * All builds use the `write` option with a value of `false` to allow for the output files
- * build result array to be populated.
- *
- * @param optionsOrInvalidate The esbuild options object to use when building or the invalidate object
- * returned from an incremental build to perform an additional incremental build.
- * @returns If output files are generated, the full esbuild BuildResult; if not, the
- * warnings and errors for the attempted build.
- */
-export async function bundle(
-  workspaceRoot: string,
-  optionsOrInvalidate: BuildOptions | BuildInvalidate,
-): Promise<
-  | (BuildResult & { outputFiles: OutputFile[]; initialFiles: FileInfo[] })
-  | (BuildFailure & { outputFiles?: never })
-> {
-  let result;
-  try {
-    if (typeof optionsOrInvalidate === 'function') {
-      result = (await optionsOrInvalidate()) as BuildResult & { outputFiles: OutputFile[] };
-    } else {
-      result = await build({
-        ...optionsOrInvalidate,
-        metafile: true,
-        write: false,
-      });
+export class BundlerContext {
+  #esbuildContext?: BuildContext<{ metafile: true; write: false }>;
+  #esbuildOptions: BuildOptions & { metafile: true; write: false };
+
+  constructor(private workspaceRoot: string, private incremental: boolean, options: BuildOptions) {
+    this.#esbuildOptions = {
+      ...options,
+      metafile: true,
+      write: false,
+    };
+  }
+
+  /**
+   * Executes the esbuild build function and normalizes the build result in the event of a
+   * build failure that results in no output being generated.
+   * All builds use the `write` option with a value of `false` to allow for the output files
+   * build result array to be populated.
+   *
+   * @returns If output files are generated, the full esbuild BuildResult; if not, the
+   * warnings and errors for the attempted build.
+   */
+  async bundle(): Promise<
+    | { errors: Message[]; warnings: Message[] }
+    | {
+        errors: undefined;
+        warnings: Message[];
+        metafile: Metafile;
+        outputFiles: OutputFile[];
+        initialFiles: FileInfo[];
+      }
+  > {
+    let result;
+    try {
+      if (this.#esbuildContext) {
+        // Rebuild using the existing incremental build context
+        result = await this.#esbuildContext.rebuild();
+      } else if (this.incremental) {
+        // Create an incremental build context and perform the first build.
+        // Context creation does not perform a build.
+        this.#esbuildContext = await context(this.#esbuildOptions);
+        result = await this.#esbuildContext.rebuild();
+      } else {
+        // For non-incremental builds, perform a single build
+        result = await build(this.#esbuildOptions);
+      }
+    } catch (failure) {
+      // Build failures will throw an exception which contains errors/warnings
+      if (isEsBuildFailure(failure)) {
+        return failure;
+      } else {
+        throw failure;
+      }
     }
-  } catch (failure) {
-    // Build failures will throw an exception which contains errors/warnings
-    if (isEsBuildFailure(failure)) {
-      return failure;
-    } else {
-      throw failure;
+
+    // Return if the build encountered any errors
+    if (result.errors.length) {
+      return {
+        errors: result.errors,
+        warnings: result.warnings,
+      };
     }
-  }
 
-  const initialFiles: FileInfo[] = [];
-  for (const outputFile of result.outputFiles) {
-    // Entries in the metafile are relative to the `absWorkingDir` option which is set to the workspaceRoot
-    const relativeFilePath = relative(workspaceRoot, outputFile.path);
-    const entryPoint = result.metafile?.outputs[relativeFilePath]?.entryPoint;
+    // Find all initial files
+    const initialFiles: FileInfo[] = [];
+    for (const outputFile of result.outputFiles) {
+      // Entries in the metafile are relative to the `absWorkingDir` option which is set to the workspaceRoot
+      const relativeFilePath = relative(this.workspaceRoot, outputFile.path);
+      const entryPoint = result.metafile?.outputs[relativeFilePath]?.entryPoint;
 
-    outputFile.path = relativeFilePath;
+      outputFile.path = relativeFilePath;
 
-    if (entryPoint) {
-      // An entryPoint value indicates an initial file
-      initialFiles.push({
-        file: outputFile.path,
-        // The first part of the filename is the name of file (e.g., "polyfills" for "polyfills.7S5G3MDY.js")
-        name: basename(outputFile.path).split('.')[0],
-        extension: extname(outputFile.path),
-      });
+      if (entryPoint) {
+        // An entryPoint value indicates an initial file
+        initialFiles.push({
+          file: outputFile.path,
+          // The first part of the filename is the name of file (e.g., "polyfills" for "polyfills.7S5G3MDY.js")
+          name: basename(outputFile.path).split('.')[0],
+          extension: extname(outputFile.path),
+        });
+      }
     }
+
+    // Return the successful build results
+    return { ...result, initialFiles, errors: undefined };
   }
 
-  return { ...result, initialFiles };
+  /**
+   * Disposes incremental build resources present in the context.
+   *
+   * @returns A promise that resolves when disposal is complete.
+   */
+  async dispose(): Promise<void> {
+    try {
+      return this.#esbuildContext?.dispose();
+    } finally {
+      this.#esbuildContext = undefined;
+    }
+  }
 }
 
 export async function logMessages(
   context: BuilderContext,
-  { errors, warnings }: { errors: PartialMessage[]; warnings: PartialMessage[] },
+  { errors, warnings }: { errors?: PartialMessage[]; warnings?: PartialMessage[] },
 ): Promise<void> {
-  if (warnings.length) {
+  if (warnings?.length) {
     const warningMessages = await formatMessages(warnings, { kind: 'warning', color: true });
     context.logger.warn(warningMessages.join('\n'));
   }
 
-  if (errors.length) {
+  if (errors?.length) {
     const errorMessages = await formatMessages(errors, { kind: 'error', color: true });
     context.logger.error(errorMessages.join('\n'));
   }