@osmix/router 0.0.11 → 0.1.0

package/src/index.ts

@@ -9,18 +9,22 @@
  * - **Graph construction**: Build routing graphs from OSM ways with highway filtering.
  * - **Multiple algorithms**: Dijkstra, A*, and bidirectional search.
  * - **Time-based routing**: Uses maxspeed tags and default speeds by highway type.
- * - **One-way support**: Respects oneway=yes/1 tags.
+ * - **One-way support**: Respects explicit one-way tags and implicit roundabout direction.
  * - **Snapping**: Find nearest routable node from arbitrary coordinates.
  *
+ * Not modeled: turn restrictions, access tags, `oneway:*` per-mode overrides,
+ * conditional restrictions, turn costs and elevation. See the README "Limitations".
+ *
  * @example
  * ```ts
- * import { buildGraph, Router, findNearestNodeOnGraph } from "@osmix/router"
+ * import { buildGraph, Router } from "@osmix/router"
  *
  * const graph = buildGraph(osm)
  * const router = new Router(osm, graph)
  *
- * const start = findNearestNodeOnGraph(osm, graph, [-73.989, 40.733], 1)
- * const end = findNearestNodeOnGraph(osm, graph, [-73.988, 40.734], 1)
+ * // Snap radius is in meters. Needs the "all" node spatial index.
+ * const start = graph.findNearestRoutableNode(osm, [-73.989, 40.733], 500)
+ * const end = graph.findNearestRoutableNode(osm, [-73.988, 40.734], 500)
  *
  * if (start && end) {
  *   const path = router.route(start.nodeIndex, end.nodeIndex)
@@ -34,8 +38,9 @@
  * @module @osmix/router
  */
 
-export * from "./algorithms/index.ts"
-export * from "./graph.ts"
-export * from "./router.ts"
-export * from "./types.ts"
-export * from "./utils.ts"
+export * from "./algorithms/index.ts";
+export * from "./graph.ts";
+export * from "./router.ts";
+export * from "./topology-stats.ts";
+export * from "./types.ts";
+export * from "./utils.ts";

package/src/router.ts

@@ -7,24 +7,25 @@
  * @module
  */
 
-import type { Osm } from "@osmix/core"
-import type { LonLat } from "@osmix/shared/types"
-import { routingAlgorithms } from "./algorithms/index.ts"
-import type { RoutingGraph } from "./graph.ts"
+import type { Osm } from "@osmix/core";
+import type { LonLat } from "@osmix/types";
+
+import { routingAlgorithms } from "./algorithms/index.ts";
+import type { RoutingGraph } from "./graph.ts";
 import type {
-	PathSegment,
-	RouteOptions,
-	RoutePathInfo,
-	RouteResult,
-	RouteStatistics,
-	WaySegment,
-} from "./types.ts"
+  PathSegment,
+  RouteOptions,
+  RoutePathInfo,
+  RouteResult,
+  RouteStatistics,
+  WaySegment,
+} from "./types.ts";
 
 /**
  * Router for finding paths through OSM road networks.
  *
  * Uses pathfinding algorithms (Dijkstra, A*, or bidirectional) to find
- * routes between node indexes. Use `findNearestNodeOnGraph()` to snap
+ * routes between node indexes. Use `graph.findNearestRoutableNode()` to snap
  * arbitrary coordinates to routable nodes before calling `route()`.
  *
  * @example
@@ -38,225 +39,212 @@ import type {
  * ```
  */
 export class Router {
-	readonly graph: RoutingGraph
-	readonly osm: Osm
-	private readonly defaults: Required<RouteOptions>
-
-	constructor(
-		osm: Osm,
-		graph: RoutingGraph,
-		options: Partial<RouteOptions> = {},
-	) {
-		this.osm = osm
-		this.graph = graph
-		this.defaults = {
-			algorithm: options.algorithm ?? "astar",
-			metric: options.metric ?? "distance",
-			includeStats: options.includeStats ?? false,
-			includePathInfo: options.includePathInfo ?? false,
-		}
-	}
-
-	/**
-	 * Find a route between two node indexes.
-	 * Returns path segments or null if no path exists.
-	 */
-	route(
-		fromNodeIndex: number,
-		toNodeIndex: number,
-		options: Partial<RouteOptions> = {},
-	): PathSegment[] | null {
-		// Trivial case: same node
-		if (fromNodeIndex === toNodeIndex)
-			return [{ nodeIndex: fromNodeIndex, cost: 0 }]
-
-		const algorithm =
-			routingAlgorithms[options.algorithm ?? this.defaults.algorithm]
-		const metric = options.metric ?? this.defaults.metric
-
-		return algorithm(
-			(nodeIndex) => this.graph.getEdges(nodeIndex),
-			fromNodeIndex,
-			toNodeIndex,
-			(edge) => (metric === "distance" ? edge.distance : edge.time),
-			(nodeIndex) => this.osm.nodes.getNodeLonLat({ index: nodeIndex }),
-			metric,
-		)
-	}
-
-	/** Build route result with coordinates from path segments. */
-	buildResult(
-		path: PathSegment[],
-		options: Partial<RouteOptions> = {},
-	): RouteResult {
-		const coordinates: LonLat[] = []
-		const wayIndexes: number[] = []
-		const nodeIndexes: number[] = []
-		const seenNodes = new Set<number>()
-
-		let currentWay: number | undefined
-
-		for (let i = 0; i < path.length; i++) {
-			const seg = path[i]!
-			const coord = this.osm.nodes.getNodeLonLat({ index: seg.nodeIndex })
-			if (coord) coordinates.push(coord)
-
-			// Track way transitions
-			if (seg.wayIndex !== undefined && seg.wayIndex !== currentWay) {
-				wayIndexes.push(seg.wayIndex)
-				currentWay = seg.wayIndex
-				// Mark node at way transition
-				if (i > 0 && !seenNodes.has(seg.nodeIndex)) {
-					seenNodes.add(seg.nodeIndex)
-					nodeIndexes.push(seg.nodeIndex)
-				}
-			}
-
-			// Mark start, end, and intersections
-			const isEndpoint = i === 0 || i === path.length - 1
-			const isIntersection = this.graph.isIntersection(seg.nodeIndex)
-			if ((isEndpoint || isIntersection) && !seenNodes.has(seg.nodeIndex)) {
-				seenNodes.add(seg.nodeIndex)
-				nodeIndexes.push(seg.nodeIndex)
-			}
-		}
-
-		const result: RouteResult = { coordinates, wayIndexes, nodeIndexes }
-
-		const includeStats = options.includeStats ?? this.defaults.includeStats
-		const includePathInfo =
-			options.includePathInfo ?? this.defaults.includePathInfo
-
-		if (includeStats) {
-			const stats = this.getRouteStatistics(path)
-			result.distance = stats.distance
-			result.time = stats.time
-		}
-
-		if (includePathInfo) {
-			const pathInfo = this.getRoutePathInfo(path)
-			result.segments = pathInfo.segments
-			result.turnPoints = pathInfo.turnPoints
-		}
-
-		return result
-	}
-
-	/**
-	 * Calculate route statistics (distance and time) from path segments.
-	 * @param path - Path segments from route().
-	 * @returns Total distance in meters and time in seconds.
-	 */
-	getRouteStatistics(path: PathSegment[]): RouteStatistics {
-		let distance = 0
-		let time = 0
-
-		for (const seg of path) {
-			if (seg.wayIndex !== undefined && seg.previousNodeIndex !== undefined) {
-				const edges = this.graph.getEdges(seg.previousNodeIndex)
-				const edge = edges.find(
-					(e) =>
-						e.targetNodeIndex === seg.nodeIndex && e.wayIndex === seg.wayIndex,
-				)
-				if (edge) {
-					distance += edge.distance
-					time += edge.time
-				}
-			}
-		}
-
-		return { distance, time }
-	}
-
-	/**
-	 * Build route path info (segments and turn points) from path segments.
-	 * Consecutive ways with the same name are merged into a single segment.
-	 * @param path - Path segments from route().
-	 * @returns Segments with per-way breakdown and turn point coordinates.
-	 */
-	getRoutePathInfo(path: PathSegment[]): RoutePathInfo {
-		// First, collect edge traversals with way info
-		interface EdgeTraversal {
-			wayIndex: number
-			transitionNodeIndex: number
-			distance: number
-			time: number
-		}
-		const edgeSequence: EdgeTraversal[] = []
-
-		for (const seg of path) {
-			if (seg.wayIndex !== undefined && seg.previousNodeIndex !== undefined) {
-				const edges = this.graph.getEdges(seg.previousNodeIndex)
-				const edge = edges.find(
-					(e) =>
-						e.targetNodeIndex === seg.nodeIndex && e.wayIndex === seg.wayIndex,
-				)
-				if (edge) {
-					edgeSequence.push({
-						wayIndex: seg.wayIndex,
-						transitionNodeIndex: seg.previousNodeIndex,
-						distance: edge.distance,
-						time: edge.time,
-					})
-				}
-			}
-		}
-
-		// Build segments, merging consecutive same-name ways
-		const segments: WaySegment[] = []
-		const turnPoints: LonLat[] = []
-		let currentSegment: WaySegment | null = null
-		let currentDisplayName: string | null = null
-
-		const getDisplayName = (tags?: Record<string, string | number>) => {
-			const name = (tags?.["name"] as string) ?? ""
-			const highway = (tags?.["highway"] as string) ?? ""
-			return name || highway
-		}
-
-		for (const {
-			wayIndex,
-			transitionNodeIndex,
-			distance,
-			time,
-		} of edgeSequence) {
-			const wayId = this.osm.ways.ids.at(wayIndex)
-			const tags = this.osm.ways.tags.getTags(wayIndex)
-			const name = (tags?.["name"] as string) ?? ""
-			const highway = (tags?.["highway"] as string) ?? ""
-			const displayName = getDisplayName(tags)
-
-			if (currentSegment && currentDisplayName === displayName) {
-				if (!currentSegment.wayIds.includes(wayId)) {
-					currentSegment.wayIds.push(wayId)
-				}
-				currentSegment.distance += distance
-				currentSegment.time += time
-			} else {
-				if (currentSegment) {
-					segments.push(currentSegment)
-					const coord = this.osm.nodes.getNodeLonLat({
-						index: transitionNodeIndex,
-					})
-					if (coord) {
-						turnPoints.push(coord)
-					}
-				}
-				currentSegment = {
-					wayIds: [wayId],
-					name,
-					highway,
-					distance,
-					time,
-				}
-				currentDisplayName = displayName
-			}
-		}
-
-		if (currentSegment) {
-			segments.push(currentSegment)
-		}
-
-		return { segments, turnPoints }
-	}
+  readonly graph: RoutingGraph;
+  readonly osm: Osm;
+  private readonly defaults: Required<RouteOptions>;
+
+  constructor(osm: Osm, graph: RoutingGraph, options: Partial<RouteOptions> = {}) {
+    this.osm = osm;
+    this.graph = graph;
+    this.defaults = {
+      algorithm: options.algorithm ?? "astar",
+      metric: options.metric ?? "distance",
+      includeStats: options.includeStats ?? false,
+      includePathInfo: options.includePathInfo ?? false,
+    };
+  }
+
+  /**
+   * Find a route between two node indexes.
+   * Returns path segments or null if no path exists.
+   */
+  route(
+    fromNodeIndex: number,
+    toNodeIndex: number,
+    options: Partial<RouteOptions> = {},
+  ): PathSegment[] | null {
+    // Trivial case: same node
+    if (fromNodeIndex === toNodeIndex) return [{ nodeIndex: fromNodeIndex, cost: 0 }];
+
+    const algorithm = routingAlgorithms[options.algorithm ?? this.defaults.algorithm];
+    const metric = options.metric ?? this.defaults.metric;
+
+    return algorithm(
+      (nodeIndex) => this.graph.getEdges(nodeIndex),
+      fromNodeIndex,
+      toNodeIndex,
+      (edge) => (metric === "distance" ? edge.distance : edge.time),
+      (nodeIndex) => this.osm.nodes.getNodeLonLat({ index: nodeIndex }),
+      metric,
+      {
+        reverseGraph: (nodeIndex) => this.graph.getIncomingEdges(nodeIndex),
+        maxSpeedMps: this.graph.maxSpeedMps,
+      },
+    );
+  }
+
+  /** Build route result with coordinates from path segments. */
+  buildResult(path: PathSegment[], options: Partial<RouteOptions> = {}): RouteResult {
+    const coordinates: LonLat[] = [];
+    const wayIndexes: number[] = [];
+    const nodeIndexes: number[] = [];
+    const seenNodes = new Set<number>();
+
+    let currentWay: number | undefined;
+
+    for (let i = 0; i < path.length; i++) {
+      const seg = path[i]!;
+      const coord = this.osm.nodes.getNodeLonLat({ index: seg.nodeIndex });
+      if (coord) coordinates.push(coord);
+
+      // Track way transitions
+      if (seg.wayIndex !== undefined && seg.wayIndex !== currentWay) {
+        wayIndexes.push(seg.wayIndex);
+        currentWay = seg.wayIndex;
+        // Mark node at way transition
+        if (i > 0 && !seenNodes.has(seg.nodeIndex)) {
+          seenNodes.add(seg.nodeIndex);
+          nodeIndexes.push(seg.nodeIndex);
+        }
+      }
+
+      // Mark start, end, and intersections
+      const isEndpoint = i === 0 || i === path.length - 1;
+      const isIntersection = this.graph.isIntersection(seg.nodeIndex);
+      if ((isEndpoint || isIntersection) && !seenNodes.has(seg.nodeIndex)) {
+        seenNodes.add(seg.nodeIndex);
+        nodeIndexes.push(seg.nodeIndex);
+      }
+    }
+
+    const result: RouteResult = { coordinates, wayIndexes, nodeIndexes };
+
+    const includeStats = options.includeStats ?? this.defaults.includeStats;
+    const includePathInfo = options.includePathInfo ?? this.defaults.includePathInfo;
+
+    if (includeStats) {
+      const stats = this.getRouteStatistics(path);
+      result.distance = stats.distance;
+      result.time = stats.time;
+    }
+
+    if (includePathInfo) {
+      const pathInfo = this.getRoutePathInfo(path);
+      result.segments = pathInfo.segments;
+      result.turnPoints = pathInfo.turnPoints;
+    }
+
+    return result;
+  }
+
+  /**
+   * Calculate route statistics (distance and time) from path segments.
+   * @param path - Path segments from route().
+   * @returns Total distance in meters and time in seconds.
+   */
+  getRouteStatistics(path: PathSegment[]): RouteStatistics {
+    let distance = 0;
+    let time = 0;
+
+    for (const seg of path) {
+      if (seg.wayIndex !== undefined && seg.previousNodeIndex !== undefined) {
+        const edges = this.graph.getEdges(seg.previousNodeIndex);
+        const edge = edges.find(
+          (e) => e.targetNodeIndex === seg.nodeIndex && e.wayIndex === seg.wayIndex,
+        );
+        if (edge) {
+          distance += edge.distance;
+          time += edge.time;
+        }
+      }
+    }
+
+    return { distance, time };
+  }
+
+  /**
+   * Build route path info (segments and turn points) from path segments.
+   * Consecutive ways with the same name are merged into a single segment.
+   * @param path - Path segments from route().
+   * @returns Segments with per-way breakdown and turn point coordinates.
+   */
+  getRoutePathInfo(path: PathSegment[]): RoutePathInfo {
+    // First, collect edge traversals with way info
+    interface EdgeTraversal {
+      wayIndex: number;
+      transitionNodeIndex: number;
+      distance: number;
+      time: number;
+    }
+    const edgeSequence: EdgeTraversal[] = [];
+
+    for (const seg of path) {
+      if (seg.wayIndex !== undefined && seg.previousNodeIndex !== undefined) {
+        const edges = this.graph.getEdges(seg.previousNodeIndex);
+        const edge = edges.find(
+          (e) => e.targetNodeIndex === seg.nodeIndex && e.wayIndex === seg.wayIndex,
+        );
+        if (edge) {
+          edgeSequence.push({
+            wayIndex: seg.wayIndex,
+            transitionNodeIndex: seg.previousNodeIndex,
+            distance: edge.distance,
+            time: edge.time,
+          });
+        }
+      }
+    }
+
+    // Build segments, merging consecutive same-name ways
+    const segments: WaySegment[] = [];
+    const turnPoints: LonLat[] = [];
+    let currentSegment: WaySegment | null = null;
+    let currentDisplayName: string | null = null;
+
+    const getDisplayName = (tags?: Record<string, string | number>) => {
+      const name = (tags?.["name"] as string) ?? "";
+      const highway = (tags?.["highway"] as string) ?? "";
+      return name || highway;
+    };
+
+    for (const { wayIndex, transitionNodeIndex, distance, time } of edgeSequence) {
+      const wayId = this.osm.ways.ids.at(wayIndex);
+      const tags = this.osm.ways.tags.getTags(wayIndex);
+      const name = (tags?.["name"] as string) ?? "";
+      const highway = (tags?.["highway"] as string) ?? "";
+      const displayName = getDisplayName(tags);
+
+      if (currentSegment && currentDisplayName === displayName) {
+        if (!currentSegment.wayIds.includes(wayId)) {
+          currentSegment.wayIds.push(wayId);
+        }
+        currentSegment.distance += distance;
+        currentSegment.time += time;
+      } else {
+        if (currentSegment) {
+          segments.push(currentSegment);
+          const coord = this.osm.nodes.getNodeLonLat({
+            index: transitionNodeIndex,
+          });
+          if (coord) {
+            turnPoints.push(coord);
+          }
+        }
+        currentSegment = {
+          wayIds: [wayId],
+          name,
+          highway,
+          distance,
+          time,
+        };
+        currentDisplayName = displayName;
+      }
+    }
+
+    if (currentSegment) {
+      segments.push(currentSegment);
+    }
+
+    return { segments, turnPoints };
+  }
 }

package/src/topology-stats.ts

@@ -0,0 +1,84 @@
+import type { OsmTags } from "@osmix/types";
+import { normalizedWayDirection } from "@osmix/types/way-direction";
+
+import type { HighwayFilter } from "./types.ts";
+
+/** Counts that describe a routing network's shape. */
+export interface RoutingTopologyStats {
+  /** Every node in the source, routable or not. */
+  nodes: number;
+  /** Nodes on at least one way the filter accepts. */
+  routableNodes: number;
+  /** Directed edges: two per segment, one for a one-way segment. */
+  edges: number;
+  /** Weakly connected components among routable nodes. */
+  components: number;
+}
+
+/** Anything that can list its ways: an `Osm`, or a planner view of pending changes. */
+export interface RoutingTopologySource {
+  nodeCount: number;
+  ways(): Iterable<{ tags?: OsmTags | undefined; refs: readonly number[] }>;
+}
+
+/**
+ * Directed edges one way adds for `filter` (two per segment, one when one-way), or null when
+ * the filter does not route it. Direction follows the router: an unsupported one-way value
+ * counts as forward on a roundabout and as two-way elsewhere.
+ */
+export function routingWayEdges(
+  way: { tags?: OsmTags | undefined; refs: readonly number[] },
+  filter: HighwayFilter,
+): number | null {
+  if (!filter(way.tags) || way.refs.length < 2) return null;
+  const normalized = normalizedWayDirection(way.tags);
+  const direction =
+    normalized === "unsupported"
+      ? way.tags?.["junction"] === "roundabout"
+        ? "forward"
+        : "both"
+      : normalized;
+  return (direction === "both" ? 2 : 1) * (way.refs.length - 1);
+}
+
+/**
+ * The same counts `RoutingGraph` would give for `filter`, computed from ways alone, without
+ * building the graph (no coordinates, speeds or CSR arrays). Direction follows the router: an
+ * unsupported one-way value counts as forward on a roundabout and as two-way elsewhere.
+ */
+export function routingTopologyStats(
+  source: RoutingTopologySource,
+  filter: HighwayFilter,
+): RoutingTopologyStats {
+  const parent = new Map<number, number>();
+  const find = (id: number): number => {
+    let root = id;
+    while (parent.get(root) !== root) root = parent.get(root)!;
+    let cursor = id;
+    while (parent.get(cursor) !== cursor) {
+      const next = parent.get(cursor)!;
+      parent.set(cursor, root);
+      cursor = next;
+    }
+    return root;
+  };
+  const union = (a: number, b: number) => {
+    if (!parent.has(a)) parent.set(a, a);
+    if (!parent.has(b)) parent.set(b, b);
+    const left = find(a);
+    const right = find(b);
+    if (left !== right) parent.set(right, left);
+  };
+  let edges = 0;
+  for (const way of source.ways()) {
+    const wayEdges = routingWayEdges(way, filter);
+    if (wayEdges == null) continue;
+    for (let index = 0; index < way.refs.length - 1; index++) {
+      union(way.refs[index]!, way.refs[index + 1]!);
+    }
+    edges += wayEdges;
+  }
+  const roots = new Set<number>();
+  for (const id of parent.keys()) roots.add(find(id));
+  return { nodes: source.nodeCount, routableNodes: parent.size, edges, components: roots.size };
+}