ConflatingQueue

data-structures. ConflatingQueue

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.

Constructor

new ConflatingQueue(optionsopt)

Description:
  • Initializes the ConflatingQueue.
Source:
See:
Parameters:
Name Type Attributes Default Description
options object <optional>
{}
Properties
Name Type Attributes Default Description
concurrency number <optional>
1 Maximum concurrent tasks executing simultaneously.
maxPending number <optional>
Infinity Maximum allowed distinct pending keys in queue.

Members

isIdle :boolean

Description:
  • Checks if the queue is completely idle (no running or pending tasks).
Source:
Checks if the queue is completely idle (no running or pending tasks).
Type:
  • boolean

size :Object

Description:
  • Returns current task count metrics.
Source:
Returns current task count metrics.
Type:
  • Object

Methods

cancel(key) → {boolean}

Description:
  • Cancels a pending unstarted task by key.
Source:
Parameters:
Name Type Description
key string | number | symbol Key of the pending task to cancel.
Returns:
True if task was cancelled, false if not found in pending queue.
Type
boolean

clear()

Description:
  • Clears and cancels all currently pending unstarted tasks.
Source:

enqueue(key, taskFn) → {Promise.<(*|{superseded: boolean})>}

Description:
  • 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.
Source:
Parameters:
Name Type Description
key string | number | symbol Unique identifier for task coalescing.
taskFn function The async or sync function to execute.
Returns:
Resolves with task result or `{ superseded: true }`.
Type
Promise.<(*|{superseded: boolean})>

getStats() → {Object}

Description:
  • Returns complete diagnostic statistics of the queue.
Source:
Returns:
Type
Object

onIdle() → {Promise.<void>}

Description:
  • Returns a promise that resolves when the queue becomes completely idle.
Source:
Returns:
Type
Promise.<void>