@osmix/router 0.0.2

package/src/algorithms/bidirectional.ts

@@ -0,0 +1,147 @@
+/**
+ * Bidirectional breadth-first search algorithm.
+ *
+ * Searches from both start and end simultaneously, terminating when the
+ * frontiers meet. Very fast for finding any path, but does not guarantee
+ * the shortest path. Use Dijkstra or A* when optimality is required.
+ *
+ * @module
+ */
+
+import type { PathSegment, RoutingAlgorithmFn } from "../types"
+
+/**
+ * Bidirectional BFS - fast path finding from both ends.
+ *
+ * Uses breadth-first search from both start and end, terminating when
+ * the frontiers meet. Very fast for finding any path, though not always
+ * the optimal shortest path. Use Dijkstra or A* if optimality is required.
+ */
+export const bidirectional: RoutingAlgorithmFn = (
+	graph,
+	start,
+	end,
+	getWeight,
+) => {
+	if (start === end) return [{ nodeIndex: start, cost: 0 }]
+
+	// Forward search state
+	const fDist = new Map<number, number>()
+	const fPrev = new Map<number, PathSegment>()
+	const fQueue: number[] = [start]
+
+	// Backward search state
+	const bDist = new Map<number, number>()
+	const bPrev = new Map<number, PathSegment>()
+	const bQueue: number[] = [end]
+
+	fDist.set(start, 0)
+	bDist.set(end, 0)
+
+	let meetNode: number | null = null
+
+	while (fQueue.length > 0 && bQueue.length > 0) {
+		// Expand forward
+		if (fQueue.length > 0) {
+			const current = fQueue.shift()!
+			const currentD = fDist.get(current)!
+
+			// Check if backward search reached this node
+			if (bDist.has(current)) {
+				meetNode = current
+				break
+			}
+
+			for (const edge of graph(current)) {
+				const neighbor = edge.targetNodeIndex
+				if (fDist.has(neighbor)) continue
+
+				const newD = currentD + getWeight(edge)
+				fDist.set(neighbor, newD)
+				fPrev.set(neighbor, {
+					nodeIndex: neighbor,
+					wayIndex: edge.wayIndex,
+					previousNodeIndex: current,
+					cost: newD,
+				})
+				fQueue.push(neighbor)
+
+				if (bDist.has(neighbor)) {
+					meetNode = neighbor
+					break
+				}
+			}
+
+			if (meetNode !== null) break
+		}
+
+		// Expand backward
+		if (bQueue.length > 0) {
+			const current = bQueue.shift()!
+			const currentD = bDist.get(current)!
+
+			// Check if forward search reached this node
+			if (fDist.has(current)) {
+				meetNode = current
+				break
+			}
+
+			for (const edge of graph(current)) {
+				const neighbor = edge.targetNodeIndex
+				if (bDist.has(neighbor)) continue
+
+				const newD = currentD + getWeight(edge)
+				bDist.set(neighbor, newD)
+				bPrev.set(neighbor, {
+					nodeIndex: neighbor,
+					wayIndex: edge.wayIndex,
+					previousNodeIndex: current,
+					cost: newD,
+				})
+				bQueue.push(neighbor)
+
+				if (fDist.has(neighbor)) {
+					meetNode = neighbor
+					break
+				}
+			}
+
+			if (meetNode !== null) break
+		}
+	}
+
+	if (meetNode === null) return null
+
+	// Build forward path: start -> meet
+	const forward: PathSegment[] = []
+	let curr: number | undefined = meetNode
+	while (curr !== undefined && curr !== start) {
+		const seg = fPrev.get(curr)
+		if (!seg) break
+		forward.unshift(seg)
+		curr = seg.previousNodeIndex
+	}
+	forward.unshift({ nodeIndex: start, cost: 0 })
+
+	// Build backward path: meet -> end (reverse direction)
+	// bDist represents distance FROM end TO node, so it decreases as we approach end.
+	// Correct cost = forward cost to meet + (backward dist at meet - backward dist at curr)
+	const meetForwardCost = fDist.get(meetNode)!
+	const meetBackwardCost = bDist.get(meetNode)!
+	curr = meetNode
+	while (curr !== undefined && curr !== end) {
+		const seg = bPrev.get(curr)
+		if (!seg) break
+		curr = seg.previousNodeIndex
+		if (curr !== undefined) {
+			forward.push({
+				nodeIndex: curr,
+				wayIndex: seg.wayIndex,
+				previousNodeIndex: seg.nodeIndex,
+				cost: meetForwardCost + meetBackwardCost - (bDist.get(curr) ?? 0),
+			})
+		}
+	}
+
+	return forward
+}

package/src/algorithms/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Routing algorithm implementations.
+ *
+ * Provides three algorithms:
+ * - `dijkstra`: Optimal shortest path, explores all directions equally.
+ * - `astar`: Optimal with heuristic guidance, faster for point-to-point.
+ * - `bidirectional`: Fast BFS from both ends, finds *a* path (not always optimal).
+ *
+ * @module
+ */
+
+import type { RoutingAlgorithm, RoutingAlgorithmFn } from "../types"
+import { bidirectional } from "./bidirectional"
+import { astar, dijkstra } from "./shortest-path"
+
+export { astar, bidirectional, dijkstra }
+export type { RoutingAlgorithmFn }
+
+export const routingAlgorithms: Record<RoutingAlgorithm, RoutingAlgorithmFn> = {
+	dijkstra,
+	astar,
+	bidirectional,
+}

package/src/algorithms/shortest-path.ts

@@ -0,0 +1,149 @@
+/**
+ * Shortest path algorithms (Dijkstra and A*).
+ *
+ * Both algorithms guarantee optimal paths. A* uses a heuristic to guide
+ * the search toward the destination, making it faster for most queries.
+ *
+ * @module
+ */
+
+import { haversineDistance } from "@osmix/shared/haversine-distance"
+import { BinaryHeap } from "../binary-heap"
+import type { GraphEdge, PathSegment, RoutingAlgorithmFn } from "../types"
+
+/**
+ * Maximum speed (m/s) for time-based heuristic.
+ * Uses 130 km/h (~36.1 m/s) to ensure admissibility on all road types.
+ */
+const MAX_SPEED_MS = (130 * 1000) / 3600
+
+/**
+ * A* shortest path algorithm with configurable heuristic.
+ *
+ * When heuristic returns 0 for all nodes, this is equivalent to Dijkstra's algorithm.
+ * 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,
+): PathSegment[] | null {
+	// 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()
+
+	gScore.set(start, 0)
+	heap.push(start, heuristic(start))
+
+	while (heap.size > 0) {
+		const current = heap.pop()!
+
+		// Reached destination
+		if (current === end) return reconstructPath(previous, start, end)
+
+		// Already seen this node
+		if (closed.has(current)) continue
+		closed.add(current)
+
+		const currentG = gScore.get(current)!
+
+		for (const edge of graph(current)) {
+			const neighbor = edge.targetNodeIndex
+
+			if (closed.has(neighbor)) continue
+
+			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,
+				})
+
+				const f = tentativeG + heuristic(neighbor)
+				heap.push(neighbor, f)
+			}
+		}
+	}
+
+	return null
+}
+
+/**
+ * Reconstruct path from predecessor map.
+ */
+function reconstructPath(
+	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
+}
+
+/**
+ * Dijkstra's algorithm - optimal shortest path without heuristic guidance.
+ * Explores nodes in order of increasing distance from start.
+ */
+export const dijkstra: RoutingAlgorithmFn = (graph, start, end, getWeight) => {
+	return shortestPath(graph, start, end, getWeight, () => 0)
+}
+
+/**
+ * A* algorithm - uses heuristic to guide search toward destination.
+ * Typically faster than Dijkstra for point-to-point queries.
+ *
+ * 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)
+ */
+export const astar: RoutingAlgorithmFn = (
+	graph,
+	start,
+	end,
+	getWeight,
+	getCoord,
+	metric,
+) => {
+	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)
+}

package/src/binary-heap.ts

@@ -0,0 +1,147 @@
+/**
+ * Priority queue implementation for pathfinding algorithms.
+ * @module
+ */
+
+/**
+ * Min-heap priority queue optimized for pathfinding.
+ *
+ * Uses a binary heap stored in a flat array for cache-friendly access.
+ * Tracks item positions to support O(log n) priority updates (decrease-key).
+ *
+ * Operations:
+ * - `push(item, priority)`: O(log n) - adds or updates item priority.
+ * - `pop()`: O(log n) - removes and returns minimum priority 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)
+	}
+}