Merge pull request #17 from NoTaskStudios/feature/hub-event-emitter

Feature/hub event emitter

Author: MtMath

README.md

@@ -69,6 +69,34 @@ await UnityHub.addEditor("2022.3.60f1", undefined, [UnityModules.AndroidBuildSup
 await UnityHub.addModule("2022.3.60f1", [UnityModules.IOSBuildSupport]);
 ```
 
+### Installation Events
+
+```typescript
+import { UnityHub, UnityModules, InstallerEventType } from "unity-cli-tools";
+
+// Install with event tracking (addEditor returns an event emitter)
+const installer = await UnityHub.addEditor("2022.3.60f1");
+
+// Get a promise that resolves when installation completes
+const installation = installer.completed;
+
+// Or listen to specific events
+installer.on(InstallerEventType.Progress, (events) => {
+  console.log("Progress:", events.map(e => `${e.module}: ${e.status} ${e.progress || 0}%`));
+});
+
+installer.on(InstallerEventType.Error, (error) => {
+  console.error("Installation error:", error);
+});
+
+installer.on(InstallerEventType.Completed, (events) => {
+  console.log("Installation completed!");
+});
+
+// Cancel installation if needed
+installer.Cancel();
+```
+
 ### Projects Management
 
 ```typescript
@@ -225,6 +253,30 @@ console.log(executionResult);
 | `ChineseTraditional` | Traditional Chinese language pack |
 | `Chinese`            | Chinese language pack (legacy)    |
 
+### InstallerStatus
+
+| Constant           | Description                     |
+| ------------------ | ------------------------------- |
+| `Queued`           | Queued for download            |
+| `Validating`       | Validating download            |
+| `InProgress`       | Installation in progress       |
+| `Downloading`      | Downloading installation files |
+| `QueuedInstall`    | Queued for install            |
+| `ValidatingInstall`| Validating installation        |
+| `Installing`       | Installing                     |
+| `Verifying`        | Verifying installation         |
+| `Installed`        | Installed successfully         |
+| `Error`            | Installation error             |
+
+### InstallerEventType
+
+| Constant     | Description                                 |
+| ------------ | ------------------------------------------- |
+| `Progress`   | Installation progress update event          |
+| `Error`      | Installation error event                    |
+| `Completed`  | Installation completed successfully event   |
+| `Cancelled`  | Installation cancelled by user event        |
+
 
 ## Configuration
 

src/events/hubEventEmitter.ts

@@ -0,0 +1,83 @@
+import { EventEmitter } from "events";
+import { InstallerEventType, InstallerEvent, InstallerStatus } from "../types/unity.ts";
+import { UnityHubEventParser } from "./hubEventParser.ts";
+
+export interface InstallerEmitter extends EventEmitter {
+  on(event: InstallerEventType.Progress, listener: (info: InstallerEvent[]) => void): this;
+  on(event: InstallerEventType.Error, listener: (error: Error) => void): this;
+  on(event: InstallerEventType.Completed, listener: (info: InstallerEvent[]) => void): this;
+  on(event: InstallerEventType.Cancelled, listener: (info: InstallerEvent[]) => void): this;
+  emit(event: InstallerEventType.Progress, info: InstallerEvent[]): boolean;
+  emit(event: InstallerEventType.Error, info: InstallerEvent[]): boolean;
+  emit(event: InstallerEventType.Completed, info: InstallerEvent[]): boolean;
+  emit(event: InstallerEventType.Cancelled, info: InstallerEvent[]): boolean;
+
+  readonly completed: Promise<InstallerEvent[]>;
+}
+
+export class UnityHubInstallerEvent extends EventEmitter implements InstallerEmitter {
+  #moduleTracker: Map<string, InstallerStatus> = new Map();
+
+  public constructor() {
+    super();
+  }
+
+  public completed: Promise<InstallerEvent[]> = new Promise((resolve, reject) => {
+    this.on(InstallerEventType.Completed, (events) => resolve(events));
+    this.on(InstallerEventType.Error, (error) => reject(error));
+    this.on(InstallerEventType.Cancelled, (events) => reject(new Error("Cancelled")));
+  });
+
+  /**
+   * Parses the raw event string and emits the appropriate event.
+   * @param raw - The raw event string from Unity Hub.
+   * @returns {void}
+   */
+  public Progress(raw: string): void {
+    const events = UnityHubEventParser.parseUnityHubEvent(raw);
+    if (events.length === 0) return;
+
+    this.#Error(events);
+
+    const progressEvents = events.filter((e) => e.status !== InstallerStatus.Error);
+
+    if (progressEvents.length === 0) return;
+    this.emit(InstallerEventType.Progress, progressEvents);
+    this.#updateModuleTracker(events);
+    this.#Complete(progressEvents);
+  }
+
+  #Error(events: InstallerEvent[]): void {
+    const errorEvents = events.filter((e) => e.status === InstallerStatus.Error);
+
+    if (errorEvents.length === 0) return;
+    this.emit(InstallerEventType.Error, errorEvents);
+  }
+
+  #Complete(events: InstallerEvent[]): void {
+    const installed = events.filter((e) => e.status === InstallerStatus.Installed);
+    if (installed.length > 0 && installed.length === events.length) {
+      this.emit(InstallerEventType.Completed, installed);
+    }
+  }
+
+  /**
+   * Emits a cancelled event.
+   * @returns {void}
+   */
+  public Cancel(): void {
+    //Cancel operation
+    this.#moduleTracker.clear();
+    this.#Cancelled([]);
+  }
+
+  #Cancelled(event: InstallerEvent[]): void {
+    this.emit(InstallerEventType.Cancelled, event);
+  }
+
+  #updateModuleTracker(events: InstallerEvent[]): void {
+    for (const event of events) {
+      this.#moduleTracker.set(event.module, event.status);
+    }
+  }
+}

src/events/hubEventParser.ts

@@ -0,0 +1,47 @@
+import { InstallerEvent, InstallerStatus } from "../types/unity.ts";
+
+export class UnityHubEventParser {
+  private static errorPatterns = [/Error:.*/];
+
+  public static parseUnityHubEvent(event: string): InstallerEvent[] {
+    const events: InstallerEvent[] = [];
+    const lines = event.split("\n");
+
+    for (const line of lines) {
+      const errorLine = this.checkForErrors(line);
+      if (errorLine) {
+        events.push(errorLine);
+        continue;
+      }
+    }
+
+    const pattern = /^\[(?<module>[^\]]+)\]\s+(?<status>.+?)(?:(?:\s+(?<progress>\d+(?:\.\d+)?))%)?\.*$/;
+
+    for (const line of lines) {
+      const match = line.match(pattern);
+      if (match?.groups) {
+        const { module, status, progress } = match.groups;
+        events.push({
+          module: module.trim(),
+          status: status.replace(/\.\.\.$/, "").trim() as InstallerStatus,
+          progress: progress ? parseFloat(progress) : status !== InstallerStatus.Downloading ? null : 0,
+        });
+      }
+    }
+
+    return events;
+  }
+
+  private static checkForErrors(line: string): InstallerEvent | null {
+    for (const pattern of this.errorPatterns) {
+      if (pattern.test(line)) {
+        return {
+          module: "UnityHub",
+          status: InstallerStatus.Error,
+          error: line.trim(),
+        };
+      }
+    }
+    return null;
+  }
+}

src/types/unity.ts

@@ -220,3 +220,42 @@ export enum UnityBuildTarget {
   /** VisionOS build target */
   VisionOS = "VisionOS",
 }
+
+/**
+ * Enum for Unity installation statuses
+ * These values correspond to the different states of a Unity installation process
+ */
+export enum InstallerStatus {
+  Queued = "queued for download",
+  Validating = "validating download",
+  InProgress = "in progress",
+  Downloading = "downloading",
+  QueuedInstall = "queued for install",
+  ValidatingInstall = "validation installation",
+  Installing = "installing",
+  Verifying = "verifying",
+  Installed = "installed successfully",
+  Error = "Error",
+}
+
+/**
+ * Interface representing an installer event
+ * Contains information about the status of a module installation process
+ */
+export interface InstallerEvent {
+  module: string;
+  status: InstallerStatus;
+  progress?: number | null;
+  error?: string | null;
+}
+
+/**
+ * Enum for installer event types
+ * These values correspond to the different types of events that can occur during the installation process
+ */
+export enum InstallerEventType {
+  Progress = "progress",
+  Error = "error",
+  Completed = "completed",
+  Cancelled = "cancelled",
+}

src/unityHub.ts

@@ -10,6 +10,7 @@ import {
 } from "./types/unity.js";
 import { CommandOptions, CommandResult, executeCommand } from "./utils/commandExecutor.js";
 import { getUnityChangeset } from "unity-changeset";
+import { UnityHubInstallerEvent } from "./events/hubEventEmitter.ts";
 
 /**
  * Class for interacting with Unity Hub via command line interface
@@ -210,15 +211,15 @@ class UnityHub {
    * @param {string} editorVersion - Unity version to add modules to (e.g. "2022.3.60f1")
    * @param {ModuleId[]} modules - Array of module IDs to add
    * @param {boolean} [childModules=false] - Whether to include child modules
-   * @returns {Promise<void>} Resolves when modules are added successfully
+   * @returns {UnityHubInstallerEvent} Event emitter for installation progress
    * @throws Will throw an error if module addition fails
    * @public
    */
   public static async addModule(
     editorVersion: string,
     modules: ModuleId[],
     childModules: boolean = true
-  ): Promise<void> {
+  ): Promise<UnityHubInstallerEvent> {
     try {
       console.debug(`Adding module ${modules} to Unity ${editorVersion}`);
 
@@ -234,19 +235,15 @@ class UnityHub {
         throw new Error("No module IDs provided.");
       }
 
-      const { stderr } = await this.execUnityHubCommand(args, {
+      const installerEmitter = new UnityHubInstallerEvent();
+      this.execUnityHubCommand(args, {
         reject: false,
-        onStderr: (data: string) => {
-          console.warn(`Unity Hub stderr: ${data}`);
-        },
-        onStdout: (data: string) => {
-          console.debug(`Unity Hub stdout: ${data}`);
-        },
+        //onStderr: (data: string) => installerEmitter.Progress(data),
+        onStdout: (data: string) => installerEmitter.Progress(data),
+      }).catch((error) => {
+        console.error(`Error adding module ${modules} to Unity ${editorVersion}:`, error);
       });
-
-      if (stderr) {
-        console.warn(`Add module command warning/error: ${stderr}`);
-      }
+      return installerEmitter;
     } catch (error) {
       console.error(`Error adding module ${modules} to Unity ${editorVersion}:`, error);
       throw error;
@@ -259,15 +256,15 @@ class UnityHub {
    * @param {string} [changeset] - Optional specific changeset to install
    * @param {ModuleId[]} [modules=[]] - Optional array of modules to install with the editor
    * @param {EditorArchitecture} [architecture=EditorArchitecture.x86_64] - Optional architecture (x86_64 or arm64)
-   * @returns {Promise<void>} Resolves when editor installation begins successfully
+   * @returns {UnityHubInstallerEvent} Event emitter for installation progress
    * @throws Will throw an error if installation fails to start
    * @public
    */
   public static async addEditor(
     version: string,
     modules: ModuleId[] = [],
     architecture?: EditorArchitecture
-  ): Promise<void> {
+  ): Promise<UnityHubInstallerEvent> {
     try {
       const data = await getUnityChangeset(version);
       const args = ["install", "-v", version];
@@ -288,21 +285,16 @@ class UnityHub {
 
       args.push("--architecture", architecture);
 
-      const { stdout, stderr } = await this.execUnityHubCommand(args, {
+      const installerEmitter = new UnityHubInstallerEvent();
+      this.execUnityHubCommand(args, {
         reject: false,
-        onStderr: (data: string) => {
-          console.warn(`Unity Hub stderr: ${data}`);
-        },
-        onStdout: (data: string) => {
-          console.debug(`Unity Hub stdout: ${data}`);
-        },
+        //onStderr: (data: string) => installerEmitter.Error(data),
+        onStdout: (data: string) => installerEmitter.Progress(data),
+      }).catch((error) => {
+        console.error(`Error installing Unity ${version}:`, error);
       });
 
-      if (stderr) {
-        throw new Error(`Error installing Unity ${version}: ${stderr}`);
-      }
-
-      console.debug(`Unity ${version}. ${stdout}`);
+      return installerEmitter;
     } catch (error) {
       console.error(error);
       throw error;