wip: expanded docs

Author: tegefaulkes

src/WorkerManager.ts

@@ -6,19 +6,18 @@ import { type WorkerTaskInformation } from './types.js';
 import * as errors from './errors.js';
 import WorkerPool from './WorkerPool.js';
 
+// TODO: events
 @CreateDestroy()
 class WorkerManager<Manifest extends WorkerManifest> {
   /**
-   * Creates the WorkerManager
-   * The workerFactory needs to be a callback:
-   * `() => spawn(new Worker(workerPath))`
-   * The `spawn` and `Worker` can be imported from `threads`
-   * The `workerPath` must point to a worker script
-   * The `workerPath` can be either an absolute path or relative path
-   * If it is a relative path, it has to be relative to the file location where
-   * the function expression is defined
-   * If `cores` is set to 0, this creates a useless worker pool
-   * Use `undefined` to mean using all cores
+   * Creates and initializes a new instance of WorkerManager.
+   *
+   * @param options - The configuration options for the WorkerManager.
+   * @param options.workerFactory - The factory for creating workers.
+   * @param options.manifest - The manifest defining the worker capabilities and operations.
+   * @param [options.cores=1] - The number of cores to allocate for workers. Defaults to 1.
+   * @param [options.logger=new Logger(this.name)] - An optional logger instance for logging activities. Defaults to a new logger.
+   * @return {Promise<WorkerManager<Manifest>>} A promise that resolves to a new WorkerManager instance.
    */
   public static async createWorkerManager<Manifest extends WorkerManifest>({
     workerFactory,
@@ -44,8 +43,21 @@ class WorkerManager<Manifest extends WorkerManifest> {
 
   protected pool: WorkerPool;
   protected logger: Logger;
+  /**
+   * Methods exposes a fully typed interface for making calls using workers.
+   * It provides all the available methods provided by the manifest with proper types applied.
+   */
   public methods: Manifest;
 
+  /**
+   * Constructs a new instance of the class using the provided parameters.
+   *
+   * @param config - The configuration for the constructor.
+   * @param config.workerFactory - The factory for creating worker instances.
+   * @param config.manifest - The manifest containing method definitions.
+   * @param config.cores - The number of cores to allocate for the worker pool.
+   * @param config.logger - The logger instance for logging messages.
+   */
   public constructor({
     workerFactory,
     manifest,
@@ -74,6 +86,13 @@ class WorkerManager<Manifest extends WorkerManifest> {
     });
   }
 
+  /**
+   * Destroys the WorkerManager instance and terminates its associated pool.
+   *
+   * @param [params={}] - An optional configuration object.
+   * @param [params.force=false] - Indicates whether to forcefully terminate the pool.
+   * @return A promise that resolves when the destruction process is complete.
+   */
   public async destroy({
     force = false,
   }: { force?: boolean } = {}): Promise<void> {
@@ -82,11 +101,23 @@ class WorkerManager<Manifest extends WorkerManifest> {
     this.logger.info('Destroyed WorkerManager');
   }
 
+  /**
+   * Processes a worker task by enqueuing it for execution.
+   *
+   * @param task - The information about the worker task to be executed.
+   * @return A promise that resolves with the result of the worker task execution.
+   */
   @ready(new errors.ErrorWorkerManagerDestroyed())
   public async call(task: WorkerTaskInformation): Promise<WorkerResult> {
     return await this.queue(task);
   }
 
+  /**
+   * Enqueues a task to be processed by the worker pool.
+   *
+   * @param task - The task to be processed by the worker pool.
+   * @return A promise that resolves with the result of the task or rejects with an error if the task fails or cannot be processed.
+   */
   @ready(new errors.ErrorWorkerManagerDestroyed())
   public queue(task: WorkerTaskInformation): Promise<WorkerResult> {
     return new Promise((resolve, reject) => {
@@ -97,11 +128,24 @@ class WorkerManager<Manifest extends WorkerManifest> {
     });
   }
 
+  /**
+   * 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.
+   */
   @ready(new errors.ErrorWorkerManagerDestroyed())
   public async completed(): Promise<void> {
     return await this.pool.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'.
+   */
   @ready(new errors.ErrorWorkerManagerDestroyed())
   public async settled() {
     return await this.pool.settled();

src/expose.ts

@@ -7,9 +7,10 @@ import { isMainThread, parentPort } from 'node:worker_threads';
 import * as workerErrors from './errors.js';
 
 /**
- * Call inside a worker to set it up and expose the supported worker functions.
- * Calling this within the main thread will do nothing
- * @param workerManifest
+ * Exposes a worker's handlers for processing tasks received from the parent thread.
+ * This can be called within the main thread however it will do nothing.
+ *
+ * @param workerManifest - An object containing the methods that the worker can handle.
  */
 function expose(workerManifest: WorkerManifest) {
   // We don't want to run this in the main thread since it's not acting as a worker

tests/WorkerPool.test.ts

@@ -89,9 +89,15 @@ describe('WorkerPool', () => {
         return resolve(result);
       });
     });
-    await expect(taskP).rejects.toThrow(errors.ErrorWorkerPoolWorkerCreationFailed);
-    await expect(pool.settled()).rejects.toThrow(errors.ErrorWorkerPoolWorkerCreationFailed);
-    await expect(pool.completed()).rejects.toThrow(errors.ErrorWorkerPoolWorkerCreationFailed);
+    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);
   });
 });