@gkucmierz/utils 4.0.2 → 4.1.1

package/README.md

@@ -1,9 +1,11 @@
 # @gkucmierz/utils
 
-[![Socket Badge](https://socket.dev/api/badge/npm/package/@gkucmierz/utils)](https://socket.dev/npm/package/@gkucmierz/utils)
-![NPM Version](https://img.shields.io/npm/v/@gkucmierz/utils)
-![License](https://img.shields.io/npm/l/@gkucmierz/utils)
-![Downloads](https://img.shields.io/npm/dm/@gkucmierz/utils)
+[![NPM Version](https://img.shields.io/npm/v/@gkucmierz/utils?color=3b82f6&logo=npm)](https://www.npmjs.com/package/@gkucmierz/utils)
+[![Socket Security](https://img.shields.io/badge/Security-Socket.dev-7036fe?logo=socket&logoColor=white)](https://socket.dev/npm/package/@gkucmierz/utils)
+[![Tests](https://img.shields.io/badge/Tests-153%20passed-22c55e?logo=jasmine&logoColor=white)](https://gitea.7u.pl/gkucmierz/utils)
+[![Downloads](https://img.shields.io/npm/dm/@gkucmierz/utils?color=8b5cf6)](https://www.npmjs.com/package/@gkucmierz/utils)
+[![License](https://img.shields.io/npm/l/@gkucmierz/utils?color=f59e0b)](https://gitea.7u.pl/gkucmierz/utils)
+[![Node Version](https://img.shields.io/node/v/@gkucmierz/utils?color=43853d&logo=node.js&logoColor=white)](https://nodejs.org)
 
 A collection of useful utility functions and data structures for solving algorithmic tasks, competitive programming, and everyday development.
 
@@ -24,6 +26,7 @@ This library provides a wide range of mathematical functions and data structures
   - `bin2gray`, `gray2bin`: Pure array-cloning bit formatters for Gray code translations.
 
 - **Data Structures**:
+  - `ConflatingQueue`: Asynchronous coalescing work queue with key-based deduplication and controllable concurrency (`class`).
   - `SetCnt`: A set-like structure with element counting (`class`).
   - `Trie`: Efficient prefix tree implementation (`class`).
   - `Heap`: Min-heap priority queue (`class`).
@@ -78,8 +81,8 @@ This library provides a wide range of mathematical functions and data structures
 
 ## 📚 Documentation
 
-Full API documentation with examples is available at:
-👉 **[https://gkucmierz.github.io/utils](https://gkucmierz.github.io/utils)**
+- **Production Docs**: 👉 **[https://docs-utils.7u.pl](https://docs-utils.7u.pl)**
+- **GitHub Pages Mirror**: [https://gkucmierz.github.io/utils](https://gkucmierz.github.io/utils)
 
 ## 🔗 Repository
 - **Internal Gitea**: [https://gitea.7u.pl/gkucmierz/utils](https://gitea.7u.pl/gkucmierz/utils)

package/main.mjs

@@ -14,6 +14,9 @@ import {
 import {
   permutations, permutationsIterator
 } from './src/combinatorics/permutations.mjs'
+import {
+  ConflatingQueue
+} from './src/data-structures/ConflatingQueue.mjs'
 import {
   SetCnt
 } from './src/data-structures/SetCnt.mjs'
@@ -137,6 +140,7 @@ export * from './src/combinatorics/combinations.mjs';
 export * from './src/combinatorics/gray-code.mjs';
 export * from './src/combinatorics/n-choose-k.mjs';
 export * from './src/combinatorics/permutations.mjs';
+export * from './src/data-structures/ConflatingQueue.mjs';
 export * from './src/data-structures/SetCnt.mjs';
 export * from './src/data-structures/Trie.mjs';
 export * from './src/data-structures/heap.mjs';
@@ -178,5 +182,5 @@ export * from './src/string-arrays/copy-case.mjs';
 export * from './src/string-arrays/format-big-number.mjs';
 
 export default [
-  createLangtonsAnt, createUnlimitedGrid, combinations, combinationsIterator, bin2gray, gray2bin, nChooseK, permutations, permutationsIterator, SetCnt, Trie, Heap, ListNode, binarySearchArr, binarySearchGE, binarySearchLE, binarySearchRangeIncl, consumeIteratorNonBlocking, getType, measurePerformance, memoize, naturalSearch, randNormal, array2range, range2array, setSafeInterval, barycentricCoordinates, axisAngleToMatrix4, crossProduct, dotProduct, getRotationMatrixFromVectors, multiplyMatrix4, normalize, projectToTrackball, matrixAsArray, egcd, factors, factorsBI, gcd, gcdBI, lcm, lcmBI, lucasLehmerBI, mobius, mobiusBI, mod, modBI, phi, phiBI, powMod, powModBI, tonelliShanksBI, nelderMead, particleSwarmOptimization, simulatedAnnealing, goldenRatio, goldenRatioBI, goldenRatioStr, gpn, gpnBI, heronsFormula, heronsFormulaBI, squareRoot, squareRootBI, arrayHistogram, fromBase64, fromBase64Url, toBase64, toBase64Url, bijective2num, bijective2numBI, num2bijective, num2bijectiveBI, chunks, chunksAsyncIterator, chunksIterator, copyCase, formatBigNumber, formatBigNumberBI, wrapFn
+  createLangtonsAnt, createUnlimitedGrid, combinations, combinationsIterator, bin2gray, gray2bin, nChooseK, permutations, permutationsIterator, ConflatingQueue, SetCnt, Trie, Heap, ListNode, binarySearchArr, binarySearchGE, binarySearchLE, binarySearchRangeIncl, consumeIteratorNonBlocking, getType, measurePerformance, memoize, naturalSearch, randNormal, array2range, range2array, setSafeInterval, barycentricCoordinates, axisAngleToMatrix4, crossProduct, dotProduct, getRotationMatrixFromVectors, multiplyMatrix4, normalize, projectToTrackball, matrixAsArray, egcd, factors, factorsBI, gcd, gcdBI, lcm, lcmBI, lucasLehmerBI, mobius, mobiusBI, mod, modBI, phi, phiBI, powMod, powModBI, tonelliShanksBI, nelderMead, particleSwarmOptimization, simulatedAnnealing, goldenRatio, goldenRatioBI, goldenRatioStr, gpn, gpnBI, heronsFormula, heronsFormulaBI, squareRoot, squareRootBI, arrayHistogram, fromBase64, fromBase64Url, toBase64, toBase64Url, bijective2num, bijective2numBI, num2bijective, num2bijectiveBI, chunks, chunksAsyncIterator, chunksIterator, copyCase, formatBigNumber, formatBigNumberBI, wrapFn
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gkucmierz/utils",
-  "version": "4.0.2",
+  "version": "4.1.1",
   "type": "module",
   "description": "Usefull functions for solving programming tasks",
   "keywords": [
@@ -12,6 +12,8 @@
     "benchmark",
     "combinations",
     "competitive-programming",
+    "conflating-queue",
+    "coalescing-queue",
     "data-structures",
     "factors",
     "gcd",

package/src/data-structures/ConflatingQueue.mjs

@@ -0,0 +1,162 @@
+/**
+ * @module data-structures
+ */
+
+/**
+ * ConflatingQueue (Coalescing Keyed Work Queue).
+ *
+ * A specialized asynchronous task queue that executes tasks with controllable concurrency
+ * (default 1 = sequential mutex) while automatically conflating (superseding/deduplicating)
+ * pending tasks with matching keys.
+ *
+ * When multiple tasks with the same key are enqueued before the previous task has started,
+ * the older pending task is superseded (resolved with `{ superseded: true }`), and only the
+ * freshest task is executed.
+ *
+ * Ideal for hardware control (DDC/CI, I2C, Serial), UI sliders, telemetry, and rate-limited APIs.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IMJQHYDMA2BDOEDAcwEUBXAUyoQF8EsYowEAiAAWIGtyBjMEJRgAvAPTlCOAM6sA3MGDps+QiQrVK8oA|▶ Try it live in Instacode}
+ */
+export class ConflatingQueue {
+  #concurrency;
+  #maxPending;
+  #pendingTasks = new Map();
+  #runningCount = 0;
+  #idleResolvers = [];
+
+  /**
+   * Initializes the ConflatingQueue.
+   *
+   * @param {object} [options={}]
+   * @param {number} [options.concurrency=1] - Maximum concurrent tasks executing simultaneously.
+   * @param {number} [options.maxPending=Infinity] - Maximum allowed distinct pending keys in queue.
+   */
+  constructor({ concurrency = 1, maxPending = Infinity } = {}) {
+    this.#concurrency = Math.max(1, concurrency || 1);
+    this.#maxPending = maxPending > 0 ? maxPending : Infinity;
+  }
+
+  /**
+   * Enqueues an asynchronous task associated with a specific key.
+   * If a pending task with the same key already exists, it is superseded by the new task.
+   *
+   * @param {string|number|symbol} key - Unique identifier for task coalescing.
+   * @param {Function} taskFn - The async or sync function to execute.
+   * @returns {Promise<*|{ superseded: boolean }>} Resolves with task result or `{ superseded: true }`.
+   */
+  enqueue(key, taskFn) {
+    if (typeof taskFn !== 'function') {
+      return Promise.reject(new TypeError('taskFn must be a function'));
+    }
+
+    if (this.#pendingTasks.has(key)) {
+      const prev = this.#pendingTasks.get(key);
+      prev.resolve({ superseded: true });
+    } else if (this.#pendingTasks.size >= this.#maxPending) {
+      return Promise.reject(new Error(`ConflatingQueue maxPending limit (${this.#maxPending}) exceeded`));
+    }
+
+    return new Promise((resolve, reject) => {
+      this.#pendingTasks.set(key, { taskFn, resolve, reject });
+      this.#drain();
+    });
+  }
+
+  /**
+   * Cancels a pending unstarted task by key.
+   *
+   * @param {string|number|symbol} key - Key of the pending task to cancel.
+   * @returns {boolean} True if task was cancelled, false if not found in pending queue.
+   */
+  cancel(key) {
+    if (!this.#pendingTasks.has(key)) return false;
+    const item = this.#pendingTasks.get(key);
+    this.#pendingTasks.delete(key);
+    item.resolve({ cancelled: true });
+    return true;
+  }
+
+  /**
+   * Clears and cancels all currently pending unstarted tasks.
+   */
+  clear() {
+    for (const item of this.#pendingTasks.values()) {
+      item.resolve({ cancelled: true });
+    }
+    this.#pendingTasks.clear();
+  }
+
+  /**
+   * Checks if the queue is completely idle (no running or pending tasks).
+   *
+   * @type {boolean}
+   */
+  get isIdle() {
+    return this.#runningCount === 0 && this.#pendingTasks.size === 0;
+  }
+
+  /**
+   * Returns current task count metrics.
+   *
+   * @type {{ running: number, pending: number, total: number }}
+   */
+  get size() {
+    return {
+      running: this.#runningCount,
+      pending: this.#pendingTasks.size,
+      total: this.#runningCount + this.#pendingTasks.size
+    };
+  }
+
+  /**
+   * Returns complete diagnostic statistics of the queue.
+   *
+   * @returns {{ running: number, pending: number, total: number, concurrency: number, maxPending: number, isIdle: boolean, pendingKeys: Array<string|number|symbol> }}
+   */
+  getStats() {
+    return {
+      running: this.#runningCount,
+      pending: this.#pendingTasks.size,
+      total: this.#runningCount + this.#pendingTasks.size,
+      concurrency: this.#concurrency,
+      maxPending: this.#maxPending,
+      isIdle: this.isIdle,
+      pendingKeys: Array.from(this.#pendingTasks.keys())
+    };
+  }
+
+  /**
+   * Returns a promise that resolves when the queue becomes completely idle.
+   *
+   * @returns {Promise<void>}
+   */
+  onIdle() {
+    if (this.isIdle) return Promise.resolve();
+    return new Promise(resolve => {
+      this.#idleResolvers.push(resolve);
+    });
+  }
+
+  async #drain() {
+    while (this.#runningCount < this.#concurrency && this.#pendingTasks.size > 0) {
+      const [key, item] = this.#pendingTasks.entries().next().value;
+      this.#pendingTasks.delete(key);
+      this.#runningCount++;
+
+      (async () => {
+        try {
+          const result = await item.taskFn();
+          item.resolve(result);
+        } catch (err) {
+          item.reject(err);
+        } finally {
+          this.#runningCount--;
+          if (this.isIdle) {
+            const resolvers = this.#idleResolvers.splice(0);
+            resolvers.forEach(r => r());
+          }
+          this.#drain();
+        }
+      })();
+    }
+  }
+}