reactive-circular-queue
v2.1.2
Published
A circular queue implementation with reactive features and Symbol.iterator support
Downloads
27
Maintainers
Readme
reactive-circular-queue
A circular queue implementation with reactive features and Symbol.iterator support.
A circular queue (or ring buffer, or circular buffer) is a data structure where elements can be stored and removed without reallocating the underline array. It's often used to implement First In-First Out queues.
npm install reactive-circular-queue
Highlights
CircularQueue<T>
provides methods such as:
enqueue(value)
, to enqueue a single value;enqueueMulti([value1, value2, ...])
, to enqueue multiple values;dequeue()
, to dequeue a single value;dequeue(n)
, to dequeue n values;dequeueAll()
, to dequeue all elements at once;clear()
, to remove all elements from the queue;toArray()
, to create an array containing the elements in the queue;at(index)
, to read (without dequeueing) an element in the queue at a given index (positive or negative);replace(index, item)
, to replace (without affecting the queue size) an element in the queue at a given index (positive or negative);remove(index)
, to remove an element from the queue given an index (positive or negative);iter()
, to get an iterator that dequeues elements one at a time (it also supportsSymbol.iterator
, see the example below).
It also provides the following stores to monitor the state of the queue:
availableSlots$
, corresponding to the number of empty slots still available in the queue;filledSlots$
, corresponding to the number of filled slots in the queue;full$
, which corresponds tofilledSlots$.content() === capacity
;empty$
, which corresponds tofilledSlots$.content() === 0
.
Finally, there is also a capacity
property, corresponding to the total number of slots in the queue, available or filled.
The stores used in this library are ReadonlyStore
s.
This library provides a function called makeCircularQueue
to create CircularQueue<T>
objects.
This function has two overloads:
makeCircularQueue(capacity)
, which takes the maximum size of the queue as its only parameter;makeCircularQueue(array, capacity)
, which takes an array that will be used to initialize the queue as its first parameter and a second optional parameter which is the capacity of the queue. If the capacity is not passed, the array length will be used to determine the maximum queue size. If the capacity is less than the array length, only the elements that can fit into the queue will be added.
import {makeCircularQueue} from 'reactive-circular-queue';
// Create an empty queue that can hold up to 3 items.
const queue1 = makeCircularQueue<string>(3);
console.log(queue1.capacity); // 3
console.log(queue1.filledSlots$.content()); // 0
// Create a full queue that can hold up to 3 items (deduced from the array length).
const queue2 = makeCircularQueue(['hello', 'world', '!']);
console.log(queue2.capacity); // 3
console.log(queue2.filledSlots$.content()); // 3
// Create an almost full queue that can hold up to 3 items (as per the second argument).
const queue3 = makeCircularQueue(['hello', 'world'], 3);
console.log(queue3.capacity); // 3
console.log(queue3.filledSlots$.content()); // 2
// Create a full queue that can hold up to 2 items (as per the second argument).
const queue4 = makeCircularQueue(['hello', 'world', '!'], 2);
console.log(queue4.capacity); // 2
console.log(queue4.filledSlots$.content()); // 2, only 'hello' and 'world' were copied inside the queue.
Examples
Basics:
const queue = makeCircularQueue<string>(3);
queue.enqueue('hello');
queue.enqueue('world');
queue.enqueue('!');
console.log(queue.dequeue()); // hello
console.log(queue.dequeue()); // world
queue.enqueue('bye');
console.log(queue.toArray().join(', ')); // !, bye
Reactivity:
const queue = makeCircularQueue<string>(3);
queue.filledSlots$.subscribe((n) => console.log(`using ${n} of ${queue.capacity} slots`)); // immediately prints "using 0 of 3 slots"
queue.enqueue('hello'); // will trigger the above console.log, printing "using 1 of 3 slots"
queue.enqueue('world'); // will trigger the above console.log, printing "using 2 of 3 slots"
queue.enqueue('!'); // will trigger the above console.log, printing "using 3 of 3 slots"
queue.dequeue(); // will trigger the above console.log, printing "using 2 of 3 slots"
queue.dequeue(); // will trigger the above console.log, printing "using 1 of 3 slots"
queue.enqueue('bye'); // will trigger the above console.log, printing "using 2 of 3 slots"
console.log(queue.toArray().join(', ')); // !, bye
Usage of enqueueMulti
:
const queue = makeCircularQueue<string>(3);
queue.enqueueMulti(['hello', 'world']);
queue.enqueue('!');
console.log(queue.toArray().join(', ')); // hello, world, !
Usage of dequeue(n)
:
const queue = makeCircularQueue<string>(3);
queue.enqueueMulti(['hello', 'world']);
queue.enqueue('!');
console.log(queue.dequeue(2).join(', ')); // hello, world
console.log(queue.dequeue()); // !
Usage of dequeueAll(n)
:
const queue = makeCircularQueue<string>(3);
queue.enqueueMulti(['hello', 'world']);
queue.enqueue('!');
console.log(queue.dequeueAll().join(', ')); // hello, world, !
Usage of at(i)
:
const queue = makeCircularQueue<string>(3);
queue.enqueueMulti(['hello', 'world']);
console.log(queue.at(0)); // hello
console.log(queue.at(1)); // world
console.log(queue.at(2)); // undefined
console.log(queue.at(-1)); // world
console.log(queue.at(-2)); // hello
Usage of replace(i, item)
:
const queue = makeCircularQueue<string>(1);
queue.enqueue('hello');
console.log(queue.replace(0, 'world')); // hello
console.log(queue.dequeue()); // world
Usage of remove(i)
:
const queue = makeCircularQueue<string>(2);
queue.enqueue('world');
queue.enqueue('hello');
console.log(queue.remove(-1)); // hello
console.log(queue.dequeue()); // world
Usage with for..of
([Symbol.iterator]()
):
const queue = makeCircularQueue<string>(3);
queue.enqueueMulti(['hello', 'world']);
console.log(queue.filledSlots$.content()); // 2
for (const value of queue) {
console.log(value); // prints hello, then world
console.log(queue.filledSlots$.content()); // prints 1, then 0
}