time-queues 1.1.2 → 1.2.0

package/README.md

@@ -39,6 +39,7 @@ The full documentation is available in the project's [wiki](https://github.com/u
 - [Scheduler](https://github.com/uhop/time-queues/wiki/Scheduler): Time-based task scheduling
 - [Retainer](https://github.com/uhop/time-queues/wiki/Retainer): Manage resource lifecycle
 - [Throttler](https://github.com/uhop/time-queues/wiki/Throttler): Control execution rate based on keys
+- [Counter](https://github.com/uhop/time-queues/wiki/Counter): Track the number of pending tasks asynchronously
 
 ### Browser-Specific Components
 
@@ -61,6 +62,7 @@ This project is licensed under the BSD-3-Clause License.
 
 ## Release History
 
+* 1.2.0 *Added `Counter`. Updated dev dependencies.*
 * 1.1.2 *Updated dev dependencies. No need to upgrade.*
 * 1.1.1 *Updates to TS typings.*
 * 1.1.0 *Added `Throttler`, `Retainer`, promise-based convenience time methods.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "time-queues",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Time queues to organize multitasking and scheduled tasks.",
   "type": "module",
   "types": "./src/index.d.ts",
@@ -56,10 +56,10 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^22.13.10",
+    "@types/node": "^22.14.1",
     "tape-six": "^1.1.1",
     "tape-six-proc": "^1.0.1",
-    "typescript": "^5.8.2"
+    "typescript": "^5.8.3"
   },
   "dependencies": {
     "list-toolkit": "^2.2.1"

package/src/Counter.d.ts

@@ -0,0 +1,63 @@
+/**
+ * A counter that can be used to track the number of pending tasks.
+ */
+export declare class Counter {
+  /**
+   * The current count.
+   */
+  count: number;
+
+  /**
+   * Creates a new counter.
+   * @param initial The initial count. Default: 0
+   */
+  constructor(initial?: number);
+
+  /**
+   * Gets the current value of the counter.
+   * @returns The current value of the counter.
+   */
+  get value(): number;
+
+  /**
+   * Sets the counter to a specific value.
+   * @param value The new value for the counter.
+   */
+  set value(value: number): void;
+
+  /**
+   * Increments the counter.
+   */
+  increment(): void;
+
+  /**
+   * Decrements the counter.
+   */
+  decrement(): void;
+
+  /**
+   * Advances the counter by a given amount.
+   * @param amount The amount to advance. Default: 1
+   */
+  advance(amount?: number): void;
+
+  /**
+   * Waits for the counter to reach zero. If the counter is already zero, the promise is resolved immediately.
+   * @returns A promise that resolves when the counter reaches zero.
+   */
+  waitForZero(): Promise<number>;
+
+  /**
+   * Waits for the counter to reach a specific value. If the counter is already at the desired value, the promise is resolved immediately.
+   * @param fn A function that returns `true` when the counter reaches the desired value.
+   * @returns A promise that resolves when the counter reaches the desired value.
+   */
+  waitFor(fn: (count: number) => boolean): Promise<number>;
+
+  /**
+   * Clears all waiters.
+   */
+  clearWaiters(): void;
+}
+
+export default Counter;

package/src/Counter.js

@@ -0,0 +1,83 @@
+// @ts-self-types="./Counter.d.ts"
+
+'use strict';
+
+export class Counter {
+  constructor(initial = 0) {
+    this.count = initial;
+    this.zeroWaiters = [];
+    this.functionWaiters = new Set();
+  }
+
+  get value() {
+    return this.count;
+  }
+
+  set value(value) {
+    this.count = value;
+    this.notify();
+  }
+
+  increment() {
+    ++this.count;
+    this.notify();
+  }
+
+  decrement() {
+    --this.count;
+    this.notify();
+  }
+
+  advance(amount = 1) {
+    this.count += amount;
+    this.notify();
+  }
+
+  waitForZero() {
+    if (this.count === 0) return Promise.resolve(0);
+    return new Promise(resolve => this.zeroWaiters.push(resolve));
+  }
+
+  waitFor(fn) {
+    if (fn(this.count)) return Promise.resolve(this.count);
+    return new Promise(resolve => this.functionWaiters.add({fn, resolve}));
+  }
+
+  clearWaiters() {
+    if (this.zeroWaiters.length > 0) {
+      for (const resolve of this.zeroWaiters) {
+        resolve(NaN);
+      }
+      this.zeroWaiters = [];
+    }
+    if (this.functionWaiters.size > 0) {
+      for (const {resolve} of this.functionWaiters) {
+        resolve(NaN);
+      }
+      this.functionWaiters.clear();
+    }
+  }
+
+  notify() {
+    if (this.count === 0 && this.zeroWaiters.length > 0) {
+      for (const resolve of this.zeroWaiters) {
+        resolve(0);
+      }
+      this.zeroWaiters = [];
+    }
+    if (this.functionWaiters.size > 0) {
+      const ready = [];
+      for (const waiter of this.functionWaiters) {
+        if (waiter.fn(this.count)) ready.push(waiter);
+      }
+      if (ready.length > 0) {
+        for (const waiter of ready) {
+          waiter.resolve(this.count);
+          this.functionWaiters.delete(waiter);
+        }
+      }
+    }
+  }
+}
+
+export default Counter;