Bump version to v1.2.0: Adding a new method waitForAvailability

Author: ori88c

README.md

@@ -145,8 +145,8 @@ async function handleDataAggregation(sensorUID): Promise<void> {
 }
 ```
 
-Please note that in a real-world scenario, sensor UIDs are more likely to be consumed from a message queue (e.g., RabbitMQ, Kafka, AWS SNS) rather than from an in-memory array. This setup **highlights the benefits** of avoiding backpressure:  
-We should avoid consuming a message if we cannot start processing it immediately. Working with message queues typically involves acknowledgements, which have timeout mechanisms. Therefore, immediate processing is crucial to ensure efficient and reliable handling of messages.  
+Please note that in a real-world scenario, sensor UIDs may be consumed from a message queue (e.g., RabbitMQ, Kafka, AWS SNS) rather than from an in-memory array. This setup **highlights the benefits** of avoiding backpressure:  
+We should avoid consuming a message if we cannot start processing it immediately. Working with message queues typically involves acknowledgements, which have **timeout** mechanisms. Therefore, immediate processing is crucial to ensure efficient and reliable handling of messages. The `waitForAvailability` method addresses this need by checking availability as a preliminary action before consuming a message.  
 Refer to the following adaptation of the previous example, where sensor UIDs are consumed from a message queue. This example overlooks error handling and message validation, for simplicity.
 
 ```ts
@@ -165,6 +165,7 @@ async function processConsumedMessages(): Promise<void> {
   let numberOfProcessedMessages = 0;
 
   do {
+    await sensorAggregationSemaphore.waitForAvailability();
     const message = await mqClient.receiveOneMessage();
     if (!message) {
       // Consider the queue as empty.
@@ -173,6 +174,9 @@ async function processConsumedMessages(): Promise<void> {
 
     ++numberOfProcessedMessages;
     const { uid } = message.data;
+
+    // At this point, `startExecution` will begin immediately, due to the
+    // preliminary `waitForAvailability` action.
     await sensorAggregationSemaphore.startExecution(
       (): Promise<void> => handleDataAggregation(uid);
     );
@@ -200,6 +204,9 @@ async function processConsumedMessages(): Promise<void> {
 }
 ```
 
+In reference to the above example, please note that `waitForAvailability` may be considered overkill or redundant if the job's duration is significantly shorter than the message timeout.  
+For example, if the message queue's timeout for acknowledging a message is 1 minute and a typical job duration is 1 second, the 59 second gap provides a substantial safety margin. In such cases, the preliminary `waitForAvailability` action can be omitted.
+
 ## 2nd use-case: Single Job Execution
 
 The `waitForCompletion` method is useful for executing a sub-procedure, for which the caller must wait before proceeding with its work.

dist/zero-backpressure-semaphore.d.ts

@@ -126,6 +126,26 @@ export declare class ZeroBackpressureSemaphore<T, UncaughtErrorType = Error> {
      * @returns A promise that resolves when all currently executing jobs are settled.
      */
     waitTillAllExecutingJobsAreSettled(): Promise<void>;
+    /**
+     * waitForAvailability
+     *
+     * This method resolves once at least one room (slot) is available for job execution.
+     * In other words, it resolves when the semaphore is available to trigger a new job immediately.
+     *
+     * ### Example Use Case
+     * Consider a scenario where we read messages from a message queue (e.g., RabbitMQ, Kafka).
+     * Each message contains job-specific metadata, meaning for each message, we want to create a
+     * corresponding semaphore job. We aim to start processing a message immediately once it is
+     * consumed, as message queues typically involve *acknowledgements*, which have *timeout*
+     * mechanisms. Therefore, immediate processing is crucial to ensure efficient and reliable
+     * handling of messages. Backpressure on the semaphore may cause messages to wait too long
+     * before their corresponding job starts, increasing the chances of their timeout being exceeded.
+     * To prevent such potential backpressure, users can utilize the `waitForAvailability` method
+     * before consuming the next message.
+     *
+     * @returns A promise that resolves once at least one room is available.
+     */
+    waitForAvailability(): Promise<void>;
     /**
      * extractUncaughtErrors
      *