Deque: use DoublyLinkedList so both ends are truly O(1)

Author: trekhleb

README.md

@@ -55,6 +55,7 @@ Remember that each data has its own trade-offs. And you need to pay attention mo
 * `B` [Doubly Linked List](src/data-structures/doubly-linked-list)
 * `B` [Queue](src/data-structures/queue)
 * `B` [Stack](src/data-structures/stack)
+* `B` [Deque](src/data-structures/deque) - double-ended queue
 * `B` [Hash Table](src/data-structures/hash-table)
 * `B` [Heap](src/data-structures/heap) - max and min heap versions
 * `B` [Priority Queue](src/data-structures/priority-queue)

src/data-structures/deque/Deque.js

@@ -1,10 +1,13 @@
-import LinkedList from '../linked-list/LinkedList';
+import DoublyLinkedList from '../doubly-linked-list/DoublyLinkedList';
 
 export default class Deque {
   constructor() {
     // We use a doubly linked list internally so that both front and back
-    // operations run in O(1) time.
-    this.linkedList = new LinkedList();
+    // operations (add, remove and peek) run in O(1) time.
+    this.linkedList = new DoublyLinkedList();
+
+    // Keep a running element count so that `size` stays O(1).
+    this.length = 0;
   }
 
   /**
@@ -43,6 +46,7 @@ export default class Deque {
    */
   addFront(value) {
     this.linkedList.prepend(value);
+    this.length += 1;
   }
 
   /**
@@ -51,6 +55,7 @@ export default class Deque {
    */
   addBack(value) {
     this.linkedList.append(value);
+    this.length += 1;
   }
 
   /**
@@ -59,7 +64,11 @@ export default class Deque {
    */
   removeFront() {
     const removedHead = this.linkedList.deleteHead();
-    return removedHead ? removedHead.value : null;
+    if (!removedHead) {
+      return null;
+    }
+    this.length -= 1;
+    return removedHead.value;
   }
 
   /**
@@ -68,21 +77,19 @@ export default class Deque {
    */
   removeBack() {
     const removedTail = this.linkedList.deleteTail();
-    return removedTail ? removedTail.value : null;
+    if (!removedTail) {
+      return null;
+    }
+    this.length -= 1;
+    return removedTail.value;
   }
 
   /**
    * Return the number of elements in the deque.
    * @return {number}
    */
   get size() {
-    let count = 0;
-    let currentNode = this.linkedList.head;
-    while (currentNode) {
-      count += 1;
-      currentNode = currentNode.next;
-    }
-    return count;
+    return this.length;
   }
 
   /**

src/data-structures/deque/README.md

@@ -1,75 +1,75 @@
-# Deque (Double-Ended Queue)
-
-A **deque** (pronounced "deck", short for **double-ended queue**) is a linear data
-structure that generalises both a stack and a queue. Elements can be added or
-removed from **either end** — the front (head) or the back (tail) — in **O(1)** time.
-
-```
-addFront(3)         addBack(4)
-    ↓                   ↓
-┌───┬───┬───┬───┐
-│ 3 │ 1 │ 2 │ 4 │   ← internal linked list
-└───┴───┴───┴───┘
-    ↑               ↑
-removeFront()    removeBack()
-```
-
-## Operations
-
-| Method        | Description                                  | Time |
-| ------------- | -------------------------------------------- | ---- |
-| `addFront(v)` | Insert element `v` at the front              | O(1) |
-| `addBack(v)`  | Insert element `v` at the back               | O(1) |
-| `removeFront()` | Remove and return the front element        | O(1) |
-| `removeBack()` | Remove and return the back element          | O(1) |
-| `peekFront()` | Return the front element without removing it | O(1) |
-| `peekBack()`  | Return the back element without removing it  | O(1) |
-| `isEmpty()`   | Return `true` if the deque has no elements   | O(1) |
-| `size`        | Return the number of elements                | O(n) |
-
-> **Note:** `size` is O(n) because the underlying linked list does not cache
-> length. If you call `size` frequently, consider maintaining an internal counter.
-
-## Complexity
-
-| | |
-| --------- | ---- |
-| Space     | O(n) |
-| addFront  | O(1) |
-| addBack   | O(1) |
-| removeFront | O(1) |
-| removeBack | O(1) |
-| peekFront | O(1) |
-| peekBack  | O(1) |
-
-## Use Cases
-
-A deque is the right tool when you need **O(1) access at both ends**:
-
-- **Sliding window maximum/minimum** — maintain candidates in a monotonic deque
-  so each element is pushed and popped at most once (overall O(n)).
-- **Browser history** — navigate backward (`removeFront`) and forward
-  (`removeBack`) through pages.
-- **Undo / redo stacks** — push actions to the back, undo from the back,
-  redo from the front.
-- **Palindrome checking** — compare characters from both ends simultaneously.
-- **Work-stealing schedulers** (e.g. Java's `ForkJoinPool`) — threads push/pop
-  from their own back, while idle threads steal from another thread's front.
-
-## Implementation Note
-
-This implementation is backed by the project's existing `LinkedList` (a doubly
-linked list). This gives O(1) `prepend` (for `addFront`) and O(1) `append` /
-`deleteTail` (for `addBack` / `removeBack`), with no need to shift array
-elements.
-
-An alternative implementation using a circular buffer (fixed-size array) offers
-better cache locality but requires resizing logic. The linked-list approach is
-chosen here to stay consistent with the other data structures in this project.
-
-## References
-
-- [Deque — Wikipedia](https://en.wikipedia.org/wiki/Double-ended_queue)
-- [Deque Data Structure — GeeksForGeeks](https://www.geeksforgeeks.org/deque-set-1-introduction-applications/)
-- [▶ Deque in 3 minutes — YouTube](https://www.youtube.com/watch?v=kLBuJ1998Do)
-- [Sliding Window Maximum using Deque — YouTube](https://www.youtube.com/watch?v=2SXqBsTR6a8)
+# Deque (Double-Ended Queue)
+
+A **deque** (pronounced "deck", short for **double-ended queue**) is a linear data
+structure that generalizes both a stack and a queue. Elements can be added or
+removed from **either end** — the front (head) or the back (tail) — in **O(1)** time.
+
+```
+   addFront(3)             addBack(4)
+        ↓                       ↓
+    ┌───────┬───────┬───────┬───────┐
+    │   3   │   1   │   2   │   4   │   ← internal doubly linked list
+    └───────┴───────┴───────┴───────┘
+        ↑                       ↑
+  removeFront()           removeBack()
+```
+
+## Operations
+
+| Method          | Description                                  | Time |
+| --------------- | -------------------------------------------- | ---- |
+| `addFront(v)`   | Insert element `v` at the front              | O(1) |
+| `addBack(v)`    | Insert element `v` at the back               | O(1) |
+| `removeFront()` | Remove and return the front element          | O(1) |
+| `removeBack()`  | Remove and return the back element           | O(1) |
+| `peekFront()`   | Return the front element without removing it | O(1) |
+| `peekBack()`    | Return the back element without removing it  | O(1) |
+| `isEmpty()`     | Return `true` if the deque has no elements   | O(1) |
+| `size`          | Return the number of elements                | O(1) |
+
+> **Note:** `size` is O(1) because the deque keeps a running element count that
+> is updated on every add and remove operation.
+
+## Complexity
+
+| Operation                    | Time |
+| ---------------------------- | ---- |
+| `addFront` / `addBack`       | O(1) |
+| `removeFront` / `removeBack` | O(1) |
+| `peekFront` / `peekBack`     | O(1) |
+| `isEmpty` / `size`           | O(1) |
+| Space                        | O(n) |
+
+## Use Cases
+
+A deque is the right tool when you need **O(1) access at both ends**:
+
+- **Sliding window maximum/minimum** — maintain candidates in a monotonic deque
+  so each element is pushed and popped at most once (overall O(n)).
+- **Browser history** — navigate backward (`removeFront`) and forward
+  (`removeBack`) through pages.
+- **Undo / redo stacks** — push actions to the back, undo from the back,
+  redo from the front.
+- **Palindrome checking** — compare characters from both ends simultaneously.
+- **Work-stealing schedulers** (e.g. Java's `ForkJoinPool`) — threads push/pop
+  from their own back, while idle threads steal from another thread's front.
+
+## Implementation Note
+
+This implementation is backed by the project's existing
+[`DoublyLinkedList`](../doubly-linked-list). Because every node keeps a reference
+to both its previous and next neighbours, this gives O(1) `prepend` (for
+`addFront`), O(1) `deleteHead` (for `removeFront`) and O(1) `append` /
+`deleteTail` (for `addBack` / `removeBack`), with no need to shift array
+elements. The number of elements is tracked in a counter, so `size` is O(1) too.
+
+An alternative implementation using a circular buffer (fixed-size array) offers
+better cache locality but requires resizing logic. The linked-list approach is
+chosen here to stay consistent with the other data structures in this project.
+
+## References
+
+- [Deque — Wikipedia](https://en.wikipedia.org/wiki/Double-ended_queue)
+- [Deque Data Structure — GeeksForGeeks](https://www.geeksforgeeks.org/deque-set-1-introduction-applications/)
+- [▶ Deque (Double-Ended Queue) — YouTube](https://www.youtube.com/watch?v=pqg0SOPRlJ4)
+- [▶ Sliding Window Maximum using Deque — YouTube](https://www.youtube.com/watch?v=2SXqBsTR6a8)