@osmix/router 0.0.13 → 0.1.0

package/src/types.ts

@@ -3,91 +3,91 @@
  * @module
  */
 
-import type { BufferType } from "@osmix/core"
-import type { LonLat, OsmTags } from "@osmix/shared/types"
+import type { BufferType } from "@osmix/core";
+import type { LonLat, OsmTags } from "@osmix/types";
 
 /** Per-way segment with distance and time (consecutive same-name ways merged). */
 export interface WaySegment {
-	/** OSM way IDs included in this segment (multiple if merged). */
-	wayIds: number[]
-	/** Way name from tags (may be empty). */
-	name: string
-	/** Highway type from tags. */
-	highway: string
-	/** Distance travelled on this segment in meters. */
-	distance: number
-	/** Time travelled on this segment in seconds. */
-	time: number
+  /** OSM way IDs included in this segment (multiple if merged). */
+  wayIds: number[];
+  /** Way name from tags (may be empty). */
+  name: string;
+  /** Highway type from tags. */
+  highway: string;
+  /** Distance travelled on this segment in meters. */
+  distance: number;
+  /** Time travelled on this segment in seconds. */
+  time: number;
 }
 
 /** Route statistics (distance and time). */
 export interface RouteStatistics {
-	/** Total route distance in meters. */
-	distance: number
-	/** Total route time in seconds. */
-	time: number
+  /** Total route distance in meters. */
+  distance: number;
+  /** Total route time in seconds. */
+  time: number;
 }
 
 /** Route path info (segments and turn points). */
 export interface RoutePathInfo {
-	/** Per-way breakdown (consecutive same-name ways merged). */
-	segments: WaySegment[]
-	/** Coordinates where way name changes (turn points). */
-	turnPoints: LonLat[]
+  /** Per-way breakdown (consecutive same-name ways merged). */
+  segments: WaySegment[];
+  /** Coordinates where way name changes (turn points). */
+  turnPoints: LonLat[];
 }
 
 /** Route result containing the path geometry and metadata. */
 export interface RouteResult {
-	/** Coordinates along the route. */
-	coordinates: LonLat[]
-	/** Way indexes traversed, in order. */
-	wayIndexes: number[]
-	/** Node indexes at turns and intersections. */
-	nodeIndexes: number[]
-	/** Total route distance in meters (when includeStats is true). */
-	distance?: number
-	/** Total route time in seconds (when includeStats is true). */
-	time?: number
-	/** Per-way breakdown (when includePathInfo is true). */
-	segments?: WaySegment[]
-	/** Coordinates where way name changes (when includePathInfo is true). */
-	turnPoints?: LonLat[]
+  /** Coordinates along the route. */
+  coordinates: LonLat[];
+  /** Way indexes traversed, in order. */
+  wayIndexes: number[];
+  /** Node indexes at turns and intersections. */
+  nodeIndexes: number[];
+  /** Total route distance in meters (when includeStats is true). */
+  distance?: number;
+  /** Total route time in seconds (when includeStats is true). */
+  time?: number;
+  /** Per-way breakdown (when includePathInfo is true). */
+  segments?: WaySegment[];
+  /** Coordinates where way name changes (when includePathInfo is true). */
+  turnPoints?: LonLat[];
 }
 
 /** Filter function to determine which highways are routable. Default: common vehicle highways. */
-export type HighwayFilter = (tags?: OsmTags) => boolean
+export type HighwayFilter = (tags?: OsmTags) => boolean;
 
 /** Available routing algorithms. */
-export type RoutingAlgorithm = "dijkstra" | "astar" | "bidirectional"
+export type RoutingAlgorithm = "dijkstra" | "astar" | "bidirectional";
 
 /** Routing metric to optimize. */
-export type RoutingMetric = "distance" | "time"
+export type RoutingMetric = "distance" | "time";
 
 /** Speed limits by highway type (km/h). */
-export type DefaultSpeeds = Record<string, number>
+export type DefaultSpeeds = Record<string, number>;
 
 /** Router configuration options. */
 export interface RouteOptions {
-	/** Routing algorithm. Default: "astar". */
-	algorithm: RoutingAlgorithm
-	/** Optimization metric. Default: "distance". */
-	metric: RoutingMetric
-	/** Include distance and time in result. Default: false. */
-	includeStats?: boolean
-	/** Include segments and turnPoints in result. Default: false. */
-	includePathInfo?: boolean
+  /** Routing algorithm. Default: "astar". */
+  algorithm: RoutingAlgorithm;
+  /** Optimization metric. Default: "distance". */
+  metric: RoutingMetric;
+  /** Include distance and time in result. Default: false. */
+  includeStats?: boolean;
+  /** Include segments and turnPoints in result. Default: false. */
+  includePathInfo?: boolean;
 }
 
 /** Edge in the routing graph. */
 export interface GraphEdge {
-	/** Target node index. */
-	targetNodeIndex: number
-	/** Way index this edge belongs to. */
-	wayIndex: number
-	/** Distance in meters. */
-	distance: number
-	/** Travel time in seconds. */
-	time: number
+  /** Target node index. */
+  targetNodeIndex: number;
+  /** Way index this edge belongs to. */
+  wayIndex: number;
+  /** Distance in meters. */
+  distance: number;
+  /** Travel time in seconds. */
+  time: number;
 }
 
 /**
@@ -95,44 +95,59 @@ export interface GraphEdge {
  * Uses CSR (Compressed Sparse Row) format for efficient storage and zero-copy transfer.
  */
 export interface RoutingGraphTransferables {
-	/** Total number of nodes in the graph. */
-	nodeCount: number
-	/** Total number of edges in the graph. */
-	edgeCount: number
-	/** CSR offsets: edges for node i are at indices [edgeOffsets[i], edgeOffsets[i+1]) */
-	edgeOffsets: BufferType
-	/** Target node index for each edge. */
-	edgeTargets: BufferType
-	/** Way index for each edge. */
-	edgeWayIndexes: BufferType
-	/** Distance in meters for each edge. */
-	edgeDistances: BufferType
-	/** Travel time in seconds for each edge. */
-	edgeTimes: BufferType
-	/** Bitset: 1 bit per node indicating if routable. */
-	routableBits: BufferType
-	/** Bitset: 1 bit per node indicating if intersection. */
-	intersectionBits: BufferType
+  /** Total number of nodes in the graph. */
+  nodeCount: number;
+  /** Total number of edges in the graph. */
+  edgeCount: number;
+  /** CSR offsets: edges for node i are at indices [edgeOffsets[i], edgeOffsets[i+1]) */
+  edgeOffsets: BufferType;
+  /** Target node index for each edge. */
+  edgeTargets: BufferType;
+  /** Way index for each edge. */
+  edgeWayIndexes: BufferType;
+  /** Distance in meters for each edge. */
+  edgeDistances: BufferType;
+  /** Travel time in seconds for each edge. */
+  edgeTimes: BufferType;
+  /** Bitset: 1 bit per node indicating if routable. */
+  routableBits: BufferType;
+  /** Bitset: 1 bit per node indicating if intersection. */
+  intersectionBits: BufferType;
 }
 
 /** Path segment returned by routing algorithms. */
 export interface PathSegment {
-	/** Node index. */
-	nodeIndex: number
-	/** Way index used to reach this node. */
-	wayIndex?: number
-	/** Previous node in path. */
-	previousNodeIndex?: number
-	/** Cost to reach this node. */
-	cost: number
+  /** Node index. */
+  nodeIndex: number;
+  /** Way index used to reach this node. */
+  wayIndex?: number;
+  /** Previous node in path. */
+  previousNodeIndex?: number;
+  /** Cost to reach this node. */
+  cost: number;
+}
+
+/** Extra graph data that some routing algorithms need. */
+export interface RoutingAlgorithmContext {
+  /**
+   * Incoming edges of a node. In each returned edge, `targetNodeIndex` is the
+   * edge's source node. Required by `bidirectional`.
+   */
+  reverseGraph?: (nodeIndex: number) => GraphEdge[];
+  /**
+   * Fastest edge speed in the graph, in meters per second. Bounds the A* time
+   * heuristic so it never overestimates. Default: 130 km/h.
+   */
+  maxSpeedMps?: number;
 }
 
 /** Function signature for routing algorithms. */
 export type RoutingAlgorithmFn = (
-	graph: (nodeIndex: number) => GraphEdge[],
-	startNodeIndex: number,
-	endNodeIndex: number,
-	getEdgeWeight: (edge: GraphEdge) => number,
-	getNodeCoord?: (nodeIndex: number) => LonLat | undefined,
-	metric?: RoutingMetric,
-) => PathSegment[] | null
+  graph: (nodeIndex: number) => GraphEdge[],
+  startNodeIndex: number,
+  endNodeIndex: number,
+  getEdgeWeight: (edge: GraphEdge) => number,
+  getNodeCoord?: (nodeIndex: number) => LonLat | undefined,
+  metric?: RoutingMetric,
+  context?: RoutingAlgorithmContext,
+) => PathSegment[] | null;

package/src/utils.ts

@@ -6,109 +6,102 @@
  * @module
  */
 
-import type { OsmTags } from "@osmix/shared/types"
-import type { DefaultSpeeds } from "./types.ts"
+import type { OsmTags } from "@osmix/types";
+
+import type { DefaultSpeeds } from "./types.ts";
 
 /** Default speeds (km/h) by highway type. */
 export const DEFAULT_SPEEDS: DefaultSpeeds = {
-	motorway: 120,
-	motorway_link: 60,
-	trunk: 100,
-	trunk_link: 50,
-	primary: 80,
-	primary_link: 50,
-	secondary: 70,
-	secondary_link: 50,
-	tertiary: 60,
-	tertiary_link: 50,
-	unclassified: 50,
-	residential: 30,
-	living_street: 20,
-	service: 20,
-	footway: 5,
-	path: 5,
-	cycleway: 20,
-	bridleway: 10,
-	steps: 2,
-}
+  motorway: 120,
+  motorway_link: 60,
+  trunk: 100,
+  trunk_link: 50,
+  primary: 80,
+  primary_link: 50,
+  secondary: 70,
+  secondary_link: 50,
+  tertiary: 60,
+  tertiary_link: 50,
+  unclassified: 50,
+  residential: 30,
+  living_street: 20,
+  service: 20,
+  footway: 5,
+  path: 5,
+  cycleway: 20,
+  bridleway: 10,
+  steps: 2,
+};
 
 /** Highways included in default vehicle routing. */
 const VEHICLE_HIGHWAYS = new Set([
-	"motorway",
-	"motorway_link",
-	"trunk",
-	"trunk_link",
-	"primary",
-	"primary_link",
-	"secondary",
-	"secondary_link",
-	"tertiary",
-	"tertiary_link",
-	"unclassified",
-	"residential",
-	"living_street",
-	"service",
-])
+  "motorway",
+  "motorway_link",
+  "trunk",
+  "trunk_link",
+  "primary",
+  "primary_link",
+  "secondary",
+  "secondary_link",
+  "tertiary",
+  "tertiary_link",
+  "unclassified",
+  "residential",
+  "living_street",
+  "service",
+]);
 
 /** Footways included in default pedestrian routing. */
-const FOOT_HIGHWAYS = new Set([
-	"footway",
-	"path",
-	"cycleway",
-	"bridleway",
-	"steps",
-])
+const FOOT_HIGHWAYS = new Set(["footway", "path", "cycleway", "bridleway", "steps"]);
 
 /** Parse maxspeed tag to km/h. Handles "50", "50 km/h", "30 mph". */
-export function parseMaxSpeed(
-	value: string | number | undefined,
-): number | null {
-	if (!value) return null
+export function parseMaxSpeed(value: string | number | undefined): number | null {
+  if (!value) return null;
 
-	const str = String(value).trim().toLowerCase()
+  const str = String(value).trim().toLowerCase();
 
-	// Numeric: assume km/h
-	const numeric = str.match(/^(\d+)$/)
-	if (numeric) return Number.parseInt(numeric[1]!, 10)
+  // Numeric: assume km/h
+  const numeric = str.match(/^(\d+)$/);
+  if (numeric) return Number.parseInt(numeric[1]!, 10);
 
-	// Explicit km/h
-	const kmh = str.match(/^(\d+)\s*(km\/h|kmh|kph)$/)
-	if (kmh) return Number.parseInt(kmh[1]!, 10)
+  // Explicit km/h
+  const kmh = str.match(/^(\d+)\s*(km\/h|kmh|kph)$/);
+  if (kmh) return Number.parseInt(kmh[1]!, 10);
 
-	// MPH -> km/h
-	const mph = str.match(/^(\d+)\s*mph$/)
-	if (mph) return Math.round(Number.parseInt(mph[1]!, 10) * 1.60934)
+  // MPH -> km/h
+  const mph = str.match(/^(\d+)\s*mph$/);
+  if (mph) return Math.round(Number.parseInt(mph[1]!, 10) * 1.60934);
 
-	// Special values
-	if (str === "walk" || str === "none") return 5
+  // Special values
+  if (str === "walk" || str === "none") return 5;
 
-	return null
+  return null;
 }
 
 /** Get speed limit (km/h) for a way. */
 export function getSpeedLimit(
-	tags: OsmTags | undefined,
-	defaultSpeeds: DefaultSpeeds = DEFAULT_SPEEDS,
+  tags: OsmTags | undefined,
+  defaultSpeeds: DefaultSpeeds = DEFAULT_SPEEDS,
 ): number {
-	if (tags?.["maxspeed"]) {
-		const parsed = parseMaxSpeed(tags["maxspeed"])
-		if (parsed !== null) return parsed
-	}
+  if (tags?.["maxspeed"]) {
+    const parsed = parseMaxSpeed(tags["maxspeed"]);
+    if (parsed !== null) return parsed;
+  }
 
-	const highway = tags?.["highway"] ? String(tags["highway"]) : undefined
-	if (highway && defaultSpeeds[highway]) return defaultSpeeds[highway]!
+  const highway = tags?.["highway"] ? String(tags["highway"]) : undefined;
+  if (highway && defaultSpeeds[highway]) return defaultSpeeds[highway]!;
 
-	return 50
+  return 50;
 }
 
 /** Default filter: common vehicle highways. */
 export function defaultHighwayFilter(tags?: OsmTags): boolean {
-	if (!tags?.["highway"]) return false
-	return VEHICLE_HIGHWAYS.has(String(tags["highway"]))
+  if (!tags?.["highway"]) return false;
+  return VEHICLE_HIGHWAYS.has(String(tags["highway"]));
 }
 
 /** Default pedestrian filter */
 export function defaultPedestrianFilter(tags?: OsmTags): boolean {
-	if (!tags?.["highway"]) return false
-	return FOOT_HIGHWAYS.has(String(tags["highway"]))
+  if (!tags?.["highway"]) return false;
+  return FOOT_HIGHWAYS.has(String(tags["highway"]));
 }