feat: add speed metric extraction from TCX files

Implements parsing of speed data from ldn:SpeedMetersSec extensions in TCX files.
Features namespace-aware XML parsing that works with any namespace prefix for
the https://limulus.net/xsd/tcx/v1 namespace.

- Add Speed enum value to SampleMetric
- Implement namespace-aware speed parsing in TCXReader
- Add comprehensive test coverage for speed extraction
- Add @sindresorhus/is dependency for runtime type assertions
- Create test fixture for different namespace prefixes

Author: limulus

fixtures/tcx/different-namespace-prefix.tcx

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<TrainingCenterDatabase
+  xmlns="http://www.garmin.com/xmlschemas/TrainingCenterDatabase/v2"
+  xmlns:limulus="https://limulus.net/xsd/tcx/v1"
+>
+<Activities>
+  <Activity Sport="Biking">
+    <Id>2025-03-02T18:38:01Z</Id>
+    <Lap StartTime="2025-03-02T18:38:01Z">
+      <TotalTimeSeconds>10</TotalTimeSeconds>
+      <DistanceMeters>100</DistanceMeters>
+      <Calories>10</Calories>
+      <Intensity>Active</Intensity>
+      <TriggerMethod>Manual</TriggerMethod>
+      <Track>
+      <Trackpoint>
+        <Time>2025-03-02T19:00:33.999</Time>
+        <Position>
+          <LatitudeDegrees>32.36415566566089</LatitudeDegrees>
+          <LongitudeDegrees>-111.01644143335649</LongitudeDegrees>
+        </Position>
+        <AltitudeMeters>714.6836803928018</AltitudeMeters>
+        <Extensions>
+          <limulus:SpeedMetersSec>8.12345</limulus:SpeedMetersSec>
+          <limulus:CourseDegrees>213.60538018719149</limulus:CourseDegrees>
+        </Extensions>
+      </Trackpoint>
+      </Track>
+    </Lap>
+  </Activity>
+</Activities>
+</TrainingCenterDatabase>

package-lock.json

@@ -46,6 +46,7 @@
   },
   "homepage": "https://github.com/limulus/tcx2webvtt#readme",
   "dependencies": {
+    "@sindresorhus/is": "^7.0.2",
     "es-main": "^1.3.0",
     "fast-xml-parser": "^5.2.3",
     "prettier": "^3.5.3",

package.json

@@ -3,6 +3,7 @@ export enum SampleMetric {
   Distance = 'distance',
   Cadence = 'cadence',
   Power = 'power',
+  Speed = 'speed',
   Location = 'location',
 }
 

src/lib/sample.ts

@@ -167,6 +167,56 @@ describe('TCXReader', () => {
           firstLocationSample.value.longitude
         )
       }
+
+      // Check for speed samples
+      const speedSamples = samples.filter((s) => s.metric === SampleMetric.Speed)
+      expect(speedSamples.length).toBeGreaterThan(0)
+
+      // Check first speed sample value matches the first trackpoint with speed data
+      const firstSpeedSample = speedSamples[0] as Sample<SampleMetric.Speed>
+      expect(firstSpeedSample.value).toBeCloseTo(6.57443257931449)
+    })
+
+    it('should handle TCX content with different namespace prefix', async () => {
+      const tcxContent = await fs.readFile(
+        join(fixturesDir, 'different-namespace-prefix.tcx'),
+        'utf8'
+      )
+      const reader = new TCXReader(tcxContent)
+      const samples = reader.getSamples()
+
+      expect(samples).toBeInstanceOf(Array)
+      expect(samples.length).toBeGreaterThan(0)
+
+      // Check for speed samples with different namespace prefix
+      const speedSamples = samples.filter((s) => s.metric === SampleMetric.Speed)
+      expect(speedSamples.length).toBe(1)
+
+      // Check speed value from different namespace prefix
+      const speedSample = speedSamples[0] as Sample<SampleMetric.Speed>
+      expect(speedSample.value).toBeCloseTo(8.12345)
+
+      // Also verify location sample exists
+      const locationSamples = samples.filter((s) => s.metric === SampleMetric.Location)
+      expect(locationSamples.length).toBe(1)
+    })
+
+    it('should handle TCX content without ldn namespace', async () => {
+      const tcxContent = await fs.readFile(join(fixturesDir, 'concept2.tcx'), 'utf8')
+      const reader = new TCXReader(tcxContent)
+
+      // This tests the case where the ldn namespace is not found
+      // The speed parsing should return null and no speed samples should be created
+      const samples = reader.getSamples()
+      const speedSamples = samples.filter((s) => s.metric === SampleMetric.Speed)
+
+      // concept2.tcx doesn't have ldn namespace, so no speed samples
+      expect(speedSamples.length).toBe(0)
+
+      // But it should have other samples
+      expect(samples.length).toBeGreaterThan(0)
+      const heartRateSamples = samples.filter((s) => s.metric === SampleMetric.HeartRate)
+      expect(heartRateSamples.length).toBeGreaterThan(0)
     })
   })
 })

src/lib/tcx-reader.spec.ts

@@ -1,10 +1,12 @@
+import { assertObject } from '@sindresorhus/is'
 import { XMLParser } from 'fast-xml-parser'
 
 import { Sample, SampleMetric, Coordinates } from './sample.js'
 
 export class TCXReader {
   private readonly parser: XMLParser
   private readonly xmlData: any
+  private readonly ldnNamespaceURI = 'https://limulus.net/xsd/tcx/v1'
 
   constructor(tcxContent: string) {
     this.parser = new XMLParser({
@@ -14,6 +16,40 @@ export class TCXReader {
     this.xmlData = this.parser.parse(tcxContent)
   }
 
+  private findNamespacePrefix(namespaceURI: string): string | null {
+    const rootElement = this.xmlData?.TrainingCenterDatabase
+
+    assertObject(
+      rootElement,
+      'TrainingCenterDatabase must be a valid object for namespace lookup'
+    )
+
+    // Look for namespace declarations
+    for (const [key, value] of Object.entries(rootElement)) {
+      if (key.startsWith('@_xmlns:') && value === namespaceURI) {
+        return key.substring('@_xmlns:'.length)
+      }
+    }
+    return null
+  }
+
+  private getSpeedFromExtensions(extensions: any): number | null {
+    if (!extensions) return null
+
+    const ldnPrefix = this.findNamespacePrefix(this.ldnNamespaceURI)
+    if (ldnPrefix === null) return null
+
+    const speedValue = extensions[`${ldnPrefix}:SpeedMetersSec`]
+
+    if (speedValue !== undefined && speedValue !== null && speedValue !== '') {
+      const speed = parseFloat(String(speedValue))
+      if (!isNaN(speed)) {
+        return speed
+      }
+    }
+    return null
+  }
+
   public getSamples(): Sample<SampleMetric>[] {
     const activities = this.xmlData?.TrainingCenterDatabase?.Activities?.Activity
     if (!activities) {
@@ -108,6 +144,12 @@ export class TCXReader {
               }
             }
           }
+
+          // Parse speed from ldn namespace extensions if available
+          const speed = this.getSpeedFromExtensions(tp.Extensions)
+          if (speed !== null) {
+            allSamples.push(new Sample<SampleMetric.Speed>(time, SampleMetric.Speed, speed))
+          }
         }
       }
     }