@osmix/router 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @osmix/router
+
+## 0.0.2
+
+### Patch Changes
+
+- cdab4db: Add router
+- Updated dependencies [3846a0c]
+- Updated dependencies [0cd8a2e]
+- Updated dependencies [cdab4db]
+  - @osmix/core@0.0.6
+  - @osmix/shared@0.0.6

package/README.md

@@ -0,0 +1,149 @@
+# @osmix/router
+
+`@osmix/router` builds a routable street network from OSM data and provides routing functionality to find paths between coordinates.
+
+## Highlights
+
+- Builds a directed graph from OSM ways and nodes
+- Configurable highway type filtering
+- Multiple routing algorithms (Dijkstra, A*, bidirectional search)
+- Support for both distance and time-based routing
+- Returns detailed route information including coordinates, way IDs, and node IDs
+- Serializable graph format for Web Worker support
+
+## Installation
+
+```sh
+bun install @osmix/router
+```
+
+## Usage
+
+```ts
+import { RoutingGraph, Router, findNearestNodeOnGraph } from "@osmix/router"
+import { Osm } from "@osmix/core"
+
+const osm = new Osm()
+// ... load OSM data into osm ...
+
+// Build routing graph
+const graph = new RoutingGraph(osm)
+
+// Snap coordinates to nearest routable nodes
+const from = findNearestNodeOnGraph(osm, graph, [-73.989, 40.733], 0.5)
+const to = findNearestNodeOnGraph(osm, graph, [-73.988, 40.734], 0.5)
+
+if (from && to) {
+	const router = new Router(osm, graph)
+	const path = router.route(from.nodeIndex, to.nodeIndex)
+
+	if (path) {
+		const result = router.buildResult(path)
+		console.log(result.coordinates) // Array of [lon, lat] coordinates
+		console.log(result.wayIndexes) // Array of way indexes used
+		console.log(result.nodeIndexes) // Array of node indexes for turns
+	}
+}
+```
+
+## API
+
+### `RoutingGraph`
+
+Build and manage a routing graph from OSM data. The graph uses a CSR (Compressed Sparse Row) format for efficient memory usage and cache locality.
+
+```ts
+import { RoutingGraph, defaultHighwayFilter } from "@osmix/router"
+
+// Build from OSM data
+const graph = new RoutingGraph(osm, defaultHighwayFilter)
+
+// Properties
+graph.size // Number of routable nodes
+graph.edges // Total edge count
+graph.isRouteable(nodeIndex) // Check if node is routable
+graph.isIntersection(nodeIndex) // Check if node is an intersection
+graph.getEdges(nodeIndex) // Get outgoing edges from node
+```
+
+#### `findNearestRoutableNode(osm, point, maxKm)`
+
+Snap a geographic coordinate to the nearest routable node.
+
+```ts
+const nearest = graph.findNearestRoutableNode(osm, [-73.989, 40.733], 0.5)
+if (nearest) {
+	console.log(nearest.nodeIndex) // Internal node index
+	console.log(nearest.coordinates) // Snapped [lon, lat]
+	console.log(nearest.distance) // Distance from input point (meters)
+}
+```
+
+**Constructor parameters:**
+
+- `osm` - The `@osmix/core` dataset.
+- `filter` - Optional function `(tags?) => boolean` to select routable ways. Default: common vehicle highways.
+- `defaultSpeeds` - Optional speed limits (km/h) by highway type.
+
+#### Serialization (Web Worker support)
+
+`RoutingGraph` can be serialized and transferred between Web Workers:
+
+```ts
+// Build graph and get transferables
+const graph = new RoutingGraph(osm)
+const transferables = graph.transferables()
+
+// Transfer to worker (zero-copy with SharedArrayBuffer)
+worker.postMessage(transferables)
+
+// Reconstruct in worker
+const reconstructed = new RoutingGraph(transferables)
+```
+
+The `transferables()` method returns an object containing:
+
+- `nodeCount`, `edgeCount` - Graph dimensions
+- `edgeOffsets`, `edgeTargets`, `edgeWayIndexes` - CSR structure
+- `edgeDistances`, `edgeTimes` - Edge weights
+- `routableBits`, `intersectionBits` - Node flags
+
+### `Router`
+
+High-level routing interface.
+
+```ts
+const router = new Router(osm, graph, { algorithm: "astar", metric: "time" })
+```
+
+**Methods:**
+
+- `route(fromNodeIndex, toNodeIndex, options?)` - Find path between nodes. Returns `PathSegment[]` or `null`.
+- `buildResult(path)` - Convert path to `RouteResult` with coordinates and metadata.
+
+**Options:**
+
+- `algorithm` - `"dijkstra"` | `"astar"` | `"bidirectional"` (default: `"astar"`)
+- `metric` - `"distance"` | `"time"` (default: `"distance"`)
+
+### Algorithms
+
+| Algorithm       | Optimal? | Speed   | Best For                              |
+| --------------- | -------- | ------- | ------------------------------------- |
+| `dijkstra`      | Yes      | Slower  | When you need guaranteed shortest path |
+| `astar`         | Yes      | Fast    | Point-to-point queries (default)      |
+| `bidirectional` | No       | Fastest | Quick connectivity checks             |
+
+## Related Packages
+
+- [`@osmix/core`](../core/README.md) - In-memory OSM index with spatial queries.
+- [`@osmix/shared`](../shared/README.md) - Haversine distance and coordinate utilities.
+- [`osmix`](../osmix/README.md) - High-level API with worker support for routing.
+
+## Development
+
+- `bun run test packages/router`
+- `bun run lint packages/router`
+- `bun run typecheck packages/router`
+
+Run `bun run check` at the repo root before publishing to ensure formatting, lint, and type coverage.

package/dist/src/algorithms/bidirectional.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 { 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 declare const bidirectional: RoutingAlgorithmFn;
+//# sourceMappingURL=bidirectional.d.ts.map

package/dist/src/algorithms/bidirectional.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bidirectional.d.ts","sourceRoot":"","sources":["../../../src/algorithms/bidirectional.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAe,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAE/D;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,kBA+H3B,CAAA"}

package/dist/src/algorithms/bidirectional.js

@@ -0,0 +1,128 @@
+/**
+ * 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
+ */
+/**
+ * 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 = (graph, start, end, getWeight) => {
+    if (start === end)
+        return [{ nodeIndex: start, cost: 0 }];
+    // Forward search state
+    const fDist = new Map();
+    const fPrev = new Map();
+    const fQueue = [start];
+    // Backward search state
+    const bDist = new Map();
+    const bPrev = new Map();
+    const bQueue = [end];
+    fDist.set(start, 0);
+    bDist.set(end, 0);
+    let meetNode = 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 = [];
+    let curr = 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;
+};
+//# sourceMappingURL=bidirectional.js.map

package/dist/src/algorithms/bidirectional.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bidirectional.js","sourceRoot":"","sources":["../../../src/algorithms/bidirectional.ts"],"names":[],"mappings":"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"}

package/dist/src/algorithms/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 declare const routingAlgorithms: Record<RoutingAlgorithm, RoutingAlgorithmFn>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/algorithms/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/algorithms/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAA;AACzC,YAAY,EAAE,kBAAkB,EAAE,CAAA;AAElC,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,gBAAgB,EAAE,kBAAkB,CAI1E,CAAA"}

package/dist/src/algorithms/index.js

@@ -0,0 +1,19 @@
+/**
+ * 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 { bidirectional } from "./bidirectional";
+import { astar, dijkstra } from "./shortest-path";
+export { astar, bidirectional, dijkstra };
+export const routingAlgorithms = {
+    dijkstra,
+    astar,
+    bidirectional,
+};
+//# sourceMappingURL=index.js.map

package/dist/src/algorithms/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/algorithms/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAA;AAGzC,MAAM,CAAC,MAAM,iBAAiB,GAAiD;IAC9E,QAAQ;IACR,KAAK;IACL,aAAa;CACb,CAAA"}

package/dist/src/algorithms/shortest-path.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 type { RoutingAlgorithmFn } from "../types";
+/**
+ * Dijkstra's algorithm - optimal shortest path without heuristic guidance.
+ * Explores nodes in order of increasing distance from start.
+ */
+export declare const dijkstra: RoutingAlgorithmFn;
+/**
+ * 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 declare const astar: RoutingAlgorithmFn;
+//# sourceMappingURL=shortest-path.d.ts.map

package/dist/src/algorithms/shortest-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shortest-path.d.ts","sourceRoot":"","sources":["../../../src/algorithms/shortest-path.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAA0B,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAkG1E;;;GAGG;AACH,eAAO,MAAM,QAAQ,EAAE,kBAEtB,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,EAAE,kBAuBnB,CAAA"}

package/dist/src/algorithms/shortest-path.js

@@ -0,0 +1,115 @@
+/**
+ * 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";
+/**
+ * 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, start, end, getWeight, heuristic) {
+    // Same node - trivial path
+    if (start === end)
+        return [{ nodeIndex: start, cost: 0 }];
+    const gScore = new Map(); // Best known cost to reach node
+    const previous = new Map(); // How we reached each node
+    const closed = new Set(); // 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, start, end) {
+    const path = [];
+    let current = 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 = (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 = (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) => {
+        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);
+};
+//# sourceMappingURL=shortest-path.js.map

package/dist/src/algorithms/shortest-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shortest-path.js","sourceRoot":"","sources":["../../../src/algorithms/shortest-path.ts"],"names":[],"mappings":"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"}

package/dist/src/binary-heap.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 declare class BinaryHeap {
+    private heap;
+    private priorities;
+    private positions;
+    get size(): number;
+    /**
+     * Add an item with given priority. If item exists, updates priority if lower.
+     */
+    push(item: number, priority: number): void;
+    /**
+     * Remove and return the minimum-priority item.
+     */
+    pop(): number | undefined;
+    /**
+     * Check if item is in the heap.
+     */
+    has(item: number): boolean;
+    /**
+     * Clear all items.
+     */
+    clear(): void;
+    private bubbleUp;
+    private bubbleDown;
+}
+//# sourceMappingURL=binary-heap.d.ts.map

package/dist/src/binary-heap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary-heap.d.ts","sourceRoot":"","sources":["../../src/binary-heap.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;GAUG;AACH,qBAAa,UAAU;IACtB,OAAO,CAAC,IAAI,CAAe;IAC3B,OAAO,CAAC,UAAU,CAAe;IACjC,OAAO,CAAC,SAAS,CAAiC;IAElD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAiB1C;;OAEG;IACH,GAAG,IAAI,MAAM,GAAG,SAAS;IAmBzB;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,QAAQ;IAwBhB,OAAO,CAAC,UAAU;CAuClB"}