Bump version to v1.0.14: Improve README and documentation, update dev dependency

Author: ori88c

README.md

@@ -21,7 +21,7 @@ Each use case necessitates distinct handling capabilities, which will be discuss
 * [Getter Methods](#getter-methods)
 * [1st use-case: Multiple Jobs Execution](#first-use-case)
 * [2nd use-case: Single Job Execution](#second-use-case)
-* [Graceful Termination](#graceful-termination)
+* [Graceful Teardown](#graceful-teardown)
 * [Error Handling for Background Jobs](#error-handling)
 * [Unavoidable / Implicit Backpressure](#unavoidable-backpressure)
 * [Promise Semaphores Are Not Promise Pools](#not-promise-pool)
@@ -31,8 +31,8 @@ Each use case necessitates distinct handling capabilities, which will be discuss
 ## Key Features :sparkles:<a id="key-features"></a>
 
 - __Weighted Jobs :weight_lifting_woman:__: Suitable for situations where jobs have **varying** processing requirements, such as in backend applications managing resource load. For instance, consider multiple machine learning models being trained on a shared GPU resource. Each model demands different amounts of GPU memory and processing power. A weighted semaphore can regulate the total GPU memory usage, ensuring that only a specific combination of models is trained concurrently, thus preventing the GPU capacity from being exceeded.
-- __Backpressure Control__: Ideal for job workers and background services. Concurrency control alone isn't sufficient to ensure stability and performance if backpressure control is overlooked. Without backpressure control, the heap can become overloaded, resulting in space complexity of O(*semaphore-slots* + *pending-jobs*) instead of O(*semaphore-slots*).
-- __Graceful Termination__: Await the completion of all currently executing jobs via the `waitForAllExecutingJobsToComplete` method.
+- __Backpressure Control :vertical_traffic_light:__: Ideal for job workers and background services. Concurrency control alone isn't sufficient to ensure stability and performance if backpressure control is overlooked. Without backpressure control, the heap can become overloaded, resulting in space complexity of O(*semaphore-slots* + *pending-jobs*) instead of O(*semaphore-slots*).
+- __Graceful Teardown :hourglass_flowing_sand:__: Await the completion of all currently executing jobs via the `waitForAllExecutingJobsToComplete` method. Example use cases include **application shutdowns** (e.g., `onModuleDestroy` in Nest.js applications) or maintaining a clear state between unit-tests.
 - __High Efficiency :gear:__: All state-altering operations have a constant time complexity, O(1).
 - __Comprehensive Documentation :books:__: The class is thoroughly documented, enabling IDEs to provide helpful tooltips that enhance the coding experience.
 - __Robust Error Handling__: Uncaught errors from background jobs triggered by `startExecution` are captured and can be accessed using the `extractUncaughtErrors` method.
@@ -106,15 +106,16 @@ interface ModelInfo {
 
 const totalAllowedWeight = 180;
 const estimatedMaxNumberOfConcurrentJobs = 12;
-const trainingSemaphore = new ZeroBackpressureWeightedSemaphore<void>(
-  totalAllowedWeight,
-  estimatedMaxNumberOfConcurrentJobs // Optional argument; can reduce dynamic slot allocations for optimization purposes.
-);
 
 async function trainModels(models: AsyncGenerator<ModelInfo>) {
+  const trainingSemaphore = new ZeroBackpressureWeightedSemaphore<void>(
+    totalAllowedWeight,
+    // Optional argument; can reduce dynamic slot allocations for optimization purposes.
+    estimatedMaxNumberOfConcurrentJobs
+  );
   let fetchedModelsCounter = 0;
 
-  for (const model of models) {
+  for await (const model of models) {
     ++fetchedModelsCounter;
 
     // Until the semaphore can start training the current model, adding more
@@ -151,24 +152,32 @@ interface ModelInfo {
   // Additional model fields.
 };
 
-interface CustomModelError extends Error {
-  model: ModelInfo; // In this manner, later you can associate an error with its model.
-  // Alternatively, a custom error may contain just a few fields of interest.
+// Since errors are extracted during a post-processing phase, using a
+// custom error class allows each error to be associated with its model.
+class CustomModelError extends Error {
+  constructor(
+    message: string,
+    public readonly model: ModelInfo
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+    Object.setPrototypeOf(this, CustomModelError.prototype);
+  }
 }
 
 const totalAllowedWeight = 180;
 const estimatedMaxNumberOfConcurrentJobs = 12;
-const trainingSemaphore =
+
+async function trainModels(models: AsyncGenerator<ModelInfo>) {
   // Notice the 2nd generic parameter (Error by default).
-  new ZeroBackpressureWeightedSemaphore<void, CustomModelError>(
+  const trainingSemaphore = new ZeroBackpressureWeightedSemaphore<void, CustomModelError>(
     totalAllowedWeight,
-    estimatedMaxNumberOfConcurrentJobs // Optional argument; can reduce dynamic slot allocations for optimization purposes.
+    // Optional argument; can reduce dynamic slot allocations for optimization purposes.
+    estimatedMaxNumberOfConcurrentJobs
   );
-
-async function trainModels(models: AsyncGenerator<ModelInfo>) {
   let fetchedModelsCounter = 0;
 
-  for (const model of models) {
+  for await (const model of models) {
     ++fetchedModelsCounter;
 
     // Until the semaphore can start training the current model, adding more
@@ -253,13 +262,13 @@ app.get('/user/', async (req, res) => {
 });
 ```
 
-## Graceful Termination :hourglass:<a id="graceful-termination"></a>
+## Graceful Teardown :hourglass_flowing_sand:<a id="graceful-teardown"></a>
 
-The `waitForAllExecutingJobsToComplete` method is essential for scenarios where it is necessary to wait for all ongoing jobs to finish, such as logging a success message or executing subsequent logic. Without this built-in capability, developers would have to implement periodic polling of the semaphore or other indicators to monitor progress, which can increase both implementation complexity and resource usage.
+The `waitForAllExecutingJobsToComplete` method is essential for scenarios where it is necessary to **wait for all ongoing jobs to finish**, such as logging a success message or executing subsequent logic. Without this built-in capability, developers would have to implement periodic polling of the semaphore or other indicators to monitor progress, which can increase both implementation complexity and resource usage.
 
-A key use case for this method is ensuring stable unit tests. Each test should start with a clean state, independent of others, to avoid interference. This prevents scenarios where a job from Test A inadvertently continues to execute during Test B.
+Example use cases include application shutdowns (e.g., `onModuleDestroy` in Nest.js applications) or maintaining a clear state between unit-tests to ensure stability. Each test should start with a clean state, independent of others, to avoid interference. This prevents scenarios where a job from Test A inadvertently continues to execute during Test B.
 
-If your component has a termination method (`stop`, `terminate`, or similar), keep that in mind.
+If your component has a termination method (`stop`, `terminate`, `dispose` or similar), keep that in mind.
 
 ## Error Handling for Background Jobs :warning:<a id="error-handling"></a>
 

dist/zero-backpressure-weighted-promise-semaphore.d.ts

@@ -15,8 +15,6 @@
  */
 export type SemaphoreJob<T> = () => Promise<T>;
 /**
- * ZeroBackpressureWeightedSemaphore
- *
  * The `ZeroBackpressureWeightedSemaphore` class implements a Promise Semaphore for Node.js projects,
  * enabling users to limit the concurrency of *weighted* jobs.
  * Each job is associated with a natural-number weight (1, 2, 3, ...). The semaphore guarantees that the
@@ -70,7 +68,6 @@ export type SemaphoreJob<T> = () => Promise<T>;
  * - **Initialization**: O(estimatedMaxNumberOfConcurrentJobs) for both time and space.
  * - **startExecution, waitForCompletion**: O(1) for both time and space, excluding the job execution itself.
  * - All the getter methods have O(1) complexity for both time and space.
- *
  */
 export declare class ZeroBackpressureWeightedSemaphore<T = void, UncaughtErrorType = Error> {
     private readonly _totalAllowedWeight;
@@ -83,36 +80,26 @@ export declare class ZeroBackpressureWeightedSemaphore<T = void, UncaughtErrorTy
     private _waitForSufficientWeight?;
     private _notifyPendingAllotment?;
     /**
-     * Constructor
-     *
-     * @param totalAllowedWeight - The maximum allowed sum of weights (inclusive) for jobs executed concurrently.
-     * @param estimatedMaxNumberOfConcurrentJobs - Estimated maximum number of concurrently executing jobs.
-     *                                             A higher estimate reduces the likelihood of additional slot
-     *                                             allocations during runtime. Please observe that the upper bound
-     *                                             is `totalAllowedWeight`, as the minimum weight is 1.
+     * @param totalAllowedWeight The maximum allowed sum of weights (inclusive) for jobs executed concurrently.
+     * @param estimatedMaxNumberOfConcurrentJobs Estimated maximum number of concurrently executing jobs.
+     *                                           A higher estimate reduces the likelihood of additional slot
+     *                                           allocations during runtime. Please observe that the upper bound
+     *                                           is `totalAllowedWeight`, as the minimum weight is 1.
      */
     constructor(totalAllowedWeight: number, estimatedMaxNumberOfConcurrentJobs?: number);
     /**
-     * totalAllowedWeight
-     *
      * @returns The maximum allowed sum of weights (inclusive) for jobs executed concurrently.
      */
     get totalAllowedWeight(): number;
     /**
-     * availableWeight
-     *
      * @returns The currently available, non-allotted amount of weight.
      */
     get availableWeight(): number;
     /**
-     * amountOfCurrentlyExecutingJobs
-     *
      * @returns The number of jobs currently being executed by the semaphore.
      */
     get amountOfCurrentlyExecutingJobs(): number;
     /**
-     * amountOfUncaughtErrors
-     *
      * Indicates the number of uncaught errors from background jobs triggered by `startExecution`,
      * that are currently stored by the instance.
      * These errors have not yet been extracted using `extractUncaughtErrors`.
@@ -124,8 +111,6 @@ export declare class ZeroBackpressureWeightedSemaphore<T = void, UncaughtErrorTy
      */
     get amountOfUncaughtErrors(): number;
     /**
-     * startExecution
-     *
      * This method resolves once the given job has *started* its execution, indicating that the
      * semaphore has allotted sufficient weight for the job.
      * Users can leverage this to prevent backpressure of pending jobs:
@@ -145,15 +130,13 @@ export declare class ZeroBackpressureWeightedSemaphore<T = void, UncaughtErrorTy
      * `extractUncaughtError` method. Users are encouraged to specify a custom `UncaughtErrorType`
      * generic parameter to the class if jobs may throw errors.
      *
-     * @param backgroundJob - The job to be executed once the semaphore is available.
-     * @param weight - A natural number representing the weight associated with the job.
-     * @throws - Error if the weight is not a natural number (1, 2, 3, ...).
+     * @param backgroundJob The job to be executed once the semaphore is available.
+     * @param weight A natural number representing the weight associated with the job.
+     * @throws Error if the weight is not a natural number (1, 2, 3, ...).
      * @returns A promise that resolves when the job starts execution.
      */
     startExecution(backgroundJob: SemaphoreJob<T>, weight: number): Promise<void>;
     /**
-     * waitForCompletion
-     *
      * This method executes the given job in a controlled manner, once the semaphore has allotted
      * sufficient weight for the job. It resolves or rejects when the job finishes execution, returning
      * the job's value or propagating any error it may throw.
@@ -167,16 +150,14 @@ export declare class ZeroBackpressureWeightedSemaphore<T = void, UncaughtErrorTy
      * This method allows you to execute the job with controlled concurrency. Once the job resolves
      * or rejects, you can continue the route handler's flow based on the result.
      *
-     * @param job - The job to be executed once the semaphore is available.
-     * @param weight - A natural number representing the weight associated with the job.
-     * @throws - Error if the weight is not a natural number (1, 2, 3, ...).
-     *           Alternatively, an error thrown by the job itself.
+     * @param job The job to be executed once the semaphore is available.
+     * @param weight A natural number representing the weight associated with the job.
+     * @throws Error if the weight is not a natural number (1, 2, 3, ...).
+     *         Alternatively, an error thrown by the job itself.
      * @returns A promise that resolves with the job's return value or rejects with its error.
      */
     waitForCompletion(job: SemaphoreJob<T>, weight: number): Promise<T>;
     /**
-     * waitForAllExecutingJobsToComplete
-     *
      * This method allows the caller to wait until all *currently* executing jobs have finished,
      * meaning once all running promises have either resolved or rejected.
      *
@@ -186,13 +167,18 @@ export declare class ZeroBackpressureWeightedSemaphore<T = void, UncaughtErrorTy
      * Note that the returned promise only awaits jobs that were executed at the time this method
      * was called. Specifically, it awaits all jobs initiated by this instance that had not completed
      * at the time of invocation.
+     * In certain scenarios - such as during application shutdown - you might also want to wait for
+     * any potentially pending jobs. This can be achieved using the following pattern:
+     * ```
+     * while (semaphore.amountOfCurrentlyExecutingJobs > 0) {
+     *   await semaphore.waitForAllExecutingJobsToComplete();
+     * }
+     * ```
      *
      * @returns A promise that resolves when all currently executing jobs are completed.
      */
     waitForAllExecutingJobsToComplete(): Promise<void>;
     /**
-     * extractUncaughtErrors
-     *
      * This method returns an array of uncaught errors, captured by the semaphore while executing
      * background jobs added by `startExecution`. The term `extract` implies that the semaphore
      * instance will no longer hold these error references once extracted, unlike `get`. In other
@@ -214,8 +200,6 @@ export declare class ZeroBackpressureWeightedSemaphore<T = void, UncaughtErrorTy
     private _allotWeight;
     private _getAvailableSlot;
     /**
-     * _handleJobExecution
-     *
      * This method manages the execution of a given job in a controlled manner. It ensures that
      * the job is executed within the constraints of the semaphore and handles updating the
      * internal state once the job has completed.
@@ -225,12 +209,12 @@ export declare class ZeroBackpressureWeightedSemaphore<T = void, UncaughtErrorTy
      * - Updates the internal state to make the allotted slot available again once the job is finished.
      * - Release the weight-allotment lock if the requested amount is available.
      *
-     * @param job - The job to be executed in the given slot.
-     * @param allottedSlot - The slot number in which the job should be executed.
-     * @param weight - A natural number representing the weight associated with the job.
-     * @param isBackgroundJob - A flag indicating whether the caller expects a return value to proceed
-     *                          with its work. If `true`, no return value is expected, and any error
-     *                          thrown by the job should not be propagated to the event loop.
+     * @param job The job to be executed in the given slot.
+     * @param allottedSlot The slot number in which the job should be executed.
+     * @param weight A natural number representing the weight associated with the job.
+     * @param isBackgroundJob A flag indicating whether the caller expects a return value to proceed
+     *                        with its work. If `true`, no return value is expected, and any error
+     *                        thrown by the job should not be propagated to the event loop.
      * @returns A promise that resolves with the job's return value or rejects with its error.
      *          Rejection occurs only if triggered by `waitForCompletion`.
      */