fit-file-parser 2.2.3 → 2.2.5

package/.agent/rules/fit-parser-dev.md

@@ -0,0 +1,35 @@
+# FIT Parser Development Rules
+
+You are working on the `fit-parser` library. Follow these rules strictly to ensure correctness and stability.
+
+## Core Principles
+
+1.  **Trust the Official SDK**:
+    *   Always verify Message IDs and Field IDs against the Official Garmin FIT SDK (`@garmin/fitsdk`).
+    *   **NEVER** guess or reuse existing IDs if they seem wrong (e.g., Message 140 vs 285).
+    *   If `@garmin/fitsdk` is available in `node_modules`, use it as the source of truth.
+
+2.  **Investigation First**:
+    *   If a field is missing, use `npm run inspect <file>` or `npm run probe <file> <value>` BEFORE modifying code.
+    *   Confirm the field exists in the file and identify its raw value.
+
+3.  **Testing is Mandatory**:
+    *   Every new message or field definition MUST have a corresponding test case in `test/`.
+    *   Test against real FIT files whenever possible (use `examples/` directory).
+    *   Use `npm run test` to verify changes.
+
+4.  **Code Generation**:
+    *   `src/fit_types.ts` is AUTO-GENERATED.
+    *   If you modify `src/fit.ts`, you **MUST** run `npm run codegen` to update types.
+    *   Do not edit `src/fit_types.ts` manually.
+
+## Workflow checklist
+
+When adding a new message or fixing a field:
+
+- [ ] Locate official Message ID in Garmin SDK
+- [ ] Locate Field IDs and Types in Garmin SDK
+- [ ] Update `src/fit.ts` with new definition
+- [ ] Run `npm run codegen`
+- [ ] Add/Update test in `test/`
+- [ ] Run `npm run build && npm run test`

package/.agent/skills/add-fit-message/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: add-fit-message
+description: Add a new FIT message or update an existing one
+---
+
+# Add/Update FIT Message
+
+## Prerequisites
+
+- Identify Message ID (e.g., 285 for Jump)
+- Identify Field IDs and Types from Garmin SDK
+
+## Steps
+
+1.  **Modify `src/fit.ts`** - Add message definition
+2.  **Run `npm run codegen`** - Updates `src/fit_types.ts`
+3.  **Add Test** - Create test in `test/`
+4.  **Verify** - Run `npm run build && npm run test`
+
+## Example Entry
+
+```typescript
+285: {
+  name: 'jump',
+  253: { field: 'timestamp', type: 'date_time', scale: null, offset: 0, units: 's' },
+  0: { field: 'distance', type: 'float32', scale: null, offset: 0, units: 'm' },
+  5: { field: 'position_lat', type: 'sint32', scale: null, offset: 0, units: 'semicircles' },
+}
+```

package/.agent/workflows/fit-workflows.md

@@ -0,0 +1,28 @@
+---
+description: common fit-parser development workflows
+---
+
+# Inspect FIT File
+
+// turbo
+1. node scripts/inspect_fit.js <path_to_fit_file> [message_key]
+
+# Probe FIT File for Value
+
+// turbo
+1. node scripts/deep_probe.js <path_to_fit_file> <value> [tolerance]
+
+# Run Tests
+
+// turbo
+1. npm run build && npm run test
+
+# Add New Message
+
+1. Locate Message ID in `@garmin/fitsdk/src/profile.js`
+2. Update `src/fit.ts` with message definition
+// turbo
+3. npm run codegen
+4. Add test in `test/`
+// turbo
+5. npm run build && npm run test

package/INVESTIGATING.md

@@ -0,0 +1,50 @@
+# Investigating FIT Files
+
+This guide explains how to investigate FIT files when you suspect fields are missing or incorrectly parsed, and how to add support for new messages.
+
+## Tools Included
+
+We provide scripts in the `scripts/` directory to help you probe FIT files.
+
+### 1. Inspecting Parsed Data (`scripts/inspect_fit.js`)
+
+Use this script to see what the parser currently outputs for a file.
+
+```bash
+# View summary of all messages in file
+node scripts/inspect_fit.js examples/jumps-mtb.fit
+
+# View specific message details
+node scripts/inspect_fit.js examples/jumps-mtb.fit jumps
+node scripts/inspect_fit.js examples/jumps-mtb.fit session
+```
+
+### 2. Probing for Unknown Data (`scripts/deep_probe.js`)
+
+Use this script when you know a value exists (e.g., from Garmin Connect or another tool) but can't find it in the parser output. It recursively searches the raw parsed structure for that value.
+
+```bash
+# Edit the script to set the value you're looking for, then run:
+node scripts/deep_probe.js
+```
+
+## Workflow for Missing Fields
+
+If you suspect a field is missing (e.g., "Jump Hang Time"):
+
+1.  **Verify it exists**: Check the file with an external tool or online viewer. Note the exact value (e.g., `0.36` seconds).
+2.  **Probe**: Use `deep_probe.js` or inspect the `examples/` output to see if the value appears in an unknown field (e.g., `field_123`).
+3.  **Identify Message ID**:
+    *   Check `src/fit.ts` for the message definition.
+    *   If the message ID seems wrong, or fields are missing, compare with the **Official Garmin FIT SDK**.
+    *   *Tip: You can find the official SDK in `@garmin/fitsdk` if installed, or search online.*
+4.  **Fix**:
+    *   Update `src/fit.ts` with the correct Message ID and Field IDs.
+    *   Run `npm run codegen` to update types.
+    *   Add a test case in `test/` relative to your new message.
+
+## Common Issues
+
+*   **Wrong Message ID**: Sometimes `fit-parser` has legacy or guessed IDs (e.g., `jump` was 140, but official is 285).
+*   **Missing Fields**: New devices add new fields. They often appear as `unknown_field_X`.
+*   **Scale/Offset**: If values look huge (e.g., 20838184 instead of 20.838), check if they need a scale factor (e.g., `semicircles` to `degrees`).

package/check_ids.js

@@ -0,0 +1,24 @@
+import fs from 'fs';
+import FitParser from './dist/fit-parser.js';
+
+const content = fs.readFileSync('../sports-lib/samples/fit/jumps-mtb.fit');
+const fitParser = new (FitParser.default || FitParser)({ force: true, mode: 'both' });
+
+fitParser.parse(content, (error, data) => {
+    if (error) { console.error(error); return; }
+
+    // The parser stores messages in data[messageName]
+    // Any unknown messages are in data[messageId] (if numeric)
+    console.log('Keys in data:', Object.keys(data));
+
+    // Let's check for anything that looks like a message ID
+    for (const key of Object.keys(data)) {
+        if (!isNaN(parseInt(key))) {
+            console.log(`Unknown Message ID found: ${key} (${data[key].length} items)`);
+        }
+    }
+
+    if (data.jumps) {
+        console.log('Jumps fields:', Object.keys(data.jumps[0]));
+    }
+});

package/check_jump_fields.js

@@ -0,0 +1,46 @@
+import fs from 'fs'
+import { createRequire } from 'module'
+
+const require = createRequire(import.meta.url)
+const FitParser = require('./dist/fit-parser.js').default
+
+const content = fs.readFileSync('./examples/jumps-mtb.fit')
+const fitParser = new FitParser({
+  force: true,
+  speedUnit: 'm/s',
+  lengthUnit: 'm',
+  temperatureUnit: 'celsius',
+  elapsedRecordField: true,
+  mode: 'both',
+})
+
+fitParser.parse(content, (error, data) => {
+  if (error) {
+    console.error(error)
+    return
+  }
+
+  console.log('=== JUMPS ARRAY ===')
+  if (data.jumps && data.jumps.length > 0) {
+    data.jumps.forEach((jump, i) => {
+      console.log(`\nJump ${i + 1}:`)
+      Object.keys(jump).forEach((key) => {
+        console.log(`  ${key}: ${JSON.stringify(jump[key])}`)
+      })
+    })
+  }
+  else {
+    console.log('No jumps found')
+  }
+
+  // Also check definitions array for message 140 (jump)
+  console.log('\n=== DEFINITIONS FOR MESSAGE 140 (JUMP) ===')
+  if (data.definitions) {
+    const jumpDefs = data.definitions.filter(d => d && d.messageType === 140)
+    console.log(`Found ${jumpDefs.length} jump definitions`)
+    jumpDefs.forEach((def, i) => {
+      console.log(`\nDefinition ${i + 1}:`)
+      console.log(JSON.stringify(def, null, 2))
+    })
+  }
+})

package/dist/binary.js

@@ -84,6 +84,10 @@ function readData(blob, fDef, startIndex, options) {
         }
         return temp;
     }
+    if (fDef.type === 'sint8') {
+        const val = blob[startIndex];
+        return val > 127 ? val - 256 : val;
+    }
     return blob[startIndex];
 }
 function formatByType(data, type, scale, offset) {

package/dist/cjs/binary.js

@@ -90,6 +90,10 @@ function readData(blob, fDef, startIndex, options) {
         }
         return temp;
     }
+    if (fDef.type === 'sint8') {
+        const val = blob[startIndex];
+        return val > 127 ? val - 256 : val;
+    }
     return blob[startIndex];
 }
 function formatByType(data, type, scale, offset) {

package/dist/cjs/fit.js

@@ -3005,13 +3005,18 @@ exports.FIT = {
                 units: 'percent',
             },
         },
-        140: {
+        285: {
             name: 'jump',
             253: { field: 'timestamp', type: 'date_time', scale: null, offset: 0, units: 's' },
-            9: { field: 'distance', type: 'uint16', scale: 100, offset: 0, units: 'm' },
-            10: { field: 'height', type: 'uint16', scale: 1000, offset: 0, units: 'm' },
-            37: { field: 'score', type: 'sint32', scale: null, offset: 0, units: '' },
-            7: { field: 'enhanced_mets', type: 'uint32', scale: 65536, offset: 0, units: 'METs' },
+            0: { field: 'distance', type: 'float32', scale: null, offset: 0, units: 'm' },
+            1: { field: 'height', type: 'float32', scale: null, offset: 0, units: 'm' },
+            2: { field: 'rotations', type: 'uint8', scale: null, offset: 0, units: '' },
+            3: { field: 'hang_time', type: 'float32', scale: null, offset: 0, units: 's' },
+            4: { field: 'score', type: 'float32', scale: null, offset: 0, units: '' },
+            5: { field: 'position_lat', type: 'sint32', scale: null, offset: 0, units: 'semicircles' },
+            6: { field: 'position_long', type: 'sint32', scale: null, offset: 0, units: 'semicircles' },
+            7: { field: 'speed', type: 'uint16', scale: 1000, offset: 0, units: 'm/s' },
+            8: { field: 'enhanced_speed', type: 'uint32', scale: 1000, offset: 0, units: 'm/s' },
         },
         21: {
             name: 'event',

package/dist/cjs/fit_types.d.ts

@@ -871,13 +871,6 @@ export interface ParsedOHrSettings {
     enabled?: number;
     timestamp: string;
 }
-export interface ParsedJump {
-    enhanced_mets?: number;
-    distance?: number;
-    height?: number;
-    score?: number;
-    timestamp: string;
-}
 export interface ParsedFieldDescription {
     developer_data_index?: number;
     field_definition_number?: number;
@@ -975,6 +968,18 @@ export interface ParsedDiveSummary {
     bottom_time?: number;
     timestamp: string;
 }
+export interface ParsedJump {
+    distance?: number;
+    height?: number;
+    rotations?: number;
+    hang_time?: number;
+    score?: number;
+    position_lat?: number;
+    position_long?: number;
+    speed?: number;
+    enhanced_speed?: number;
+    timestamp: string;
+}
 export interface ParsedTankUpdate {
     sensor?: number;
     pressure?: number;

package/dist/fit.js

@@ -3002,13 +3002,18 @@ export const FIT = {
                 units: 'percent',
             },
         },
-        140: {
+        285: {
             name: 'jump',
             253: { field: 'timestamp', type: 'date_time', scale: null, offset: 0, units: 's' },
-            9: { field: 'distance', type: 'uint16', scale: 100, offset: 0, units: 'm' },
-            10: { field: 'height', type: 'uint16', scale: 1000, offset: 0, units: 'm' },
-            37: { field: 'score', type: 'sint32', scale: null, offset: 0, units: '' },
-            7: { field: 'enhanced_mets', type: 'uint32', scale: 65536, offset: 0, units: 'METs' },
+            0: { field: 'distance', type: 'float32', scale: null, offset: 0, units: 'm' },
+            1: { field: 'height', type: 'float32', scale: null, offset: 0, units: 'm' },
+            2: { field: 'rotations', type: 'uint8', scale: null, offset: 0, units: '' },
+            3: { field: 'hang_time', type: 'float32', scale: null, offset: 0, units: 's' },
+            4: { field: 'score', type: 'float32', scale: null, offset: 0, units: '' },
+            5: { field: 'position_lat', type: 'sint32', scale: null, offset: 0, units: 'semicircles' },
+            6: { field: 'position_long', type: 'sint32', scale: null, offset: 0, units: 'semicircles' },
+            7: { field: 'speed', type: 'uint16', scale: 1000, offset: 0, units: 'm/s' },
+            8: { field: 'enhanced_speed', type: 'uint32', scale: 1000, offset: 0, units: 'm/s' },
         },
         21: {
             name: 'event',

package/dist/fit_types.d.ts

@@ -871,13 +871,6 @@ export interface ParsedOHrSettings {
     enabled?: number;
     timestamp: string;
 }
-export interface ParsedJump {
-    enhanced_mets?: number;
-    distance?: number;
-    height?: number;
-    score?: number;
-    timestamp: string;
-}
 export interface ParsedFieldDescription {
     developer_data_index?: number;
     field_definition_number?: number;
@@ -975,6 +968,18 @@ export interface ParsedDiveSummary {
     bottom_time?: number;
     timestamp: string;
 }
+export interface ParsedJump {
+    distance?: number;
+    height?: number;
+    rotations?: number;
+    hang_time?: number;
+    score?: number;
+    position_lat?: number;
+    position_long?: number;
+    speed?: number;
+    enhanced_speed?: number;
+    timestamp: string;
+}
 export interface ParsedTankUpdate {
     sensor?: number;
     pressure?: number;

package/find_field.js

@@ -0,0 +1,23 @@
+const fs = require('fs');
+const FitParser = require('./dist/fit-parser.js').default;
+
+const content = fs.readFileSync('../sports-lib/samples/fit/jumps-mtb.fit');
+const fitParser = new FitParser({ force: true, mode: 'both' });
+
+fitParser.parse(content, (error, data) => {
+    if (error) { console.error(error); return; }
+    
+    function search(obj, path = '') {
+        if (!obj || typeof obj !== 'object') return;
+        for (const [key, value] of Object.entries(obj)) {
+            const currentPath = path ? `${path}.${key}` : key;
+            if (key === 'enhanced_mets') {
+                console.log(`FOUND enhanced_mets at ${currentPath}: ${value}`);
+            }
+            search(value, currentPath);
+        }
+    }
+    
+    search(data);
+    console.log('Search finished.');
+});

package/find_field_esm.js

@@ -0,0 +1,28 @@
+import fs from 'fs';
+import FitParser from './dist/fit-parser.js';
+
+const content = fs.readFileSync('../sports-lib/samples/fit/jumps-mtb.fit');
+// Try both ways to instantiate
+const fitParser = new (FitParser.default || FitParser)({ force: true, mode: 'both' });
+
+fitParser.parse(content, (error, data) => {
+    if (error) { console.error(error); return; }
+
+    function search(obj, path = '') {
+        if (!obj || typeof obj !== 'object') return;
+        if (Array.isArray(obj)) {
+            obj.forEach((item, index) => search(item, `${path}[${index}]`));
+            return;
+        }
+        for (const [key, value] of Object.entries(obj)) {
+            const currentPath = path ? `${path}.${key}` : key;
+            if (key === 'enhanced_mets') {
+                console.log(`FOUND enhanced_mets at ${currentPath}: ${value}`);
+            }
+            search(value, currentPath);
+        }
+    }
+
+    search(data);
+    console.log('Search finished.');
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fit-file-parser",
   "type": "module",
-  "version": "2.2.3",
+  "version": "2.2.5",
   "private": false,
   "description": "Parse your .FIT files easily, directly from JS (Garmin, Polar, Suunto)",
   "author": {
@@ -75,4 +75,4 @@
     "typescript": "^5.9.3",
     "vitest": "^4.0.13"
   }
-}
+}

package/scan_jumps.js

@@ -0,0 +1,29 @@
+import fs from 'fs';
+import FitParser from './dist/fit-parser.js';
+
+const content = fs.readFileSync('../sports-lib/samples/fit/jumps-mtb.fit');
+const fitParser = new (FitParser.default || FitParser)({ force: true, mode: 'both' });
+
+fitParser.parse(content, (error, data) => {
+    if (error) { console.error(error); return; }
+
+    if (data.jumps && data.jumps.length > 0) {
+        console.log(`Found ${data.jumps.length} jumps.`);
+        data.jumps.forEach((j, i) => {
+            // check for values close to 16.3038
+            const target = 16.3038;
+            const epsilon = 0.1;
+
+            Object.entries(j).forEach(([key, val]) => {
+                if (typeof val === 'number' && Math.abs(val - target) < epsilon) {
+                    console.log(`MATCH INDEX ${i} KEY ${key}: ${val}`);
+                }
+            });
+
+            // Also just print field 7 ('speed' in new def)
+            console.log(`Jump ${i}: speed=${j.speed}`);
+        });
+    } else {
+        console.log('No jumps found.');
+    }
+});

package/scripts/deep_probe.js

@@ -0,0 +1,74 @@
+import fs from 'fs'
+import { createRequire } from 'module'
+
+const require = createRequire(import.meta.url)
+// Try to load from local build or node_modules
+let FitParser
+try {
+  FitParser = require('../dist/fit-parser.js').default
+}
+catch (e) {
+  FitParser = require('fit-file-parser').default
+}
+
+const args = process.argv.slice(2)
+if (args.length < 2) {
+  console.log('Usage: node deep_probe.js <path_to_fit_file> <search_value> [tolerance]')
+  console.log('Example: node deep_probe.js ../examples/jumps-mtb.fit 11 0.1')
+  process.exit(1)
+}
+
+const filePath = args[0]
+const targetValue = Number.parseFloat(args[1])
+const tolerance = args[2] ? Number.parseFloat(args[2]) : 0.001
+
+if (isNaN(targetValue)) {
+  console.error('Error: Search value must be a number')
+  process.exit(1)
+}
+
+try {
+  const content = fs.readFileSync(filePath)
+  const fitParser = new FitParser({
+    force: true,
+    speedUnit: 'm/s',
+    lengthUnit: 'm',
+    temperatureUnit: 'celsius',
+    elapsedRecordField: true,
+    mode: 'both',
+  })
+
+  function search(obj, path = []) {
+    if (!obj || typeof obj !== 'object')
+      return
+
+    Object.keys(obj).forEach((key) => {
+      const val = obj[key]
+      const newPath = [...path, key]
+
+      if (typeof val === 'number') {
+        if (Math.abs(val - targetValue) <= tolerance) {
+          console.log(`>>> FOUND MATCH at: ${newPath.join('.')} (Value: ${val})`)
+        }
+      }
+
+      if (typeof val === 'object') {
+        search(val, newPath)
+      }
+    })
+  }
+
+  fitParser.parse(content, (error, data) => {
+    if (error) {
+      console.error(error)
+    }
+    else {
+      console.log(`Searching for value ${targetValue} (±${tolerance}) in ${filePath}...`)
+      search(data)
+      console.log('Search complete.')
+    }
+  })
+}
+catch (e) {
+  console.error('Error:', e.message)
+}

package/scripts/inspect_fit.js

@@ -0,0 +1,69 @@
+import fs from 'fs'
+import { createRequire } from 'module'
+
+const require = createRequire(import.meta.url)
+// Try to load from local build or node_modules
+let FitParser
+try {
+  FitParser = require('../dist/fit-parser.js').default
+}
+catch (e) {
+  FitParser = require('fit-file-parser').default
+}
+
+const args = process.argv.slice(2)
+if (args.length < 1) {
+  console.log('Usage: node inspect_fit.js <path_to_fit_file> [message_key]')
+  console.log('Example: node inspect_fit.js ../examples/jumps-mtb.fit jumps')
+  process.exit(1)
+}
+
+const filePath = args[0]
+const messageKey = args[1]
+
+try {
+  const content = fs.readFileSync(filePath)
+  const fitParser = new FitParser({
+    force: true,
+    mode: 'both',
+    speedUnit: 'm/s',
+    lengthUnit: 'm',
+  })
+
+  fitParser.parse(content, (error, data) => {
+    if (error) {
+      console.error('Error parsing FIT file:', error)
+      return
+    }
+
+    if (messageKey) {
+      if (data[messageKey]) {
+        console.log(`\n=== ${messageKey.toUpperCase()} (${Array.isArray(data[messageKey]) ? data[messageKey].length : 'object'}) ===`)
+        console.log(JSON.stringify(data[messageKey], null, 2))
+      }
+      else if (data.activity && data.activity[messageKey]) {
+        console.log(`\n=== ACTIVITY.${messageKey.toUpperCase()} ===`)
+        console.log(JSON.stringify(data.activity[messageKey], null, 2))
+      }
+      else {
+        console.log(`\nMessage key '${messageKey}' not found in root or activity object.`)
+        console.log('Available keys:', Object.keys(data).join(', '))
+      }
+    }
+    else {
+      console.log('\n=== ROOT KEYS ===')
+      console.log(Object.keys(data).join('\n'))
+
+      // Print summary of counts
+      console.log('\n=== SUMMARY ===')
+      Object.keys(data).forEach((key) => {
+        if (Array.isArray(data[key])) {
+          console.log(`${key}: ${data[key].length} items`)
+        }
+      })
+    }
+  })
+}
+catch (e) {
+  console.error('Error reading file:', e.message)
+}

package/deep_probe.js

@@ -1,70 +0,0 @@
-import fs from 'fs'
-import { createRequire } from 'module'
-
-const require = createRequire(import.meta.url)
-const FitParser = require('./dist/fit-parser.js').default
-
-const content = fs.readFileSync('/Users/dimitrios/Projects/sports-lib/samples/fit/jumps-mtb.fit')
-const fitParser = new FitParser({
-  force: true,
-  speedUnit: 'km/h',
-  lengthUnit: 'm',
-  temperatureUnit: 'celsius',
-  elapsedRecordField: true,
-  mode: 'both',
-})
-
-function search(obj, path = []) {
-  if (!obj || typeof obj !== 'object')
-    return
-
-  Object.keys(obj).forEach((key) => {
-    const val = obj[key]
-    const newPath = [...path, key]
-
-    // Check match 11 (Jump Count)
-    if (typeof val === 'number' && Math.abs(val - 11) < 0.001) {
-      console.log(`>>> FOUND 11 at: ${newPath.join('.')} (Value: ${val})`)
-    }
-    // Check match 159 (Resting Cals)
-    if (typeof val === 'number' && Math.abs(val - 159) < 0.1) {
-      console.log(`>>> FOUND 159 at: ${newPath.join('.')} (Value: ${val})`)
-    }
-    // Check match for Training Load Peak
-    if (typeof val === 'number' && Math.abs(val - 6079174) < 100) {
-      console.log(`>>> FOUND 6M at: ${newPath.join('.')} (Value: ${val})`)
-    }
-
-    if (typeof val === 'object') {
-      search(val, newPath)
-    }
-  })
-}
-
-fitParser.parse(content, (error, data) => {
-  if (error) {
-    console.error(error)
-  }
-  else {
-    console.log('Starting deep search...')
-    search(data)
-
-    if (data.sessions && data.sessions.length > 0) {
-      console.log('\n=== SESSION OBJECT (First) ===')
-      const session = data.sessions[0]
-      Object.keys(session).forEach((key) => {
-        console.log(`${key}: ${session[key]}`)
-      })
-    }
-    // Explicitly check for jump-related keys
-    if (data.jumps) {
-      console.log('=== JUMPS OBJECT === ')
-      console.log(JSON.stringify(data.jumps, null, 2))
-    }
-    // Also check for jump events in events
-    if (data.events) {
-      const jumpEvents = data.events.filter(e => JSON.stringify(e).includes('jump'))
-      console.log(`Found ${jumpEvents.length} jump events`)
-    }
-  }
-})