roadgraph-router-v2 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -62,6 +62,8 @@ interface RoadGraph {
      * for a profile whose routes depend on the vehicle's size. See `./limits`.
      */
     edgeLimits?: EdgeLimits;
+    /** Conditional restrictions for the edges that carry one; absent when none do. */
+    edgeConditions?: EdgeConditions;
     /**
      * One bit per turn restriction, saying whether this vehicle obeys it. The
      * pairs come first, then the sequences. Absent means all of them apply.
@@ -100,6 +102,14 @@ interface RouteSnap {
     point: Coordinate;
     /** How far the requested coordinate was from that road. */
     distanceMeters: number;
+    /**
+     * How far the route actually travels along that road, for an end that
+     * begins or finishes part-way along one. Zero where the end sits on a
+     * junction, and zero at the destination of a route that never leaves a
+     * single road, whose whole length is reported at the origin instead so
+     * that adding the two up gives the route and not twice the route.
+     */
+    travelledMeters?: number;
 }
 interface RouteResult {
     geometry: GeoJsonLineString;
@@ -139,6 +149,26 @@ interface EdgeLimits {
     /** Half-tonnes. */
     weightHalfTonnes: Uint8Array;
 }
+/**
+ * Conditional restrictions for the few edges carrying one: the raw
+ * `value @ condition` text, kept as written and parsed when a bundle opens.
+ *
+ * A side table for the same reason the limits are one — a country has a few
+ * thousand of these among millions of edges. The text is deduplicated into
+ * `values`, because the same working-hours ban is repeated along every segment
+ * of the street it applies to. One edge may have several rows: a lorry ban and
+ * a night speed limit are both conditional and both apply.
+ */
+interface EdgeConditions {
+    /** Sorted by edge, then by kind; an edge may appear more than once. */
+    edges: Uint32Array;
+    /** What the value means: 0 is access, 1 is a speed limit in km/h. */
+    kinds: Uint8Array;
+    /** Index into `values`. */
+    rules: Uint16Array;
+    /** The deduplicated conditional values, as tagged. */
+    values: string[];
+}
 /**
  * A tile's vehicle-independent half: everything a v7 `shared` chunk holds.
  * It is not routable on its own — a profile supplies the durations.
@@ -154,6 +184,8 @@ interface ProfileChunk {
     edgeAccess?: Uint8Array;
     /** Signed limits for the few edges that state any; absent for vehicles whose size does not matter. */
     edgeLimits?: EdgeLimits;
+    /** Conditional restrictions for the edges that carry one; absent when none do. */
+    edgeConditions?: EdgeConditions;
     /**
      * One bit per turn restriction the shared chunk holds, saying whether this
      * vehicle obeys it. `except=hgv` lifts a restriction for lorries and not for
@@ -318,15 +350,76 @@ declare function componentsFor(graph: RoadGraph): Int32Array;
 /** How many nodes carry each label, so the smaller piece can be recognised. */
 declare function componentSizes(labels: Int32Array): Map<number, number>;
 
+/**
+ * Roads the caller knows are shut.
+ *
+ * A compiled bundle is as current as the extract it came from: roadworks, a
+ * burst main, a festival closing the square are all things that happened
+ * after it was built, and nothing inside it can know about them. What it can
+ * do is let whoever does know say so at the time of asking.
+ *
+ * An area rather than a road, because a caller reading an incident feed has a
+ * place and a radius, not an edge number. Anything the circle touches is
+ * closed to the search and to snapping, exactly as a tagged restriction would
+ * be, so a route neither drives through a closure nor starts in the middle of
+ * one.
+ */
+
+/** A circle of road that cannot be driven, whatever the map says. */
+type AvoidArea = {
+    lat: number;
+    lng: number;
+    /** How far the closure reaches from that point. */
+    radiusMeters: number;
+};
+/**
+ * Whether any part of this edge lies inside the circle.
+ *
+ * The whole of each segment counts, not only its ends: a motorway crossing a
+ * closed junction may have no shape point anywhere near it, and testing the
+ * ends alone would drive a route straight through.
+ */
+declare function touchesArea(graph: RoadGraph, edge: number, area: AvoidArea, centre?: Coordinate): boolean;
+/**
+ * The access mask with every road the caller has closed cleared as well.
+ *
+ * Only the roads near each circle are looked at, so closing a junction costs
+ * the same whether the graph holds a town or a country.
+ */
+declare function accessAvoiding(graph: RoadGraph, areas: AvoidArea[] | undefined, base?: Uint8Array): Uint8Array | undefined;
+/** How many roads these closures take away, for reporting rather than routing. */
+declare function countAvoided(graph: RoadGraph, areas: AvoidArea[] | undefined): number;
+
+/**
+ * Reading a speed off an OSM tag.
+ *
+ * It lives on its own because both the profiles and the conditional
+ * restrictions need it, and a conditional limit is written in the same units
+ * as a plain one: `maxspeed:conditional = 30 mph @ (Mo-Fr 07:00-19:00)` means
+ * 30 mph, not 30 km/h.
+ */
+/** Kilometres per hour, or null when the value is not a speed this reads. */
+declare function parseMaxSpeedKph(value: string | undefined): number | null;
+
 /**
  * Routing profiles turn raw OSM tags into routable facts: may a vehicle use
  * this way, in which directions, and how fast. Keeping the rules behind one
  * interface lets the compiler stay generic — it never inspects a tag itself —
  * and lets the rules be unit-tested without a PBF file.
  */
+
 type OsmTags = Record<string, string | undefined>;
 /** How a profile may traverse one OSM way. */
 type WayTraversal = {
+    /**
+     * Conditional restrictions tagged on the way, kept as written for the
+     * router to evaluate against a departure time. They apply to both
+     * directions: OSM states these per vehicle class, not per direction.
+     */
+    conditions?: {
+        kind: number;
+        value: string;
+    }[];
     /** Travel from the first node reference towards the last is allowed. */
     forward: boolean;
     /** Travel from the last node reference towards the first is allowed. */
@@ -398,13 +491,6 @@ interface RoutingProfile {
      */
     evaluateBarrier?(tags: OsmTags): boolean;
 }
-/**
- * Reads a `maxspeed`-style value. Returns null for every value that is not a
- * plain number with an optional unit — country codes such as `PT:urban`,
- * `none`, `signals` and `variable` included — so the caller can fall back to a
- * class default instead of inventing a country-specific table.
- */
-declare function parseMaxSpeedKph(value: string | undefined): number | null;
 /**
  * Reads a `maxheight`-style value in metres. Feet and inches are accepted
  * because they are how the limit is written wherever it is signed that way;
@@ -535,6 +621,188 @@ declare function accessForVehicle(graph: RoadGraph, vehicle: VehicleDimensions |
 /** How many edges this vehicle may not use, for reporting rather than routing. */
 declare function countBlocked(graph: RoadGraph, vehicle: VehicleDimensions): number;
 
+/**
+ * Conditional restrictions: `hgv:conditional = no @ (Mo-Fr 07:00-19:00)`.
+ *
+ * A road can be closed overnight, a square pedestrianised on Sundays, a bridge
+ * limited to 7.5 tonnes only for vehicles over a certain length. Until now
+ * every one of those read as permanently open, which is the limitation most
+ * likely to make a route wrong rather than merely longer.
+ *
+ * The value is a list of `value @ condition` pairs separated by semicolons,
+ * and where several match, OpenStreetMap says the **last** one wins — the
+ * convention being to write the general rule first and the specific one last.
+ *
+ * Not every condition can be answered. Weather, a driver's occupation and a
+ * stay duration are not things a compiled graph knows, and a rule resting on
+ * one is kept but marked, so a caller can count what was not understood
+ * instead of being told silently that a road is open.
+ */
+
+/**
+ * How many distinct conditional values one table can hold. The stored index
+ * is sixteen bits wide, so the values are numbered 0 to 65535.
+ */
+declare const MAX_STORED_VALUES = 65536;
+/** When a journey passes, in the local time of the road it passes on. */
+type TravelTime = {
+    /** 0 is Monday, 6 is Sunday. */
+    weekday: number;
+    /** Minutes since midnight, 0 to 1439. */
+    minutes: number;
+    /** 1 to 12, for a seasonal rule. */
+    month: number;
+    /**
+     * The day of the month, 1 to 31. Only a span running past midnight needs
+     * it, to know whether the morning it ends on began in the month before.
+     * Leaving it out treats such a morning as belonging to the current month,
+     * which is right on every day but the first.
+     */
+    dayOfMonth?: number;
+    /** Whether it is a public holiday there, which only a caller can know. */
+    publicHoliday?: boolean;
+};
+/** A span of minutes within a day, which may run past midnight. */
+type MinuteSpan = {
+    from: number;
+    to: number;
+};
+/** An inclusive range of weekdays, months, or anything else counted in order. */
+type Range = {
+    from: number;
+    to: number;
+};
+/** A measurement of the vehicle compared against a number, as `weight>7.5`. */
+type VehicleComparison = {
+    property: "weight" | "height" | "width" | "length";
+    operator: "<" | "<=" | ">" | ">=" | "=";
+    amount: number;
+};
+/** One `(...)` group: every part present must hold for the group to match. */
+type Condition = {
+    days?: Range[];
+    times?: MinuteSpan[];
+    months?: Range[];
+    publicHoliday?: boolean;
+    vehicle?: VehicleComparison[];
+    /**
+     * Circumstances this library cannot know by itself: the weather, who is
+     * driving, what for. They are read from the tag and answered only by a
+     * caller who says so; unanswered, the condition does not hold.
+     */
+    circumstances?: string[];
+    /**
+     * The part of the condition this parser could not read at all — a stay
+     * duration, a form of words nobody has taught it. A condition carrying one
+     * is never matched, and is counted so it can be reported rather than
+     * quietly ignored.
+     */
+    unreadable?: string;
+};
+/**
+ * What the caller knows that the map does not: whether it is raining, who is
+ * at the wheel, what the journey is for. A conditional rule resting on one of
+ * these is ignored unless the answer is given here.
+ */
+type Circumstances = {
+    /** Named states of the road or sky, such as `wet`, `snow`, `ice`. */
+    conditions?: string[];
+    /** Who is driving, such as `disabled`, `resident`, `emergency`. */
+    userGroups?: string[];
+    /** Why, such as `delivery`, `destination`, `agricultural`. */
+    purposes?: string[];
+};
+type ConditionalRule = {
+    /** What applies when the condition holds: `no`, `destination`, `30`, `7.5`. */
+    value: string;
+    /** Any of these matching makes the rule apply, as `Mo-Fr 07:00-19:00, Sa 08:00-12:00`. */
+    conditions: Condition[];
+};
+/**
+ * Reads a `*:conditional` value into its rules. An empty list means the value
+ * was not a conditional expression at all.
+ */
+declare function parseConditional(value: string | undefined): ConditionalRule[];
+/** Whether one condition group holds at this moment, for this vehicle. */
+declare function conditionHolds(condition: Condition, when: TravelTime, vehicle?: VehicleDimensions, circumstances?: Circumstances): boolean;
+/**
+ * What a conditional value comes to at this moment, or null when none of its
+ * rules applies. Where several match, the last wins, which is what
+ * OpenStreetMap says and why the convention is general first, specific last.
+ */
+declare function conditionalValue(rules: ConditionalRule[], when: TravelTime, vehicle?: VehicleDimensions, circumstances?: Circumstances): string | null;
+/**
+ * How many of these rules rest on something this parser cannot read at all.
+ * A rule resting on the weather or on who is driving is readable and is not
+ * counted here; it simply needs a caller to answer it.
+ */
+declare function unreadableConditions(rules: ConditionalRule[]): number;
+/**
+ * The moment a journey is travelled.
+ *
+ * Without a time zone the date is read as the machine reads it, which is
+ * right when the roads and the reader are in the same place and wrong by
+ * however many hours when they are not. Naming the zone the roads are in —
+ * `"Europe/Lisbon"` — reads the date there instead, which is what a
+ * restriction written in local time means.
+ *
+ * The zone names are the IANA ones the platform already knows; nothing is
+ * bundled for this.
+ */
+declare function travelTimeFrom(date: Date, publicHoliday?: boolean, timeZone?: string): TravelTime;
+/** What a stored conditional row says: an access rule or a speed limit. */
+declare const ConditionKind: {
+    readonly access: 0;
+    readonly maxspeed: 1;
+};
+/** Collects what a compiler found into the stored side table. */
+declare function packEdgeConditions(entries: {
+    edge: number;
+    kind: number;
+    value: string;
+}[]): EdgeConditions | undefined;
+/** A bundle's conditional values parsed once, rather than per edge per search. */
+type ParsedConditions = {
+    table: EdgeConditions;
+    parsed: ConditionalRule[][];
+};
+declare function parseEdgeConditions(table: EdgeConditions | undefined): ParsedConditions | undefined;
+/**
+ * What the conditional rules say about one edge at one moment: whether it is
+ * closed, and any speed limit that applies.
+ *
+ * `destination` and the permit-style values count as closed because this
+ * library has no notion of a journey's purpose, and treating "only if you live
+ * here" as open would route strangers down a residents' street.
+ */
+declare function conditionsOnEdge(conditions: ParsedConditions, edge: number, when: TravelTime, vehicle?: VehicleDimensions, circumstances?: Circumstances): {
+    closed: boolean;
+    speedKph: number | undefined;
+};
+/**
+ * The access mask for a departure time: the graph's own with the roads shut at
+ * that moment cleared as well.
+ *
+ * Only closures are applied. A road whose plain tags already forbid it stays
+ * forbidden even where a conditional value would open it, because the stored
+ * mask has already dropped it and reopening one would need the compiler to
+ * keep roads it currently discards. That errs towards refusing a road that is
+ * in fact usable, which is the direction this library errs in everywhere else.
+ */
+declare function accessAtTime(graph: Pick<RoadGraph, "edgeTargets" | "edgeAccess">, conditions: ParsedConditions | undefined, when: TravelTime | undefined, vehicle?: VehicleDimensions, base?: Uint8Array, circumstances?: Circumstances): Uint8Array | undefined;
+/** How many edges this moment closes, for reporting rather than routing. */
+declare function countClosedAt(graph: Pick<RoadGraph, "edgeTargets" | "edgeAccess">, conditions: ParsedConditions | undefined, when: TravelTime, vehicle?: VehicleDimensions): number;
+declare function conditionsOf(graph: Pick<RoadGraph, "edgeConditions">): ParsedConditions | undefined;
+/**
+ * The edges a conditional speed limit slows at this moment, as whole seconds.
+ *
+ * A conditional limit may only slow an edge, never speed it up. A faster
+ * stored duration is left alone, because the A* bound is built from the
+ * profile's ceiling and an edge quicker than the graph says would break the
+ * guarantee that the route found is the best one.
+ */
+declare function conditionalDurations(graph: Pick<RoadGraph, "edgeTargets" | "edgeDistancesMeters" | "edgeDistanceScale" | "edgeDurationsSeconds" | "edgeDurationScale">, conditions: ParsedConditions | undefined, when: TravelTime, vehicle?: VehicleDimensions, circumstances?: Circumstances): Map<number, number> | undefined;
+
 /**
  * The nearest routing node to a coordinate. After topology simplification a
  * node is a junction rather than an arbitrary point on a road, so on a long
@@ -555,74 +823,130 @@ type RouteOptions = {
      * is too large or too heavy for are closed to the search and to snapping.
      */
     vehicle?: VehicleDimensions;
+    /**
+     * When the journey starts, in the local time of the roads being travelled.
+     *
+     * Leaving it out ignores every conditional restriction, which is what this
+     * library did before it could read them: a road closed only at certain hours
+     * counts as open. Supplying it closes the roads shut at that moment and
+     * slows the ones a conditional speed limit slows.
+     *
+     * One moment is used for the whole route rather than an arrival time per
+     * edge. A route crossing a boundary as a restriction begins is therefore
+     * judged by where it set out, which is the honest limit of a departure time.
+     */
+    departAt?: Date | TravelTime;
+    /** Whether that day is a public holiday, which only a caller can know. */
+    publicHoliday?: boolean;
+    /**
+     * The time zone the roads are in, as an IANA name such as
+     * `"Europe/Lisbon"`. A restriction is written in the local time of the road
+     * it is on, so a caller routing somewhere other than where it is running
+     * should say where. Left out, a `Date` is read as this machine reads it.
+     */
+    timeZone?: string;
+    /**
+     * What the map cannot know: whether it is raining, who is driving, what the
+     * journey is for. A conditional rule resting on one of these is ignored
+     * unless it is answered here, so a road shut `@ (wet)` stays open until a
+     * caller says it is wet.
+     */
+    circumstances?: Circumstances;
+    /**
+     * Roads the caller knows are shut — roadworks, an incident, an event. A
+     * compiled bundle cannot know about any of them; whoever is reading a feed
+     * of them can say so here, and the search will neither drive through a
+     * closure nor begin in the middle of one.
+     */
+    avoid?: AvoidArea[];
+    /**
+     * Multipliers making certain edges dearer to the search than they really
+     * are, used to push a search away from a route already found. The route
+     * reported back is always priced at the graph's own cost, so a penalty
+     * changes which roads are chosen and never what they are said to cost.
+     */
+    costPenalties?: ReadonlyMap<number, number>;
+    /**
+     * Whether a route that cannot reach the road nearest its destination may
+     * finish on one a little further away. On by default, because the nearest
+     * road is sometimes one the network cannot legally enter — a pocket of
+     * one-way streets behind banned turns, an island of service roads — and
+     * refusing to route at all is a worse answer than finishing nearby.
+     *
+     * Turn it off to be told plainly that the point asked for cannot be
+     * reached. `RouteResult.destinationSnap.distanceMeters` reports how far
+     * short a route finished either way.
+     */
+    finishOnANearbyRoad?: boolean;
 };
 declare function route(graph: RoadGraph, from: Coordinate, to: Coordinate, preference?: RoutePreference, options?: RouteOptions): RouteResult;
 
-/** Where a coordinate lands on one directed edge. */
-type EdgeProjection = {
-    edge: number;
-    source: number;
-    target: number;
-    /** How far along the edge the projection sits, 0 at the source and 1 at the target. */
-    fraction: number;
-    /** The point on the road itself. */
-    point: Coordinate;
-    /** Distance from the queried coordinate to that point. */
-    distanceMeters: number;
-    /** Index of the polyline vertex the projection follows, for slicing geometry. */
-    vertexIndex: number;
-    polyline: Coordinate[];
-};
 /**
- * Snapping a coordinate onto the graph. A `node` snap behaves exactly as this
- * package always has; an `edge` snap carries one projection per directed edge
- * covering the same stretch of road, so a two-way road offers both directions
- * and a one-way road offers only the legal one.
+ * Several ways to get there, not just the best one.
+ *
+ * A second route is only worth offering if it is genuinely different and not
+ * much worse. The method here is the simple one: find the best route, make the
+ * roads it used dearer to the search than they really are, and search again.
+ * A road that is the only sensible way through survives the penalty and is
+ * used again; one that was merely convenient gives way to its neighbour.
+ *
+ * The penalty never reaches the answer. A route is always reported at the
+ * graph's own cost, so an alternative's distance and duration are what it
+ * would really take, not what the search was told to believe.
+ *
+ * Candidates are then filtered rather than trusted: one that reuses most of a
+ * route already offered, or that is far worse than the best, is not an
+ * alternative anybody wants. What comes back is in order, best first.
  */
-type GraphSnap = {
-    kind: "node";
-    node: number;
-    point: Coordinate;
-    distanceMeters: number;
-} | {
-    kind: "edge";
-    projections: EdgeProjection[];
-    point: Coordinate;
-    distanceMeters: number;
+
+type AlternativeRoutesOptions = Omit<RouteOptions, "costPenalties" | "costBound"> & {
+    /** How many routes to return at most, the best one included. Default 3. */
+    count?: number;
+    /**
+     * How much worse than the best route an alternative may be. 1.4 allows one
+     * taking 40% longer; raising it offers more routes and worse ones.
+     */
+    maxStretch?: number;
+    /**
+     * How much of the routes already offered an alternative may reuse, measured
+     * by distance. 0.75 rejects one that is three-quarters the same road.
+     */
+    maxSharing?: number;
+    /**
+     * How much dearer a road already used is made to look. Too small and the
+     * search returns the same route again; too large and it flees onto
+     * absurdities. Default 2.
+     */
+    penaltyFactor?: number;
+    /**
+     * Whether to download the wider corridor an alternative might lie in.
+     *
+     * On by default, because an alternative is allowed to be worse than the
+     * best by `maxStretch` and the tiles holding one therefore reach further
+     * than the tiles that proved the best route. On a long journey that is
+     * about three megabytes more map. Turning it off keeps the download to
+     * what one route needed and offers only the alternatives already inside
+     * it, which on a dense network is usually most of them.
+     */
+    searchWiderCorridor?: boolean;
 };
 /**
- * Finds the road nearest to a coordinate. Returns null when nothing routable
- * lies within `maxDistanceMeters` of the coordinate — measured to the road
- * surface, not to the nearest junction.
+ * Rejects options that would make the search unbounded or meaningless.
+ *
+ * Exported so the public entry point can refuse them before it downloads
+ * anything: a caller who passed `count: NaN` should be told so, not billed
+ * for a corridor first.
  */
-declare function snapToGraph(graph: RoadGraph, coordinate: Coordinate, maxDistanceMeters?: number, access?: Uint8Array | undefined, accept?: (node: number) => boolean): GraphSnap | null;
-
+declare function checkAlternativeOptions(options: AlternativeRoutesOptions): void;
 /**
- * A uniform-grid index over directed edges. Snapping needs the nearest *road*,
- * not the nearest junction: after topology simplification a rural edge can run
- * for a kilometre without a node, so a node-only index cannot answer "which
- * road am I standing on".
+ * Routes from one point to another, best first, with up to `count - 1`
+ * genuinely different alternatives after it.
  *
- * Each edge is registered in every cell its bounding box touches, which keeps
- * construction linear and lookups to a handful of cells.
+ * Returns at least the best route; fewer than `count` means the graph held
+ * nothing else worth offering, which is the usual answer on a road network
+ * with one obvious way through.
  */
-type EdgeSpatialIndex = {
-    cellSizeDegrees: number;
-    cells: Map<string, Uint32Array>;
-    /** Edges whose extent covers too many cells to list individually. */
-    oversized: Uint32Array;
-};
-/** Recovers an edge's source node from the CSR offsets. */
-declare function edgeSource(graph: RoadGraph, edge: number): number;
-/** The full vertex list of a directed edge: source node, shape points, target node. */
-declare function edgePolyline(graph: RoadGraph, edge: number, source?: number): Coordinate[];
-declare function createEdgeSpatialIndex(graph: RoadGraph, cellSizeDegrees?: number): EdgeSpatialIndex;
-declare function edgeSpatialIndexFor(graph: RoadGraph, cellSizeDegrees?: number): EdgeSpatialIndex;
-declare function nearbyEdgeIds(index: EdgeSpatialIndex, coordinate: Coordinate, maxDistanceMeters: number): Set<number>;
-
-/** Builds a uniform-grid index. It can be created after decoding without changing the graph format. */
-declare function createSpatialIndex(graph: RoadGraph, cellSizeDegrees?: number): NodeSpatialIndex;
-declare function withSpatialIndex(graph: RoadGraph, cellSizeDegrees?: number): RoadGraph;
+declare function routeAlternatives(graph: RoadGraph, from: Coordinate, to: Coordinate, preference?: RoutePreference, options?: AlternativeRoutesOptions): RouteResult[];
 
 type FetchLike$2 = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
 /**
@@ -653,6 +977,8 @@ type RoadRouterOptions = {
  * High-level route entry point. `open()` accepts an EFRB bundle, an EFRT
  * manifest, or an already-decoded graph.
  */
+/** When a journey starts, for the conditional restrictions that depend on it. */
+type DepartureOptions = Pick<RouteOptions, "departAt" | "publicHoliday" | "timeZone" | "circumstances" | "avoid">;
 declare class RoadRouter {
     private readonly graph?;
     private readonly loader?;
@@ -685,7 +1011,12 @@ declare class RoadRouter {
      * network once: switching vehicle costs only the small per-vehicle chunks.
      */
     withProfile(name: string): RoadRouter;
-    route(from: Coordinate, to: Coordinate, preference?: RoutePreference): Promise<RouteResult>;
+    /**
+     * `when` says when the journey starts, so conditional restrictions apply.
+     * Leaving it out ignores them, which is how this library behaved before it
+     * could read them.
+     */
+    route(from: Coordinate, to: Coordinate, preference?: RoutePreference, when?: DepartureOptions): Promise<RouteResult>;
     /**
      * Downloads a corridor, routes, then asks whether any tile left out could
      * still hold something better. A route through a tile costs at least the
@@ -695,10 +1026,93 @@ declare class RoadRouter {
      * graph contains. Because the test measures ground distance rather than
      * counting neighbours, the answer does not depend on the tile size.
      */
+    /**
+     * Several ways there, best first, with up to `count - 1` alternatives after
+     * it. Fewer than asked for means the network held nothing else worth
+     * offering, which is the usual answer where there is one obvious way.
+     *
+     * Over a bundle this downloads a wider corridor than a single route needs:
+     * an alternative may be worse than the best by as much as `maxStretch`, and
+     * the tiles holding it lie outside the corridor that proved the best route.
+     */
+    routeAlternatives(from: Coordinate, to: Coordinate, preference?: RoutePreference, options?: AlternativeRoutesOptions): Promise<RouteResult[]>;
     private routeOverBundle;
+    /**
+     * The same corridor walk, stopping with the graph it settled on as well as
+     * the route. Alternatives need the graph, and need to be able to widen it
+     * once more: a second route may be worse than the best by more than the
+     * corridor was ever sized to hold.
+     */
+    private bestOverBundle;
     private routeOverLoader;
 }
 
+/** Where a coordinate lands on one directed edge. */
+type EdgeProjection = {
+    edge: number;
+    source: number;
+    target: number;
+    /** How far along the edge the projection sits, 0 at the source and 1 at the target. */
+    fraction: number;
+    /** The point on the road itself. */
+    point: Coordinate;
+    /** Distance from the queried coordinate to that point. */
+    distanceMeters: number;
+    /** Index of the polyline vertex the projection follows, for slicing geometry. */
+    vertexIndex: number;
+    polyline: Coordinate[];
+};
+/**
+ * Snapping a coordinate onto the graph. A `node` snap behaves exactly as this
+ * package always has; an `edge` snap carries one projection per directed edge
+ * covering the same stretch of road, so a two-way road offers both directions
+ * and a one-way road offers only the legal one.
+ */
+type GraphSnap = {
+    kind: "node";
+    node: number;
+    point: Coordinate;
+    distanceMeters: number;
+} | {
+    kind: "edge";
+    projections: EdgeProjection[];
+    point: Coordinate;
+    distanceMeters: number;
+};
+/**
+ * Finds the road nearest to a coordinate. Returns null when nothing routable
+ * lies within `maxDistanceMeters` of the coordinate — measured to the road
+ * surface, not to the nearest junction.
+ */
+declare function snapToGraph(graph: RoadGraph, coordinate: Coordinate, maxDistanceMeters?: number, access?: Uint8Array | undefined, accept?: (node: number) => boolean, everyNearbyRoad?: boolean): GraphSnap | null;
+
+/**
+ * A uniform-grid index over directed edges. Snapping needs the nearest *road*,
+ * not the nearest junction: after topology simplification a rural edge can run
+ * for a kilometre without a node, so a node-only index cannot answer "which
+ * road am I standing on".
+ *
+ * Each edge is registered in every cell its bounding box touches, which keeps
+ * construction linear and lookups to a handful of cells.
+ */
+type EdgeSpatialIndex = {
+    cellSizeDegrees: number;
+    cells: Map<string, Uint32Array>;
+    /** Edges whose extent covers too many cells to list individually. */
+    oversized: Uint32Array;
+};
+/** Recovers an edge's source node from the CSR offsets. */
+declare function edgeSource(graph: RoadGraph, edge: number): number;
+/** The full vertex list of a directed edge: source node, shape points, target node. */
+declare function edgePolyline(graph: RoadGraph, edge: number, source?: number): Coordinate[];
+declare function createEdgeSpatialIndex(graph: RoadGraph, cellSizeDegrees?: number): EdgeSpatialIndex;
+declare function edgeSpatialIndexFor(graph: RoadGraph, cellSizeDegrees?: number): EdgeSpatialIndex;
+declare function nearbyEdgeIds(index: EdgeSpatialIndex, coordinate: Coordinate, maxDistanceMeters: number): Set<number>;
+
+/** Builds a uniform-grid index. It can be created after decoding without changing the graph format. */
+declare function createSpatialIndex(graph: RoadGraph, cellSizeDegrees?: number): NodeSpatialIndex;
+declare function withSpatialIndex(graph: RoadGraph, cellSizeDegrees?: number): RoadGraph;
+
 declare const BundleCompression: {
     readonly none: 0;
     readonly gzip: 1;
@@ -938,4 +1352,4 @@ type GuardedJunctions = {
 };
 declare function guardedJunctionsFor(graph: RoadGraph, restrictions: TurnRestrictionIndex | null, sequences: TurnSequenceIndex | null): GuardedJunctions;
 
-export { type BundleBounds, type BundleChunkRef, BundleCompression, type BundleEncodeOptions, type BundleGraphTile, type BundleOpenOptions, type BundleProfiledTile, type BundleTile, type CompactEncodeOptions, type CompactGraphOptions, type Coordinate, type CoordinateStorage, DEFAULT_VEHICLE_PRESET, type EdgeLimits, type EdgeProjection, type EdgeSpatialIndex, type EdgeWeightStorage, type GeoJsonLineString, type GeoJsonPosition, type GraphBounds, type GraphSnap, type GraphTile, type GuardedJunctions, type NodeSpatialIndex, type OsmTags, type ParsedTurnRestriction, type ProfileChunk, ProfileId, type RoadGraph, type RoadGraphBundle, RoadRouter, type RoadRouterOptions, type RouteGraphLoader, type RouteGraphManifest, type RouteOptions, type RoutePreference, type RouteResult, type RouteSnap, RouterError, type RouterErrorCode, type RoutingProfile, type SearchBounds, type SharedRoadGraph, type TurnRestrictionIndex, type TurnRestrictionKind, type TurnSequenceIndex, VEHICLE_PRESETS, VarintReader, VarintWriter, type VehicleDimensions, type VehicleInput, type VehicleLimits, VehiclePresetId, type WayTraversal, accessForVehicle, accessMaskFor, allowsEverything, buildTurnRestrictionIndex, buildTurnSequenceIndex, carRoutingProfile, combineProfiledGraph, compactGraph, componentSizes, componentsFor, countBlocked, createEdgeSpatialIndex, createRouteGraphLoader, createSpatialIndex, decodeGraph, decodeProfileChunk, decodeSharedGraph, distanceToBounds, edgeAllowed, edgePolyline, edgeSource, edgeSpatialIndexFor, encodeCompactGraph, encodeCompressedRoadGraphBundle, encodeGraph, encodeProfileChunk, encodeProfiledRoadGraphBundle, encodeRoadGraphBundle, encodeSharedGraph, findNearestNode, fromDecimetres, fromHalfTonnes, getRoutingProfile, getRoutingProfileById, guardedJunctionsFor, isTurnBanned, maxSpeedMpsFor, mergeRoadGraphs, motorcycleRoutingProfile, nearbyEdgeIds, openRoadGraphBundle, packEdgeLimits, packTurnRestrictions, packTurnSequences, parseLengthMeters, parseMaxSpeedKph, parseWeightTonnes, profileOf, resolveVehicle, route, routingProfiles, searchBoundsFor, snapToGraph, straightLineAtMost, toDecimetres, toHalfTonnes, truckRoutingProfile, unzigzag, vehiclePreset, vehiclePresetName, withSpatialIndex, zigzag };
+export { type AlternativeRoutesOptions, type AvoidArea, type BundleBounds, type BundleChunkRef, BundleCompression, type BundleEncodeOptions, type BundleGraphTile, type BundleOpenOptions, type BundleProfiledTile, type BundleTile, type Circumstances, type CompactEncodeOptions, type CompactGraphOptions, type Condition, ConditionKind, type ConditionalRule, type Coordinate, type CoordinateStorage, DEFAULT_VEHICLE_PRESET, type DepartureOptions, type EdgeConditions, type EdgeLimits, type EdgeProjection, type EdgeSpatialIndex, type EdgeWeightStorage, type GeoJsonLineString, type GeoJsonPosition, type GraphBounds, type GraphSnap, type GraphTile, type GuardedJunctions, MAX_STORED_VALUES, type MinuteSpan, type NodeSpatialIndex, type OsmTags, type ParsedConditions, type ParsedTurnRestriction, type ProfileChunk, ProfileId, type RoadGraph, type RoadGraphBundle, RoadRouter, type RoadRouterOptions, type RouteGraphLoader, type RouteGraphManifest, type RouteOptions, type RoutePreference, type RouteResult, type RouteSnap, RouterError, type RouterErrorCode, type RoutingProfile, type SearchBounds, type SharedRoadGraph, type TravelTime, type TurnRestrictionIndex, type TurnRestrictionKind, type TurnSequenceIndex, VEHICLE_PRESETS, VarintReader, VarintWriter, type VehicleComparison, type VehicleDimensions, type VehicleInput, type VehicleLimits, VehiclePresetId, type WayTraversal, accessAtTime, accessAvoiding, accessForVehicle, accessMaskFor, allowsEverything, buildTurnRestrictionIndex, buildTurnSequenceIndex, carRoutingProfile, checkAlternativeOptions, combineProfiledGraph, compactGraph, componentSizes, componentsFor, conditionHolds, conditionalDurations, conditionalValue, conditionsOf, conditionsOnEdge, countAvoided, countBlocked, countClosedAt, createEdgeSpatialIndex, createRouteGraphLoader, createSpatialIndex, decodeGraph, decodeProfileChunk, decodeSharedGraph, distanceToBounds, edgeAllowed, edgePolyline, edgeSource, edgeSpatialIndexFor, encodeCompactGraph, encodeCompressedRoadGraphBundle, encodeGraph, encodeProfileChunk, encodeProfiledRoadGraphBundle, encodeRoadGraphBundle, encodeSharedGraph, findNearestNode, fromDecimetres, fromHalfTonnes, getRoutingProfile, getRoutingProfileById, guardedJunctionsFor, isTurnBanned, maxSpeedMpsFor, mergeRoadGraphs, motorcycleRoutingProfile, nearbyEdgeIds, openRoadGraphBundle, packEdgeConditions, packEdgeLimits, packTurnRestrictions, packTurnSequences, parseConditional, parseEdgeConditions, parseLengthMeters, parseMaxSpeedKph, parseWeightTonnes, profileOf, resolveVehicle, route, routeAlternatives, routingProfiles, searchBoundsFor, snapToGraph, straightLineAtMost, toDecimetres, toHalfTonnes, touchesArea, travelTimeFrom, truckRoutingProfile, unreadableConditions, unzigzag, vehiclePreset, vehiclePresetName, withSpatialIndex, zigzag };