@gkucmierz/utils 4.0.1 → 4.1.0

package/README.md

@@ -24,6 +24,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`).

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.1",
+  "version": "4.1.0",
   "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,163 @@
+/**
+ * @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.
+   *
+   * @template T
+   * @param {string|number|symbol} key - Unique identifier for task coalescing.
+   * @param {() => Promise<T>|T} taskFn - The async/sync function to execute.
+   * @returns {Promise<T|{ 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();
+        }
+      })();
+    }
+  }
+}

package/src/string-arrays/format-big-number.mjs

@@ -15,7 +15,7 @@
 const formatBigNumberBoth = (num, separator = '', wrapFn = _ => _) => {
   const str = String(num);
   const rev = [...str].reverse().join('');
-  const match = rev.match(/(\d*\.\-?)|(\d{3}\-?)|(\d{1,3}\-?)|(\-)/g);
+  const match = rev.match(/(\d*\.[+-]?)|(\d{3}[+-]?)|(\d{1,3}[+-]?)|([+-])/g);
   const revInside = (match && match.join('') === rev)
     ? match.map(part => [...part].reverse().join(''))
     : [str];
@@ -45,6 +45,13 @@ export const formatBigNumber = formatBigNumberBoth;
  */
 export const formatBigNumberBI = formatBigNumberBoth;
 
+/**
+ * Creates an alternating span wrapper function for number segments with 'even' and 'odd' classes.
+ * Useful for syntax highlighting or alternating styles of formatted number segments.
+ *
+ * @returns {function(string): string} A wrapper callback function for number segments.
+ * @see {@link https://instacode.app/run/FASwtgDg9gTgLgAgN4IO4wIYQGIDsEC+CAZjFGAgEQACA5gNYCuAxmCAKYwBeA9I3CAA2AZ0oBuYMHRY8EoA|▶ Try it live in Instacode}
+ */
 export const wrapFn = () => {
   let even = true;
   return part => {
@@ -53,3 +60,4 @@ export const wrapFn = () => {
     return `<span class="${cls}">${part}</span>`;
   };
 };
+