refactor(@angular-devkit/build-angular): maintain experimental public API for karma builder

Adds an `executeKarmaBuilder` wrapper function in the package entry point
that returns an RxJS `Observable`. This maintains backward compatibility
for the experimental public API while the internal implementation has been
migrated to use `AsyncIterable`.

Author: clydin

goldens/public-api/angular_devkit/build_angular/index.api.md

@@ -49,7 +49,7 @@ export type BrowserBuilderOptions = {
     i18nDuplicateTranslation?: I18NTranslation;
     i18nMissingTranslation?: I18NTranslation;
     index: IndexUnion;
-    inlineStyleLanguage?: InlineStyleLanguage;
+    inlineStyleLanguage?: InlineStyleLanguage_2;
     localize?: Localize;
     main: string;
     namedChunks?: boolean;
@@ -58,16 +58,16 @@ export type BrowserBuilderOptions = {
     outputHashing?: OutputHashing;
     outputPath: string;
     poll?: number;
-    polyfills?: Polyfills;
+    polyfills?: Polyfills_2;
     preserveSymlinks?: boolean;
     progress?: boolean;
     resourcesOutputPath?: string;
-    scripts?: ScriptElement[];
+    scripts?: ScriptElement_2[];
     serviceWorker?: boolean;
     sourceMap?: SourceMapUnion;
     statsJson?: boolean;
     stylePreprocessorOptions?: StylePreprocessorOptions;
-    styles?: StyleElement[];
+    styles?: StyleElement_2[];
     subresourceIntegrity?: boolean;
     tsConfig: string;
     vendorChunk?: boolean;
@@ -216,18 +216,18 @@ export type KarmaBuilderOptions = {
     exclude?: string[];
     fileReplacements?: FileReplacement_2[];
     include?: string[];
-    inlineStyleLanguage?: InlineStyleLanguage_2;
+    inlineStyleLanguage?: InlineStyleLanguage;
     karmaConfig?: string;
     main?: string;
     poll?: number;
-    polyfills?: Polyfills_2;
+    polyfills?: Polyfills;
     preserveSymlinks?: boolean;
     progress?: boolean;
     reporters?: string[];
-    scripts?: ScriptElement_2[];
+    scripts?: ScriptElement[];
     sourceMap?: SourceMapUnion_2;
     stylePreprocessorOptions?: StylePreprocessorOptions_2;
-    styles?: StyleElement_2[];
+    styles?: StyleElement[];
     tsConfig: string;
     watch?: boolean;
     webWorkerTsConfig?: string;

packages/angular_devkit/build_angular/src/builders/karma/index.ts

@@ -171,7 +171,6 @@ function getBuiltInKarmaConfig(
 export type { KarmaBuilderOptions };
 export default createBuilder<KarmaBuilderOptions>(execute);
 
-
 async function checkForEsbuild(
   options: KarmaBuilderOptions,
   context: BuilderContext,

packages/angular_devkit/build_angular/src/index.ts

@@ -6,6 +6,15 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import type { BuilderContext, BuilderOutput } from '@angular-devkit/architect';
+import { type Observable, from } from 'rxjs';
+import {
+  type KarmaBuilderOptions,
+  type KarmaConfigOptions,
+  execute as executeKarmaBuilderInternal,
+} from './builders/karma';
+import type { ExecutionTransformer } from './transforms';
+
 export * from './transforms';
 
 export { CrossOrigin, OutputHashing, Type } from './builders/browser/schema';
@@ -40,11 +49,21 @@ export {
   type ExtractI18nBuilderOptions,
 } from './builders/extract-i18n';
 
-export {
-  execute as executeKarmaBuilder,
-  type KarmaBuilderOptions,
-  type KarmaConfigOptions,
-} from './builders/karma';
+/**
+ * @experimental Direct usage of this function is considered experimental.
+ */
+export function executeKarmaBuilder(
+  options: KarmaBuilderOptions,
+  context: BuilderContext,
+  transforms?: {
+    webpackConfiguration?: ExecutionTransformer<import('webpack').Configuration>;
+    karmaOptions?: (options: KarmaConfigOptions) => KarmaConfigOptions;
+  },
+): Observable<BuilderOutput> {
+  return from(executeKarmaBuilderInternal(options, context, transforms));
+}
+
+export { type KarmaBuilderOptions, type KarmaConfigOptions };
 
 export {
   execute as executeProtractorBuilder,