minotor 11.2.3 → 11.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/CHANGELOG.md +3 -3
  2. package/README.md +27 -0
  3. package/dist/cli.mjs +310 -102
  4. package/dist/cli.mjs.map +1 -1
  5. package/dist/gtfs/parser.d.ts +3 -1
  6. package/dist/gtfs/routes.d.ts +1 -2
  7. package/dist/gtfs/transfers.d.ts +7 -3
  8. package/dist/gtfs/trips.d.ts +2 -1
  9. package/dist/parser.cjs.js +235 -85
  10. package/dist/parser.cjs.js.map +1 -1
  11. package/dist/parser.d.ts +6 -2
  12. package/dist/parser.esm.js +234 -86
  13. package/dist/parser.esm.js.map +1 -1
  14. package/dist/router.cjs.js +1 -1
  15. package/dist/router.cjs.js.map +1 -1
  16. package/dist/router.d.ts +4 -3
  17. package/dist/router.esm.js +1 -1
  18. package/dist/router.esm.js.map +1 -1
  19. package/dist/router.umd.js +1 -1
  20. package/dist/router.umd.js.map +1 -1
  21. package/dist/routing/result.d.ts +1 -4
  22. package/dist/routing/route.d.ts +9 -5
  23. package/dist/timetable/route.d.ts +9 -5
  24. package/dist/timetable/timetable.d.ts +24 -3
  25. package/dist/transfers/__tests__/straightLineTransferGenerator.test.d.ts +1 -0
  26. package/dist/transfers/generator.d.ts +40 -0
  27. package/dist/transfers/straightLineTransferGenerator.d.ts +58 -0
  28. package/dist/utils/map.d.ts +10 -0
  29. package/package.json +1 -1
  30. package/src/__e2e__/router.test.ts +6 -2
  31. package/src/cli/minotor.ts +21 -1
  32. package/src/cli/repl.ts +6 -12
  33. package/src/gtfs/__tests__/parser.test.ts +29 -1
  34. package/src/gtfs/__tests__/routes.test.ts +4 -3
  35. package/src/gtfs/__tests__/transfers.test.ts +108 -21
  36. package/src/gtfs/__tests__/trips.test.ts +60 -24
  37. package/src/gtfs/parser.ts +51 -2
  38. package/src/gtfs/profiles/__tests__/extended.test.ts +2 -1
  39. package/src/gtfs/profiles/extended.ts +14 -14
  40. package/src/gtfs/profiles/standard.ts +11 -10
  41. package/src/gtfs/routes.ts +5 -2
  42. package/src/gtfs/transfers.ts +20 -7
  43. package/src/gtfs/trips.ts +7 -14
  44. package/src/parser.ts +20 -2
  45. package/src/router.ts +12 -6
  46. package/src/routing/__tests__/access.test.ts +14 -6
  47. package/src/routing/__tests__/plainRouter.test.ts +25 -23
  48. package/src/routing/__tests__/plotter.test.ts +8 -3
  49. package/src/routing/__tests__/rangeResult.test.ts +6 -2
  50. package/src/routing/__tests__/rangeRouter.test.ts +10 -6
  51. package/src/routing/__tests__/raptor.test.ts +15 -9
  52. package/src/routing/__tests__/result.test.ts +9 -4
  53. package/src/routing/__tests__/route.test.ts +3 -4
  54. package/src/routing/__tests__/router.test.ts +2 -1
  55. package/src/routing/access.ts +7 -4
  56. package/src/routing/plotter.ts +8 -3
  57. package/src/routing/raptor.ts +5 -5
  58. package/src/routing/result.ts +32 -14
  59. package/src/routing/route.ts +13 -10
  60. package/src/routing/state.ts +1 -1
  61. package/src/timetable/__tests__/io.test.ts +22 -10
  62. package/src/timetable/__tests__/route.test.ts +18 -24
  63. package/src/timetable/__tests__/timetable.test.ts +17 -11
  64. package/src/timetable/io.ts +30 -28
  65. package/src/timetable/route.ts +14 -7
  66. package/src/timetable/timetable.ts +77 -28
  67. package/src/transfers/README.md +97 -0
  68. package/src/transfers/__tests__/straightLineTransferGenerator.test.ts +204 -0
  69. package/src/transfers/generator.ts +45 -0
  70. package/src/transfers/straightLineTransferGenerator.ts +143 -0
  71. package/src/utils/map.ts +22 -0
@@ -0,0 +1,143 @@
1
+ import { distance } from 'geokdbush';
2
+
3
+ import { Stop } from '../stops/stops.js';
4
+ import { StopsIndex } from '../stops/stopsIndex.js';
5
+ import { Duration } from '../timetable/time.js';
6
+ import { Transfer, TransferTypes } from '../timetable/timetable.js';
7
+ import { getOrInsert } from '../utils/map.js';
8
+ import { GeneratedTransfers, TransferGenerator } from './generator.js';
9
+
10
+ export type StraightLineTransferGeneratorOptions = {
11
+ /**
12
+ * Maximum straight-line distance between two stops for a transfer to be generated, in meters.
13
+ */
14
+ maxDistanceMeters?: number;
15
+
16
+ /**
17
+ * Assumed pedestrian walking speed, in kilometers per hour.
18
+ */
19
+ walkingSpeedKmh?: number;
20
+
21
+ /**
22
+ * Multiplier applied to the straight-line distance to approximate the real
23
+ * walking path length. Use 1 to disable.
24
+ */
25
+ detourFactor?: number;
26
+
27
+ /**
28
+ * Flat penalty, in minutes, added to every generated transfer to account for
29
+ * the general overhead of changing (orientation, walking through the
30
+ * station). Use 0 to disable.
31
+ */
32
+ changePenaltyMinutes?: number;
33
+ };
34
+
35
+ const DEFAULT_MAX_DISTANCE_METERS = 500;
36
+ const DEFAULT_WALKING_SPEED_KMH = 4;
37
+ const DEFAULT_DETOUR_FACTOR = 1.3;
38
+ const DEFAULT_CHANGE_PENALTY_MINUTES = 3;
39
+
40
+ /**
41
+ * A {@link TransferGenerator} that connects geographically close stops with
42
+ * virtual walking transfers.
43
+ *
44
+ * The transfer time is derived from the straight-line (great-circle / haversine)
45
+ * distance between two stops, scaled up by a detour factor to approximate the
46
+ * real walking path and divided by an assumed walking speed. This is a
47
+ * deliberately crude heuristic meant to fill in footpaths for feeds that
48
+ * under-specify `transfers.txt` (e.g. large interchanges where subway, tram and
49
+ * bus stops sit close together but are left unconnected).
50
+ *
51
+ * Generated transfers use {@link TransferTypes.REQUIRES_MINIMAL_TIME} so they
52
+ * are treated as walking connections by both the router's transfer step and
53
+ * its access/egress computation. Each origin is connected to its nearby stops
54
+ * with a single directed edge; the reverse edge is produced when the neighbor
55
+ * is itself visited as an origin.
56
+ *
57
+ * On top of the walking time, a flat `changePenaltyMinutes` is added for the
58
+ * general overhead of any change. It is symmetric, so the two directions of a
59
+ * transfer share the same minimum time.
60
+ */
61
+ export class StraightLineTransferGenerator implements TransferGenerator {
62
+ private readonly maxDistanceMeters: number;
63
+ private readonly walkingSpeedKmh: number;
64
+ private readonly detourFactor: number;
65
+ private readonly changePenaltyMinutes: number;
66
+
67
+ constructor(options: StraightLineTransferGeneratorOptions = {}) {
68
+ this.maxDistanceMeters =
69
+ options.maxDistanceMeters ?? DEFAULT_MAX_DISTANCE_METERS;
70
+ this.walkingSpeedKmh = options.walkingSpeedKmh ?? DEFAULT_WALKING_SPEED_KMH;
71
+ this.detourFactor = options.detourFactor ?? DEFAULT_DETOUR_FACTOR;
72
+ this.changePenaltyMinutes =
73
+ options.changePenaltyMinutes ?? DEFAULT_CHANGE_PENALTY_MINUTES;
74
+ }
75
+
76
+ generate(originStops: Stop[], stops: StopsIndex): GeneratedTransfers {
77
+ const generated: GeneratedTransfers = new Map();
78
+ const maxDistanceKm = this.maxDistanceMeters / 1000;
79
+
80
+ for (const origin of originStops) {
81
+ const { id, lat, lon } = origin;
82
+ if (lat === undefined || lon === undefined) {
83
+ continue;
84
+ }
85
+ const neighbors = stops.findStopsByLocation(
86
+ lat,
87
+ lon,
88
+ Infinity,
89
+ maxDistanceKm,
90
+ );
91
+ for (const neighbor of neighbors) {
92
+ const { id: neighborId, lat: neighborLat, lon: neighborLon } = neighbor;
93
+ if (
94
+ neighborId === id ||
95
+ neighborLat === undefined ||
96
+ neighborLon === undefined
97
+ ) {
98
+ continue;
99
+ }
100
+ const walkingTime = this.walkingDuration(
101
+ lon,
102
+ lat,
103
+ neighborLon,
104
+ neighborLat,
105
+ );
106
+ // Emit a single directed edge; the reverse edge is emitted when the
107
+ // neighbor is itself visited as an origin. The penalty is symmetric, so
108
+ // both directions end up with the same minimum time.
109
+ const minTransferTime = walkingTime + this.changePenaltyMinutes;
110
+ this.addTransfer(generated, id, neighborId, minTransferTime);
111
+ }
112
+ }
113
+ return generated;
114
+ }
115
+
116
+ private addTransfer(
117
+ transfers: GeneratedTransfers,
118
+ from: number,
119
+ to: number,
120
+ minTransferTime: Duration,
121
+ ): void {
122
+ const transfer: Transfer = {
123
+ destination: to,
124
+ type: TransferTypes.REQUIRES_MINIMAL_TIME,
125
+ minTransferTime,
126
+ };
127
+ getOrInsert(transfers, from, []).push(transfer);
128
+ }
129
+
130
+ /**
131
+ * Estimates the walking time between two coordinates, in whole minutes.
132
+ */
133
+ private walkingDuration(
134
+ lon1: number,
135
+ lat1: number,
136
+ lon2: number,
137
+ lat2: number,
138
+ ): Duration {
139
+ const straightLineKm = distance(lon1, lat1, lon2, lat2);
140
+ const walkingKm = straightLineKm * this.detourFactor;
141
+ return Math.round((walkingKm / this.walkingSpeedKmh) * 60);
142
+ }
143
+ }
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Returns the value stored under `key`, inserting and returning `defaultValue`
3
+ * when the key is absent. Mirrors the TC39 `Map.prototype.getOrInsert`
4
+ * proposal.
5
+ *
6
+ * TODO: remove this helper and call `map.getOrInsert(key, defaultValue)`
7
+ * directly once we only target Node 26+ (where the method is built in).
8
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/getOrInsert
9
+ */
10
+ export const getOrInsert = <K, V>(
11
+ map: Map<K, V>,
12
+ key: K,
13
+ defaultValue: V,
14
+ ): V => {
15
+ if (map.has(key)) {
16
+ // Key is present, so `get` returns the stored value (which may itself be a
17
+ // legitimately-stored `undefined`).
18
+ return map.get(key) as V;
19
+ }
20
+ map.set(key, defaultValue);
21
+ return defaultValue;
22
+ };