terra-route 0.0.6 → 0.0.7

package/src/distance/haversine.ts

@@ -1,5 +1,6 @@
 import { Position } from "geojson";
 
+/** Distance measured in kilometers */
 export const haversineDistance = (pointOne: Position, pointTwo: Position): number => {
     const toRadians = (latOrLng: number) => (latOrLng * Math.PI) / 180;
 
@@ -22,4 +23,4 @@ export const haversineDistance = (pointOne: Position, pointTwo: Position): numbe
     const distance = radius * c;
 
     return distance / 1000;
-}
+}

package/src/heap/fibonacci-heap.spec.ts

@@ -0,0 +1,98 @@
+import { FibonacciHeap } from "./fibonacci-heap";
+
+describe("FibonacciHeap", () => {
+    it("should report size zero for a new heap", () => {
+        const heap = new FibonacciHeap();
+        expect(heap.size()).toBe(0);
+    });
+
+    it("should insert a single element and extract it as the minimum", () => {
+        const heap = new FibonacciHeap();
+        heap.insert(42, 42);
+        expect(heap.size()).toBe(1);
+        expect(heap.extractMin()).toBe(42);
+        expect(heap.size()).toBe(0);
+    });
+
+    it("should always extract the smallest key first when inserting ascending keys", () => {
+        const heap = new FibonacciHeap();
+        for (let key = 1; key <= 10; key += 1) {
+            heap.insert(key, key);
+        }
+        expect(heap.extractMin()).toBe(1);
+    });
+
+    it("should extract elements in ascending order regardless of insertion order", () => {
+        const heap = new FibonacciHeap();
+        const keys = [5, 3, 8, 1, 7, 2, 4, 6];
+        keys.forEach((key) => heap.insert(key, key));
+
+        const extracted: number[] = [];
+        while (heap.size() > 0) {
+            const value = heap.extractMin();
+            // value is typed as number | null but should never be null inside the loop
+            extracted.push(value as number);
+        }
+
+        expect(extracted).toEqual(keys.slice().sort((first, second) => first - second));
+    });
+
+    it("should handle duplicate keys correctly and still extract all values", () => {
+        const heap = new FibonacciHeap();
+        heap.insert(10, 100);
+        heap.insert(10, 200);
+        heap.insert(5, 50);
+
+        expect(heap.extractMin()).toBe(50); // key 5
+        // the two duplicate keys (10) can come out in any order for value
+        const remaining = [heap.extractMin(), heap.extractMin()].sort();
+        expect(remaining).toEqual([100, 200]);
+        expect(heap.extractMin()).toBeNull();
+    });
+
+    it("should return null when extracting from an empty heap", () => {
+        const heap = new FibonacciHeap();
+        expect(heap.extractMin()).toBeNull();
+    });
+
+    it("should update size correctly after mixed insert and extract operations", () => {
+        const heap = new FibonacciHeap();
+        heap.insert(20, 20);
+        heap.insert(5, 5);
+        heap.insert(15, 15);
+        expect(heap.size()).toBe(3);
+
+        heap.extractMin(); // removes value 5
+        expect(heap.size()).toBe(2);
+
+        heap.extractMin(); // removes value 15
+        heap.extractMin(); // removes value 20
+        expect(heap.size()).toBe(0);
+    });
+
+    it("should cope with a larger randomised workload", () => {
+        const heap = new FibonacciHeap();
+        const elementCount = 1000;
+        const insertedKeys: number[] = [];
+
+        for (let index = 0; index < elementCount; index += 1) {
+            // random key in range [0, 9999]
+            const randomKey = Math.floor(Math.random() * 10000);
+            insertedKeys.push(randomKey);
+            heap.insert(randomKey, randomKey);
+        }
+        insertedKeys.sort((first, second) => first - second);
+
+        const extracted: number[] = [];
+        let extractedValue: number | null;
+        do {
+            extractedValue = heap.extractMin();
+            if (extractedValue !== null) {
+                extracted.push(extractedValue);
+            }
+        } while (extractedValue !== null);
+
+        expect(extracted).toEqual(insertedKeys);
+        expect(heap.size()).toBe(0);
+    });
+});

package/src/heap/fibonacci-heap.ts

@@ -0,0 +1,210 @@
+import { Heap } from "./heap";
+
+/**
+ * Internal node representation for the Fibonacci heap, expressed as a plain
+ * JavaScript object (no dedicated class).
+ */
+interface FibonacciNode {
+    key: number;
+    value: number;
+    degree: number;
+    parent: FibonacciNode | null;
+    child: FibonacciNode | null;
+    next: FibonacciNode; // clockwise pointer in circular list
+    prev: FibonacciNode; // counter‑clockwise pointer in circular list
+    mark: boolean;       // used by decrease‑key (not implemented here)
+}
+
+/**
+ * Fibonacci heap that conforms to the Terra Route `Heap` interface.
+ * Only the heap itself is a class; each node is a lightweight object created
+ * inline where needed.
+ */
+export class FibonacciHeap implements Heap {
+    private minNode: FibonacciNode | null = null;
+    private totalNodes = 0;
+
+    /**
+     * Inserts a new `(key, value)` pair into the heap.
+     */
+    public insert(key: number, value: number): void {
+        // ---------------- inline node creation ---------------- //
+        const node: FibonacciNode = {
+            key,
+            value,
+            degree: 0,
+            parent: null,
+            child: null,
+            next: null as unknown as FibonacciNode,
+            prev: null as unknown as FibonacciNode,
+            mark: false,
+        };
+        node.next = node;
+        node.prev = node;
+        // ------------------------------------------------------- //
+
+        if (this.minNode === null) {
+            this.minNode = node;
+        } else {
+            // splice node into the circular doubly‑linked root list right after `minNode`
+            node.prev = this.minNode;
+            node.next = this.minNode.next;
+            this.minNode.next.prev = node;
+            this.minNode.next = node;
+
+            if (node.key < this.minNode.key) {
+                this.minNode = node;
+            }
+        }
+
+        this.totalNodes += 1;
+    }
+
+    /**
+     * Removes and returns the value associated with the minimum key. Returns
+     * `null` if the heap is empty.
+     */
+    public extractMin(): number | null {
+        const oldMin = this.minNode;
+        if (oldMin === null) {
+            return null;
+        }
+
+        // Promote each child of `oldMin` to the root list
+        if (oldMin.child !== null) {
+            let childStart = oldMin.child;
+            const children: FibonacciNode[] = [];
+            do {
+                children.push(childStart);
+                childStart = childStart.next;
+            } while (childStart !== oldMin.child);
+
+            for (const child of children) {
+                // detach from child list
+                child.parent = null;
+                child.prev.next = child.next;
+                child.next.prev = child.prev;
+
+                // add to root list right after `oldMin`
+                child.prev = this.minNode!;
+                child.next = this.minNode!.next;
+                this.minNode!.next.prev = child;
+                this.minNode!.next = child;
+            }
+        }
+
+        // Remove `oldMin` from root list
+        oldMin.prev.next = oldMin.next;
+        oldMin.next.prev = oldMin.prev;
+
+        if (oldMin === oldMin.next) {
+            // The heap had exactly one root node and is now empty
+            this.minNode = null;
+        } else {
+            this.minNode = oldMin.next;
+            this.consolidate();
+        }
+
+        this.totalNodes -= 1;
+        return oldMin.value;
+    }
+
+    /** Returns the number of elements stored in the heap. */
+    public size(): number {
+        return this.totalNodes;
+    }
+
+    // --------------------------- internal helpers --------------------------- //
+
+    /**
+     * Merges trees of equal degree so that at most one root of each degree
+     * remains. Runs in `O(log n)` time and is called after `extractMin`.
+     */
+    private consolidate(): void {
+        if (this.minNode === null) {
+            return;
+        }
+
+        // upper bound for the degree of any node is ⌊log₂ n⌋
+        const upperBound = Math.floor(Math.log2(this.totalNodes)) + 2;
+        const degreeTable: Array<FibonacciNode | null> = new Array(upperBound).fill(null);
+
+        // snapshot of the current root list prior to mutation
+        const rootList: FibonacciNode[] = [];
+        let currentRoot = this.minNode;
+        do {
+            rootList.push(currentRoot);
+            currentRoot = currentRoot.next;
+        } while (currentRoot !== this.minNode);
+
+        for (const root of rootList) {
+            let x = root;
+            let degree = x.degree;
+
+            while (degreeTable[degree] !== null) {
+                let y = degreeTable[degree] as FibonacciNode;
+                if (y.key < x.key) {
+                    // ensure `x` has the smaller key
+                    const temporary = x;
+                    x = y;
+                    y = temporary;
+                }
+                this.link(y, x);
+                degreeTable[degree] = null;
+                degree += 1;
+            }
+            degreeTable[degree] = x;
+        }
+
+        // rebuild root list and identify new minimum
+        this.minNode = null;
+        for (const node of degreeTable) {
+            if (node === null) {
+                continue;
+            }
+
+            if (this.minNode === null) {
+                this.minNode = node;
+                node.prev = node;
+                node.next = node;
+            } else {
+                // insert `node` right after current min
+                node.prev = this.minNode;
+                node.next = this.minNode.next;
+                this.minNode.next.prev = node;
+                this.minNode.next = node;
+
+                if (node.key < this.minNode.key) {
+                    this.minNode = node;
+                }
+            }
+        }
+    }
+
+    /**
+     * Makes `child` a child of `parent`. Assumes both nodes are roots of equal
+     * degree. Runs in `O(1)` time.
+     */
+    private link(child: FibonacciNode, parent: FibonacciNode): void {
+        // detach `child` from the root list
+        child.prev.next = child.next;
+        child.next.prev = child.prev;
+
+        // make `child` a child of `parent`
+        child.parent = parent;
+        child.mark = false;
+
+        if (parent.child === null) {
+            parent.child = child;
+            child.prev = child;
+            child.next = child;
+        } else {
+            child.prev = parent.child;
+            child.next = parent.child.next;
+            parent.child.next.prev = child;
+            parent.child.next = child;
+        }
+
+        parent.degree += 1;
+    }
+}

package/src/heap/heap.d.ts

@@ -0,0 +1,10 @@
+export interface Heap {
+    insert: (key: number, value: number) => void;
+    extractMin: () => number | null;
+    size: () => number;
+}
+
+export interface HeapConstructor {
+    // new() returns an instance that implements ExampleInterface
+    new(): Heap;
+}

package/src/heap/min-heap.spec.ts

@@ -0,0 +1,127 @@
+import { MinHeap } from "./min-heap";
+
+describe("MinHeap", () => {
+    let minHeap: MinHeap;
+
+    beforeEach(() => {
+        minHeap = new MinHeap();
+    });
+
+    it("inserts and extracts a single element", () => {
+        expect(minHeap.size()).toBe(0);
+
+        minHeap.insert(5, 123);
+
+        expect(minHeap.size()).toBe(1);
+        expect(minHeap.extractMin()).toBe(123);
+        expect(minHeap.size()).toBe(0);
+    });
+
+    it("extracts null when the heap is empty", () => {
+        expect(minHeap.extractMin()).toBeNull();
+        expect(minHeap.size()).toBe(0);
+    });
+
+    it("maintains proper order for ascending key inserts", () => {
+        const keys = [1, 2, 3, 4, 5];
+        keys.forEach((key) => {
+            minHeap.insert(key, key + 100);
+        });
+
+        // Expect the smallest key to be extracted first
+        expect(minHeap.extractMin()).toBe(101); // key=1 => value=101
+        expect(minHeap.extractMin()).toBe(102); // key=2 => value=102
+        expect(minHeap.extractMin()).toBe(103);
+        expect(minHeap.extractMin()).toBe(104);
+        expect(minHeap.extractMin()).toBe(105);
+        expect(minHeap.extractMin()).toBeNull();
+    });
+
+    it("maintains proper order for descending key inserts", () => {
+        const keys = [5, 4, 3, 2, 1];
+        keys.forEach((key) => {
+            minHeap.insert(key, key + 200);
+        });
+
+        // The smallest key is 1
+        expect(minHeap.extractMin()).toBe(201);
+        // Next smallest is 2
+        expect(minHeap.extractMin()).toBe(202);
+        // Then 3, 4, 5
+        expect(minHeap.extractMin()).toBe(203);
+        expect(minHeap.extractMin()).toBe(204);
+        expect(minHeap.extractMin()).toBe(205);
+        expect(minHeap.extractMin()).toBeNull();
+    });
+
+    it("handles duplicate keys by respecting insertion order", () => {
+        // Insert multiple items with the same key but different values
+        minHeap.insert(10, 1);
+        minHeap.insert(10, 2);
+        minHeap.insert(10, 3);
+
+        // The heap should prioritize the earliest inserted item first
+        expect(minHeap.extractMin()).toBe(1);
+        expect(minHeap.extractMin()).toBe(2);
+        expect(minHeap.extractMin()).toBe(3);
+        expect(minHeap.extractMin()).toBeNull();
+    });
+
+    it("handles a mix of negative and positive keys", () => {
+        const items = [
+            { key: -10, value: 1 },
+            { key: 0, value: 2 },
+            { key: 10, value: 3 },
+            { key: -5, value: 4 },
+            { key: 5, value: 5 },
+        ];
+        items.forEach((item) => minHeap.insert(item.key, item.value));
+
+        // Order of extracted values should respect key order (lowest key first)
+        expect(minHeap.extractMin()).toBe(1); // key = -10
+        expect(minHeap.extractMin()).toBe(4); // key = -5
+        expect(minHeap.extractMin()).toBe(2); // key = 0
+        expect(minHeap.extractMin()).toBe(5); // key = 5
+        expect(minHeap.extractMin()).toBe(3); // key = 10
+        expect(minHeap.extractMin()).toBeNull();
+    });
+
+    it("reflects correct size throughout inserts and extracts", () => {
+        expect(minHeap.size()).toBe(0);
+
+        minHeap.insert(2, 100);
+        minHeap.insert(1, 200);
+        minHeap.insert(3, 300);
+
+        expect(minHeap.size()).toBe(3);
+
+        minHeap.extractMin(); // remove key=1
+        expect(minHeap.size()).toBe(2);
+
+        minHeap.extractMin(); // remove key=2
+        expect(minHeap.size()).toBe(1);
+
+        minHeap.extractMin(); // remove key=3
+        expect(minHeap.size()).toBe(0);
+
+        // Now empty, should return null
+        expect(minHeap.extractMin()).toBeNull();
+        expect(minHeap.size()).toBe(0);
+    });
+
+    it("handles random insertion order consistently", () => {
+        const items = [5, 1, 4, 1, 3, 2, 8, 0, -1];
+        items.forEach((k) => {
+            minHeap.insert(k, k + 1000);
+        });
+
+        // Sort items to check expected order
+        const sorted = [...items].sort((a, b) => a - b);
+        sorted.forEach((expectedKey) => {
+            const extractedValue = minHeap.extractMin();
+            const expectedValue = expectedKey + 1000;
+            expect(extractedValue).toBe(expectedValue);
+        });
+        expect(minHeap.extractMin()).toBeNull();
+    });
+});

package/src/heap/min-heap.ts

@@ -0,0 +1,90 @@
+import { Heap } from "./heap";
+
+export class MinHeap implements Heap {
+    private heap: Array<{ key: number; value: number; index: number }> = [];
+    private insertCounter = 0;
+
+    insert(key: number, value: number): void {
+        const node = { key, value, index: this.insertCounter++ };
+        let idx = this.heap.length;
+        this.heap.push(node);
+
+        // Optimized Bubble Up
+        while (idx > 0) {
+            const parentIdx = (idx - 1) >>> 1; // Fast Math.floor((idx - 1) / 2)
+            const parent = this.heap[parentIdx];
+            if (node.key > parent.key || (node.key === parent.key && node.index > parent.index)) break;
+            this.heap[idx] = parent;
+            idx = parentIdx;
+        }
+        this.heap[idx] = node;
+    }
+
+    extractMin(): number | null {
+        const length = this.heap.length;
+        if (length === 0) return null;
+
+        const minNode = this.heap[0];
+        const endNode = this.heap.pop()!;
+
+        if (length > 1) {
+            this.heap[0] = endNode;
+            this.bubbleDown(0);
+        }
+
+        return minNode.value;
+    }
+
+    size(): number {
+        return this.heap.length;
+    }
+
+    private bubbleDown(idx: number): void {
+        const { heap } = this;
+        const length = heap.length;
+        // Grab the parent node once, then move it down only if needed
+        const node = heap[idx];
+        const nodeKey = node.key;
+        const nodeIndex = node.index;
+
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            // Calculate left and right child indexes
+            const leftIdx = (idx << 1) + 1;
+            if (leftIdx >= length) {
+                // No children => we’re already in place
+                break;
+            }
+
+            // Assume left child is the smaller one by default
+            let smallestIdx = leftIdx;
+            let smallestKey = heap[leftIdx].key;
+            let smallestIndex = heap[leftIdx].index;
+
+            const rightIdx = leftIdx + 1;
+            if (rightIdx < length) {
+                // Compare left child vs. right child
+                const rightKey = heap[rightIdx].key;
+                const rightIndex = heap[rightIdx].index;
+                if (rightKey < smallestKey || (rightKey === smallestKey && rightIndex < smallestIndex)) {
+                    smallestIdx = rightIdx;
+                    smallestKey = rightKey;
+                    smallestIndex = rightIndex;
+                }
+            }
+
+            // Compare the smaller child with the parent
+            if (smallestKey < nodeKey || (smallestKey === nodeKey && smallestIndex < nodeIndex)) {
+                // Swap the smaller child up
+                heap[idx] = heap[smallestIdx];
+                idx = smallestIdx;
+            } else {
+                // We’re in the correct position now, so stop
+                break;
+            }
+        }
+
+        // Place the original node in its final position
+        heap[idx] = node;
+    }
+}

package/src/heap/pairing-heap.spec.ts

@@ -0,0 +1,101 @@
+import { PairingHeap } from "./pairing-heap";
+
+describe("PairingHeap", () => {
+    it("starts empty", () => {
+        const heap = new PairingHeap();
+        expect(heap.size()).toBe(0);
+        expect(heap.extractMin()).toBeNull();
+    });
+
+    it("inserts elements and extracts them in ascending key order", () => {
+        const heap = new PairingHeap();
+
+        heap.insert(10, 10);
+        heap.insert(5, 5);
+        heap.insert(20, 20);
+
+        expect(heap.size()).toBe(3);
+
+        expect(heap.extractMin()).toBe(5);
+        expect(heap.extractMin()).toBe(10);
+        expect(heap.extractMin()).toBe(20);
+
+        expect(heap.size()).toBe(0);
+        expect(heap.extractMin()).toBeNull();
+    });
+
+    it("handles duplicate keys correctly", () => {
+        const heap = new PairingHeap();
+
+        heap.insert(7, 70);
+        heap.insert(7, 71);
+        heap.insert(3, 30);
+
+        // The two smallest keys are equal (3 and 7). The order of equal‑key
+        // removals is not defined, but each extracted value must correspond
+        // to the minimum remaining key.
+        const first = heap.extractMin();
+        expect(first).toBe(30);
+
+        const second = heap.extractMin();
+        const third = heap.extractMin();
+        const extractedValues = [second, third].sort((a, b) => (a as number) - (b as number));
+
+        expect(extractedValues).toEqual([70, 71]);
+    });
+
+    it("works with negative keys", () => {
+        const heap = new PairingHeap();
+
+        heap.insert(-2, -2);
+        heap.insert(-10, -10);
+        heap.insert(0, 0);
+
+        expect(heap.extractMin()).toBe(-10);
+        expect(heap.extractMin()).toBe(-2);
+        expect(heap.extractMin()).toBe(0);
+    });
+
+    it("maintains size correctly through mixed operations", () => {
+        const heap = new PairingHeap();
+
+        heap.insert(4, 4);
+        heap.insert(1, 1);
+        heap.insert(3, 3);
+        expect(heap.size()).toBe(3);
+
+        heap.extractMin(); // removes 1
+        expect(heap.size()).toBe(2);
+
+        heap.insert(2, 2);
+        expect(heap.size()).toBe(3);
+
+        heap.extractMin(); // removes 2
+        heap.extractMin(); // removes 3
+        heap.extractMin(); // removes 4
+        expect(heap.size()).toBe(0);
+    });
+
+    it("can handle a large random workload and still produce sorted output", () => {
+        const heap = new PairingHeap();
+
+        const randomValues: number[] = [];
+        const elementCount = 10_000;
+
+        for (let index = 0; index < elementCount; index += 1) {
+            const key = Math.floor(Math.random() * 1_000_000) - 500_000;
+            randomValues.push(key);
+            heap.insert(key, key);
+        }
+
+        randomValues.sort((a, b) => a - b);
+
+        for (let index = 0; index < elementCount; index += 1) {
+            const extracted = heap.extractMin();
+            expect(extracted).toBe(randomValues[index]);
+        }
+
+        expect(heap.size()).toBe(0);
+        expect(heap.extractMin()).toBeNull();
+    });
+});