terra-route 0.0.6 → 0.0.8

package/src/terra-route.ts

@@ -1,31 +1,30 @@
 import { FeatureCollection, LineString, Point, Feature, Position } from "geojson";
-import { FibonacciHeap } from "./fibonacci-heap";
 import { haversineDistance } from "./distance/haversine";
 import { createCheapRuler } from "./distance/cheap-ruler";
+import { MinHeap } from "./heap/min-heap";
+import { HeapConstructor } from "./heap/heap";
 
-/**
- * TerraRoute is a routing utility for finding the shortest path
- * between two geographic points over a given GeoJSON LineString network.
- *
- * The class builds an internal graph structure based on the provided network,
- * then applies A* algorithm to compute the shortest route.
- */
-class TerraRoute {
-    private network: FeatureCollection<LineString> | undefined;
-    private distanceMeasurement: (positionA: Position, positionB: Position) => number;
-    private adjacencyList: Map<number, Array<{ node: number; distance: number }>> = new Map();
-    private coords: Position[] = []
-    private coordMap: Map<number, Map<number, number>> = new Map();
+interface Router {
+    buildRouteGraph(network: FeatureCollection<LineString>): void;
+    getRoute(start: Feature<Point>, end: Feature<Point>): Feature<LineString> | null;
+}
 
-    /**
-     * Creates a new instance of TerraRoute.
-     * 
-     * @param distanceMeasurement - Optional custom distance measurement function (defaults to haversine distance).
-     */
-    constructor(
-        distanceMeasurement?: (positionA: Position, positionB: Position) => number
-    ) {
-        this.distanceMeasurement = distanceMeasurement ? distanceMeasurement : haversineDistance;
+class TerraRoute implements Router {
+    private network: FeatureCollection<LineString> | null = null;
+    private distanceMeasurement: (a: Position, b: Position) => number;
+    private heapConstructor: HeapConstructor;
+
+    // Map from longitude → (map from latitude → index)
+    private coordinateIndexMap: Map<number, Map<number, number>> = new Map();
+    private coordinates: Position[] = [];
+    private adjacencyList: Array<Array<{ node: number; distance: number }>> = [];
+
+    constructor(options?: {
+        distanceMeasurement?: (a: Position, b: Position) => number;
+        heap?: HeapConstructor;
+    }) {
+        this.distanceMeasurement = options?.distanceMeasurement ?? haversineDistance;
+        this.heapConstructor = options?.heap ?? MinHeap;
     }
 
     /**
@@ -35,54 +34,65 @@ class TerraRoute {
      * @param coord - A GeoJSON Position array representing [longitude, latitude].
      * @returns A unique numeric index for the coordinate.
      */
-    private coordinateIndex(coord: Position): number {
-        const [lng, lat] = coord;
-        if (!this.coordMap.has(lng)) this.coordMap.set(lng, new Map());
-
-        const latMap = this.coordMap.get(lng)!;
-        if (latMap.has(lat)) {
-            return latMap.get(lat)!;
-        }
+    public buildRouteGraph(network: FeatureCollection<LineString>): void {
+        this.network = network;
 
-        const index = this.coords.length;
-        this.coords.push(coord);
-        latMap.set(lat, index);
+        // Reset everything
+        this.coordinateIndexMap = new Map();
+        this.coordinates = [];
+        this.adjacencyList = [];
+
+        // Hoist to locals for speed
+        const coordIndexMapLocal = this.coordinateIndexMap;
+        const coordsLocal = this.coordinates;
+        const adjListLocal = this.adjacencyList;
+        const measureDistance = this.distanceMeasurement;
+
+        for (const feature of network.features) {
+            const lineCoords = feature.geometry.coordinates;
+
+            for (let i = 0; i < lineCoords.length - 1; i++) {
+                const [lngA, latA] = lineCoords[i];
+                const [lngB, latB] = lineCoords[i + 1];
+
+                // get or assign index for A 
+                let latMapA = coordIndexMapLocal.get(lngA);
+                if (!latMapA) {
+                    latMapA = new Map<number, number>();
+                    coordIndexMapLocal.set(lngA, latMapA);
+                }
+                let indexA = latMapA.get(latA);
+                if (indexA === undefined) {
+                    indexA = coordsLocal.length;
+                    coordsLocal.push(lineCoords[i]);
+                    latMapA.set(latA, indexA);
+                    adjListLocal[indexA] = [];
+                }
 
-        return index;
-    }
+                // get or assign index for B 
+                let latMapB = coordIndexMapLocal.get(lngB);
+                if (!latMapB) {
+                    latMapB = new Map<number, number>();
+                    coordIndexMapLocal.set(lngB, latMapB);
+                }
+                let indexB = latMapB.get(latB);
+                if (indexB === undefined) {
+                    indexB = coordsLocal.length;
+                    coordsLocal.push(lineCoords[i + 1]);
+                    latMapB.set(latB, indexB);
+                    adjListLocal[indexB] = [];
+                }
 
-    /**
-     * Builds the internal graph representation (adjacency list) from the input network.
-     * Each LineString segment is translated into bidirectional graph edges with associated distances.
-     * Assumes that the network is a connected graph of LineStrings with shared coordinates. Calling this 
-     * method with a new network overwrite any existing network and reset all internal data structures.
-     * 
-     * @param network - A GeoJSON FeatureCollection of LineStrings representing the road network.
-     */
-    public buildRouteGraph(network: FeatureCollection<LineString>): void {
-        this.network = network;
-        this.adjacencyList = new Map();
-        this.coords = [];
-        this.coordMap = new Map();
-
-        for (const feature of this.network.features) {
-            const coords = feature.geometry.coordinates;
-            for (let i = 0; i < coords.length - 1; i++) {
-                const aIndex = this.coordinateIndex(coords[i]);
-                const bIndex = this.coordinateIndex(coords[i + 1]);
-                const distance = this.distanceMeasurement(coords[i], coords[i + 1]);
-
-                if (!this.adjacencyList.has(aIndex)) this.adjacencyList.set(aIndex, []);
-                if (!this.adjacencyList.has(bIndex)) this.adjacencyList.set(bIndex, []);
-
-                this.adjacencyList.get(aIndex)!.push({ node: bIndex, distance });
-                this.adjacencyList.get(bIndex)!.push({ node: aIndex, distance });
+                // record the bidirectional edge 
+                const segmentDistance = measureDistance(lineCoords[i], lineCoords[i + 1]);
+                adjListLocal[indexA].push({ node: indexB, distance: segmentDistance });
+                adjListLocal[indexB].push({ node: indexA, distance: segmentDistance });
             }
         }
     }
 
     /**
-    * Computes the shortest route between two points in the network using bidirectional A* algorithm.
+    * Computes the shortest route between two points in the network using the A* algorithm.
     * 
     * @param start - A GeoJSON Point Feature representing the start location.
     * @param end - A GeoJSON Point Feature representing the end location.
@@ -90,99 +100,96 @@ class TerraRoute {
     * 
     * @throws Error if the network has not been built yet with buildRouteGraph(network).
     */
-    public getRoute(start: Feature<Point>, end: Feature<Point>): Feature<LineString> | null {
+    public getRoute(
+        start: Feature<Point>,
+        end: Feature<Point>
+    ): Feature<LineString> | null {
         if (!this.network) {
             throw new Error("Network not built. Please call buildRouteGraph(network) first.");
         }
 
-        const startIndex = this.coordinateIndex(start.geometry.coordinates);
-        const endIndex = this.coordinateIndex(end.geometry.coordinates);
+        // ensure start/end are in the index maps
+        const startIndex = this.getOrCreateIndex(start.geometry.coordinates);
+        const endIndex = this.getOrCreateIndex(end.geometry.coordinates);
 
         if (startIndex === endIndex) {
             return null;
         }
 
-        const openSetForward = new FibonacciHeap();
-        const openSetBackward = new FibonacciHeap();
-        openSetForward.insert(0, startIndex);
-        openSetBackward.insert(0, endIndex);
+        const openSet = new this.heapConstructor();
+        openSet.insert(0, startIndex);
 
-        const cameFromForward = new Map<number, number>();
-        const cameFromBackward = new Map<number, number>();
-        const gScoreForward = new Map<number, number>([[startIndex, 0]]);
-        const gScoreBackward = new Map<number, number>([[endIndex, 0]]);
+        const nodeCount = this.coordinates.length;
+        const gScore = new Array<number>(nodeCount).fill(Infinity);
+        const cameFrom = new Array<number>(nodeCount).fill(-1);
+        const visited = new Array<boolean>(nodeCount).fill(false);
 
-        const visitedForward = new Set<number>();
-        const visitedBackward = new Set<number>();
+        gScore[startIndex] = 0;
 
-        let meetingNode: number | null = null;
-
-        while (openSetForward.size() > 0 && openSetBackward.size() > 0) {
-            const currentForward = openSetForward.extractMin()!;
-            visitedForward.add(currentForward);
-
-            if (visitedBackward.has(currentForward)) {
-                meetingNode = currentForward;
-                break;
-            }
-
-            for (const neighbor of this.adjacencyList.get(currentForward) || []) {
-                const tentativeG = (gScoreForward.get(currentForward) ?? Infinity) + neighbor.distance;
-                if (tentativeG < (gScoreForward.get(neighbor.node) ?? Infinity)) {
-                    cameFromForward.set(neighbor.node, currentForward);
-                    gScoreForward.set(neighbor.node, tentativeG);
-                    const fScore = tentativeG + this.distanceMeasurement(this.coords[neighbor.node], this.coords[endIndex]);
-                    openSetForward.insert(fScore, neighbor.node);
-                }
+        while (openSet.size() > 0) {
+            const current = openSet.extractMin()!;
+            if (visited[current]) {
+                continue;
             }
-
-            const currentBackward = openSetBackward.extractMin()!;
-            visitedBackward.add(currentBackward);
-
-            if (visitedForward.has(currentBackward)) {
-                meetingNode = currentBackward;
+            if (current === endIndex) {
                 break;
             }
-
-            for (const neighbor of this.adjacencyList.get(currentBackward) || []) {
-                const tentativeG = (gScoreBackward.get(currentBackward) ?? Infinity) + neighbor.distance;
-                if (tentativeG < (gScoreBackward.get(neighbor.node) ?? Infinity)) {
-                    cameFromBackward.set(neighbor.node, currentBackward);
-                    gScoreBackward.set(neighbor.node, tentativeG);
-                    const fScore = tentativeG + this.distanceMeasurement(this.coords[neighbor.node], this.coords[startIndex]);
-                    openSetBackward.insert(fScore, neighbor.node);
+            visited[current] = true;
+
+            for (const neighbor of this.adjacencyList[current] || []) {
+                const tentativeG = gScore[current] + neighbor.distance;
+                if (tentativeG < gScore[neighbor.node]) {
+                    gScore[neighbor.node] = tentativeG;
+                    cameFrom[neighbor.node] = current;
+                    const heuristic = this.distanceMeasurement(
+                        this.coordinates[neighbor.node],
+                        this.coordinates[endIndex]
+                    );
+                    openSet.insert(tentativeG + heuristic, neighbor.node);
                 }
             }
         }
 
-        if (meetingNode === null) {
+        if (cameFrom[endIndex] < 0) {
             return null;
         }
 
-        // Reconstruct forward path
-        const pathForward: Position[] = [];
-        let node = meetingNode;
-        while (node !== undefined) {
-            pathForward.unshift(this.coords[node]);
-            node = cameFromForward.get(node)!;
-        }
-
-        // Reconstruct backward path (omit meeting node to avoid duplication)
-        const pathBackward: Position[] = [];
-        node = cameFromBackward.get(meetingNode)!;
-        while (node !== undefined) {
-            pathBackward.push(this.coords[node]);
-            node = cameFromBackward.get(node)!;
+        // Reconstruct path
+        const path: Position[] = [];
+        let current = endIndex;
+        while (current !== startIndex) {
+            path.unshift(this.coordinates[current]);
+            current = cameFrom[current];
         }
-
-        const fullPath = [...pathForward, ...pathBackward];
+        path.unshift(this.coordinates[startIndex]);
 
         return {
             type: "Feature",
-            geometry: { type: "LineString", coordinates: fullPath },
+            geometry: { type: "LineString", coordinates: path },
             properties: {},
         };
     }
+
+    /**
+     * Helper to index start/end in getRoute.
+     */
+    private getOrCreateIndex(coord: Position): number {
+        const [lng, lat] = coord;
+        let latMap = this.coordinateIndexMap.get(lng);
+        if (!latMap) {
+            latMap = new Map<number, number>();
+            this.coordinateIndexMap.set(lng, latMap);
+        }
+        let index = latMap.get(lat);
+        if (index === undefined) {
+            index = this.coordinates.length;
+            this.coordinates.push(coord);
+            latMap.set(lat, index);
+            // ensure adjacencyList covers this new node
+            this.adjacencyList[index] = [];
+        }
+        return index;
+    }
 }
 
 export { TerraRoute, createCheapRuler, haversineDistance }

package/src/test-utils/test-utils.ts

@@ -1,4 +1,5 @@
 import { Position, Feature, Point, LineString, FeatureCollection } from "geojson";
+import { haversineDistance } from "../terra-route";
 
 export const createPointFeature = (coord: Position): Feature<Point> => ({
     type: "Feature",
@@ -23,6 +24,20 @@ export const createLineStringFeature = (coordinates: Position[]): Feature<LineSt
     properties: {},
 });
 
+export function routeLength(
+    line: Feature<LineString>,
+
+) {
+    const lineCoords = line.geometry.coordinates;
+
+    // Calculate the total route distance
+    let routeDistance = 0;
+    for (let i = 0; i < lineCoords.length - 1; i++) {
+        routeDistance += haversineDistance(lineCoords[i], lineCoords[i + 1]);
+    }
+    return routeDistance
+}
+
 export function generateGridWithDiagonals(n: number, spacing: number): FeatureCollection<LineString> {
     const features: Feature<LineString>[] = [];
 
@@ -111,9 +126,9 @@ export function generateGridWithDiagonals(n: number, spacing: number): FeatureCo
  */
 export function generateStarPolygon(
     n: number,
-    radius: number = 0.01,
+    radius = 0.01,
     center: Position = [0, 0],
-    connectAll: boolean = true
+    connectAll = true
 ): FeatureCollection<LineString> {
     if (n < 3) {
         throw new Error("Star polygon requires at least 3 vertices.");
@@ -212,7 +227,7 @@ export function generateTreeFeatureCollection(
     depth: number,
     branchingFactor: number,
     root: Position = [0, 0],
-    length: number = 0.01
+    length = 0.01
 ): FeatureCollection<LineString> {
     if (depth < 1) {
         throw new Error("Tree must have at least depth 1.");
@@ -400,3 +415,62 @@ export function getReasonIfLineStringInvalid(
         seen.add(key);
     }
 }
+
+/**
+ * Checks if the start and end coordinates of a LineString match the given start and end points.
+ * 
+ * @param line - The LineString feature to check
+ * @param start - The start point feature
+ * @param end - The end point feature
+ * @return True if the start and end coordinates match, false otherwise
+ * */
+export function startAndEndAreCorrect(line: Feature<LineString>, start: Feature<Point>, end: Feature<Point>) {
+    const lineCoords = line.geometry.coordinates;
+    const startCoords = start.geometry.coordinates;
+    const endCoords = end.geometry.coordinates;
+
+    // Check if the first coordinate of the LineString matches the start point
+    const startMatches = lineCoords[0][0] === startCoords[0] && lineCoords[0][1] === startCoords[1];
+
+    // Check if the last coordinate of the LineString matches the end point
+    const endMatches = lineCoords[lineCoords.length - 1][0] === endCoords[0] && lineCoords[lineCoords.length - 1][1] === endCoords[1];
+
+    return startMatches && endMatches;
+}
+
+export function routeIsLongerThanDirectPath(line: Feature<LineString>, start: Feature<Point>, end: Feature<Point>) {
+    const lineCoords = line.geometry.coordinates;
+    const startCoords = start.geometry.coordinates;
+    const endCoords = end.geometry.coordinates;
+
+    if (lineCoords.length <= 2) {
+        return true;
+    }
+
+    // Calculate the direct distance between the start and end points
+    const directDistance = haversineDistance(startCoords, endCoords);
+
+    // Calculate the route distance
+    let routeDistance = 0;
+    for (let i = 0; i < lineCoords.length - 1; i++) {
+        routeDistance += haversineDistance(lineCoords[i], lineCoords[i + 1]);
+    }
+
+    // If the route distance is 0, it means the start and end points are the same
+    if (routeDistance === 0) {
+        return true;
+    }
+
+    if (routeDistance < directDistance) {
+
+        // Check if the route distance is very close to the direct distance
+        const absoluteDifference = Math.abs(routeDistance - directDistance);
+        if (absoluteDifference < 0.000000000001) {
+            return true;
+        }
+
+        return false;
+    }
+
+    return true
+}

package/src/fibonacci-heap.spec.ts

@@ -1,55 +0,0 @@
-import { FibonacciHeap } from './fibonacci-heap';
-
-describe('FibonacciHeap', () => {
-    let heap: FibonacciHeap;
-
-    beforeEach(() => {
-        heap = new FibonacciHeap();
-    });
-
-    test('insert() and size()', () => {
-        expect(heap.size()).toBe(0);
-        heap.insert(10, 1);
-        expect(heap.size()).toBe(1);
-        heap.insert(5, 2);
-        expect(heap.size()).toBe(2);
-    });
-
-    test('extractMin() returns the correct value', () => {
-        heap.insert(20, 101);
-        heap.insert(5, 102);
-        heap.insert(15, 103);
-
-        expect(heap.extractMin()).toBe(102); // key 5
-        expect(heap.size()).toBe(2);
-        expect(heap.extractMin()).toBe(103); // key 15
-        expect(heap.extractMin()).toBe(101); // key 20
-        expect(heap.extractMin()).toBeNull();
-    });
-
-    test('extractMin() on empty heap returns null', () => {
-        expect(heap.extractMin()).toBeNull();
-    });
-
-    test('insert() handles duplicate keys', () => {
-        heap.insert(10, 201);
-        heap.insert(10, 202);
-        heap.insert(10, 203);
-
-        const values = [heap.extractMin(), heap.extractMin(), heap.extractMin()];
-        expect(values).toContain(201);
-        expect(values).toContain(202);
-        expect(values).toContain(203);
-        expect(heap.size()).toBe(0);
-    });
-
-    test('interleaved insert and extractMin()', () => {
-        heap.insert(30, 301);
-        heap.insert(10, 302);
-        expect(heap.extractMin()).toBe(302);
-        heap.insert(20, 303);
-        expect(heap.extractMin()).toBe(303);
-        expect(heap.extractMin()).toBe(301);
-        expect(heap.extractMin()).toBeNull();
-    });
-});

package/src/fibonacci-heap.ts

@@ -1,131 +0,0 @@
-type FibNode = {
-    key: number;
-    value: number;
-    degree: number;
-    mark: boolean;
-    parent: FibNode | null;
-    child: FibNode | null;
-    left: FibNode;
-    right: FibNode;
-};
-
-export class FibonacciHeap {
-    private nodeCount = 0;
-    private minNode: FibNode | null = null;
-
-    insert(key: number, value: number): void {
-        const node: FibNode = {
-            key,
-            value,
-            degree: 0,
-            mark: false,
-            parent: null,
-            child: null,
-            left: null as any,
-            right: null as any,
-        };
-        node.left = node;
-        node.right = node;
-
-        this.minNode = this.mergeLists(this.minNode, node);
-        this.nodeCount++;
-    }
-
-    extractMin(): number | null {
-        const z = this.minNode;
-        if (!z) return null;
-
-        // Add children to root list
-        if (z.child) {
-            let child = z.child;
-            do {
-                child.parent = null;
-                child = child.right!;
-            } while (child !== z.child);
-            this.minNode = this.mergeLists(this.minNode, z.child);
-        }
-
-        this.removeFromList(z);
-
-        if (z === z.right) {
-            this.minNode = null;
-        } else {
-            this.minNode = z.right;
-            this.consolidate();
-        }
-
-        this.nodeCount--;
-        return z.value;
-    }
-
-    size(): number {
-        return this.nodeCount;
-    }
-
-    // ========== Internal Methods ==========
-
-    private consolidate(): void {
-        const maxDegree = Math.floor(Math.log2(this.nodeCount)) + 1;
-        const A = new Array<FibNode | null>(maxDegree).fill(null);
-
-        const rootList: FibNode[] = [];
-        let curr = this.minNode!;
-        do {
-            rootList.push(curr);
-            curr = curr.right!;
-        } while (curr !== this.minNode);
-
-        for (const w of rootList) {
-            let x = w;
-            let d = x.degree;
-            while (A[d]) {
-                let y = A[d]!;
-                if (x.key > y.key) {
-                    const temp = x;
-                    x = y;
-                    y = temp;
-                }
-                this.link(y, x);
-                A[d] = null;
-                d++;
-            }
-            A[d] = x;
-        }
-
-        this.minNode = null;
-        for (const node of A) {
-            if (node) {
-                this.minNode = this.mergeLists(this.minNode, node);
-            }
-        }
-    }
-
-    private link(y: FibNode, x: FibNode): void {
-        this.removeFromList(y);
-        y.left = y.right = y;
-        x.child = this.mergeLists(x.child, y);
-        y.parent = x;
-        x.degree++;
-        y.mark = false;
-    }
-
-    private mergeLists(a: FibNode | null, b: FibNode | null): FibNode {
-        if (!a) return b!;
-        if (!b) return a;
-
-        const aRight = a.right!;
-        const bRight = b.right!;
-
-        a.right = bRight;
-        bRight.left = a;
-        b.right = aRight;
-        aRight.left = b;
-
-        return a.key < b.key ? a : b;
-    }
-
-    private removeFromList(node: FibNode): void {
-        node.left.right = node.right;
-        node.right.left = node.left;
-    }
-}