terra-route 0.0.5 → 0.0.7

package/src/terra-route.ts

@@ -1,7 +1,8 @@
 import { FeatureCollection, LineString, Point, Feature, Position } from "geojson";
-import { MinHeap } from "./min-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
@@ -16,16 +17,19 @@ class TerraRoute {
     private adjacencyList: Map<number, Array<{ node: number; distance: number }>> = new Map();
     private coords: Position[] = []
     private coordMap: Map<number, Map<number, number>> = new Map();
+    private heap: HeapConstructor;
 
     /**
      * 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;
+    constructor(options?: {
+        distanceMeasurement?: (positionA: Position, positionB: Position) => number,
+        heap?: HeapConstructor
+    }) {
+        this.heap = options?.heap ? options.heap : MinHeap
+        this.distanceMeasurement = options?.distanceMeasurement ? options.distanceMeasurement : haversineDistance;
     }
 
     /**
@@ -53,7 +57,7 @@ class TerraRoute {
 
     /**
      * Builds the internal graph representation (adjacency list) from the input network.
-     * Each LineString segment is translated into bidirectional graph edges with associated distances.
+     * Each LineString segment is translated into 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.
      * 
@@ -82,7 +86,7 @@ class TerraRoute {
     }
 
     /**
-    * 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,7 +94,10 @@ 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.");
         }
@@ -102,87 +109,65 @@ class TerraRoute {
             return null;
         }
 
-        const openSetForward = new MinHeap();
-        const openSetBackward = new MinHeap();
-        openSetForward.insert(0, startIndex);
-        openSetBackward.insert(0, endIndex);
+        const openSet = new this.heap();
+        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 cameFrom = new Map<number, number>();
+        const gScore = new Map<number, number>([[startIndex, 0]]);
+        const visited = new Set<number>();
 
-        const visitedForward = new Set<number>();
-        const visitedBackward = new Set<number>();
+        while (openSet.size() > 0) {
+            // Extract the node with the smallest fScore
+            const current = openSet.extractMin()!;
 
-        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;
+            // If we've reached the end node, we're done
+            if (current === endIndex) {
                 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);
-                }
-            }
+            visited.add(current);
 
-            const currentBackward = openSetBackward.extractMin()!;
-            visitedBackward.add(currentBackward);
+            // Explore neighbors
+            for (const neighbor of this.adjacencyList.get(current) || []) {
+                // Tentative cost from start to this neighbor
+                const tentativeG = (gScore.get(current) ?? Infinity) + neighbor.distance;
 
-            if (visitedForward.has(currentBackward)) {
-                meetingNode = currentBackward;
-                break;
-            }
+                // If this path to neighbor is better, record it
+                if (tentativeG < (gScore.get(neighbor.node) ?? Infinity)) {
+                    cameFrom.set(neighbor.node, current);
+                    gScore.set(neighbor.node, tentativeG);
 
-            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);
+                    // Calculate fScore: gScore + heuristic distance to the end
+                    const fScore =
+                        tentativeG +
+                        this.distanceMeasurement(this.coords[neighbor.node], this.coords[endIndex]);
+
+                    openSet.insert(fScore, neighbor.node);
                 }
             }
         }
 
-        if (meetingNode === null) {
+        // If we never set a path to the end node, there's no route
+        if (!cameFrom.has(endIndex)) {
             return null;
         }
 
-        // Reconstruct forward path
-        const pathForward: Position[] = [];
-        let node = meetingNode;
-        while (node !== undefined) {
-            pathForward.unshift(this.coords[node]);
-            node = cameFromForward.get(node)!;
-        }
+        // Reconstruct the path from end node to start node
+        const path: Position[] = [];
+        let node = endIndex;
 
-        // 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)!;
+            path.unshift(this.coords[node]);
+            node = cameFrom.get(node)!;
         }
 
-        const fullPath = [...pathForward, ...pathBackward];
-
         return {
             type: "Feature",
-            geometry: { type: "LineString", coordinates: fullPath },
+            geometry: { type: "LineString", coordinates: path },
             properties: {},
         };
     }
+
 }
 
 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.");
@@ -374,6 +389,8 @@ export function getReasonIfLineStringInvalid(
         return `Not enough coordinates: ${coords.length} (${coords})`;
     }
 
+    const seen = new Set<string>();
+
     // 5. Validate each coordinate is a valid Position
     //    (At minimum, [number, number] or [number, number, number])
     for (const position of coords) {
@@ -389,5 +406,71 @@ export function getReasonIfLineStringInvalid(
         ) {
             return 'Not a Position; elements are not a numbers';
         }
+
+        // 6. Check for duplicates
+        const key = `${position[0]},${position[1]}`;
+        if (seen.has(key)) {
+            return `Duplicate coordinate: ${key}`;
+        }
+        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/min-heap.spec.ts

@@ -1,75 +0,0 @@
-import { MinHeap } from './min-heap';
-
-describe('MinHeap', () => {
-    let heap: MinHeap;
-
-    beforeEach(() => {
-        heap = new MinHeap();
-    });
-
-    it('should create an empty heap', () => {
-        expect(heap.size()).toBe(0);
-    });
-
-    it('should insert a single element', () => {
-        heap.insert(5, 100);
-        expect(heap.size()).toBe(1);
-        expect(heap.extractMin()).toBe(100);
-        expect(heap.size()).toBe(0);
-    });
-
-    it('should maintain correct heap order when inserting multiple elements', () => {
-        heap.insert(10, 200);
-        heap.insert(5, 100);
-        heap.insert(3, 50);
-        heap.insert(7, 150);
-
-        expect(heap.size()).toBe(4);
-        expect(heap.extractMin()).toBe(50);
-        expect(heap.extractMin()).toBe(100);
-        expect(heap.extractMin()).toBe(150);
-        expect(heap.extractMin()).toBe(200);
-        expect(heap.size()).toBe(0);
-    });
-
-    it('should return null when extracting from an empty heap', () => {
-        expect(heap.extractMin()).toBeNull();
-    });
-
-    it('should handle duplicate keys properly', () => {
-        heap.insert(5, 100);
-        heap.insert(5, 200);
-        heap.insert(5, 300);
-
-        expect(heap.size()).toBe(3);
-        expect(heap.extractMin()).toBe(100);
-        expect(heap.extractMin()).toBe(200);
-        expect(heap.extractMin()).toBe(300);
-        expect(heap.size()).toBe(0);
-    });
-
-    it('should correctly reorder after sequential insert and extract', () => {
-        heap.insert(10, 100);
-        heap.insert(1, 50);
-        expect(heap.extractMin()).toBe(50);
-
-        heap.insert(2, 60);
-        heap.insert(3, 70);
-        expect(heap.extractMin()).toBe(60);
-        expect(heap.extractMin()).toBe(70);
-        expect(heap.extractMin()).toBe(100);
-    });
-
-    it('should handle large number of elements correctly', () => {
-        const elements = Array.from({ length: 1000 }, (_, i) => ({ key: 1000 - i, value: i }));
-        elements.forEach(el => heap.insert(el.key, el.value));
-
-        expect(heap.size()).toBe(1000);
-
-        for (let i = 999; i >= 0; i--) {
-            expect(heap.extractMin()).toBe(i);
-        }
-
-        expect(heap.size()).toBe(0);
-    });
-});