minotor 1.0.0

package/.cspell.json

@@ -0,0 +1,43 @@
+{
+  "version": "0.2",
+  "language": "en",
+  "words": [
+    "Minotor",
+    "gtfs",
+    "minotor",
+    "luxon",
+    "Gtfs",
+    "GTFS",
+    "Tilleul",
+    "Cathédrale",
+    "tcrqn",
+    "tcrqo",
+    "lswfbh",
+    "Neuveville",
+    "Cathedrale",
+    "bufbuild",
+    "protoc",
+    "geokdbush",
+    "kdbush",
+    "slimsearch",
+    "geospatial",
+    "NeTEx",
+    "Ksfdp",
+    "Tsvg",
+    "Landquart",
+    "Davos",
+    "moleson",
+    "Klosters",
+    "Engadin"
+  ],
+  "flagWords": [],
+  "ignorePaths": [
+    "package.json",
+    "package-lock.json",
+    "yarn.lock",
+    "tsconfig.json",
+    "node_modules/**",
+    "src/gtfs/__tests__/gtfs.test.ts",
+    "parser.test.ts"
+  ]
+}

package/.czrc

@@ -0,0 +1,3 @@
+{
+  "path": "./node_modules/@ryansonshine/cz-conventional-changelog"
+}

package/.editorconfig

@@ -0,0 +1,10 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+
+[*.ts,*.tsx]
+indent_style = space
+indent_size = 2
+quote_type = single

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug report
+about: Create a report to help us improve @aubrio/minotor
+title: ''
+labels: 'bug'
+assignees: ''
+---
+
+**Describe the bug**
+A clear and concise description of the bug.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+
+1.
+2.
+3.
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Environment**
+
+- OS version:
+- Node version / Browser version:
+- Minotor Version:
+
+**Additional context**
+Add any other context about the problem here.

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: GitHub Discussions
+    url: https://github.com/aubryio/minotor/discussions
+    about: To discuss topics which are not suited for being discussed in issues

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,29 @@
+---
+name: Feature Request
+about: Suggest a new feature or enhancement for @aubrio/minotor
+title: ''
+labels: 'enhancement'
+assignees: ''
+---
+
+## Feature Request
+
+### Description
+
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+### Proposed Solution
+
+A clear and concise description of what you want to happen.
+
+### Alternatives Considered
+
+A clear and concise description of any alternative solutions or features you've considered.
+
+### Additional Context
+
+Add any other context or screenshots about the feature request here.
+
+### Related Issues
+
+If applicable, add links to existing issues or discussions that are related to this feature request.

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,4 @@
+Fixes # (issue)
+
+Please provide a concise description of your changes, and the motivation for making them.
+If relevant, include links to related issues or pull requests.

package/.github/workflows/minotor.yml

@@ -0,0 +1,85 @@
+name: minotor
+
+on: [push]
+
+env:
+  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+jobs:
+  format:
+    name: 💅 Prettier
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - uses: bahmutov/npm-install@v1
+      - name: 💅 Prettier
+        run: npm run format:check
+
+  lint:
+    name: 🔍 ESLint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - uses: bahmutov/npm-install@v1
+      - name: ⬣ ESLint
+        run: npm run lint:check
+
+  audit:
+    name: 🛡️ Audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - name: 🛡️ Audit
+        run: npm audit --audit-level=high
+
+  spell:
+    name: 🔠 Spellcheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - uses: bahmutov/npm-install@v1
+      - name: 🈸 Spellcheck
+        run: npm run spell:check
+
+  type:
+    name: ʦ Typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - uses: bahmutov/npm-install@v1
+      - name: ʦ Typecheck
+        run: npm run type:check
+
+  test:
+    name: ⚡ Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '21.1.0'
+      - uses: bahmutov/npm-install@v1
+      - name: ⚡ Tests
+        run: npm run test:coverage
+
+  build-and-release:
+    name: 🚀 Build & release
+    needs: [format, lint, audit, spell, type, test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - uses: bahmutov/npm-install@v1
+      - uses: arduino/setup-protoc@v3
+      - name: 🔨 Build
+        run: npm run build
+      - name: 🚀 Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm run semantic-release

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "singleQuote": true,
+  "semi": true,
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false
+}

package/.releaserc.json

@@ -0,0 +1,27 @@
+{
+  "branches": [
+    "main",
+    {
+      "name": "beta",
+      "prerelease": true
+    },
+    {
+      "name": "alpha",
+      "prerelease": true
+    }
+  ],
+  "repositoryUrl": "https://github.com/aubryio/minotor.git",
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    "@semantic-release/npm",
+    [
+      "@semantic-release/github",
+      {
+        "successComment": false,
+        "failTitle": false
+      }
+    ]
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# 1.0.0 (2025-02-02)
+
+
+### Features
+
+* prototype GTFS parser, stop index and Raptor router. ([912cc7d](https://github.com/aubryio/minotor/commit/912cc7d822bfa2e08260074ecb05e8777d36dc4d))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 Aubry Cholleton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# Minotor
+
+![GitHub Workflow Status](https://github.com/aubryio/minotor/actions/workflows/minotor.yml/badge.svg?branch=main)
+
+A lightweight and easy to use public transit router primarily targeting client-side usage for research, data visualization, dynamic web and mobile apps.
+
+Unlike most transit planners out there, **minotor** allows to store all the transit data for a given day in memory on the client, allowing for fast runtime queries using only local data.
+This is particularly useful for highly dynamic applications or complex visualizations for research purposes where the user needs to query the data in real-time.
+Privacy-conscious applications where the user does not want to share their location data with a server can also benefit from this model.
+
+The transit router and the stops index of **minotor** can run in the browser, on react-native or in a Node.js environment.
+Transit data (GTFS) parsing runs on Node.js, and the resulting data is serialized as a protobuf binary that can be loaded from the router.
+
+## Features
+
+- GTFS feed parsing (standard and extended)
+- Geographic and textual stops search
+- Transit routing from origin(s) stop(s) to destination(s) stop(s) at a given time
+- Computation for arrival times at all stops given a destination and start time
+
+### Tested GTFS feeds
+
+| Feed                                                                                       | Parsing time | Timetable Size for a Day (Compressed) |
+| ------------------------------------------------------------------------------------------ | ------------ | ------------------------------------- |
+| [Swiss GTFS feed](https://data.opentransportdata.swiss/en/dataset/timetable-2025-gtfs2020) | ~2 minutes   | 44 MB (9MB)                           |
+
+## Get started
+
+### Installation
+
+`npm i minotor`
+
+### Typescript API Usage example
+
+#### GTFS Feed parsing (Node.js only)
+
+```
+import { GtfsParser, chGtfsProfile } from 'minotor';
+
+const parser = new GtfsParser('gtfs-feed.zip', chGtfsProfile);
+const { timetable, stopsIndex } = await parser.parse(new Date());
+```
+
+Note that this operation can take a few minutes for large GTFS feeds.
+See comments in the code for more options.
+
+#### Stop Search (Browser or Node.js)
+
+```
+const origins = stopsIndex.findStopsByName('Fribourg');
+const destinations = stopsIndex.findStopsByName('Moles'); // Partial name search
+```
+
+Query stops by ID:
+
+`const stopFromId = stopsIndex.findStopById('8592374:0:A');`
+
+Or by location:
+
+`const nearbyStops = stopsIndex.findStopsByLocation(46.80314924, 7.1510478, 5, 0.5);`
+
+#### Routing (Browser or Node.js)
+
+```
+import { Query, Router, Time } from 'minotor';
+
+const router = new Router(timetable, stopsIndex);
+
+const query = new Query.Builder()
+  .from('Parent8504100')
+  .to('Parent8504748')
+  .departureTime(Time.fromHMS(8,0,0))
+  .maxTransfers(5)
+  .build();
+const result = router.route(query);
+```
+
+Get the route between origin and the closest destination (optionally provide another destination stop than the one in the query, the resulting route will be found if it's reachable before the first query destination reached).
+
+`const bestRoute = result.bestRoute();`
+
+Get the arrival time to any stop (optionally provide the max number of transfers if you're interested in a lower one than the one provided in the query).
+This time will be correct for any stop reachable before the first query destination reached.
+
+`const arrivalTime = result.arrivalAt(toStop.id);`
+
+### CLI Usage example
+
+Parse GTFS data for a day and output the timetable and stops index (`minotor parse-gtfs -h` for more options):
+
+`minotor parse-gtfs gtfs_feed.zip`
+
+Note that this operation can take a few minutes for very large GTFS feeds.
+Without extra parameters it saves the timetable and stopsIndex for the current day in `/tmp` as binary protobufs.
+
+Run the REPL to query the router or the stop index (`minotor repl -h` for more options):
+
+`minotor repl`
+
+Search stops (`minotor> .find -h for more options`):
+
+`minotor> .find moleson`
+
+Query routes (`minotor> .route -h for more options`):
+
+`minotor> .route from fribourg to moleson at 08:00`
+
+## Development
+
+### Debugging
+
+It is possible to plot the router graph to debug the algorithm:
+
+`minotor repl`
+
+`minotor> .plot from <stationId> to <stationId> at <HH:mm> [with <N> transfers] [to <graph.dot>]`
+
+`dot -Ksfdp -Tsvg graph.dot -o graph.svg `
+
+### Build
+
+Make sure you have a working node setup as well as a protobuf compiler.
+
+- `build`: builds the project in the `dist/` directory
+- `clean`: removes the `dist/` directory
+
+### Tests
+
+- `test`: runs test runner
+- `test:coverage`: runs test runner with coverage reports
+
+### Formatting & linting
+
+- `lint`: ESLint with automatic fixing
+- `format`: Prettier with automatic fixing
+- `spell:check`: Spell checker
+
+### Releasing
+
+- `cz`: generates a valid git commit message (See [Commitizen](https://github.com/commitizen/cz-cli))
+
+Releases are automatically published to npm when merging to the `main` or `beta` (pre-release) branch.
+
+## Known issues
+
+### \[Work in Progress\] Train splits in Switzerland
+
+In the swiss GTFS feed, some transfers are missing for proper handling of trains that splits in two and diverge route at a given station.
+They are modeled as 2 routes, one covering the full route of the first variant and the other covering the route for the other variant but only from the split station (on the platforms where the part of train splitting is located) to the destination.
+The challenge is that no transfer indicates that it's possible to continue from the platform where the train arrives to the part of the platform where the other part of the train splits and continues on the other route.
+This is for example the case with the train starting from Landquart splitting in Klosters to reach lower Engadin or Davos. A transfer between 8509068:0:3 and 8509068:0:3AB is missing to understand that it's possible to continue on the way to Davos.
+While these transfers should ideally be handled at a route/trip level (the swiss feed contains only stop level transfers for now), artificially adding transfers between a station platform and its corresponding "sub-platforms" would be enough to tackle the issue in a minimal way.
+
+## Roadmap
+
+The project is under active development. Here are some of the features that are planned:
+
+- Documentation website and examples
+- Load multiple GTFS archives at once
+- Range queries
+- Transfer preferences
+- Support for exporting a calendar range as opposed to a single day
+- Support for GTFS `frequencies.txt`
+- Support for more types of transfers
+- NeTEx support
+- RT-GTFS Support