roadgraph-router-v2 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -4,7 +4,343 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims
 to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.3.0] - 2026-10-15
+
+### Added
+
+- **Conditional restrictions, when a route says when it starts.**
+  `router.route(from, to, "fastest", { departAt })` closes the roads shut at
+  that moment to both the search and the snapping, and slows the ones a
+  conditional speed limit slows. The reported duration is the slowed one, not
+  the one the route was planned against.
+
+  `*:conditional` is read from the access ladder — `access`, `vehicle`,
+  `motor_vehicle` and the profile's own key — and from `maxspeed`. Conditions
+  resting on time of day, weekday, month, public holiday and the vehicle's own
+  dimensions are answered, including windows that run past midnight, seasons
+  that span the new year and several windows in one rule. Where more than one
+  rule matches, the last wins, which is what OpenStreetMap specifies.
+
+  Measured on Portugal, where the Ponte 25 de Abril carries
+  `hgv:conditional = no @ (05:00-02:00)`: routing Almada to Lisbon, a lorry
+  with no departure time takes the bridge in 13.0 km, at 03:00 takes it in
+  13.0 km, and at 10:00 detours 63.4 km over the Ponte Vasco da Gama. A car
+  crosses in 12.2 km at every hour. 3,328 of Portugal's 2,760,171 edges carry
+  a conditional restriction, costing 14.8 kB — the bundle grew from 40.17 MB
+  to 40.18 MB — and about 10 ms on a repeat long-distance route.
+
+- **Alternative routes.** `routeAlternatives(from, to, preference, { count })`
+  returns several routes, best first. It finds the best one, makes the roads
+  it used dearer to the search than they really are, and searches again; the
+  penalty steers the search and never reaches the answer, so every route is
+  reported at the graph's own cost. Candidates far worse than the best, or
+  mostly along the same road, are rejected rather than offered, so fewer
+  routes than asked for is the normal answer on a network with one obvious
+  way through.
+
+  Porto to Lisbon returned three routes — 312.0 km, 319.0 km and 350.5 km —
+  in 3.4 s against 2.5 s for the single route, downloading 3.0 MB beyond the
+  29.2 MB the first route needed. A short urban route returned two in 79 ms
+  with nothing further to download.
+
+- **A departure may name the time zone the roads are in.** `timeZone:
+  "Europe/Lisbon"` reads the date there rather than wherever the code runs,
+  which is what a restriction written in local time means. Built on `Intl`;
+  nothing is bundled for it.
+
+- **Weather, who is driving and what for can be answered.**
+  `circumstances: { conditions: ["wet"], userGroups: ["resident"],
+  purposes: ["delivery"] }` makes the rules resting on them apply.
+  Unanswered they never hold, so the behaviour of anyone not passing them is
+  unchanged. `unreadableConditions` now counts only what the parser genuinely
+  cannot read, which is what its name always claimed.
+
+- **Roads the caller knows are shut can be avoided.** `avoid: [{ lat, lng,
+  radiusMeters }]` closes everything a circle touches, to the search and to
+  snapping alike, for that call only. Roadworks and incidents happen after a
+  bundle is compiled and cannot be in it; this is how a caller reading a feed
+  of them says so.
+
+- **`searchWiderCorridor: false`** keeps an alternatives search to the tiles
+  one route needed, trading reach for about three megabytes on a long
+  journey.
+
+- **The compile report counts `conditionalTurnRestrictionsIgnored`.** A turn
+  banned only at certain hours is still banned at every hour; the number now
+  says how much of a region that costs. Across Portugal it is 1 relation in
+  26,599.
+
+### Fixed
+
+- **A road is identified by its shape in order, not by a sum of its points.**
+  Adding coordinates up does not care which point came first, so a road
+  bending north then east and one bending east then north read as the same
+  road and one of them would be dropped as a duplicate alternative.
+
+- **A closure standing on the date line shuts the roads under it.** The
+  projection it was tested against subtracted longitudes at face value, so a
+  road a few metres away measured half a world off.
+
+- **A rule table too wide for its index stops the compile.** It used to drop
+  the surplus rows, which turned a restricted road into an unrestricted one
+  with nothing said. A tile holds up to 65,536 distinct conditional values;
+  past that the compile fails and names `--tile-size-km` as the way through.
+
+- **Two roads joining the same pair of junctions are two roads.** Telling
+  alternatives apart by their endpoints alone treated a slip road and the road
+  beside it as one, hiding a genuine second way there. The Porto to Lisbon
+  corridor holds 12,015 such pairs, none the same length as its twin, so the
+  length now separates them while staying equal for the two directions of one
+  road.
+
+- **Each end of a route counts what it actually drives.** The distance driven
+  on the part-roads a route begins and ends on was split evenly between the
+  two, which misreports overlap whenever one end joins its road near the far
+  junction. `RouteSnap.travelledMeters` now carries the real figure.
+
+- **A month selector is read with the window it governs.**
+  `no @ (Oct 22:00-06:00)` stopped at midnight on the thirty-first instead of
+  running to six on the first of November. `TravelTime` may now carry
+  `dayOfMonth`; without one the answer is unchanged, which is right on thirty
+  days in thirty-one.
+
+- **Alternative options are refused before anything is downloaded**, rather
+  than after a remote bundle has been asked for tiles.
+
+- **A window named with a day is read as one window.** `no @ (Fr 22:00-06:00)`
+  was matched by asking "is it Friday?" and "is it between 22:00 and 06:00?"
+  separately, which answered both ends of it backwards: it applied at two on
+  Friday morning, before it began, and not at two on Saturday morning, while
+  it was still in force. A span running past midnight now belongs to the day
+  it starts on, which also fixes Sunday into Monday.
+
+- **`24:30` is no longer a time.** It parsed as half past midnight, quietly
+  moving a window onto the following day. Only `24:00` is the end of a day.
+
+- **A conditional speed limit keeps its units.** `30 mph @ (…)` was read with
+  `parseFloat` and became 30 km/h — two-thirds of the real limit, applied to
+  the road as fact. It now uses the same parser as a plain `maxspeed`.
+
+- **A rule table too wide for its index drops its surplus.** Past 65,535
+  distinct values the extra rows were kept and left pointing at rule zero,
+  applying one road's restriction to another.
+
+- **Alternatives search the corridor that was downloaded for them.** The
+  widening that fetches the tiles an alternative could lie in replaced the
+  stitched graph, but the search was handed the graph from before it, so the
+  tiles were downloaded and discarded. Asking for a single route no longer
+  widens the corridor at all.
+
+- **Alternatives come back in the order they would be driven**, by their real
+  cost, rather than in the order the penalties happened to find them; and two
+  routes are told apart by the road they travel rather than by which direction
+  of it, so coming back along a road already offered is no longer a different
+  way there.
+
+- **A bundle compiled for one vehicle now carries its conditional
+  restrictions.** They were stored in the per-vehicle chunk, which only exists
+  when a bundle holds several vehicles or one whose routes depend on its size.
+  A `--profile car` compile wrote the single-chunk layout instead, where
+  nothing held them, so every road read as permanently open however carefully
+  a route named its departure time. The restrictions now ride in that layout
+  too, in a header byte no chunk written before them ever used.
+
+  Found while comparing bundle sizes between releases: a car-only Portugal
+  compiled byte for byte the same under 0.2.0 and 0.3.0, which it should not
+  have, since 129 of its ways carry `access:conditional` and 85
+  `motor_vehicle:conditional`. Compiled for motorcycle alone, Monaco now
+  stores the Avenue Pasteur ban it used to drop, and a route across it travels
+  183 m at midday and 3,081 m at 23:00 — the same answers the multi-vehicle
+  bundle gives.
+
+- **Points on a road the network cannot reach no longer report no route.** The
+  road nearest a point is sometimes one nothing may legally enter: a pocket of
+  one-way streets behind banned turns, or an island of service roads. A route
+  to such a point failed outright, however much of the network lay between.
+
+  It now finishes on a road a little further off, trying the nearest few in
+  turn and taking the first that works, and `destinationSnap.distanceMeters`
+  reports how far short it stopped. `finishOnANearbyRoad: false` restores the
+  old behaviour of being told plainly that the point cannot be reached.
+
+  Found on Évora, where `no_left_turn` and `no_right_turn` relations on Rua de
+  Serpa Pinto seal the only entry to a street: Lisbon to a point there now
+  routes 133.2 km, finishing 23 m away, and Braga to Évora routes 460.2 km
+  where both previously failed. Lisbon airport, whose terminal roads are an
+  island 527 m from the nearest road a car can reach, routes too.
+
+### Added
+
+- `edgesWithConditionalRestrictions` in the compile report, beside
+  `edgesWithPhysicalLimits`, so a region's conditional data can be counted
+  rather than assumed.
+
+### Known limitations
+
+- **Nothing changes without `departAt`.** Omitting it ignores conditional
+  restrictions entirely, which is how the library behaved before.
+- **Only closures are applied.** A road the plain tags already forbid stays
+  forbidden where a conditional value would open it, which errs towards
+  refusing a usable road rather than permitting a forbidden one.
+- **One moment for the whole route**, rather than an arrival time per edge. A
+  long route is judged by when it set out.
+- **`restriction:conditional` on a turn restriction relation is still not
+  read.** A morning-peak no-left-turn is enforced at every hour.
+- **Conditions this library cannot answer are counted, not guessed.** Weather,
+  user groups, the purpose of access and a stay duration are parsed, reported
+  by `unreadableConditions`, and then left to one side with the road open.
+- **`departAt` is the local time of the roads travelled.** No time-zone
+  conversion is done and no clock is consulted.
+
+Measured against the earlier releases on one machine: routing is as fast as
+0.2.0 — Porto to Lisbon 2,252 ms cold and 206 ms repeated, against 2,252 and
+208 — and the compiler is 1% slower back to back, 8 min 05 s against
+8 min 01 s, for 0.17 GB more memory. The browser build grew from 21.1 kB
+gzipped to 24.8 kB, and the published tarball from 75.9 kB to 91.0 kB.
+
+Braga to Évora is the one journey that changed materially, and it changed
+from failing to working: 0.2.0 spent 7.9 s widening its corridor before
+reporting no route, where this release finishes in 2.3 s.
+
+### Compatibility
+
+A bundle whose roads carry no conditional restriction is byte for byte the
+file 0.2.0 wrote, in both layouts: the new sections live in header bytes that
+every version so far left as zero. Monaco for a car is 26,177 bytes from
+either compiler. Every bundle published so far still opens and routes
+identically.
+
+A bundle that does carry conditional restrictions cannot be opened by 0.2.0
+or earlier, which report a truncated chunk.
+
+## [0.2.0] - 2026-10-15
+
+Multi-vehicle routing. One bundle can now serve a car, a motorcycle and a
+lorry, and a lorry's routes depend on its size and weight. Walking and cycling
+ship too, in a bundle of their own. Alternative routes moved to 0.3.0.
+
+### Added
+
+- **Coordinates in a shared chunk are written as differences**, which takes
+  about 6% off a multi-vehicle bundle and loses nothing: Portugal for walking
+  and cycling went from 102.3 MB to 96.1 MB, and the three motor vehicles from
+  42.8 MB to 40.2 MB. The single-chunk layout a one-vehicle bundle uses is
+  untouched, so those stay readable by 0.1.0.
+- **Barriers.** A gate, bollard or stile across a road is read from the node
+  and becomes a ban on passing through it, which still lets you turn back the
+  way you came. The same barrier stops different travellers differently: a
+  bollard is nothing on foot and the end of the road in a car, a stile is the
+  reverse. An unfamiliar barrier is left passable rather than guessed at.
+- **`bicycle` and `pedestrian` profiles.** Not motor vehicles with different
+  numbers: a posted limit never makes anyone pedal harder, so the way class
+  decides the pace and `maxspeed` can only lower it; a one-way sign restrains
+  traffic, which a pedestrian is not and a cyclist often has a signed
+  contraflow out of; and footways, paths, steps and cycleways are the network
+  rather than roads left out of it. They need their own bundle — Portugal is
+  102.3 MB for both against 42.8 MB for the three motor vehicles — because
+  folding them in would make every driver download the footpaths.
+- **`motorcycle` and `truck` profiles.** The car profile became a factory
+  parameterised by the mode name, so all three read the same tags in the same
+  order and differ in the key at the bottom of each hierarchy: `motorcar`,
+  `motorcycle`, `hgv`. `truck` caps every speed at 90 km/h rather than only
+  bounding the A* heuristic, because a heavy vehicle is held below the posted
+  limit nearly everywhere.
+- **Physical limits for lorries.** `maxheight`, `maxwidth`, `maxlength` and
+  `maxweight` are read per direction, preferring a limit signed for this
+  direction, then one signed for lorries, then the general one, and taking the
+  stricter of a signed and a `:physical` value. Feet and inches parse. A value
+  that states no number reads as unknown rather than as zero.
+- **Vehicle presets** — `van`, `rigid`, `articulated`, `road-train`,
+  `us-semi` — resolved from the caller, then the bundle's own
+  `--default-vehicle`, then `articulated`. The resolved dimensions are on
+  `router.vehicle`, so a default is visible rather than hidden.
+- **EFR2 v7 and EFRB v2.** A tile is written as a shared chunk holding the road
+  network and one small chunk per vehicle holding its durations, access mask,
+  restriction mask and limits. The directory lists them by `(tile, profile)`,
+  so a reader downloads the shared half plus the one vehicle it wants.
+- **`--profile car,truck,motorcycle`** compiles one bundle for several
+  vehicles, reading the extract once.
+- **`RoadRouter.profiles`, `RoadRouter.profile`, `RoadRouter.withProfile()`**
+  for reading a bundle as another vehicle, reusing every shared chunk already
+  downloaded.
+- **Profile metadata in both formats**, in header bytes that were already
+  reserved, so nothing published grew.
+
+### Changed
+
+- **Repeated routes are about four times faster.** The stitched corridor is
+  cached between routes, and the stitch itself no longer builds a string key
+  per node copy. Porto to Lisbon went from 2107 ms to 534 ms with nothing left
+  to download. `mergedCacheSize` controls it; `0` restores the old behaviour.
+- **The A* heuristic and the tile budget take their speed ceiling from the
+  graph** rather than from the car profile. The heuristic stayed admissible
+  with the wrong ceiling but collapsed towards zero; the tile budget would have
+  over-downloaded badly for a slower vehicle.
+- The car profile also reads `oneway:motor_vehicle`, `oneway:motorcar` and
+  `maxspeed:motorcar`, which only matter where those tags exist.
+
+### Fixed
+
+- **`engines.node` was `>=22.5`**, the compiler's requirement, applied to the
+  whole package — so installing the library on Node 18 or 20 warned, and failed
+  under `engine-strict`. It is now `>=18`, and the CLI checks its own
+  requirement at startup rather than after streaming the whole extract.
+- **Switching vehicle threw when the first one had dimensions.** Opening as a
+  lorry and asking for the car refused the switch, because the dimensions
+  travelled with the options and a car cannot use them. The check moved to
+  where a caller pairs a vehicle with a profile; past that, dimensions travel
+  with the reader and apply only where they mean something, so truck to car to
+  motorcycle and back ends with the dimensions it started with.
+- **Switching vehicle discarded the stitched corridor.** A bundle kept two
+  corridors however many vehicles it held, so three vehicles evicted each
+  other and every switch re-stitched. It keeps one per vehicle now: a repeated
+  Porto to Lisbon fell from about 1500 ms to 257 ms by car, 140 ms by lorry.
+- **A route could fail because an end snapped to a disconnected stub.** The
+  nearest road to a point is not always one that leads anywhere: a path behind
+  a fence, a service road in a compound, a stretch clipped at a tile edge. A
+  failed route is now retried against the piece of the network the other end
+  is in. It runs only after a failure, so an ordinary route never pays for it.
+  Walking and cycling networks feel this most, being full of small fragments.
+- **Merging tiles dropped per-vehicle data.** Limits, access masks and
+  restriction masks are rebased onto the merged numbering, keeping the stricter
+  limit where two tiles disagree. A corridor built from more than one tile
+  would otherwise have routed a lorry under a bridge it does not fit through.
+- A truck bundle written in the single-chunk layout, which has nowhere to keep
+  limits, is refused rather than routed with the dimensions silently ignored.
+
+### Documentation
+
+- **The README now states plainly what a route does not guarantee.** A route
+  is a path over roads the data does not say are forbidden, which is weaker
+  than legal or physical suitability. Time-dependent access, seasonal and
+  weather rules, temporary closures, zone-level lorry bans and low-emission
+  zones, axle load and hazardous goods rules, and untagged limits are all
+  listed as unread, with the consequence for a heavy vehicle said directly:
+  a route may pass under a bridge too low for it or along a street it is
+  banned from at the hour you travel.
+
+### Known limitations
+
+- **Conditional restrictions are not read in this release.**
+  `access:conditional`, `restriction:conditional` and `hgv:conditional` are
+  ignored, so a street closed to lorries overnight or a square pedestrianised
+  on Sundays appears permanently open. It is the limitation most likely to
+  make a route wrong rather than merely longer, particularly for a lorry, so
+  it was scheduled ahead of alternative routes and is addressed under
+  Unreleased above.
+- An active-travel bundle at country scale cannot be compiled with small
+  tiles: Portugal for walking and cycling at 40 km tiles exceeds the
+  compiler's 3 GB ceiling and is refused. The default 120 km works, at the
+  cost of a larger first download for a short urban route.
+- Alternative routes are not in this release; they are planned for 0.3.0,
+  after conditional restrictions.
+
+### Compatibility
+
+Bundles compiled by 0.1.0 open and route identically. A single-vehicle compile
+with no physical limits still writes the one-chunk layout byte for byte. The
+new formats appear only when a bundle holds several vehicles or a vehicle whose
+routes depend on its size, and a 0.1.0 reader cannot open those.
 
 ## [0.1.0] - 2026-10-12
 
@@ -39,6 +375,17 @@ package does rather than how it changed.
 - **Formats.** Reads EFRT v1 and EFR2 v2 through v6; writes EFR2 v6 by default
   and the v2-v5 layout on request.
 
+### Documentation
+
+- **The README now states plainly what a route does not guarantee.** A route
+  is a path over roads the data does not say are forbidden, which is weaker
+  than legal or physical suitability. Time-dependent access, seasonal and
+  weather rules, temporary closures, zone-level lorry bans and low-emission
+  zones, axle load and hazardous goods rules, and untagged limits are all
+  listed as unread, with the consequence for a heavy vehicle said directly:
+  a route may pass under a bridge too low for it or along a street it is
+  banned from at the hour you travel.
+
 ### Known limitations
 
 See the "Supported OSM features and limitations" section of the README.