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
@@ -3,10 +3,6 @@ import { SourceStopId, StopId } from '../stops/stops.js';
3
3
  import { StopsIndex } from '../stops/stopsIndex.js';
4
4
  import { Route } from './route.js';
5
5
  import { Arrival, RoutingState } from './router.js';
6
- /**
7
- * Details about the pickup and drop-off modalities at each stop in each trip of a route.
8
- */
9
- export type PickUpDropOffType = 'REGULAR' | 'NOT_AVAILABLE' | 'MUST_PHONE_AGENCY' | 'MUST_COORDINATE_WITH_DRIVER';
10
6
  export declare class Result {
11
7
  private readonly destinations;
12
8
  readonly routingState: RoutingState;
@@ -42,6 +38,7 @@ export declare class Result {
42
38
  * @returns a route to the destination stop if it exists.
43
39
  */
44
40
  bestRoute(to?: StopId | Set<StopId>): Route | undefined;
41
+ private buildServiceRouteInfo;
45
42
  /**
46
43
  * Builds a vehicle leg from a chain of vehicle edges.
47
44
  *
@@ -1,7 +1,11 @@
1
1
  import { Stop } from '../stops/stops.js';
2
+ import type { PickUpDropOffTypeString } from '../timetable/route.js';
2
3
  import { Duration, Time } from '../timetable/time.js';
3
- import { ServiceRouteInfo, TransferType } from '../timetable/timetable.js';
4
- export type PickUpDropOffType = 'REGULAR' | 'NOT_AVAILABLE' | 'MUST_PHONE_AGENCY' | 'MUST_COORDINATE_WITH_DRIVER';
4
+ import type { RouteTypeString, TransferTypeString } from '../timetable/timetable.js';
5
+ export type ServiceRouteInfo = {
6
+ type: RouteTypeString;
7
+ name: string;
8
+ };
5
9
  export type BaseLeg = {
6
10
  from: Stop;
7
11
  to: Stop;
@@ -11,14 +15,14 @@ export type Access = BaseLeg & {
11
15
  };
12
16
  export type Transfer = BaseLeg & {
13
17
  minTransferTime?: Duration;
14
- type: TransferType;
18
+ type: TransferTypeString;
15
19
  };
16
20
  export type VehicleLeg = BaseLeg & {
17
21
  route: ServiceRouteInfo;
18
22
  departureTime: Time;
19
23
  arrivalTime: Time;
20
- pickUpType: PickUpDropOffType;
21
- dropOffType: PickUpDropOffType;
24
+ pickUpType: PickUpDropOffTypeString;
25
+ dropOffType: PickUpDropOffTypeString;
22
26
  };
23
27
  export type Leg = Transfer | Access | VehicleLeg;
24
28
  /**
@@ -9,11 +9,15 @@ import { ServiceRouteId } from './timetable.js';
9
9
  * from a service route sharing the same list of stops.
10
10
  */
11
11
  export type RouteId = number;
12
- export type RawPickUpDropOffType = 0 | 1 | 2 | 3;
13
- export declare const REGULAR = 0;
14
- export declare const NOT_AVAILABLE = 1;
15
- export declare const MUST_PHONE_AGENCY = 2;
16
- export declare const MUST_COORDINATE_WITH_DRIVER = 3;
12
+ export declare const PickUpDropOffTypes: {
13
+ readonly REGULAR: 0;
14
+ readonly NOT_AVAILABLE: 1;
15
+ readonly MUST_PHONE_AGENCY: 2;
16
+ readonly MUST_COORDINATE_WITH_DRIVER: 3;
17
+ };
18
+ export type PickUpDropOffType = (typeof PickUpDropOffTypes)[keyof typeof PickUpDropOffTypes];
19
+ export type PickUpDropOffTypeString = keyof typeof PickUpDropOffTypes;
20
+ export type RawPickUpDropOffType = PickUpDropOffType;
17
21
  export type TripRouteIndex = number;
18
22
  export type StopRouteIndex = number;
19
23
  /**
@@ -2,8 +2,14 @@ import { StopId } from '../stops/stops.js';
2
2
  import { Route, RouteId, StopRouteIndex, TripRouteIndex } from './route.js';
3
3
  import { Duration, Time } from './time.js';
4
4
  import { TripStopId } from './tripStopId.js';
5
- export type TransferType = // TODO use number to represent that.
6
- 'RECOMMENDED' | 'GUARANTEED' | 'REQUIRES_MINIMAL_TIME' | 'IN_SEAT';
5
+ export declare const TransferTypes: {
6
+ readonly RECOMMENDED: 1;
7
+ readonly GUARANTEED: 2;
8
+ readonly REQUIRES_MINIMAL_TIME: 3;
9
+ readonly IN_SEAT: 4;
10
+ };
11
+ export type TransferType = (typeof TransferTypes)[keyof typeof TransferTypes];
12
+ export type TransferTypeString = keyof typeof TransferTypes;
7
13
  export type Transfer = {
8
14
  destination: StopId;
9
15
  type: TransferType;
@@ -20,7 +26,20 @@ export type StopAdjacency = {
20
26
  };
21
27
  export type TripTransfers = Map<TripStopId, TripStop[]>;
22
28
  export type ServiceRouteId = number;
23
- export type RouteType = 'TRAM' | 'SUBWAY' | 'RAIL' | 'BUS' | 'FERRY' | 'CABLE_TRAM' | 'AERIAL_LIFT' | 'FUNICULAR' | 'TROLLEYBUS' | 'MONORAIL';
29
+ export declare const RouteTypes: {
30
+ readonly TRAM: 1;
31
+ readonly SUBWAY: 2;
32
+ readonly RAIL: 3;
33
+ readonly BUS: 4;
34
+ readonly FERRY: 5;
35
+ readonly CABLE_TRAM: 6;
36
+ readonly AERIAL_LIFT: 7;
37
+ readonly FUNICULAR: 8;
38
+ readonly TROLLEYBUS: 9;
39
+ readonly MONORAIL: 10;
40
+ };
41
+ export type RouteType = (typeof RouteTypes)[keyof typeof RouteTypes];
42
+ export type RouteTypeString = keyof typeof RouteTypes;
24
43
  export type ServiceRoute = {
25
44
  type: RouteType;
26
45
  name: string;
@@ -149,3 +168,5 @@ export declare class Timetable {
149
168
  */
150
169
  getGuaranteedTripTransfers(stopIndex: StopRouteIndex, routeId: RouteId, tripIndex: TripRouteIndex): TripStop[];
151
170
  }
171
+ export declare const routeTypeToString: (type: RouteType) => RouteTypeString;
172
+ export declare const transferTypeToString: (type: TransferType) => TransferTypeString;
@@ -0,0 +1,40 @@
1
+ import { Stop, StopId } from '../stops/stops.js';
2
+ import { StopsIndex } from '../stops/stopsIndex.js';
3
+ import { Transfer } from '../timetable/timetable.js';
4
+ /**
5
+ * A map of directed transfers keyed by their origin stop id. Structurally
6
+ * identical to the parser's `TransfersMap`, so generated transfers can be
7
+ * merged directly into a feed's parsed transfers.
8
+ */
9
+ export type GeneratedTransfers = Map<StopId, Transfer[]>;
10
+ /**
11
+ * Strategy for synthesizing additional stop-to-stop (walking) transfers that
12
+ * are missing from a transit feed.
13
+ *
14
+ * It runs as a pre-processing step between parsing and serialization and is
15
+ * therefore agnostic of the source parser: it depends only on the generic
16
+ * stops model, not on any GTFS-specific types. This keeps the door open for
17
+ * smarter generators (e.g. an OSM pedestrian router) and for reuse across
18
+ * parsers.
19
+ */
20
+ export interface TransferGenerator {
21
+ /**
22
+ * Generates candidate directed transfers between nearby stops.
23
+ *
24
+ * Implementations connect each origin to its nearby stops as directed edges
25
+ * (emit `origin -> neighbor`; the reverse edge is produced when the neighbor
26
+ * is itself visited as an origin). The caller deduplicates the result against
27
+ * the transfers already present in the feed and only keeps the relevant ones,
28
+ * so an implementation can freely emit a transfer for every nearby pair
29
+ * without tracking what already exists.
30
+ *
31
+ * Implementations may be synchronous (return the transfers directly) or
32
+ * asynchronous (return a promise, e.g. when calling out to a routing engine);
33
+ * the caller awaits the result either way.
34
+ *
35
+ * @param originStops - Stops to generate outgoing transfers from.
36
+ * @param stops - Index of all stops, providing coordinates and geo search.
37
+ * @returns Candidate transfers to merge into the feed's transfers.
38
+ */
39
+ generate(originStops: Stop[], stops: StopsIndex): GeneratedTransfers | Promise<GeneratedTransfers>;
40
+ }
@@ -0,0 +1,58 @@
1
+ import { Stop } from '../stops/stops.js';
2
+ import { StopsIndex } from '../stops/stopsIndex.js';
3
+ import { GeneratedTransfers, TransferGenerator } from './generator.js';
4
+ export type StraightLineTransferGeneratorOptions = {
5
+ /**
6
+ * Maximum straight-line distance between two stops for a transfer to be generated, in meters.
7
+ */
8
+ maxDistanceMeters?: number;
9
+ /**
10
+ * Assumed pedestrian walking speed, in kilometers per hour.
11
+ */
12
+ walkingSpeedKmh?: number;
13
+ /**
14
+ * Multiplier applied to the straight-line distance to approximate the real
15
+ * walking path length. Use 1 to disable.
16
+ */
17
+ detourFactor?: number;
18
+ /**
19
+ * Flat penalty, in minutes, added to every generated transfer to account for
20
+ * the general overhead of changing (orientation, walking through the
21
+ * station). Use 0 to disable.
22
+ */
23
+ changePenaltyMinutes?: number;
24
+ };
25
+ /**
26
+ * A {@link TransferGenerator} that connects geographically close stops with
27
+ * virtual walking transfers.
28
+ *
29
+ * The transfer time is derived from the straight-line (great-circle / haversine)
30
+ * distance between two stops, scaled up by a detour factor to approximate the
31
+ * real walking path and divided by an assumed walking speed. This is a
32
+ * deliberately crude heuristic meant to fill in footpaths for feeds that
33
+ * under-specify `transfers.txt` (e.g. large interchanges where subway, tram and
34
+ * bus stops sit close together but are left unconnected).
35
+ *
36
+ * Generated transfers use {@link TransferTypes.REQUIRES_MINIMAL_TIME} so they
37
+ * are treated as walking connections by both the router's transfer step and
38
+ * its access/egress computation. Each origin is connected to its nearby stops
39
+ * with a single directed edge; the reverse edge is produced when the neighbor
40
+ * is itself visited as an origin.
41
+ *
42
+ * On top of the walking time, a flat `changePenaltyMinutes` is added for the
43
+ * general overhead of any change. It is symmetric, so the two directions of a
44
+ * transfer share the same minimum time.
45
+ */
46
+ export declare class StraightLineTransferGenerator implements TransferGenerator {
47
+ private readonly maxDistanceMeters;
48
+ private readonly walkingSpeedKmh;
49
+ private readonly detourFactor;
50
+ private readonly changePenaltyMinutes;
51
+ constructor(options?: StraightLineTransferGeneratorOptions);
52
+ generate(originStops: Stop[], stops: StopsIndex): GeneratedTransfers;
53
+ private addTransfer;
54
+ /**
55
+ * Estimates the walking time between two coordinates, in whole minutes.
56
+ */
57
+ private walkingDuration;
58
+ }
@@ -0,0 +1,10 @@
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 declare const getOrInsert: <K, V>(map: Map<K, V>, key: K, defaultValue: V) => V;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "minotor",
3
- "version": "11.2.3",
3
+ "version": "11.4.0",
4
4
  "description": "A lightweight client-side transit routing library.",
5
5
  "keywords": [
6
6
  "minotor",
@@ -3,6 +3,10 @@ import { describe, it } from 'node:test';
3
3
 
4
4
  import fs from 'fs';
5
5
 
6
+ import type {
7
+ ServiceRouteInfo,
8
+ TransferType as TransferTypeString,
9
+ } from '../router.js';
6
10
  import {
7
11
  Query,
8
12
  RangeQuery,
@@ -21,13 +25,13 @@ type ExpectedVehicleLeg = {
21
25
  to: StopRef;
22
26
  departure: string;
23
27
  arrival: string;
24
- route: { type: string; name: string };
28
+ route: ServiceRouteInfo;
25
29
  };
26
30
 
27
31
  type ExpectedTransferLeg = {
28
32
  from: StopRef;
29
33
  to: StopRef;
30
- type: string;
34
+ type: TransferTypeString;
31
35
  minTransferTime?: number;
32
36
  };
33
37
 
@@ -8,6 +8,7 @@ import {
8
8
  GtfsParser,
9
9
  GtfsProfile,
10
10
  standardGtfsProfile,
11
+ StraightLineTransferGenerator,
11
12
  } from '../parser.js';
12
13
  import { Router, StopsIndex, Timetable } from '../router.js';
13
14
  import {
@@ -63,6 +64,10 @@ program
63
64
  'Profile name for GTFS config',
64
65
  'extended',
65
66
  )
67
+ .option(
68
+ '--virtual-transfers-radius <meters>',
69
+ 'Generate virtual walking transfers between stops within this radius (in meters). Disabled when omitted.',
70
+ )
66
71
  .option('-v, --verbose', 'Verbose mode', false)
67
72
  .action(
68
73
  async (
@@ -72,6 +77,7 @@ program
72
77
  timetableOutputPath: string;
73
78
  stopsOutputPath: string;
74
79
  profileName: string;
80
+ virtualTransfersRadius?: string;
75
81
  verbose: boolean;
76
82
  },
77
83
  ) => {
@@ -80,7 +86,21 @@ program
80
86
  } else {
81
87
  log.setDefaultLevel(log.levels.ERROR);
82
88
  }
83
- const parser = new GtfsParser(gtfsPath, profiles[options.profileName]);
89
+ const radiusMeters =
90
+ options.virtualTransfersRadius !== undefined
91
+ ? parseInt(options.virtualTransfersRadius, 10)
92
+ : undefined;
93
+ const transferGenerator =
94
+ radiusMeters !== undefined && Number.isFinite(radiusMeters)
95
+ ? new StraightLineTransferGenerator({
96
+ maxDistanceMeters: radiusMeters,
97
+ })
98
+ : undefined;
99
+ const parser = new GtfsParser(
100
+ gtfsPath,
101
+ profiles[options.profileName],
102
+ transferGenerator,
103
+ );
84
104
  const stopsIndex = await parser.parseStops();
85
105
  fs.writeFileSync(options.stopsOutputPath, stopsIndex.serialize());
86
106
  const timetable = await parser.parseTimetable(new Date(options.date));
package/src/cli/repl.ts CHANGED
@@ -4,14 +4,8 @@ import fs from 'fs';
4
4
 
5
5
  import { Query, RangeQuery, Router, StopsIndex, Timetable } from '../router.js';
6
6
  import type { Stop } from '../stops/stops.js';
7
- import {
8
- MUST_COORDINATE_WITH_DRIVER,
9
- MUST_PHONE_AGENCY,
10
- NOT_AVAILABLE,
11
- RawPickUpDropOffType,
12
- REGULAR,
13
- } from '../timetable/route.js';
14
- import { Route } from '../timetable/route.js';
7
+ import type { RawPickUpDropOffType } from '../timetable/route.js';
8
+ import { PickUpDropOffTypes, Route } from '../timetable/route.js';
15
9
  import { timeFromString, timeToString } from '../timetable/time.js';
16
10
  import { plotGraphToDotFile } from './utils.js';
17
11
 
@@ -306,13 +300,13 @@ export const startRepl = (stopsPath: string, timetablePath: string) => {
306
300
 
307
301
  const formatPickupDropoffType = (type: RawPickUpDropOffType): string => {
308
302
  switch (type) {
309
- case REGULAR:
303
+ case PickUpDropOffTypes.REGULAR:
310
304
  return 'R';
311
- case NOT_AVAILABLE:
305
+ case PickUpDropOffTypes.NOT_AVAILABLE:
312
306
  return 'N';
313
- case MUST_PHONE_AGENCY:
307
+ case PickUpDropOffTypes.MUST_PHONE_AGENCY:
314
308
  return 'A';
315
- case MUST_COORDINATE_WITH_DRIVER:
309
+ case PickUpDropOffTypes.MUST_COORDINATE_WITH_DRIVER:
316
310
  return 'D';
317
311
  default:
318
312
  return '?';
@@ -2,6 +2,8 @@ import assert from 'node:assert';
2
2
  import { beforeEach, describe, it } from 'node:test';
3
3
 
4
4
  import { timeFromHMS } from '../../timetable/time.js';
5
+ import { RouteTypes, TransferTypes } from '../../timetable/timetable.js';
6
+ import { StraightLineTransferGenerator } from '../../transfers/straightLineTransferGenerator.js';
5
7
  import { GtfsParser } from '../parser.js';
6
8
  describe('GTFS parser', () => {
7
9
  let parser: GtfsParser;
@@ -70,6 +72,32 @@ describe('GTFS parser', () => {
70
72
  const serviceRoute = timetable.getServiceRouteInfo(route);
71
73
  assert(serviceRoute);
72
74
  assert.strictEqual(serviceRoute.name, '10');
73
- assert.strictEqual(serviceRoute.type, 'BUS');
75
+ assert.strictEqual(serviceRoute.type, RouteTypes.BUS);
76
+ });
77
+
78
+ it('adds virtual transfers flagged as generated when a generator is supplied', async () => {
79
+ // The sample feed has no transfers.txt, so a wide radius connects the
80
+ // route-served stops to each other.
81
+ const generatorParser = new GtfsParser(
82
+ './src/gtfs/__tests__/resources/sample-feed.zip',
83
+ undefined,
84
+ new StraightLineTransferGenerator({ maxDistanceMeters: 1_000_000 }),
85
+ );
86
+ const timetable = await generatorParser.parseTimetable(
87
+ new Date('2007-01-10'),
88
+ );
89
+ const stopsIndex = await generatorParser.parseStops();
90
+
91
+ const furCreekResId =
92
+ stopsIndex.findStopBySourceStopId('FUR_CREEK_RES')?.id;
93
+ assert(furCreekResId !== undefined);
94
+
95
+ const transfers = timetable.getTransfers(furCreekResId);
96
+ assert(transfers.length > 0);
97
+ assert(
98
+ transfers.every((t) => t.type === TransferTypes.REQUIRES_MINIMAL_TIME),
99
+ );
100
+ // Transfers only point at route-served stops, never at the origin itself.
101
+ assert(transfers.every((t) => t.destination !== furCreekResId));
74
102
  });
75
103
  });
@@ -2,6 +2,7 @@ import assert from 'node:assert';
2
2
  import { Readable } from 'node:stream';
3
3
  import { describe, it } from 'node:test';
4
4
 
5
+ import { RouteTypes } from '../../timetable/timetable.js';
5
6
  import { parseRoutes } from '../routes.js';
6
7
 
7
8
  describe('GTFS routes parser', () => {
@@ -22,14 +23,14 @@ describe('GTFS routes parser', () => {
22
23
  [
23
24
  'routeA',
24
25
  {
25
- type: 'BUS',
26
+ type: RouteTypes.BUS,
26
27
  name: 'B1',
27
28
  },
28
29
  ],
29
30
  [
30
31
  'routeB',
31
32
  {
32
- type: 'TRAM',
33
+ type: RouteTypes.TRAM,
33
34
  name: 'T1',
34
35
  },
35
36
  ],
@@ -52,7 +53,7 @@ describe('GTFS routes parser', () => {
52
53
  [
53
54
  'routeA',
54
55
  {
55
- type: 'BUS',
56
+ type: RouteTypes.BUS,
56
57
  name: 'B1',
57
58
  },
58
59
  ],