@osmix/router 0.0.11 → 0.1.0

package/src/algorithms/shortest-path.ts

@@ -7,15 +7,16 @@
  * @module
  */
 
-import { haversineDistance } from "@osmix/shared/haversine-distance"
-import { BinaryHeap } from "../binary-heap.ts"
-import type { GraphEdge, PathSegment, RoutingAlgorithmFn } from "../types.ts"
+import { haversineDistance } from "@osmix/geo/haversine-distance";
+
+import { BinaryHeap } from "../binary-heap.ts";
+import type { GraphEdge, PathSegment, RoutingAlgorithmFn } from "../types.ts";
 
 /**
- * Maximum speed (m/s) for time-based heuristic.
- * Uses 130 km/h (~36.1 m/s) to ensure admissibility on all road types.
+ * Default maximum speed (m/s) for the time heuristic when the caller does not
+ * pass the graph's real maximum: 130 km/h (~36.1 m/s).
  */
-const MAX_SPEED_MS = (130 * 1000) / 3600
+const DEFAULT_MAX_SPEED_MPS = (130 * 1000) / 3600;
 
 /**
  * A* shortest path algorithm with configurable heuristic.
@@ -24,87 +25,87 @@ const MAX_SPEED_MS = (130 * 1000) / 3600
  * With an admissible heuristic (never overestimates), guarantees optimal paths.
  */
 function shortestPath(
-	graph: (nodeIndex: number) => GraphEdge[],
-	start: number,
-	end: number,
-	getWeight: (edge: GraphEdge) => number,
-	heuristic: (nodeIndex: number) => number,
+  graph: (nodeIndex: number) => GraphEdge[],
+  start: number,
+  end: number,
+  getWeight: (edge: GraphEdge) => number,
+  heuristic: (nodeIndex: number) => number,
 ): PathSegment[] | null {
-	// Same node - trivial path
-	if (start === end) return [{ nodeIndex: start, cost: 0 }]
+  // Same node - trivial path
+  if (start === end) return [{ nodeIndex: start, cost: 0 }];
 
-	const gScore = new Map<number, number>() // Best known cost to reach node
-	const previous = new Map<number, PathSegment>() // How we reached each node
-	const closed = new Set<number>() // Fully processed nodes
-	const heap = new BinaryHeap()
+  const gScore = new Map<number, number>(); // Best known cost to reach node
+  const previous = new Map<number, PathSegment>(); // How we reached each node
+  const closed = new Set<number>(); // Fully processed nodes
+  const heap = new BinaryHeap();
 
-	gScore.set(start, 0)
-	heap.push(start, heuristic(start))
+  gScore.set(start, 0);
+  heap.push(start, heuristic(start));
 
-	while (heap.size > 0) {
-		const current = heap.pop()!
+  while (heap.size > 0) {
+    const current = heap.pop()!;
 
-		// Reached destination
-		if (current === end) return reconstructPath(previous, start, end)
+    // Reached destination
+    if (current === end) return reconstructPath(previous, start, end);
 
-		// Already seen this node
-		if (closed.has(current)) continue
-		closed.add(current)
+    // Already seen this node
+    if (closed.has(current)) continue;
+    closed.add(current);
 
-		const currentG = gScore.get(current)!
+    const currentG = gScore.get(current)!;
 
-		for (const edge of graph(current)) {
-			const neighbor = edge.targetNodeIndex
+    for (const edge of graph(current)) {
+      const neighbor = edge.targetNodeIndex;
 
-			if (closed.has(neighbor)) continue
+      if (closed.has(neighbor)) continue;
 
-			const tentativeG = currentG + getWeight(edge)
-			const existingG = gScore.get(neighbor)
+      const tentativeG = currentG + getWeight(edge);
+      const existingG = gScore.get(neighbor);
 
-			if (existingG === undefined || tentativeG < existingG) {
-				gScore.set(neighbor, tentativeG)
-				previous.set(neighbor, {
-					nodeIndex: neighbor,
-					wayIndex: edge.wayIndex,
-					previousNodeIndex: current,
-					cost: tentativeG,
-				})
+      if (existingG === undefined || tentativeG < existingG) {
+        gScore.set(neighbor, tentativeG);
+        previous.set(neighbor, {
+          nodeIndex: neighbor,
+          wayIndex: edge.wayIndex,
+          previousNodeIndex: current,
+          cost: tentativeG,
+        });
 
-				const f = tentativeG + heuristic(neighbor)
-				heap.push(neighbor, f)
-			}
-		}
-	}
+        const f = tentativeG + heuristic(neighbor);
+        heap.push(neighbor, f);
+      }
+    }
+  }
 
-	return null
+  return null;
 }
 
 /**
  * Reconstruct path from predecessor map.
  */
 function reconstructPath(
-	previous: Map<number, PathSegment>,
-	start: number,
-	end: number,
+  previous: Map<number, PathSegment>,
+  start: number,
+  end: number,
 ): PathSegment[] {
-	const path: PathSegment[] = []
-	let current: number | undefined = end
-
-	while (current !== undefined) {
-		const segment = previous.get(current)
-		if (!segment) {
-			path.unshift({ nodeIndex: current, cost: 0 })
-			break
-		}
-		path.unshift(segment)
-		current = segment.previousNodeIndex
-	}
-
-	if (path.length === 0 || path[0]?.nodeIndex !== start) {
-		path.unshift({ nodeIndex: start, cost: 0 })
-	}
-
-	return path
+  const path: PathSegment[] = [];
+  let current: number | undefined = end;
+
+  while (current !== undefined) {
+    const segment = previous.get(current);
+    if (!segment) {
+      path.unshift({ nodeIndex: current, cost: 0 });
+      break;
+    }
+    path.unshift(segment);
+    current = segment.previousNodeIndex;
+  }
+
+  if (path.length === 0 || path[0]?.nodeIndex !== start) {
+    path.unshift({ nodeIndex: start, cost: 0 });
+  }
+
+  return path;
 }
 
 /**
@@ -112,8 +113,8 @@ function reconstructPath(
  * Explores nodes in order of increasing distance from start.
  */
 export const dijkstra: RoutingAlgorithmFn = (graph, start, end, getWeight) => {
-	return shortestPath(graph, start, end, getWeight, () => 0)
-}
+  return shortestPath(graph, start, end, getWeight, () => 0);
+};
 
 /**
  * A* algorithm - uses heuristic to guide search toward destination.
@@ -121,29 +122,32 @@ export const dijkstra: RoutingAlgorithmFn = (graph, start, end, getWeight) => {
  *
  * The heuristic is adapted based on the metric:
  * - distance: haversine distance in meters
- * - time: haversine distance / max speed (lower bound on travel time in seconds)
+ * - time: haversine distance / `context.maxSpeedMps` (lower bound on travel time in seconds).
+ *   Pass the graph's real maximum; the 130 km/h default overestimates on faster roads.
  */
 export const astar: RoutingAlgorithmFn = (
-	graph,
-	start,
-	end,
-	getWeight,
-	getCoord,
-	metric,
+  graph,
+  start,
+  end,
+  getWeight,
+  getCoord,
+  metric,
+  context,
 ) => {
-	if (!getCoord) return null
-
-	const endCoord = getCoord(end)
-	if (!endCoord) return null
-
-	// Haversine heuristic scaled by metric
-	// For time: divide by max speed to get admissible time estimate
-	const heuristic = (nodeIndex: number): number => {
-		const coord = getCoord(nodeIndex)
-		if (!coord) return 0
-		const distance = haversineDistance(endCoord, coord)
-		return metric === "time" ? distance / MAX_SPEED_MS : distance
-	}
-
-	return shortestPath(graph, start, end, getWeight, heuristic)
-}
+  if (!getCoord) return null;
+  const maxSpeedMps = context?.maxSpeedMps ?? DEFAULT_MAX_SPEED_MPS;
+
+  const endCoord = getCoord(end);
+  if (!endCoord) return null;
+
+  // Haversine heuristic scaled by metric
+  // For time: divide by max speed to get admissible time estimate
+  const heuristic = (nodeIndex: number): number => {
+    const coord = getCoord(nodeIndex);
+    if (!coord) return 0;
+    const distance = haversineDistance(endCoord, coord);
+    return metric === "time" ? distance / maxSpeedMps : distance;
+  };
+
+  return shortestPath(graph, start, end, getWeight, heuristic);
+};

package/src/binary-heap.ts

@@ -12,136 +12,140 @@
  * Operations:
  * - `push(item, priority)`: O(log n) - adds or updates item priority.
  * - `pop()`: O(log n) - removes and returns minimum priority item.
+ * - `peekPriority()`: O(1) - priority of the minimum item.
  * - `has(item)`: O(1) - checks if item is in heap.
  */
 export class BinaryHeap {
-	private heap: number[] = []
-	private priorities: number[] = []
-	private positions: Map<number, number> = new Map()
-
-	get size(): number {
-		return this.heap.length
-	}
-
-	/**
-	 * Add an item with given priority. If item exists, updates priority if lower.
-	 */
-	push(item: number, priority: number): void {
-		const existing = this.positions.get(item)
-		if (existing !== undefined) {
-			if (priority < this.priorities[existing]!) {
-				this.priorities[existing] = priority
-				this.bubbleUp(existing)
-			}
-			return
-		}
-
-		const index = this.heap.length
-		this.heap.push(item)
-		this.priorities.push(priority)
-		this.positions.set(item, index)
-		this.bubbleUp(index)
-	}
-
-	/**
-	 * Remove and return the minimum-priority item.
-	 */
-	pop(): number | undefined {
-		if (this.heap.length === 0) return undefined
-
-		const min = this.heap[0]!
-		this.positions.delete(min)
-
-		const last = this.heap.pop()!
-		const lastPriority = this.priorities.pop()!
-
-		if (this.heap.length > 0) {
-			this.heap[0] = last
-			this.priorities[0] = lastPriority
-			this.positions.set(last, 0)
-			this.bubbleDown(0)
-		}
-
-		return min
-	}
-
-	/**
-	 * Check if item is in the heap.
-	 */
-	has(item: number): boolean {
-		return this.positions.has(item)
-	}
-
-	/**
-	 * Clear all items.
-	 */
-	clear(): void {
-		this.heap.length = 0
-		this.priorities.length = 0
-		this.positions.clear()
-	}
-
-	private bubbleUp(startIndex: number): void {
-		const item = this.heap[startIndex]!
-		const priority = this.priorities[startIndex]!
-		let index = startIndex
-
-		while (index > 0) {
-			const parentIndex = (index - 1) >> 1
-			const parentPriority = this.priorities[parentIndex]!
-
-			if (priority >= parentPriority) break
-
-			// Swap with parent
-			this.heap[index] = this.heap[parentIndex]!
-			this.priorities[index] = parentPriority
-			this.positions.set(this.heap[index]!, index)
-
-			index = parentIndex
-		}
-
-		this.heap[index] = item
-		this.priorities[index] = priority
-		this.positions.set(item, index)
-	}
-
-	private bubbleDown(startIndex: number): void {
-		const length = this.heap.length
-		const item = this.heap[startIndex]!
-		const priority = this.priorities[startIndex]!
-		let index = startIndex
-
-		while (true) {
-			const leftIndex = (index << 1) + 1
-			const rightIndex = leftIndex + 1
-			let smallest = index
-
-			if (
-				leftIndex < length &&
-				this.priorities[leftIndex]! < this.priorities[smallest]!
-			) {
-				smallest = leftIndex
-			}
-
-			if (
-				rightIndex < length &&
-				this.priorities[rightIndex]! < this.priorities[smallest]!
-			) {
-				smallest = rightIndex
-			}
-
-			if (smallest === index) break
-
-			// Swap with smallest child
-			this.heap[index] = this.heap[smallest]!
-			this.priorities[index] = this.priorities[smallest]!
-			this.positions.set(this.heap[index]!, index)
-
-			index = smallest
-		}
-
-		this.heap[index] = item
-		this.priorities[index] = priority
-		this.positions.set(item, index)
-	}
+  private heap: number[] = [];
+  private priorities: number[] = [];
+  private positions: Map<number, number> = new Map();
+
+  get size(): number {
+    return this.heap.length;
+  }
+
+  /**
+   * Add an item with given priority. If item exists, updates priority if lower.
+   */
+  push(item: number, priority: number): void {
+    const existing = this.positions.get(item);
+    if (existing !== undefined) {
+      if (priority < this.priorities[existing]!) {
+        this.priorities[existing] = priority;
+        this.bubbleUp(existing);
+      }
+      return;
+    }
+
+    const index = this.heap.length;
+    this.heap.push(item);
+    this.priorities.push(priority);
+    this.positions.set(item, index);
+    this.bubbleUp(index);
+  }
+
+  /**
+   * Remove and return the minimum-priority item.
+   */
+  pop(): number | undefined {
+    if (this.heap.length === 0) return undefined;
+
+    const min = this.heap[0]!;
+    this.positions.delete(min);
+
+    const last = this.heap.pop()!;
+    const lastPriority = this.priorities.pop()!;
+
+    if (this.heap.length > 0) {
+      this.heap[0] = last;
+      this.priorities[0] = lastPriority;
+      this.positions.set(last, 0);
+      this.bubbleDown(0);
+    }
+
+    return min;
+  }
+
+  /**
+   * Priority of the minimum item, or `Infinity` when the heap is empty.
+   */
+  peekPriority(): number {
+    return this.priorities[0] ?? Number.POSITIVE_INFINITY;
+  }
+
+  /**
+   * Check if item is in the heap.
+   */
+  has(item: number): boolean {
+    return this.positions.has(item);
+  }
+
+  /**
+   * Clear all items.
+   */
+  clear(): void {
+    this.heap.length = 0;
+    this.priorities.length = 0;
+    this.positions.clear();
+  }
+
+  private bubbleUp(startIndex: number): void {
+    const item = this.heap[startIndex]!;
+    const priority = this.priorities[startIndex]!;
+    let index = startIndex;
+
+    while (index > 0) {
+      const parentIndex = (index - 1) >> 1;
+      const parentPriority = this.priorities[parentIndex]!;
+
+      if (priority >= parentPriority) break;
+
+      // Swap with parent
+      this.heap[index] = this.heap[parentIndex]!;
+      this.priorities[index] = parentPriority;
+      this.positions.set(this.heap[index]!, index);
+
+      index = parentIndex;
+    }
+
+    this.heap[index] = item;
+    this.priorities[index] = priority;
+    this.positions.set(item, index);
+  }
+
+  private bubbleDown(startIndex: number): void {
+    const length = this.heap.length;
+    const item = this.heap[startIndex]!;
+    const priority = this.priorities[startIndex]!;
+    let index = startIndex;
+
+    while (true) {
+      const leftIndex = (index << 1) + 1;
+      const rightIndex = leftIndex + 1;
+      let smallest = index;
+      let smallestPriority = priority;
+
+      if (leftIndex < length && this.priorities[leftIndex]! < smallestPriority) {
+        smallest = leftIndex;
+        smallestPriority = this.priorities[leftIndex]!;
+      }
+
+      if (rightIndex < length && this.priorities[rightIndex]! < smallestPriority) {
+        smallest = rightIndex;
+      }
+
+      if (smallest === index) break;
+
+      // Swap with smallest child
+      this.heap[index] = this.heap[smallest]!;
+      this.priorities[index] = this.priorities[smallest]!;
+      this.positions.set(this.heap[index]!, index);
+
+      index = smallest;
+    }
+
+    this.heap[index] = item;
+    this.priorities[index] = priority;
+    this.positions.set(item, index);
+  }
 }