@cityssm/unique-timed-entry-queue

Unique, Timed-Entry Queue for Node

A queue with delayed enqueue of unique entries, perfect for queuing update notifications.

For use in scenarios where, for example, a user can trigger a notification after updating a record, but may perform several updates close together, and in the end only one notification should be sent.

Installation

npm install @cityssm/unique-timed-entry-queue

Usage

import UniqueTimedEntryQueue from '@cityssm/unique-timed-entry-queue'

// Initialize a queue that adds entries after a 5 minute delay.
const queue = new UniqueTimedEntryQueue(5 * 60_000)

// Add a work order number to the queue.
queue.enqueue('WO.26.00001')

// Check the queue immediately. It's empty.
console.log(queue.size())
// => 0

// Wait 5 minutes, plus a second.
await wait(5 * 60_000 + 1000)

// Check the queue. The work order is now there.
console.log(queue.size())
// => 1

Supports all of the standard queue functions for using the queue, along with additional functions for managing the pending entries.

Basic Functions

enqueue(entry, [entryDelayMilliseconds])
enqueueAll(entries, [entryDelayMilliseconds])
Adds an entry (or entries) to the queue after the specified delay. The enqueue delay can optionally be overridden for the specific entry. If the entry is still waiting to be added to the queue, the delay will be reset.

enqueuePending()
Immediately add all pending entries to the queue.

dequeue()
Dequeues an entry from the queue.

Queue Checks

size()
Returns the size of the queue.

pendingSize()
Returns the number of entries waiting to be added to the queue.

isEmpty()
Returns true if the queue is empty.

hasPending()
Returns true if there are pending entries.

hasPendingEntry(entry)
Returns true if the entry is waiting to be added to the queue.

Clear Functions

clear()
Clears all queue entries.

clearPending()
Clears all pending queue entries.

clearPendingEntry(entry)
Clears a specific pending entry.

clearAll()
Clears all queue entries, and all pending entries.

Export Functions

toArray()
Exports all queue entries to an array.

pendingToArray()
Exports all pending entries to an array.

Note Regarding Shutdown

This queue uses timeouts for moving pending entries to the queue. These timeouts are cancelled automatically when the application quits, however they may need to be cancelled manually if the queue is no longer needed.

To ensure all timeouts are cancelled and that garbage collection can run, include clearPending() or clearAll() in your cleanup process.

Related Projects

ShiftLog
A work management system with work order recording, shift activity logging, and timesheet tracking. Uses a UniqueTimedEntryQueue to dispatch notifications when work orders have been updated.