minotor 1.0.0

package/dist/timetable/proto/timetable.d.ts

@@ -0,0 +1,122 @@
+import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
+export declare const protobufPackage = "minotor.timetable";
+export declare enum PickUpDropOffType {
+    NOT_AVAILABLE = 0,
+    MUST_PHONE_AGENCY = 1,
+    MUST_COORDINATE_WITH_DRIVER = 2,
+    UNRECOGNIZED = -1
+}
+export declare function pickUpDropOffTypeFromJSON(object: any): PickUpDropOffType;
+export declare function pickUpDropOffTypeToJSON(object: PickUpDropOffType): string;
+export declare enum TransferType {
+    RECOMMENDED_TRANSFER_POINT = 0,
+    TIMED_TRANSFER = 1,
+    REQUIRES_MINIMAL_TIME = 2,
+    IN_SEAT_TRANSFER = 3,
+    UNRECOGNIZED = -1
+}
+export declare function transferTypeFromJSON(object: any): TransferType;
+export declare function transferTypeToJSON(object: TransferType): string;
+export declare enum RouteType {
+    TRAM = 0,
+    SUBWAY = 1,
+    RAIL = 2,
+    BUS = 3,
+    FERRY = 4,
+    CABLE_TRAM = 5,
+    AERIAL_LIFT = 6,
+    FUNICULAR = 7,
+    TROLLEYBUS = 8,
+    MONORAIL = 9,
+    UNRECOGNIZED = -1
+}
+export declare function routeTypeFromJSON(object: any): RouteType;
+export declare function routeTypeToJSON(object: RouteType): string;
+export interface StopTimes {
+    arrival: number;
+    departure: number;
+    pickUpType?: PickUpDropOffType | undefined;
+    dropOffType?: PickUpDropOffType | undefined;
+}
+export interface Route {
+    stopTimes: StopTimes[];
+    stops: string[];
+    serviceRouteId: string;
+}
+export interface RoutesAdjacency {
+    routes: {
+        [key: string]: Route;
+    };
+}
+export interface RoutesAdjacency_RoutesEntry {
+    key: string;
+    value: Route | undefined;
+}
+export interface Transfer {
+    destination: string;
+    type: TransferType;
+    minTransferTime?: number | undefined;
+}
+export interface StopsAdjacency {
+    stops: {
+        [key: string]: StopsAdjacency_StopAdjacency;
+    };
+}
+export interface StopsAdjacency_StopAdjacency {
+    transfers: Transfer[];
+    routes: string[];
+}
+export interface StopsAdjacency_StopsEntry {
+    key: string;
+    value: StopsAdjacency_StopAdjacency | undefined;
+}
+export interface ServiceRoute {
+    type: RouteType;
+    name: string;
+}
+export interface ServiceRoutesMap {
+    routes: {
+        [key: string]: ServiceRoute;
+    };
+}
+export interface ServiceRoutesMap_RoutesEntry {
+    key: string;
+    value: ServiceRoute | undefined;
+}
+export interface Timetable {
+    version: string;
+    stopsAdjacency: StopsAdjacency | undefined;
+    routesAdjacency: RoutesAdjacency | undefined;
+    routes: ServiceRoutesMap | undefined;
+}
+export declare const StopTimes: MessageFns<StopTimes>;
+export declare const Route: MessageFns<Route>;
+export declare const RoutesAdjacency: MessageFns<RoutesAdjacency>;
+export declare const RoutesAdjacency_RoutesEntry: MessageFns<RoutesAdjacency_RoutesEntry>;
+export declare const Transfer: MessageFns<Transfer>;
+export declare const StopsAdjacency: MessageFns<StopsAdjacency>;
+export declare const StopsAdjacency_StopAdjacency: MessageFns<StopsAdjacency_StopAdjacency>;
+export declare const StopsAdjacency_StopsEntry: MessageFns<StopsAdjacency_StopsEntry>;
+export declare const ServiceRoute: MessageFns<ServiceRoute>;
+export declare const ServiceRoutesMap: MessageFns<ServiceRoutesMap>;
+export declare const ServiceRoutesMap_RoutesEntry: MessageFns<ServiceRoutesMap_RoutesEntry>;
+export declare const Timetable: MessageFns<Timetable>;
+type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
+export type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : Partial<T>;
+type KeysOfUnion<T> = T extends T ? keyof T : never;
+export type Exact<P, I extends P> = P extends Builtin ? P : P & {
+    [K in keyof P]: Exact<P[K], I[K]>;
+} & {
+    [K in Exclude<keyof I, KeysOfUnion<P>>]: never;
+};
+export interface MessageFns<T> {
+    encode(message: T, writer?: BinaryWriter): BinaryWriter;
+    decode(input: BinaryReader | Uint8Array, length?: number): T;
+    fromJSON(object: any): T;
+    toJSON(message: T): unknown;
+    create<I extends Exact<DeepPartial<T>, I>>(base?: I): T;
+    fromPartial<I extends Exact<DeepPartial<T>, I>>(object: I): T;
+}
+export {};

package/dist/timetable/time.d.ts

@@ -0,0 +1,98 @@
+import { Duration } from './duration.js';
+/**
+ * A class representing a time in hours, minutes, and seconds.
+ */
+export declare class Time {
+    private secondsSinceMidnight;
+    /**
+     * Gets the infinity time as a Time instance.
+     * This represents a time that is conceptually beyond any real possible time.
+     *
+     * @returns A Time instance representing an "infinity" time.
+     */
+    static infinity(): Time;
+    /**
+     * Gets the midnight time as a Time instance.
+     *
+     * @returns A Time instance representing midnight (00:00:00).
+     */
+    static origin(): Time;
+    private constructor();
+    /**
+     * Creates a Time instance from the number of seconds since midnight.
+     *
+     * @param seconds - The number of seconds since midnight.
+     * @returns A Time instance representing the specified time.
+     */
+    static fromSeconds(seconds: number): Time;
+    /**
+     * Creates a Time instance from hours, minutes, and seconds.
+     *
+     * @param hours - The hours component of the time.
+     * @param minutes - The minutes component of the time.
+     * @param seconds - The seconds component of the time.
+     * @returns A Time instance representing the specified time.
+     */
+    static fromHMS(hours: number, minutes: number, seconds: number): Time;
+    /**
+     * Parses a JavaScript Date object and creates a Time instance.
+     *
+     * @param date - A JavaScript Date object representing the time.
+     * @returns A Time instance representing the parsed time.
+     */
+    static fromDate(date: Date): Time;
+    /**
+     * Parses a time string in the format "HH:MM:SS" or "HH:MM" and creates a Time instance.
+     *
+     * @param timeStr - A string representing the time in "HH:MM:SS" or "HH:MM" format.
+     * @returns A Time instance representing the parsed time.
+     */
+    static fromString(timeStr: string): Time;
+    /**
+     * Converts the Time instance to a string in "HH:MM:SS" format.
+     *
+     * @returns A string representing the time.
+     */
+    toString(): string;
+    /**
+     * Gets the time as the number of seconds since midnight.
+     *
+     * @returns The time in seconds since midnight.
+     */
+    toSeconds(): number;
+    /**
+     * Adds a Duration to the current Time instance and returns a new Time instance.
+     *
+     * @param duration - A Duration instance representing the duration to add.
+     * @returns A new Time instance with the added duration.
+     */
+    plus(duration: Duration): Time;
+    /**
+     * Subtracts a Duration from the current Time instance and returns a new Time instance.
+     *
+     * @param duration - A Duration instance representing the duration to subtract.
+     * @returns A new Time instance with the subtracted duration.
+     */
+    minus(duration: Duration): Time;
+    /**
+     * Subtracts another Time instance from the current Time instance and returns the Duration.
+     *
+     * @param otherTime - A Time instance representing the time to subtract.
+     * @returns A Duration instance representing the time difference.
+     */
+    diff(otherTime: Time): Duration;
+    /**
+     * Computes the maximum Time instance among the provided Time instances.
+     *
+     * @param times - An array of Time instances to compare.
+     * @returns A Time instance representing the maximum time.
+     */
+    static max(...times: Time[]): Time;
+    /**
+     * Computes the minimum Time instance among the provided Time instances.
+     *
+     * @param times - An array of Time instances to compare.
+     * @returns A Time instance representing the minimum time.
+     */
+    static min(...times: Time[]): Time;
+}

package/dist/timetable/timetable.d.ts

@@ -0,0 +1,82 @@
+import { StopId } from '../stops/stops.js';
+import { Duration } from './duration.js';
+import { Time } from './time.js';
+export type PickUpDropOffType = 'REGULAR' | 'NOT_AVAILABLE' | 'MUST_PHONE_AGENCY' | 'MUST_COORDINATE_WITH_DRIVER';
+export type StopTimes = {
+    arrival: Time;
+    departure: Time;
+    pickUpType: PickUpDropOffType;
+    dropOffType: PickUpDropOffType;
+};
+export type RouteId = string;
+export type IndexedStopId = {
+    stopId: StopId;
+    index: number;
+};
+export type Route = {
+    stopTimes: StopTimes[];
+    stops: StopId[];
+    stopIndices: Map<StopId, number>;
+    serviceRouteId: ServiceRouteId;
+};
+export type RoutesAdjacency = Map<RouteId, Route>;
+export type TransferType = 'RECOMMENDED' | 'GUARANTEED' | 'REQUIRES_MINIMAL_TIME' | 'IN_SEAT';
+export type Transfer = {
+    destination: StopId;
+    type: TransferType;
+    minTransferTime?: Duration;
+};
+export type StopsAdjacency = Map<StopId, {
+    transfers: Transfer[];
+    routes: RouteId[];
+}>;
+export type ServiceRouteId = string;
+export type RouteType = 'TRAM' | 'SUBWAY' | 'RAIL' | 'BUS' | 'FERRY' | 'CABLE_TRAM' | 'AERIAL_LIFT' | 'FUNICULAR' | 'TROLLEYBUS' | 'MONORAIL';
+export type ServiceRoute = {
+    type: RouteType;
+    name: string;
+};
+export type ServiceRoutesMap = Map<ServiceRouteId, ServiceRoute>;
+type TripIndex = number;
+export declare const ALL_TRANSPORT_MODES: RouteType[];
+export declare const CURRENT_VERSION = "0.0.1";
+/**
+ * The internal transit timetable format
+ * reuses some GTFS concepts for the sake of simplicity for now.
+ */
+export declare class Timetable {
+    private readonly stopsAdjacency;
+    private readonly routesAdjacency;
+    private readonly routes;
+    constructor(stopsAdjacency: StopsAdjacency, routesAdjacency: RoutesAdjacency, routes: ServiceRoutesMap);
+    /**
+     * Serializes the Timetable into a binary protobuf.
+     *
+     * @returns {Uint8Array} - The serialized binary data.
+     */
+    serialize(): Uint8Array;
+    /**
+     * Deserializes a binary protobuf into a Timetable object.
+     *
+     * @param {Uint8Array} data - The binary data to deserialize.
+     * @returns {Timetable} - The deserialized Timetable object.
+     */
+    static fromData(data: Uint8Array): Timetable;
+    getRoute(routeId: RouteId): Route | undefined;
+    getTransfers(stopId: StopId): Transfer[];
+    /**
+     * Finds routes that are reachable from a set of stop IDs.
+     * Also identifies the first stop available to hop on each route among
+     * the input stops.
+     */
+    findReachableRoutes(fromStops: Set<StopId>, transportModes?: RouteType[]): Map<RouteId, StopId>;
+    getServiceRouteFromRouteId(routeId: RouteId): ServiceRoute | undefined;
+    getServiceRoute(serviceRouteId: ServiceRouteId): ServiceRoute | undefined;
+    /**
+     * Finds the earliest trip that can be taken from a specific stop on a given route,
+     * optionally constrained by a latest trip index and a time before which the trip
+     * should not depart.
+     */
+    findEarliestTrip(route: Route, stopId: StopId, beforeTrip?: TripIndex, after?: Time): TripIndex | undefined;
+}
+export {};

package/dist/umdIndex.d.ts

@@ -0,0 +1,9 @@
+import { Plotter } from './routing/plotter.js';
+import { Query } from './routing/query.js';
+import { Result } from './routing/result.js';
+import { Route } from './routing/route.js';
+import { Router } from './routing/router.js';
+import { StopsIndex } from './stops/stopsIndex.js';
+import { Time } from './timetable/time.js';
+import { Timetable } from './timetable/timetable.js';
+export { Plotter, Query, Result, Route, Router, StopsIndex, Time, Timetable };

package/eslint.config.mjs

@@ -0,0 +1,52 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import prettierConfig from 'eslint-config-prettier';
+import simpleImportSort from 'eslint-plugin-simple-import-sort';
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommendedTypeChecked,
+  ...tseslint.configs.strictTypeChecked,
+  prettierConfig,
+  {
+    ignores: ['scripts/*', 'rollup.config.js'],
+  },
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      ecmaVersion: 2019,
+      sourceType: 'module',
+      parser: tseslint.parser,
+      parserOptions: {
+        project: './tsconfig.json',
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    plugins: {
+      'simple-import-sort': simpleImportSort,
+    },
+    rules: {
+      '@typescript-eslint/no-unused-expressions': 'off', // Breaks the linting
+      '@typescript-eslint/restrict-template-expressions': [
+        'error',
+        { allowNumber: true },
+      ],
+      'simple-import-sort/imports': 'error',
+      'simple-import-sort/exports': 'error',
+    },
+  },
+  {
+    files: ['src/**/*.test.ts'],
+    rules: {
+      '@typescript-eslint/no-floating-promises': 'off',
+    },
+  },
+  {
+    files: ['src/stops/proto/*.ts', 'src/timetable/proto/*.ts'],
+    rules: {
+      'eslint-comments/no-unlimited-disable': 'off',
+      'eslint-comments/disable-enable-pair': 'off',
+    },
+  },
+);

package/package.json

@@ -0,0 +1,109 @@
+{
+  "name": "minotor",
+  "version": "1.0.0",
+  "description": "A lightweight client-side transit router.",
+  "keywords": [
+    "minotor",
+    "raptor",
+    "transit",
+    "planner",
+    "transport",
+    "router",
+    "gtfs",
+    "trains",
+    "netex"
+  ],
+  "homepage": "https://github.com/aubryio/minotor",
+  "bugs": "https://github.com/aubryio/minotor/issues",
+  "author": "Aubry Cholleton <aubry.cholleton@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aubryio/minotor.git"
+  },
+  "type": "module",
+  "main": "dist/bundle.cjs.js",
+  "module": "dist/bundle.esm.js",
+  "browser": "dist/bundle.umd.js",
+  "bin": {
+    "minotor": "./dist/cli.mjs"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/bundle.esm.js",
+      "require": "./dist/bundle.cjs.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "engines": {
+    "node": ">=21.1.0",
+    "npm": ">=10.9.1"
+  },
+  "volta": {
+    "node": "21.1.0",
+    "npm": "10.9.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build:proto": "protoc --plugin=./node_modules/.bin/protoc-gen-ts_proto --ts_proto_out=. ./src/timetable/proto/timetable.proto; protoc --plugin=./node_modules/.bin/protoc-gen-ts_proto --ts_proto_out=. ./src/stops/proto/stops.proto",
+    "build": "npm run clean && npm run build:proto && npm run type:dts && npm run build:src",
+    "build:src": "rollup -c",
+    "clean": "rimraf build coverage",
+    "type:dts": "tsc --emitDeclarationOnly --project tsconfig.build.json",
+    "type:check": "tsc --noEmit",
+    "lint": "eslint src --fix",
+    "lint:check": "eslint src",
+    "format:check": "prettier . --check",
+    "format": "prettier --write .",
+    "test": "tsx --test src/**/*.test.ts",
+    "test:watch": "tsx --watch --test src/**/*.test.ts",
+    "test:coverage": "c8 -x 'src/**/proto/*.ts' -x 'src/**/__tests__/*.ts' --check-coverage --lines=85 tsx --test src/**/*.test.ts",
+    "spell:check": "cspell \"{README.md,.github/*.md,src/**/*.ts}\" -u",
+    "cz": "cz",
+    "semantic-release": "semantic-release"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@rollup/plugin-commonjs": "^28.0.1",
+    "@rollup/plugin-node-resolve": "^15.3.0",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^12.1.1",
+    "@ryansonshine/commitizen": "^4.2.8",
+    "@ryansonshine/cz-conventional-changelog": "^3.3.4",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.0",
+    "@semantic-release/github": "^11.0.1",
+    "@semantic-release/npm": "^12.0.1",
+    "@semantic-release/release-notes-generator": "^14.0.1",
+    "@types/eslint__js": "^8.42.3",
+    "@types/geokdbush": "^1.1.5",
+    "@types/luxon": "^3.4.2",
+    "@types/node": "^22.9.0",
+    "c8": "^10.1.2",
+    "cspell": "^8.16.0",
+    "eslint": "^9.15.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "prettier": "^3.3.3",
+    "rimraf": "^6.0.1",
+    "rollup": "^4.27.2",
+    "semantic-release": "^24.2.0",
+    "ts-proto": "^2.2.7",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3",
+    "typescript-eslint": "^8.14.0"
+  },
+  "dependencies": {
+    "@bufbuild/protobuf": "^2.2.2",
+    "commander": "^12.1.0",
+    "csv-parse": "^5.5.6",
+    "geokdbush": "^2.0.1",
+    "kdbush": "^4.0.2",
+    "loglevel": "^1.9.2",
+    "luxon": "^3.5.0",
+    "node-stream-zip": "^1.15.0",
+    "slimsearch": "^2.2.1"
+  }
+}

package/rollup.config.js

@@ -0,0 +1,44 @@
+import typescript from '@rollup/plugin-typescript';
+import resolve from '@rollup/plugin-node-resolve';
+import commonjs from '@rollup/plugin-commonjs';
+import terser from '@rollup/plugin-terser';
+
+export default [
+  {
+    input: 'src/umdIndex.ts',
+    output: {
+      file: 'dist/bundle.umd.js',
+      format: 'umd',
+      name: 'minotor',
+      sourcemap: true,
+    },
+    plugins: [resolve(), commonjs(), typescript(), terser()],
+  },
+  // CommonJS and ES module builds for Node.js and bundlers
+  {
+    input: 'src/index.ts',
+    output: [
+      {
+        file: 'dist/bundle.esm.js',
+        format: 'es',
+        sourcemap: true,
+      },
+      {
+        file: 'dist/bundle.cjs.js',
+        format: 'cjs',
+        sourcemap: true,
+      },
+    ],
+    plugins: [resolve(), commonjs(), typescript()],
+  },
+  {
+    input: 'src/cli/minotor.ts',
+    output: {
+      file: 'dist/cli.mjs',
+      format: 'es',
+      banner: '#!/usr/bin/env node',
+      sourcemap: true,
+    },
+    plugins: [resolve(), commonjs(), typescript()],
+  },
+];

package/src/cli/__tests__/minotor.test.ts

@@ -0,0 +1,23 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe } from 'node:test';
+
+describe('timetable io', () => {
+  let tempDir: string;
+  let filePath: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'test-io-'));
+    filePath = path.join(tempDir, 'test-timetable.bin');
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+    }
+    if (fs.existsSync(tempDir)) {
+      fs.rmdirSync(tempDir);
+    }
+  });
+});

package/src/cli/minotor.ts

@@ -0,0 +1,112 @@
+import { Command } from 'commander';
+import fs from 'fs';
+import log from 'loglevel';
+import { DateTime } from 'luxon';
+
+import { chGtfsProfile, GtfsParser, GtfsProfile } from '../index.js';
+import { startRepl } from './repl.js';
+
+const program = new Command();
+
+export type GtfsVariant = string;
+
+export type Config = {
+  [config: GtfsVariant]: GtfsProfile;
+};
+
+const profiles: Config = {
+  CH: chGtfsProfile,
+};
+
+program
+  .name('minotor')
+  .description('CLI for minotor route planner.')
+  .version('0.0.1');
+
+program
+  .command('parse-gtfs')
+  .description('Parse a GTFS feed and output a timetable and stops file.')
+  .argument('<gtfsPath>', 'Path to GTFS data')
+  .option(
+    '-d, --date <date>',
+    'Date of the day to parse in yyyy-MM-dd format',
+    DateTime.now().toFormat('yyyy-MM-dd'),
+  )
+  .option(
+    '-t, --timetableOutputPath <path>',
+    'Path to output timetable file',
+    '/tmp/timetable',
+  )
+  .option(
+    '-s, --stopsOutputPath <path>',
+    'Path to output stops file',
+    '/tmp/stops',
+  )
+  .option('-p, --profileName <name>', 'Profile name for GTFS config', 'CH')
+  .option('-v, --verbose', 'Verbose mode', false)
+  .action(
+    async (
+      gtfsPath: string,
+      options: {
+        date: string;
+        timetableOutputPath: string;
+        stopsOutputPath: string;
+        profileName: string;
+        verbose: boolean;
+      },
+    ) => {
+      if (options.verbose) {
+        log.setDefaultLevel(log.levels.INFO);
+      } else {
+        log.setDefaultLevel(log.levels.ERROR);
+      }
+      const parser = new GtfsParser(gtfsPath, profiles[options.profileName]);
+      const { timetable, stopsIndex } = await parser.parse(
+        new Date(options.date),
+      );
+      fs.writeFileSync(options.timetableOutputPath, timetable.serialize());
+      fs.writeFileSync(options.stopsOutputPath, stopsIndex.serialize());
+    },
+  );
+
+program
+  .command('parse-stops')
+  .description('Parse a GTFS feed and output a timetable and stops file.')
+  .argument('<gtfsPath>', 'Path to GTFS data')
+  .option('-s, --outputPath <path>', 'Path to output stops file', '/tmp/stops')
+  .option('-p, --profileName <name>', 'Profile name for GTFS config', 'CH')
+  .option('-v, --verbose', 'Verbose mode', false)
+  .action(
+    async (
+      gtfsPath: string,
+      options: {
+        stopsOutputPath: string;
+        profileName: string;
+        verbose: boolean;
+      },
+    ) => {
+      if (options.verbose) {
+        log.setDefaultLevel(log.levels.INFO);
+      } else {
+        log.setDefaultLevel(log.levels.ERROR);
+      }
+      const parser = new GtfsParser(gtfsPath, profiles[options.profileName]);
+      const stopsIndex = await parser.parseStops();
+      fs.writeFileSync(options.stopsOutputPath, stopsIndex.serialize());
+    },
+  );
+
+program
+  .command('repl')
+  .description('Find stops matching a textual query')
+  .option('-s, --stopsPath <path>', 'Path to the stops file', '/tmp/stops')
+  .option(
+    '-t, --timetablePath <path>',
+    'Path to the timetable file',
+    '/tmp/timetable',
+  )
+  .action((options: { stopsPath: string; timetablePath: string }) => {
+    startRepl(options.stopsPath, options.timetablePath);
+  });
+
+program.parse(process.argv);