feat: add min heap and max heap data structure (TheAlgorithms#117)

* feat: add min heap and max heap data structure

* fix: extract common heap operations to base class

* add check for heap invariant

* move check operations to _check, throw error when check fails

* `return` and `&&` are superfluous now

* Fix return types

* Missed a `return true`

---------

Co-authored-by: Lars Müller <[email protected]>

Author: codeazq

data_structures/heap/heap.ts

@@ -0,0 +1,121 @@
+export abstract class Heap<T> {
+  protected heap: T[];
+
+  constructor(elements: T[] = []) {
+    this.heap = [];
+    for (let element of elements) {
+      this.insert(element);
+    }
+  }
+
+  /**
+   * Compares the value at parentIndex with the value at childIndex
+   * In a maxHeap the value at parentIndex should be larger than the value at childIndex
+   * In a minHeap the value at parentIndex should be smaller than the value at childIndex
+   *
+   */
+  protected abstract isRightlyPlaced(
+    childIndex: number,
+    parentIndex: number
+  ): boolean;
+
+  /**
+   * In a maxHeap the the index with the larger value in returned
+   * In a maxHeap the the index with the larger value in returned
+   */
+  protected abstract getChildIndexToSwap(
+    leftChildIndex: number,
+    rightChildIndex: number
+  ): number;
+
+  public insert(value: T): void {
+    this.heap.push(value);
+    this.bubbleUp();
+  }
+
+  public extract(): T {
+    let maxElement = this.heap[0];
+    this.heap[0] = this.heap[this.size() - 1];
+    this.heap.pop();
+    this.sinkDown();
+    return maxElement;
+  }
+
+  public size(): number {
+    return this.heap.length;
+  }
+
+  public isEmpty(): boolean {
+    return this.size() === 0;
+  }
+
+  protected bubbleUp(): void {
+    let index = this.size() - 1;
+    let parentIndex;
+
+    while (index > 0) {
+      parentIndex = Math.floor((index - 1) / 2);
+      if (this.isRightlyPlaced(index, parentIndex)) break;
+      [this.heap[parentIndex], this.heap[index]] = [
+        this.heap[index],
+        this.heap[parentIndex],
+      ];
+      index = parentIndex;
+    }
+  }
+
+  protected sinkDown(): void {
+    let index = 0;
+    let leftChildIndex = this.getLeftChildIndex(index);
+    let rightChildIndex = this.getRightChildIndex(index);
+    let childIndexToSwap;
+
+    while (this.heap[leftChildIndex] || this.heap[rightChildIndex]) {
+      childIndexToSwap = this.getChildIndexToSwap(
+        leftChildIndex,
+        rightChildIndex
+      );
+      if (this.isRightlyPlaced(childIndexToSwap, index)) break;
+      [this.heap[childIndexToSwap], this.heap[index]] = [
+        this.heap[index],
+        this.heap[childIndexToSwap],
+      ];
+      index = childIndexToSwap;
+      leftChildIndex = this.getLeftChildIndex(index);
+      rightChildIndex = this.getRightChildIndex(index);
+    }
+  }
+
+  protected getLeftChildIndex(index: number): number {
+    return index * 2 + 1;
+  }
+
+  protected getRightChildIndex(index: number): number {
+    return index * 2 + 2;
+  }
+
+  public check(): void {
+    return this._check();
+  }
+
+  protected _check(index: number = 0): void {
+    if (!this.heap[index]) return;
+    const leftChildIndex = this.getLeftChildIndex(index);
+    const rightChildIndex = this.getRightChildIndex(index);
+
+    if (
+      this.heap[leftChildIndex] &&
+      !this.isRightlyPlaced(leftChildIndex, index)
+    )
+      throw new Error("Heap does not adhere to heap invariant");
+
+    if (
+      this.heap[rightChildIndex] &&
+      !this.isRightlyPlaced(rightChildIndex, index)
+    )
+      throw new Error("Heap does not adhere to heap invariant");
+
+    this._check(leftChildIndex);
+    this._check(rightChildIndex);
+  }
+}

data_structures/heap/max_heap.ts

@@ -0,0 +1,40 @@
+import { Heap } from "./heap";
+
+/**
+ * A heap is a complete binary tree
+ * In a complete binary tree each level is filled before lower levels are added
+ * Each level is filled from left to right
+ *
+ * In a max heap the value of every node is greater than that if its children
+ *
+ * The heap if often implemented using an array structure.
+ * In the array implementation, the relationship between a parent index and its two children
+ * are ((parentindex * 2) + 1) and ((parentindex * 2) + 2)
+ *
+ */
+export class MaxHeap<T> extends Heap<T> {
+  constructor(elements: T[] = []) {
+    super(elements);
+  }
+
+  /**
+   * Checks if the value at the parent index is larger than or equal to
+   * the value at the child index
+   */
+  protected isRightlyPlaced(childIndex: number, parentIndex: number): boolean {
+    return this.heap[parentIndex] >= this.heap[childIndex];
+  }
+
+  /**
+   * Returns the child index that stores a larger value
+   */
+  protected getChildIndexToSwap(
+    leftChildIndex: number,
+    rightChildIndex: number
+  ): number {
+    return (this.heap[leftChildIndex] || -Infinity) >
+      (this.heap[rightChildIndex] || -Infinity)
+      ? leftChildIndex
+      : rightChildIndex;
+  }
+}

data_structures/heap/min_heap.ts

@@ -0,0 +1,40 @@
+import { Heap } from "./heap";
+
+/**
+ * A heap is a complete binary tree
+ * In a complete binary tree each level is filled before lower levels are added
+ * Each level is filled from left to right
+ *
+ * In a min heap the value of every node is smaller than that if its children
+ *
+ * The heap if often implemented using an array structure.
+ * In the array implementation, the relationship between a parent index and its two children
+ * are ((parentindex * 2) + 1) and ((parentindex * 2) + 2)
+ *
+ */
+export class MinHeap<T> extends Heap<T> {
+  constructor(elements: T[] = []) {
+    super(elements);
+  }
+
+  /**
+   * Checks if the value at the parent index is lesser than or equal to
+   * the value at the child index
+   */
+  protected isRightlyPlaced(childIndex: number, parentIndex: number): boolean {
+    return this.heap[parentIndex] <= this.heap[childIndex];
+  }
+
+  /**
+   * Returns the child index that stores a smaller value
+   */
+  protected getChildIndexToSwap(
+    leftChildIndex: number,
+    rightChildIndex: number
+  ): number {
+    return (this.heap[leftChildIndex] || -Infinity) <
+      (this.heap[rightChildIndex] || -Infinity)
+      ? leftChildIndex
+      : rightChildIndex;
+  }
+}

data_structures/heap/test/max_heap.test.ts

@@ -0,0 +1,29 @@
+import { MaxHeap } from "../max_heap";
+
+describe("MaxHeap", () => {
+  let heap: MaxHeap<number>;
+
+  beforeAll(() => {
+    const elements: number[] = [
+      12, 4, 43, 42, 9, 7, 39, 16, 55, 1, 51, 34, 81, 18,
+    ];
+    heap = new MaxHeap(elements);
+  });
+
+  it("should initialize a heap from input array", () => {
+    expect(heap.isEmpty()).toEqual(false);
+    heap.check();
+  });
+
+  it("should remove and return the max element in the heap", () => {
+    const maxValue = heap.extract();
+
+    expect(maxValue).toEqual(81);
+    heap.check();
+  });
+
+  it("should insert a new element and bubble Up the element to it correct index in the heap", () => {
+    heap.insert(61);
+    heap.check();
+  });
+});

data_structures/heap/test/min_heap.test.ts

@@ -0,0 +1,29 @@
+import { MinHeap } from "../min_heap";
+
+describe("MinHeap", () => {
+  let heap: MinHeap<number>;
+
+  beforeAll(() => {
+    const elements: number[] = [
+      12, 4, 43, 42, 9, 7, 39, 16, 55, 1, 51, 34, 81, 18,
+    ];
+    heap = new MinHeap(elements);
+  });
+
+  it("should initialize a heap from input array", () => {
+    expect(heap.isEmpty()).toEqual(false);
+    heap.check();
+  });
+
+  it("should remove and return the min element in the heap", () => {
+    const minValue = heap.extract();
+
+    expect(minValue).toEqual(1);
+    heap.check();
+  });
+
+  it("should insert a new element and bubble Up the element to it correct index in the heap", () => {
+    heap.insert(24);
+    heap.check();
+  });
+});