datastructures-js / queue

➡️ A performant queue implementation in javascript.

@datastructures-js/queue

A performant queue implementation in javascript.

Contents

• Install
• require
• import
• API
  • constructor
  • Queue.fromArray
  • enqueue (push)
  • front
  • back
  • dequeue (pop)
  • isEmpty
  • size
  • clone
  • toArray
  • clear
• Build
• License

Install

npm install --save @datastructures-js/queue

require

const { Queue } = require('@datastructures-js/queue');

import

import { Queue } from '@datastructures-js/queue';

API

constructor

JS

// empty queue
const queue = new Queue();

// from an array
const queue = new Queue([1, 2, 3]);

TS

// empty queue
const queue = new Queue<number>();

// from an array
const queue = new Queue<number>([1, 2, 3]);

Queue.fromArray

JS

// empty queue
const queue = Queue.fromArray([]);

// with elements
const list = [10, 3, 8, 40, 1];
const queue = Queue.fromArray(list);

// If the list should not be mutated, use a copy of it.
const queue = Queue.fromArray(list.slice());

TS

// empty queue
const queue = Queue.fromArray<number>([]);

// with elements
const list = [10, 3, 8, 40, 1];
const queue = Queue.fromArray<number>(list);

enqueue (push)

adds an element to the back of the queue.

queue.enqueue(10).enqueue(20); // or queue.push(123)

front

peeks on the front element of the queue.

console.log(queue.front()); // 10

back

peeks on the back element in the queue.

console.log(queue.back()); // 20

dequeue (pop)

removes and returns the front element of the queue in O(1) runtime.

console.log(queue.dequeue()); // 10 // or queue.pop()
console.log(queue.front()); // 20

Dequeuing all elements takes O(n) instead of O(n²) when using shift/unshift with arrays.

Explanation by @alexypdu:

Internally, when half the elements have been dequeued, we will resize the dynamic array using Array.slice() which runs in $O(n)$. Since dequeuing all $n$ elements will resize the array $\log_2n$ times, the complexity is $$1 + 2 + 4 + \cdots + 2^{\log_2 n - 1} = 2 ^ {(\log_2 n - 1) + 1} - 1 = n - 1 = O(n)$$ Hence the overall complexity of dequeuing all elements is $O(n + n) = O(n)$, and the amortized complexity of dequeue() is thus $O(1)$.

benchmark:

dequeuing 1 million elements in Node v14

Queue.dequeue	Array.shift
~27 ms	~4 mins 31 secs

isEmpty

checks if the queue is empty.

console.log(queue.isEmpty()); // false

size

returns the number of elements in the queue.

console.log(queue.size()); // 1

clone

creates a shallow copy of the queue.

const queue = Queue.fromArray([{ id: 2 }, { id: 4 } , { id: 8 }]);
const clone =  queue.clone();

clone.dequeue();

console.log(queue.front()); // { id: 2 }
console.log(clone.front()); // { id: 4 }

toArray

returns a copy of the remaining elements as an array.

queue.enqueue(4).enqueue(2);
console.log(queue.toArray()); // [20, 4, 2]

clear

clears all elements from the queue.

queue.clear();
queue.size(); // 0

Build

grunt build

License

The MIT License. Full License is here

queue's Issues

Clarify the complexity of `dequeue()`

Hello, I wonder why dequeuing all elements runs in $O(n \log n)$? The following operation will only run $\log n$ times:

// only remove dequeued elements when reaching half size
// to decrease latency of shifting elements.
this._elements = this._elements.slice(this._offset);

And since Array.slice() runs in $O(n)$, the complexity should be: $$\frac{n}{2} + \frac{n}{4} + \cdots + 1 < \frac{n}{2} + \frac{n}{4} + \cdots = \frac{n}{2} \cdot \sum_{i=0}^{\infty} \frac{1}{2^i} = \frac{n}{2} \cdot 2 = n = O(n)$$

So the overall complexity of dequeuing all elements should be $O(n + n) = O(n)$, and hence the amortized complexity of dequeue() is $O(1)$. Please correct me if I am wrong :)

pop_back & deque

deque which allows push_front & pop_back, is a very useful data structure
when it comes to inserting/ deleting either ends

https://en.cppreference.com/w/cpp/container/deque

---

we can create a new data structure with name deque
or
allow one more param in constructor of queue, that enables it to work like deque and has similar operation to pop_back

what are your views on this? thanks