fegger
98e74ee48d
Add linting to the mobile app and include core and api-client packages in the root lint, typecheck, and test scripts. Ignore node_modules in all subdirectories and clean up stale test results. Update lint and typecheck scripts for all packages Add ESLint configuration for mobile app and shared packages. Rename mobile jest config to .cjs and enable ESM. Include packages/core and packages/api-client in monorepo lint, typecheck, and test scripts.
148 lines
6.7 KiB
Markdown
148 lines
6.7 KiB
Markdown
# ⏱️ TimeToLeave
|
|
|
|
|
|
|
|
> **TimeToLeave** is a smart departure planner that tells you exactly when to leave home to catch your public transport for upcoming appointments. It syncs with your personal calendar, checks real-time train/bus departures (HAFAS & WienerLinien), and provides a live "Leave Status" based on real-time delays.
|
|
|
|
   
|
|
|
|
## 🚀 How It Works
|
|
|
|
1. **Sync Your Calendar:** Import your `.ics` file or provide a calendar URL. The app extracts your upcoming events and destinations.
|
|
2. **Set Your Origin:** Define your home station or let the app use your current geolocation.
|
|
3. **Journey Calculation:** The app queries the HAFAS protocol and WienerLinien APIs to find the best public transport connections to your event destination.
|
|
4. **Real-Time Monitoring:** It monitors your train's real-time departure time, accounts for delays, and adds your local travel time (e.g., biking to the station) to calculate a dynamic countdown.
|
|
5. **Leave Status:** You get a clear status: `Leave now`, `On time`, `Delayed +X min`, or `Departure missed`.
|
|
|
|
## 🧱 Project Structure
|
|
|
|
This project uses a monorepo setup (npm workspaces) to manage multiple, interconnected parts:
|
|
|
|
| Directory | Description |
|
|
| :--- | :--- |
|
|
| `apps/web/` | The main web dashboard built with **Next.js 16**, React 19, and Tailwind CSS 4. |
|
|
| `apps/mobile/` | The on-the-go mobile client built with **React Native 0.81** and **Expo 54**. |
|
|
| `packages/core/` | Shared domain logic, types (`Event`, `Journey`, `Station`), countdown utilities, and status calculators. |
|
|
| `packages/api-client/` | A lightweight client that handles API proxies for HAFAS requests, calendar parsing, geocoding, and bike routing. |
|
|
|
|
## 🛠 Development & Running the Application
|
|
|
|
### Prerequisites
|
|
|
|
* Node.js (version 20.x or higher)
|
|
* npm (version 9.x or higher)
|
|
|
|
### Installation
|
|
|
|
1. **Clone the repository:**
|
|
```bash
|
|
git clone <repository-url>
|
|
cd TimeToLeave
|
|
```
|
|
|
|
2. **Install dependencies:**
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. **Environment variables:**
|
|
* For `apps/web` and `apps/mobile`, copy `.env.example` to `.env` in each app directory and update the backend API URL and any required keys.
|
|
|
|
### Available Scripts
|
|
|
|
| Script | Command | Description |
|
|
| :--- | :--- | :--- |
|
|
| `dev` | `npm run dev` | Starts the Next.js development server for the Web dashboard. |
|
|
| `dev:mobile` | `npm run dev:mobile` | Starts the Expo development server for the Mobile client. |
|
|
| `build` | `npm run build` | Builds the production bundle for the Web application. |
|
|
| `test` | `npm run test` | Runs Vitest for the Web app and Jest for the Mobile app. |
|
|
| `lint` | `npm run lint` | Runs ESLint across both web and mobile clients. |
|
|
| `typecheck` | `npm run typecheck` | Runs TypeScript type checking across all workspaces. |
|
|
|
|
## 📝 Key Features & Tech Stack
|
|
|
|
### Web Application (`apps/web`)
|
|
* **Framework:** Next.js 16.2.6 (App Router)
|
|
* **UI:** React 19.2.4 with Tailwind CSS 4
|
|
* **State Management:** React Context (via `EventsProvider` and `ReminderSettingsProvider`)
|
|
* **Routing:** Next.js built-in routing for `/` (event list) and `/calendar` views.
|
|
|
|
### Mobile Application (`apps/mobile`)
|
|
* **Framework:** React Native 0.81 via Expo 54
|
|
* **Navigation:** React Navigation 7 (Native Stack)
|
|
* **Device APIs:**
|
|
* `expo-location`: For geocoding your current position.
|
|
* `expo-calendar`: For native calendar event integration.
|
|
* `expo-notifications`: For native push notifications when it's time to leave.
|
|
* `@react-native-async-storage/async-storage`: For persisting settings and local state.
|
|
|
|
### Core Logic (`packages/core`)
|
|
* **Countdown Utilities:** Calculates time-deltas and assigns color codes (Red/Orange/Yellow/Green/Blue) based on urgency.
|
|
* **HAFAS Time Parsing:** Highly accurate timezone-aware parsing for HAFAS timestamps, specifically handling `Europe/Vienna` (CET/CEST) and DST transitions.
|
|
* **WienerLinien Support:** Native types and handling for Vienna public transport departures.
|
|
* **Leave Status:** Derives human-readable statuses (`Leave now`, `Delayed +10 min`, etc.) by comparing the best non-cancelled journey's real departure time against the current time.
|
|
|
|
## 📄 API Client Usage
|
|
|
|
The `@timetoleave/api-client` package provides a clean interface to interact with your backend proxy, which handles the heavy lifting of HAFAS protocol communication and calendar parsing.
|
|
|
|
```typescript
|
|
import { ApiClient } from "@timetoleave/api-client";
|
|
|
|
// Initialize with your backend URL
|
|
const api = new ApiClient("http://localhost:3000");
|
|
|
|
// 1. Sync your calendar
|
|
const events = await api.fetchCalendar("https://example.com/calendar.ics", 7);
|
|
|
|
// 2. Search for a station via the HAFAS LocMatch endpoint
|
|
const stationResult = await api.hafasRequest({
|
|
svcReqL: [
|
|
{
|
|
meth: "LocMatch",
|
|
req: { searchTxt: "Wien Mitte", maxMatches: 5 },
|
|
},
|
|
],
|
|
});
|
|
const stations = stationResult?.svcReqL?.[0]?.res?.locL ?? [];
|
|
|
|
// 3. Find journeys between stations for a specific date
|
|
const journeys = await api.searchJourneys(
|
|
stations[0].extId, // From
|
|
"dest:extId", // To
|
|
new Date() // Date
|
|
);
|
|
|
|
// 4. Get a bike route from your current location to the station
|
|
const bikeRoute = await api.getBikeRoute(
|
|
48.2082, 16.3738, // From lat/lng
|
|
48.1850, 16.3780 // To lat/lng
|
|
);
|
|
```
|
|
|
|
## 🛡️ Testing & Quality Assurance
|
|
|
|
The project provides comprehensive scripts for maintaining code quality:
|
|
|
|
* **Linting:** Use `npm run lint` to catch stylistic and structural errors via ESLint 9.
|
|
* **Type Checking:** Use `npm run typecheck` to ensure strict type safety across the codebase via TypeScript 5.
|
|
* **Testing:**
|
|
* The web application uses **Vitest** (v4.1.5) with **jsdom** and **@testing-library/react**.
|
|
* The mobile application uses **Jest** (v29.7.0) with **jest-expo** and **react-test-renderer**.
|
|
|
|
## 📂 File Structure
|
|
|
|
```text
|
|
├── apps/
|
|
│ ├── mobile/ # Mobile application using React Native and Expo
|
|
│ └── web/ # Web application using Next.js and Tailwind CSS
|
|
├── packages/
|
|
│ ├── api-client/ # API client for HAFAS, Calendar, and Routing proxies
|
|
│ └── core/ # Shared domain types, countdowns, and HAFAS time utilities
|
|
├── node_modules/ # Third-party dependencies
|
|
└── README.md # The file you're reading now
|
|
```
|
|
|
|
---
|
|
*Built for developers who bike to the train and hate missing their connections.*
|