wip: expanding docs

Author: tegefaulkes

src/WorkerManager.ts

@@ -59,8 +59,8 @@ class WorkerManager<Manifest extends WorkerManifest> {
   }) {
     this.logger = logger;
     this.pool = new WorkerPool(cores, workerFactory);
-    this.methods = new Proxy(manifest, {
-      get: (target: Manifest, prop: string | symbol) => {
+    this.methods = new Proxy<Manifest>(manifest, {
+      get: (_, prop: string | symbol) => {
         if (typeof prop === 'symbol') return;
         return async (
           data: WorkerResult,

src/WorkerPool.ts

@@ -10,6 +10,10 @@ import { AsyncResource } from 'node:async_hooks';
 import { Subject } from 'rxjs';
 import * as errors from './errors.js';
 
+/**
+ * This defines a `WorkerTask` `AsyncResource` for tracking the life-cycle of a worker task
+ * It works with the `Node:Async_hooks` for tracking async resources.
+ */
 class WorkerTask extends AsyncResource {
   protected callback: TaskCallback;
 
@@ -27,6 +31,12 @@ class WorkerTask extends AsyncResource {
 const taskInfoSymbol = Symbol('Task Info Symbol');
 type PoolStatus = 'terminated' | 'idle' | 'working' | 'queued';
 
+/**
+ * A WorkerPool class that manages a pool of worker threads for parallel processing.
+ * This class allows tasks to be distributed among a fixed number of workers, ensuring
+ * efficient utilization of resources. It provides mechanisms to queue tasks when all workers
+ * are occupied and handles error recovery and worker recreation.
+ */
 class WorkerPool {
   protected workerFactory: WorkerFactory;
   protected workers: Set<Worker> = new Set();
@@ -45,6 +55,14 @@ class WorkerPool {
   public $poolStatus = new Subject<PoolStatus>();
   public poolStatus: PoolStatus = 'idle';
 
+  /**
+   * Constructs an instance of the Worker Pool class and initializes the specified number of workers.
+   *
+   * @param workerNum - The number of workers to be created in the pool. Must be at least 1.
+   * @param workerFactory - A factory instance responsible for creating workers.
+   * @return A Worker Pool instance initialized with the specified workers and configurations.
+   * @throws {ErrorWorkerPoolInvalidWorkers} If the value of workerNum is less than 1.
+   */
   constructor(workerNum: number, workerFactory: WorkerFactory) {
     if (workerNum < 1) throw new errors.ErrorWorkerPoolInvalidWorkers();
     this.workerFactory = workerFactory;
@@ -71,6 +89,14 @@ class WorkerPool {
     });
   }
 
+  /**
+   * Adds a new worker to the worker pool by initializing its lifecycle handlers.
+   *
+   * This method creates a worker instance using the `workerFactory`, sets up its message and error event handlers,
+   * and handles worker initialization, error propagation, task completion, and cleanup when the worker exits.
+   * The initialized worker is stored in the list of free workers upon success.
+   *
+   */
   protected addWorker() {
     const worker = this.workerFactory();
     let workerError: Error;
@@ -133,6 +159,12 @@ class WorkerPool {
     this.$workerCreated.next();
   }
 
+  /**
+   * Executes a task using an available worker. If no workers are free, the task is added to the queue.
+   *
+   * @param task - The task information to be executed by a worker, including type, data, and transfer list.
+   * @param callback - The callback function to handle the outcome of the executed task.
+   */
   public runTask(task: WorkerTaskInformation, callback: TaskCallback) {
     if (this.terminatedError != null) throw this.terminatedError;
     if (this.freeWorkers.length === 0) {
@@ -151,6 +183,12 @@ class WorkerPool {
     );
   }
 
+  /**
+   * Terminates the worker pool by stopping all workers, preventing new tasks, and cleaning up resources.
+   *
+   * @param force - Determines whether to force termination immediately (true) or wait for existing tasks to complete (false).
+   * @return A promise that resolves when all workers are terminated and resources are cleaned up.
+   */
   public async terminate(force: boolean) {
     if (this.terminatedError != null) return;
     this.terminatedError = new errors.ErrorWorkerPoolWorkerTerminated();
@@ -184,42 +222,59 @@ class WorkerPool {
   }
 
   /**
-   * Returns a promise that will resolve once all tasks have been completed.
-   * Will reject if a task failed.
+   * Returns a promise that resolves when the pool status becomes 'idle',
+   * or rejects if the pool status changes to 'terminated' or an error occurs.
+   *
+   * @return A promise that resolves when the pool is idle or rejects with an error.
    */
   public completed(): Promise<void> {
     return new Promise<void>((resolve, reject) => {
-      if (this.poolStatus === 'idle' || this.poolStatus === 'terminated') {
-        return resolve();
+      if (this.poolStatus === 'idle') return resolve();
+      if (this.poolStatus === 'terminated') {
+        return reject(this.terminatedError!);
       }
       const errorSubscription = this.$workerError.subscribe((e) => {
         errorSubscription.unsubscribe();
         stateSubscription.unsubscribe();
         reject(e);
       });
       const stateSubscription = this.$poolStatus.subscribe((v) => {
-        if (v === 'idle' || this.poolStatus === 'terminated') {
+        if (v === 'idle') {
           errorSubscription.unsubscribe();
           stateSubscription.unsubscribe();
           return resolve();
         }
+        if (v === 'terminated') {
+          errorSubscription.unsubscribe();
+          stateSubscription.unsubscribe();
+          return reject(this.terminatedError!);
+        }
       });
     });
   }
 
   /**
-   * Returns a promise that will resolve once all tasks have been completed.
+   * Returns a promise that resolves when the pool status becomes 'idle',
+   * or rejects if the pool status becomes 'terminated'.
+   *
+   * @return A promise that resolves once the pool status is 'idle',
+   * or rejects if the pool status becomes 'terminated'.
    */
   public settled(): Promise<void> {
-    return new Promise<void>((resolve) => {
-      if (this.poolStatus === 'idle' || this.poolStatus === 'terminated') {
-        return resolve();
+    return new Promise<void>((resolve, reject) => {
+      if (this.poolStatus === 'idle') return resolve();
+      if (this.poolStatus === 'terminated') {
+        return reject(this.terminatedError!);
       }
       const subscription = this.$poolStatus.subscribe((v) => {
-        if (v === 'idle' || this.poolStatus === 'terminated') {
+        if (v === 'idle') {
           subscription.unsubscribe();
           return resolve();
         }
+        if (v === 'terminated') {
+          subscription.unsubscribe();
+          return reject(this.terminatedError!);
+        }
       });
     });
   }

src/index.ts

@@ -1,2 +1,4 @@
 export { default as WorkerManager } from './WorkerManager.js';
+export { expose } from './expose.js';
 export * as errors from './errors.js';
+export * from './types.js';

src/worker.ts

@@ -1,8 +1,9 @@
-// This is an example worker script
-
 import type { WorkerManifest } from './types.js';
 import { expose } from './expose.js';
 
+/**
+ * This is an example worker script used purely for example and internal testing
+ */
 const worker = {
   test: async (): Promise<{ data: 'hello world!' }> => {
     return { data: 'hello world!' };

tests/WorkerPool.test.ts

@@ -89,8 +89,9 @@ describe('WorkerPool', () => {
         return resolve(result);
       });
     });
-    await expect(taskP).rejects.toThrow();
-    await pool.settled();
+    await expect(taskP).rejects.toThrow(errors.ErrorWorkerPoolWorkerCreationFailed);
+    await expect(pool.settled()).rejects.toThrow(errors.ErrorWorkerPoolWorkerCreationFailed);
+    await expect(pool.completed()).rejects.toThrow(errors.ErrorWorkerPoolWorkerCreationFailed);
     await pool.terminate(false);
   });
 });