How tderflinger/tcx-ls works
Project type and purpose
• This is a single‐executable command‐line tool, written in TypeScript for the Deno runtime, that reads Garmin TCX XML files, computes activity metrics (distance, time, speed, cadence), and either prints them to the console or exports them as GeoJSON or CSV.
File structure
• Top‐level:
• main.ts – CLI entry point
• deno.json, deno.lock – Deno config & dependency lock
• README.md, doc/... – Project documentation
• .github/workflows – CI/CD for building/releasing binary
• src/ folder: core modules
• tcx-reader.ts – reads & parses the raw XML
• parse-tcx-xml.ts – XML→in-memory AST of TCX
• calculations.ts – computes aggregates & statistics
• tcx-console-printer.ts – formats and prints to terminal
• geojson-writer.ts – serializes trackpoints to GeoJSON
• laps-csv-writer.ts – serializes lap records to CSV
• tests/: automated tests for output formatting
Key insights from README
• CLI options trigger different exporters (console, geojson, csv).
• Written for Deno – uses Deno.run, --allow-read, --allow-write.
• No external microservices – pure local file processing.
Main components
a. CLI Layer (main.ts + Deno runtime)
b. Input subsystem – TCX Reader & XML parser
c. Processing subsystem – Calculations & Metrics Engine
d. Output subsystem – Console Printer, GeoJSON Writer, CSV Writer
e. File System / OS – read .tcx, write .json/.csv
Relationships and data flow
1. User invokes main.ts with flags and file path.
2. CLI Layer parses arguments, passes file path + mode to Input subsystem.
3. TCX Reader loads file → hands raw XML to XML Parser.
4. Parser outputs structured data (arrays of laps, trackpoints).
5. Calculations module ingests structured data → computes time/distance/speed/cadence.
6. Depending on flags:
– Console Printer reads calc results → writes to stdout.
– GeoJSON Writer takes trackpoints → writes GeoJSON file.
– CSV Writer takes lap records → writes CSV file.
7. Deno runtime handles file I/O permissions.
Architectural patterns & design principles
• Modular single‐process pipeline
• Separation of concerns: parsing / computing / formatting
• Dependency injection by passing data structures between layers
• Easily extensible: add new writer modules (e.g., KML writer)
Technologies & frameworks
• Deno (runtime, permission model, built-in testing)
• TypeScript modules
• Standard Deno file and stream APIs
• GitHub Actions for building and releasing native binaries