fit-file-parser 5.0.2 → 5.2.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## Unreleased
 
+### Added
+
+- Add opt-in, message-filterable `raw_messages` output with exact native and
+  developer-field bytes, wire base types, endianness, message occurrence, and
+  reconstructed compressed timestamps. Existing decoded output remains
+  unchanged when the option is disabled.
+- Add `rawMessagesOnly` for bounded metadata consumers that do not need decoded
+  activity collections alongside retained messages.
+
+### Fixed
+
+- Decode compressed timestamp records without consuming bytes for the omitted
+  timestamp field.
+
+## 5.1.0
+
+### Added
+
+- Add opt-in, message-filterable `raw_developer_fields` output with exact
+  developer-field bytes, global-message occurrence, developer-data index, and
+  field-definition number. Existing decoded output remains unchanged when the
+  option is disabled.
+
 ## 5.0.2
 
 ### Fixed

package/README.md

@@ -135,20 +135,98 @@ callback API receives as its first argument.
 
 All options are optional.
 
-| Option               | Values                                  | Default   | Behavior                                                                                                                                       |
-| -------------------- | --------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mode`               | `list`, `cascade`, `both`               | `list`    | Controls whether primary activity collections are returned as root lists, nested data, or both.                                                |
-| `force`              | `true`, `false`                         | `true`    | Skips header and file CRC validation and enables supported best-effort field recovery. Structural header and data bounds are always validated. |
-| `speedUnit`          | `m/s`, `km/h`, `mph`                    | `m/s`     | Converts speed-related fields.                                                                                                                 |
-| `lengthUnit`         | `m`, `km`, `mi`                         | `m`       | Converts distance, altitude, and other length-related fields.                                                                                  |
-| `temperatureUnit`    | `celsius`, `°C`, `kelvin`, `fahrenheit` | `celsius` | Converts temperature fields. `°C` remains available as a legacy alias.                                                                         |
-| `pressureUnit`       | `bar`, `cbar`, `psi`                    | `bar`     | Converts pressure and tank-pressure fields.                                                                                                    |
-| `elapsedRecordField` | `true`, `false`                         | `false`   | Adds `elapsed_time` and `timer_time`, in seconds, to records.                                                                                  |
+| Option                      | Values                                  | Default   | Behavior                                                                                                                                       |
+| --------------------------- | --------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`                      | `list`, `cascade`, `both`               | `list`    | Controls whether primary activity collections are returned as root lists, nested data, or both.                                                |
+| `force`                     | `true`, `false`                         | `true`    | Skips header and file CRC validation and enables supported best-effort field recovery. Structural header and data bounds are always validated. |
+| `speedUnit`                 | `m/s`, `km/h`, `mph`                    | `m/s`     | Converts speed-related fields.                                                                                                                 |
+| `lengthUnit`                | `m`, `km`, `mi`                         | `m`       | Converts distance, altitude, and other length-related fields.                                                                                  |
+| `temperatureUnit`           | `celsius`, `°C`, `kelvin`, `fahrenheit` | `celsius` | Converts temperature fields. `°C` remains available as a legacy alias.                                                                         |
+| `pressureUnit`              | `bar`, `cbar`, `psi`                    | `bar`     | Converts pressure and tank-pressure fields.                                                                                                    |
+| `elapsedRecordField`        | `true`, `false`                         | `false`   | Adds `elapsed_time` and `timer_time`, in seconds, to records.                                                                                  |
+| `includeRawDeveloperFields` | `true`, `false`, message-number array   | `false`   | Adds a lossless, message-associated view of developer-field bytes at `raw_developer_fields`.                                                   |
+| `includeRawMessages`        | `true`, `false`, message-number array   | `false`   | Adds selected FIT messages with exact native/developer bytes and wire metadata at `raw_messages`.                                              |
+| `rawMessagesOnly`           | `true`, `false`                         | `false`   | Omits decoded activity collections when a consumer needs only the opt-in raw-message representation.                                           |
 
 `force: true` does not make arbitrary bytes a valid FIT file. Inputs that are
 too short, have an invalid header size or signature, or declare data beyond the
 available bytes are rejected in both modes.
 
+### Lossless developer fields
+
+By default, developer fields retain the existing decoded, name-keyed output.
+Set `includeRawDeveloperFields: true` when a consumer also needs exact field
+bytes or must distinguish same-named fields from different developer-data
+indexes:
+
+```javascript
+const data = await new FitParser({
+  force: false,
+  includeRawDeveloperFields: [18],
+}).parseAsync(content)
+
+for (const field of data.raw_developer_fields ?? []) {
+  console.log({
+    globalMessageNumber: field.global_message_number,
+    messageIndex: field.message_index,
+    developerDataIndex: field.developer_data_index,
+    fieldDefinitionNumber: field.field_definition_number,
+    rawBytes: field.raw_value,
+  })
+}
+```
+
+`message_index` is the zero-based occurrence of that global message number in
+file order. `raw_value` is a defensive plain-number copy of the exact FIT field
+bytes, including interior NUL bytes and invalid sentinels. Join
+`developer_data_index` and `field_definition_number` to the existing
+`developer_data_ids` and `field_descriptions` collections to interpret an
+application and field. The parser deliberately does not infer application- or
+provider-specific semantics. Pass `true` to retain developer fields from every
+global message, or an array such as `[18]` to bound collection to specific FIT
+message numbers.
+
+### Lossless selected messages
+
+Set `includeRawMessages` when a consumer needs native FIT numeric codes rather
+than the parser's intentionally formatted enum names, or needs native and
+developer fields grouped exactly by message occurrence:
+
+```javascript
+const data = await new FitParser({
+  force: false,
+  includeRawMessages: [18, 26, 72, 206, 207],
+  rawMessagesOnly: true,
+}).parseAsync(content)
+
+for (const message of data.raw_messages ?? []) {
+  console.log({
+    globalMessageNumber: message.global_message_number,
+    messageIndex: message.message_index,
+    littleEndian: message.little_endian,
+    fields: message.fields,
+    developerFields: message.developer_fields,
+  })
+}
+```
+
+Each native field includes its field-definition number, wire base-type byte,
+and a defensive plain-number copy of its exact bytes. Developer fields retain
+their developer-data index, field-definition number, and exact bytes. Empty
+selected messages are retained with empty field arrays. For a compressed
+timestamp record, the timestamp is not present on the wire and therefore is
+not invented in `fields`; its reconstructed native FIT timestamp is exposed as
+`compressed_timestamp` instead.
+
+The parser does not apply profile enum formatting, scaling, invalid-sentinel
+filtering, or provider semantics to this opt-in representation. Its normal
+decoded output remains unchanged. Pass `true` to retain every message or a
+global-message-number array to keep memory use bounded. `raw_messages` and
+`raw_developer_fields` are independent opt-ins; enabling `raw_messages` does
+not add the flattened `raw_developer_fields` property. Set `rawMessagesOnly`
+when only this representation is needed; the parser still validates and walks
+the complete FIT data section but does not retain decoded activity collections.
+
 ## Output modes
 
 The mode controls where sessions, laps, records, and related activity

package/dist/binary.d.ts

@@ -20,11 +20,26 @@ export interface DecoderState {
     lastTimestamp?: number;
     monitoringTimestamp?: number;
 }
+export interface RawDeveloperFieldValue {
+    developerDataIndex: number;
+    fieldDefinitionNumber: number;
+    rawValue: number[];
+}
+export interface RawFieldValue {
+    fieldDefinitionNumber: number;
+    baseType: number;
+    rawValue: number[];
+}
 export declare function addEndian(littleEndian: boolean, bytes: number[]): number;
-export declare function readRecord(blob: Uint8Array, messageTypes: MessageTypeDefinition[], developerFields: any[], startIndex: number, options: FitParserOptions, startDate: number | undefined, pausedTime: number, dataView?: DataView, decoderState?: DecoderState): {
+export declare function readRecord(blob: Uint8Array, messageTypes: MessageTypeDefinition[], developerFields: any[], startIndex: number, options: FitParserOptions, startDate: number | undefined, pausedTime: number, dataView?: DataView, decoderState?: DecoderState, dataEnd?: number): {
     messageType: MessageName | 'definition' | '';
     nextIndex: number;
     message?: any;
+    globalMessageNumber?: number;
+    littleEndian?: boolean;
+    compressedTimestamp?: number;
+    rawFields?: RawFieldValue[];
+    rawDeveloperFields?: RawDeveloperFieldValue[];
 };
 export declare function getArrayBuffer(buffer: ArrayBuffer | Buffer): ArrayBuffer;
 export declare function calculateCRC(blob: Uint8Array, start: number, end: number): number;

package/dist/binary.js

@@ -8,6 +8,37 @@ const GarminTimeOffset = 631065600000;
 const InvalidFieldData = Symbol('invalid FIT field data');
 const formatTypeMetadata = new Map();
 const uint8CompatibleTypes = new Set(['enum', 'uint8', 'byte']);
+const fitBaseTypeWidths = new Map([
+    [0, 1],
+    [1, 1],
+    [2, 1],
+    [3, 2],
+    [4, 2],
+    [5, 4],
+    [6, 4],
+    [7, 1],
+    [8, 4],
+    [9, 8],
+    [10, 1],
+    [11, 2],
+    [12, 4],
+    [13, 1],
+    [14, 8],
+    [15, 8],
+    [16, 8],
+]);
+function retainsRawMessages(options) {
+    return options.includeRawMessages === true
+        || Array.isArray(options.includeRawMessages);
+}
+function isValidRawFieldDefinition(size, baseType) {
+    if (size <= 0 || (baseType & 0x60) !== 0) {
+        return false;
+    }
+    const typeId = baseType & 0x1F;
+    const width = fitBaseTypeWidths.get(typeId);
+    return width !== undefined && (typeId === 7 || size % width === 0);
+}
 function baseTypeSize(type) {
     switch (type) {
         case 'enum':
@@ -368,7 +399,7 @@ function resolveDeveloperFieldDefinition(developerFieldDef, littleEndian, develo
     if (!Number.isInteger(baseType) || type === undefined) {
         developerFieldDef.resolvedFieldDef = undefined;
         developerFieldDef.resolvedFrom = undefined;
-        if (options.force) {
+        if (options.force || retainsRawMessages(options)) {
             return undefined;
         }
         throw new Error(`Unsupported base type for developer data index ${developerFieldDef.developerDataIndex}, field ${developerFieldDef.fieldDefinitionNumber}`);
@@ -399,8 +430,11 @@ function resolveDeveloperFieldDefinition(developerFieldDef, littleEndian, develo
     developerFieldDef.resolvedFrom = description;
     return resolvedFieldDef;
 }
-export function readRecord(blob, messageTypes, developerFields, startIndex, options, startDate, pausedTime, dataView = new DataView(blob.buffer, blob.byteOffset, blob.byteLength), decoderState = {}) {
+export function readRecord(blob, messageTypes, developerFields, startIndex, options, startDate, pausedTime, dataView = new DataView(blob.buffer, blob.byteOffset, blob.byteLength), decoderState = {}, dataEnd = dataView.byteLength) {
     var _a, _b, _c;
+    if (startIndex < 0 || startIndex >= dataEnd) {
+        throw new Error('Invalid FIT record bounds');
+    }
     const recordHeader = blob[startIndex];
     let localMessageType = recordHeader & 15;
     const isCompressedTimestamp = (recordHeader & CompressedHeaderMask) === CompressedHeaderMask;
@@ -411,12 +445,29 @@ export function readRecord(blob, messageTypes, developerFields, startIndex, opti
     else if ((recordHeader & 64) === 64) {
         // is definition message
         // startIndex + 1 is reserved
+        if (retainsRawMessages(options) && startIndex + 6 > dataEnd) {
+            throw new Error('Invalid FIT definition bounds');
+        }
         const hasDeveloperData = (recordHeader & 32) === 32;
         const lEnd = blob[startIndex + 2] === 0;
         const numberOfFields = blob[startIndex + 5];
+        const nativeDefinitionsEnd = startIndex + 6 + numberOfFields * 3;
+        if (retainsRawMessages(options)
+            && ((recordHeader & 16) !== 0
+                || blob[startIndex + 1] !== 0
+                || blob[startIndex + 2] > 1
+                || nativeDefinitionsEnd > dataEnd
+                || (hasDeveloperData && nativeDefinitionsEnd + 1 > dataEnd))) {
+            throw new Error('Invalid FIT definition');
+        }
         const numberOfDeveloperDataFields = hasDeveloperData
             ? blob[startIndex + 5 + numberOfFields * 3 + 1]
             : 0;
+        const definitionEnd = nativeDefinitionsEnd
+            + (hasDeveloperData ? 1 + numberOfDeveloperDataFields * 3 : 0);
+        if (retainsRawMessages(options) && definitionEnd > dataEnd) {
+            throw new Error('Invalid FIT developer definition bounds');
+        }
         const mTypeDef = {
             littleEndian: lEnd,
             globalMessageNumber: addEndian(lEnd, [
@@ -429,17 +480,26 @@ export function readRecord(blob, messageTypes, developerFields, startIndex, opti
             rawData: [],
         };
         const message = getFitMessage(mTypeDef.globalMessageNumber);
+        const nativeFieldNumbers = new Set();
         for (let i = 0; i < numberOfFields; i++) {
             const fDefIndex = startIndex + 6 + i * 3;
             const baseType = blob[fDefIndex + 2];
+            const fieldNumber = blob[fDefIndex];
+            const fieldSize = blob[fDefIndex + 1];
+            if (retainsRawMessages(options)
+                && (nativeFieldNumbers.has(fieldNumber)
+                    || !isValidRawFieldDefinition(fieldSize, baseType))) {
+                throw new Error('Invalid FIT native field definition');
+            }
+            nativeFieldNumbers.add(fieldNumber);
             const wireType = FIT.types.fit_base_type[baseType];
             const { field, type, baseType: profileBaseType, array, scale, offset, units, } = message.getAttributes(blob[fDefIndex]);
             const profileCompatible = areProfileBaseTypesCompatible(profileBaseType, wireType);
             const fDef = {
                 type: profileCompatible ? type : wireType,
                 rawType: wireType,
-                fDefNo: blob[fDefIndex],
-                size: blob[fDefIndex + 1],
+                fDefNo: fieldNumber,
+                size: fieldSize,
                 array: profileCompatible
                     ? array === true || String(type).endsWith('_array')
                     : false,
@@ -451,12 +511,19 @@ export function readRecord(blob, messageTypes, developerFields, startIndex, opti
                 scale: profileCompatible ? scale : null,
                 offset: profileCompatible ? offset : 0,
                 units: profileCompatible ? units : '',
-                requiresBoundedDataView: requiresBoundedEndianDataView(wireType, blob[fDefIndex + 1]),
+                requiresBoundedDataView: requiresBoundedEndianDataView(wireType, fieldSize),
             };
             mTypeDef.fieldDefs.push(fDef);
         }
+        const developerFieldNumbers = new Set();
         for (let i = 0; i < numberOfDeveloperDataFields; i++) {
             const fDefIndex = startIndex + 6 + numberOfFields * 3 + 1 + i * 3;
+            const developerFieldKey = `${blob[fDefIndex + 2]}:${blob[fDefIndex]}`;
+            if (retainsRawMessages(options)
+                && (blob[fDefIndex + 1] === 0 || developerFieldNumbers.has(developerFieldKey))) {
+                throw new Error('Invalid FIT developer field definition');
+            }
+            developerFieldNumbers.add(developerFieldKey);
             (_a = mTypeDef.developerFieldDefs) === null || _a === void 0 ? void 0 : _a.push({
                 fieldDefinitionNumber: blob[fDefIndex],
                 size: blob[fDefIndex + 1],
@@ -472,29 +539,73 @@ export function readRecord(blob, messageTypes, developerFields, startIndex, opti
             nextIndex: hasDeveloperData ? nextIndexWithDeveloperData : nextIndex,
         };
     }
-    const messageType = messageTypes[localMessageType] || messageTypes[0];
+    if (!isCompressedTimestamp && (recordHeader & 0x30) !== 0) {
+        throw new Error('Invalid FIT data record header');
+    }
+    const messageType = messageTypes[localMessageType];
+    if (!messageType) {
+        throw new Error('FIT data record has no local definition');
+    }
+    if (isCompressedTimestamp && retainsRawMessages(options)) {
+        const timestampField = messageType.fieldDefs[0];
+        if (!timestampField
+            || timestampField.fDefNo !== 253
+            || timestampField.size !== 4
+            || (timestampField.baseTypeNo & 0x1F) !== 6) {
+            throw new Error('Invalid FIT compressed timestamp definition');
+        }
+    }
     let messageSize = 0;
     let readDataFromIndex = startIndex + 1;
     const fields = {};
     const message = getFitMessage(messageType.globalMessageNumber);
     const developerFieldDefs = (_b = messageType.developerFieldDefs) !== null && _b !== void 0 ? _b : [];
     const totalFieldCount = messageType.fieldDefs.length + developerFieldDefs.length;
+    const includeRawMessage = options.includeRawMessages === true
+        || (Array.isArray(options.includeRawMessages)
+            && options.includeRawMessages.includes(messageType.globalMessageNumber));
+    const includeRawDeveloperFields = options.includeRawDeveloperFields === true
+        || (Array.isArray(options.includeRawDeveloperFields)
+            && options.includeRawDeveloperFields.includes(messageType.globalMessageNumber));
+    const rawFields = includeRawMessage ? [] : undefined;
+    const rawDeveloperFields = includeRawDeveloperFields || includeRawMessage ? [] : undefined;
+    if (retainsRawMessages(options)) {
+        const nativeSize = messageType.fieldDefs.reduce((total, field, index) => (total + (isCompressedTimestamp && index === 0 && field.fDefNo === 253 ? 0 : field.size)), 0);
+        const developerSize = developerFieldDefs.reduce((total, field) => total + field.size, 0);
+        if (startIndex + 1 + nativeSize + developerSize > dataEnd) {
+            throw new Error('Invalid FIT data record bounds');
+        }
+    }
     const rawData = (_c = messageType.rawData) !== null && _c !== void 0 ? _c : (messageType.rawData = Array.from({ length: totalFieldCount }, () => InvalidFieldData));
     let validFieldCount = 0;
     for (let i = 0; i < messageType.fieldDefs.length; i++) {
         const fDef = messageType.fieldDefs[i];
+        if (isCompressedTimestamp && i === 0 && fDef.fDefNo === 253) {
+            rawData[i] = InvalidFieldData;
+            continue;
+        }
+        if (rawFields && readDataFromIndex + fDef.size <= dataEnd) {
+            rawFields.push({
+                fieldDefinitionNumber: fDef.fDefNo,
+                baseType: fDef.baseTypeNo,
+                rawValue: Array.from(blob.subarray(readDataFromIndex, readDataFromIndex + fDef.size)),
+            });
+        }
         const data = readData(blob, dataView, fDef, readDataFromIndex);
         if (data !== InvalidFieldData
             && !isInvalidValue(data, fDef.type)
             && !isInvalidBaseTypeValue(data, fDef.baseTypeNo)) {
             rawData[i] = data;
             validFieldCount++;
-            if (!isCompressedTimestamp && fDef.fDefNo === 253 && typeof data === 'number') {
-                decoderState.lastTimestamp = data;
+            if (!isCompressedTimestamp && fDef.fDefNo === 253) {
+                decoderState.lastTimestamp = typeof data === 'number' ? data : undefined;
             }
         }
         else {
             rawData[i] = InvalidFieldData;
+            if (!isCompressedTimestamp && fDef.fDefNo === 253) {
+                decoderState.lastTimestamp = undefined;
+            }
         }
         readDataFromIndex += fDef.size;
         messageSize += fDef.size;
@@ -502,6 +613,14 @@ export function readRecord(blob, messageTypes, developerFields, startIndex, opti
     for (let i = 0; i < developerFieldDefs.length; i++) {
         const developerFieldDef = developerFieldDefs[i];
         const rawDataIndex = messageType.fieldDefs.length + i;
+        if (rawDeveloperFields
+            && readDataFromIndex + developerFieldDef.size <= dataEnd) {
+            rawDeveloperFields.push({
+                developerDataIndex: developerFieldDef.developerDataIndex,
+                fieldDefinitionNumber: developerFieldDef.fieldDefinitionNumber,
+                rawValue: Array.from(blob.subarray(readDataFromIndex, readDataFromIndex + developerFieldDef.size)),
+            });
+        }
         const fDef = resolveDeveloperFieldDefinition(developerFieldDef, messageType.littleEndian, developerFields, options);
         if (fDef) {
             const data = readData(blob, dataView, fDef, readDataFromIndex);
@@ -563,6 +682,7 @@ export function readRecord(blob, messageTypes, developerFields, startIndex, opti
             fields[field] = formatFieldValue(data, fDef, options, fields);
         }
     }
+    let compressedTimestamp;
     if (isCompressedTimestamp) {
         const previousTimestamp = decoderState.lastTimestamp;
         if (previousTimestamp === undefined) {
@@ -574,8 +694,12 @@ export function readRecord(blob, messageTypes, developerFields, startIndex, opti
             const timeOffset = recordHeader & CompressedTimestampMask;
             const previousOffset = previousTimestamp & CompressedTimestampMask;
             const rollover = timeOffset < previousOffset ? 0x20 : 0;
-            const timestamp = (previousTimestamp & ~CompressedTimestampMask) + timeOffset + rollover;
+            const timestamp = previousTimestamp - previousOffset + timeOffset + rollover;
+            if (timestamp >= 0xFFFFFFFF) {
+                throw new Error('Compressed timestamp exceeds FIT uint32 range');
+            }
             decoderState.lastTimestamp = timestamp;
+            compressedTimestamp = timestamp;
             fields.timestamp = new Date(timestamp * 1000 + GarminTimeOffset);
             validFieldCount++;
         }
@@ -607,9 +731,14 @@ export function readRecord(blob, messageTypes, developerFields, startIndex, opti
         }
     }
     return {
+        globalMessageNumber: messageType.globalMessageNumber,
+        littleEndian: messageType.littleEndian,
+        compressedTimestamp,
         messageType: message.name,
         nextIndex: startIndex + messageSize + 1,
         message: fields,
+        rawFields,
+        rawDeveloperFields,
     };
 }
 export function getArrayBuffer(buffer) {

package/dist/cjs/binary.d.ts

@@ -20,11 +20,26 @@ export interface DecoderState {
     lastTimestamp?: number;
     monitoringTimestamp?: number;
 }
+export interface RawDeveloperFieldValue {
+    developerDataIndex: number;
+    fieldDefinitionNumber: number;
+    rawValue: number[];
+}
+export interface RawFieldValue {
+    fieldDefinitionNumber: number;
+    baseType: number;
+    rawValue: number[];
+}
 export declare function addEndian(littleEndian: boolean, bytes: number[]): number;
-export declare function readRecord(blob: Uint8Array, messageTypes: MessageTypeDefinition[], developerFields: any[], startIndex: number, options: FitParserOptions, startDate: number | undefined, pausedTime: number, dataView?: DataView, decoderState?: DecoderState): {
+export declare function readRecord(blob: Uint8Array, messageTypes: MessageTypeDefinition[], developerFields: any[], startIndex: number, options: FitParserOptions, startDate: number | undefined, pausedTime: number, dataView?: DataView, decoderState?: DecoderState, dataEnd?: number): {
     messageType: MessageName | 'definition' | '';
     nextIndex: number;
     message?: any;
+    globalMessageNumber?: number;
+    littleEndian?: boolean;
+    compressedTimestamp?: number;
+    rawFields?: RawFieldValue[];
+    rawDeveloperFields?: RawDeveloperFieldValue[];
 };
 export declare function getArrayBuffer(buffer: ArrayBuffer | Buffer): ArrayBuffer;
 export declare function calculateCRC(blob: Uint8Array, start: number, end: number): number;

package/dist/cjs/binary.js

@@ -14,6 +14,37 @@ const GarminTimeOffset = 631065600000;
 const InvalidFieldData = Symbol('invalid FIT field data');
 const formatTypeMetadata = new Map();
 const uint8CompatibleTypes = new Set(['enum', 'uint8', 'byte']);
+const fitBaseTypeWidths = new Map([
+    [0, 1],
+    [1, 1],
+    [2, 1],
+    [3, 2],
+    [4, 2],
+    [5, 4],
+    [6, 4],
+    [7, 1],
+    [8, 4],
+    [9, 8],
+    [10, 1],
+    [11, 2],
+    [12, 4],
+    [13, 1],
+    [14, 8],
+    [15, 8],
+    [16, 8],
+]);
+function retainsRawMessages(options) {
+    return options.includeRawMessages === true
+        || Array.isArray(options.includeRawMessages);
+}
+function isValidRawFieldDefinition(size, baseType) {
+    if (size <= 0 || (baseType & 0x60) !== 0) {
+        return false;
+    }
+    const typeId = baseType & 0x1F;
+    const width = fitBaseTypeWidths.get(typeId);
+    return width !== undefined && (typeId === 7 || size % width === 0);
+}
 function baseTypeSize(type) {
     switch (type) {
         case 'enum':
@@ -374,7 +405,7 @@ function resolveDeveloperFieldDefinition(developerFieldDef, littleEndian, develo
     if (!Number.isInteger(baseType) || type === undefined) {
         developerFieldDef.resolvedFieldDef = undefined;
         developerFieldDef.resolvedFrom = undefined;
-        if (options.force) {
+        if (options.force || retainsRawMessages(options)) {
             return undefined;
         }
         throw new Error(`Unsupported base type for developer data index ${developerFieldDef.developerDataIndex}, field ${developerFieldDef.fieldDefinitionNumber}`);
@@ -405,8 +436,11 @@ function resolveDeveloperFieldDefinition(developerFieldDef, littleEndian, develo
     developerFieldDef.resolvedFrom = description;
     return resolvedFieldDef;
 }
-function readRecord(blob, messageTypes, developerFields, startIndex, options, startDate, pausedTime, dataView = new DataView(blob.buffer, blob.byteOffset, blob.byteLength), decoderState = {}) {
+function readRecord(blob, messageTypes, developerFields, startIndex, options, startDate, pausedTime, dataView = new DataView(blob.buffer, blob.byteOffset, blob.byteLength), decoderState = {}, dataEnd = dataView.byteLength) {
     var _a, _b, _c;
+    if (startIndex < 0 || startIndex >= dataEnd) {
+        throw new Error('Invalid FIT record bounds');
+    }
     const recordHeader = blob[startIndex];
     let localMessageType = recordHeader & 15;
     const isCompressedTimestamp = (recordHeader & CompressedHeaderMask) === CompressedHeaderMask;
@@ -417,12 +451,29 @@ function readRecord(blob, messageTypes, developerFields, startIndex, options, st
     else if ((recordHeader & 64) === 64) {
         // is definition message
         // startIndex + 1 is reserved
+        if (retainsRawMessages(options) && startIndex + 6 > dataEnd) {
+            throw new Error('Invalid FIT definition bounds');
+        }
         const hasDeveloperData = (recordHeader & 32) === 32;
         const lEnd = blob[startIndex + 2] === 0;
         const numberOfFields = blob[startIndex + 5];
+        const nativeDefinitionsEnd = startIndex + 6 + numberOfFields * 3;
+        if (retainsRawMessages(options)
+            && ((recordHeader & 16) !== 0
+                || blob[startIndex + 1] !== 0
+                || blob[startIndex + 2] > 1
+                || nativeDefinitionsEnd > dataEnd
+                || (hasDeveloperData && nativeDefinitionsEnd + 1 > dataEnd))) {
+            throw new Error('Invalid FIT definition');
+        }
         const numberOfDeveloperDataFields = hasDeveloperData
             ? blob[startIndex + 5 + numberOfFields * 3 + 1]
             : 0;
+        const definitionEnd = nativeDefinitionsEnd
+            + (hasDeveloperData ? 1 + numberOfDeveloperDataFields * 3 : 0);
+        if (retainsRawMessages(options) && definitionEnd > dataEnd) {
+            throw new Error('Invalid FIT developer definition bounds');
+        }
         const mTypeDef = {
             littleEndian: lEnd,
             globalMessageNumber: addEndian(lEnd, [
@@ -435,17 +486,26 @@ function readRecord(blob, messageTypes, developerFields, startIndex, options, st
             rawData: [],
         };
         const message = (0, messages_js_1.getFitMessage)(mTypeDef.globalMessageNumber);
+        const nativeFieldNumbers = new Set();
         for (let i = 0; i < numberOfFields; i++) {
             const fDefIndex = startIndex + 6 + i * 3;
             const baseType = blob[fDefIndex + 2];
+            const fieldNumber = blob[fDefIndex];
+            const fieldSize = blob[fDefIndex + 1];
+            if (retainsRawMessages(options)
+                && (nativeFieldNumbers.has(fieldNumber)
+                    || !isValidRawFieldDefinition(fieldSize, baseType))) {
+                throw new Error('Invalid FIT native field definition');
+            }
+            nativeFieldNumbers.add(fieldNumber);
             const wireType = fit_js_1.FIT.types.fit_base_type[baseType];
             const { field, type, baseType: profileBaseType, array, scale, offset, units, } = message.getAttributes(blob[fDefIndex]);
             const profileCompatible = areProfileBaseTypesCompatible(profileBaseType, wireType);
             const fDef = {
                 type: profileCompatible ? type : wireType,
                 rawType: wireType,
-                fDefNo: blob[fDefIndex],
-                size: blob[fDefIndex + 1],
+                fDefNo: fieldNumber,
+                size: fieldSize,
                 array: profileCompatible
                     ? array === true || String(type).endsWith('_array')
                     : false,
@@ -457,12 +517,19 @@ function readRecord(blob, messageTypes, developerFields, startIndex, options, st
                 scale: profileCompatible ? scale : null,
                 offset: profileCompatible ? offset : 0,
                 units: profileCompatible ? units : '',
-                requiresBoundedDataView: requiresBoundedEndianDataView(wireType, blob[fDefIndex + 1]),
+                requiresBoundedDataView: requiresBoundedEndianDataView(wireType, fieldSize),
             };
             mTypeDef.fieldDefs.push(fDef);
         }
+        const developerFieldNumbers = new Set();
         for (let i = 0; i < numberOfDeveloperDataFields; i++) {
             const fDefIndex = startIndex + 6 + numberOfFields * 3 + 1 + i * 3;
+            const developerFieldKey = `${blob[fDefIndex + 2]}:${blob[fDefIndex]}`;
+            if (retainsRawMessages(options)
+                && (blob[fDefIndex + 1] === 0 || developerFieldNumbers.has(developerFieldKey))) {
+                throw new Error('Invalid FIT developer field definition');
+            }
+            developerFieldNumbers.add(developerFieldKey);
             (_a = mTypeDef.developerFieldDefs) === null || _a === void 0 ? void 0 : _a.push({
                 fieldDefinitionNumber: blob[fDefIndex],
                 size: blob[fDefIndex + 1],
@@ -478,29 +545,73 @@ function readRecord(blob, messageTypes, developerFields, startIndex, options, st
             nextIndex: hasDeveloperData ? nextIndexWithDeveloperData : nextIndex,
         };
     }
-    const messageType = messageTypes[localMessageType] || messageTypes[0];
+    if (!isCompressedTimestamp && (recordHeader & 0x30) !== 0) {
+        throw new Error('Invalid FIT data record header');
+    }
+    const messageType = messageTypes[localMessageType];
+    if (!messageType) {
+        throw new Error('FIT data record has no local definition');
+    }
+    if (isCompressedTimestamp && retainsRawMessages(options)) {
+        const timestampField = messageType.fieldDefs[0];
+        if (!timestampField
+            || timestampField.fDefNo !== 253
+            || timestampField.size !== 4
+            || (timestampField.baseTypeNo & 0x1F) !== 6) {
+            throw new Error('Invalid FIT compressed timestamp definition');
+        }
+    }
     let messageSize = 0;
     let readDataFromIndex = startIndex + 1;
     const fields = {};
     const message = (0, messages_js_1.getFitMessage)(messageType.globalMessageNumber);
     const developerFieldDefs = (_b = messageType.developerFieldDefs) !== null && _b !== void 0 ? _b : [];
     const totalFieldCount = messageType.fieldDefs.length + developerFieldDefs.length;
+    const includeRawMessage = options.includeRawMessages === true
+        || (Array.isArray(options.includeRawMessages)
+            && options.includeRawMessages.includes(messageType.globalMessageNumber));
+    const includeRawDeveloperFields = options.includeRawDeveloperFields === true
+        || (Array.isArray(options.includeRawDeveloperFields)
+            && options.includeRawDeveloperFields.includes(messageType.globalMessageNumber));
+    const rawFields = includeRawMessage ? [] : undefined;
+    const rawDeveloperFields = includeRawDeveloperFields || includeRawMessage ? [] : undefined;
+    if (retainsRawMessages(options)) {
+        const nativeSize = messageType.fieldDefs.reduce((total, field, index) => (total + (isCompressedTimestamp && index === 0 && field.fDefNo === 253 ? 0 : field.size)), 0);
+        const developerSize = developerFieldDefs.reduce((total, field) => total + field.size, 0);
+        if (startIndex + 1 + nativeSize + developerSize > dataEnd) {
+            throw new Error('Invalid FIT data record bounds');
+        }
+    }
     const rawData = (_c = messageType.rawData) !== null && _c !== void 0 ? _c : (messageType.rawData = Array.from({ length: totalFieldCount }, () => InvalidFieldData));
     let validFieldCount = 0;
     for (let i = 0; i < messageType.fieldDefs.length; i++) {
         const fDef = messageType.fieldDefs[i];
+        if (isCompressedTimestamp && i === 0 && fDef.fDefNo === 253) {
+            rawData[i] = InvalidFieldData;
+            continue;
+        }
+        if (rawFields && readDataFromIndex + fDef.size <= dataEnd) {
+            rawFields.push({
+                fieldDefinitionNumber: fDef.fDefNo,
+                baseType: fDef.baseTypeNo,
+                rawValue: Array.from(blob.subarray(readDataFromIndex, readDataFromIndex + fDef.size)),
+            });
+        }
         const data = readData(blob, dataView, fDef, readDataFromIndex);
         if (data !== InvalidFieldData
             && !isInvalidValue(data, fDef.type)
             && !isInvalidBaseTypeValue(data, fDef.baseTypeNo)) {
             rawData[i] = data;
             validFieldCount++;
-            if (!isCompressedTimestamp && fDef.fDefNo === 253 && typeof data === 'number') {
-                decoderState.lastTimestamp = data;
+            if (!isCompressedTimestamp && fDef.fDefNo === 253) {
+                decoderState.lastTimestamp = typeof data === 'number' ? data : undefined;
             }
         }
         else {
             rawData[i] = InvalidFieldData;
+            if (!isCompressedTimestamp && fDef.fDefNo === 253) {
+                decoderState.lastTimestamp = undefined;
+            }
         }
         readDataFromIndex += fDef.size;
         messageSize += fDef.size;
@@ -508,6 +619,14 @@ function readRecord(blob, messageTypes, developerFields, startIndex, options, st
     for (let i = 0; i < developerFieldDefs.length; i++) {
         const developerFieldDef = developerFieldDefs[i];
         const rawDataIndex = messageType.fieldDefs.length + i;
+        if (rawDeveloperFields
+            && readDataFromIndex + developerFieldDef.size <= dataEnd) {
+            rawDeveloperFields.push({
+                developerDataIndex: developerFieldDef.developerDataIndex,
+                fieldDefinitionNumber: developerFieldDef.fieldDefinitionNumber,
+                rawValue: Array.from(blob.subarray(readDataFromIndex, readDataFromIndex + developerFieldDef.size)),
+            });
+        }
         const fDef = resolveDeveloperFieldDefinition(developerFieldDef, messageType.littleEndian, developerFields, options);
         if (fDef) {
             const data = readData(blob, dataView, fDef, readDataFromIndex);
@@ -569,6 +688,7 @@ function readRecord(blob, messageTypes, developerFields, startIndex, options, st
             fields[field] = formatFieldValue(data, fDef, options, fields);
         }
     }
+    let compressedTimestamp;
     if (isCompressedTimestamp) {
         const previousTimestamp = decoderState.lastTimestamp;
         if (previousTimestamp === undefined) {
@@ -580,8 +700,12 @@ function readRecord(blob, messageTypes, developerFields, startIndex, options, st
             const timeOffset = recordHeader & CompressedTimestampMask;
             const previousOffset = previousTimestamp & CompressedTimestampMask;
             const rollover = timeOffset < previousOffset ? 0x20 : 0;
-            const timestamp = (previousTimestamp & ~CompressedTimestampMask) + timeOffset + rollover;
+            const timestamp = previousTimestamp - previousOffset + timeOffset + rollover;
+            if (timestamp >= 0xFFFFFFFF) {
+                throw new Error('Compressed timestamp exceeds FIT uint32 range');
+            }
             decoderState.lastTimestamp = timestamp;
+            compressedTimestamp = timestamp;
             fields.timestamp = new Date(timestamp * 1000 + GarminTimeOffset);
             validFieldCount++;
         }
@@ -613,9 +737,14 @@ function readRecord(blob, messageTypes, developerFields, startIndex, options, st
         }
     }
     return {
+        globalMessageNumber: messageType.globalMessageNumber,
+        littleEndian: messageType.littleEndian,
+        compressedTimestamp,
         messageType: message.name,
         nextIndex: startIndex + messageSize + 1,
         message: fields,
+        rawFields,
+        rawDeveloperFields,
     };
 }
 function getArrayBuffer(buffer) {

package/dist/cjs/fit-parser.d.ts

@@ -2,6 +2,7 @@ import type { Buffer } from 'buffer';
 import type { ParsedFit } from './fit_types.js';
 export { FitBaseType, FitEncoder } from './fit-encoder.js';
 export type { FitEncoderField, FitEncoderOptions } from './fit-encoder.js';
+export type { ParsedFit, ParsedRawDeveloperField, ParsedRawFitField, ParsedRawFitMessage, ParsedRawFitMessageDeveloperField, } from './fit_types.js';
 export interface FitParserOptions {
     force?: boolean;
     speedUnit?: string;
@@ -10,6 +11,12 @@ export interface FitParserOptions {
     elapsedRecordField?: boolean;
     pressureUnit?: string;
     mode?: 'list' | 'cascade' | 'both';
+    /** Retains exact developer-field bytes for all or selected global message numbers. */
+    includeRawDeveloperFields?: boolean | readonly number[];
+    /** Retains exact native and developer fields for all or selected global message numbers. */
+    includeRawMessages?: boolean | readonly number[];
+    /** Returns only parser metadata and retained raw messages instead of decoded activity collections. */
+    rawMessagesOnly?: boolean;
 }
 type FitParserCallback = (error: string | undefined, data: ParsedFit | undefined) => void;
 export default class FitParser {

package/dist/cjs/fit-parser.js

@@ -8,6 +8,7 @@ Object.defineProperty(exports, "FitBaseType", { enumerable: true, get: function
 Object.defineProperty(exports, "FitEncoder", { enumerable: true, get: function () { return fit_encoder_js_1.FitEncoder; } });
 class FitParser {
     constructor(options = {}) {
+        var _a, _b, _c;
         this.options = {
             force: options.force != null ? options.force : true,
             speedUnit: options.speedUnit || 'm/s',
@@ -16,6 +17,9 @@ class FitParser {
             elapsedRecordField: options.elapsedRecordField || false,
             pressureUnit: options.pressureUnit || 'bar',
             mode: options.mode || 'list',
+            includeRawDeveloperFields: (_a = options.includeRawDeveloperFields) !== null && _a !== void 0 ? _a : false,
+            includeRawMessages: (_b = options.includeRawMessages) !== null && _b !== void 0 ? _b : false,
+            rawMessagesOnly: (_c = options.rawMessagesOnly) !== null && _c !== void 0 ? _c : false,
         };
     }
     parseAsync(content) {
@@ -31,7 +35,7 @@ class FitParser {
         });
     }
     parse(content, callback) {
-        var _a, _b;
+        var _a, _b, _c;
         const blob = content instanceof ArrayBuffer
             ? new Uint8Array(content)
             : new Uint8Array(content.buffer, content.byteOffset, content.byteLength);
@@ -118,6 +122,15 @@ class FitParser {
         const time_in_zone = [];
         const activity_metrics = [];
         const user_metrics = [];
+        const rawDeveloperFields = this.options.includeRawDeveloperFields === true
+            || Array.isArray(this.options.includeRawDeveloperFields)
+            ? []
+            : undefined;
+        const rawMessages = this.options.includeRawMessages === true
+            || Array.isArray(this.options.includeRawMessages)
+            ? []
+            : undefined;
+        const messageCountsByGlobalNumber = new Map();
         let loopIndex = headerLength;
         const messageTypes = [];
         const developerFields = [];
@@ -128,12 +141,41 @@ class FitParser {
         let lastStopTimestamp;
         let pausedTime = 0;
         while (loopIndex < crcStart) {
-            const { nextIndex, messageType, message } = (0, binary_js_1.readRecord)(blob, messageTypes, developerFields, loopIndex, this.options, startDate, pausedTime, dataView, decoderState);
+            const { globalMessageNumber, littleEndian, message, messageType, nextIndex, compressedTimestamp, rawFields: recordRawFields, rawDeveloperFields: recordRawDeveloperFields, } = (0, binary_js_1.readRecord)(blob, messageTypes, developerFields, loopIndex, this.options, startDate, pausedTime, dataView, decoderState, crcStart);
             loopIndex = nextIndex;
+            if (globalMessageNumber !== undefined) {
+                const messageIndex = (_a = messageCountsByGlobalNumber.get(globalMessageNumber)) !== null && _a !== void 0 ? _a : 0;
+                messageCountsByGlobalNumber.set(globalMessageNumber, messageIndex + 1);
+                if (recordRawFields && littleEndian !== undefined) {
+                    rawMessages === null || rawMessages === void 0 ? void 0 : rawMessages.push(Object.assign(Object.assign({ global_message_number: globalMessageNumber, message_index: messageIndex, little_endian: littleEndian }, (compressedTimestamp === undefined
+                        ? {}
+                        : { compressed_timestamp: compressedTimestamp })), { fields: recordRawFields.map(field => ({
+                            field_definition_number: field.fieldDefinitionNumber,
+                            base_type: field.baseType,
+                            raw_value: field.rawValue,
+                        })), developer_fields: (recordRawDeveloperFields !== null && recordRawDeveloperFields !== void 0 ? recordRawDeveloperFields : []).map(field => ({
+                            developer_data_index: field.developerDataIndex,
+                            field_definition_number: field.fieldDefinitionNumber,
+                            raw_value: field.rawValue,
+                        })) }));
+                }
+                recordRawDeveloperFields === null || recordRawDeveloperFields === void 0 ? void 0 : recordRawDeveloperFields.forEach((field) => {
+                    rawDeveloperFields === null || rawDeveloperFields === void 0 ? void 0 : rawDeveloperFields.push({
+                        global_message_number: globalMessageNumber,
+                        message_index: messageIndex,
+                        developer_data_index: field.developerDataIndex,
+                        field_definition_number: field.fieldDefinitionNumber,
+                        raw_value: field.rawValue,
+                    });
+                });
+            }
+            if (this.options.rawMessagesOnly) {
+                continue;
+            }
             if (messageType !== ''
                 && messageType !== 'definition'
                 && message !== undefined) {
-                ((_a = messages[messageType]) !== null && _a !== void 0 ? _a : (messages[messageType] = [])).push(message);
+                ((_b = messages[messageType]) !== null && _b !== void 0 ? _b : (messages[messageType] = [])).push(message);
             }
             switch (messageType) {
                 case 'lap':
@@ -249,6 +291,16 @@ class FitParser {
                     break;
             }
         }
+        if (this.options.rawMessagesOnly) {
+            if (rawDeveloperFields) {
+                fitObj.raw_developer_fields = rawDeveloperFields;
+            }
+            if (rawMessages) {
+                fitObj.raw_messages = rawMessages;
+            }
+            callback(undefined, fitObj);
+            return;
+        }
         fitObj.hr_zone = hr_zone;
         fitObj.power_zone = power_zone;
         fitObj.dive_gases = dive_gases;
@@ -268,11 +320,17 @@ class FitParser {
         fitObj.activity_metrics = activity_metrics;
         fitObj.user_metrics = user_metrics;
         fitObj.messages = messages;
+        if (rawDeveloperFields) {
+            fitObj.raw_developer_fields = rawDeveloperFields;
+        }
+        if (rawMessages) {
+            fitObj.raw_messages = rawMessages;
+        }
         if (isCascadeNeeded) {
             laps = (0, helper_js_1.mapDataIntoLap)(laps, 'records', records);
             laps = (0, helper_js_1.mapDataIntoLap)(laps, 'lengths', lengths);
             sessions = (0, helper_js_1.mapDataIntoSession)(sessions, laps);
-            fitObj.activity = Object.assign(Object.assign({}, ((_b = fitObj.activity) !== null && _b !== void 0 ? _b : {})), { // ugly but we assume the activity was parsed correctly with all other members correctly
+            fitObj.activity = Object.assign(Object.assign({}, ((_c = fitObj.activity) !== null && _c !== void 0 ? _c : {})), { // ugly but we assume the activity was parsed correctly with all other members correctly
                 sessions,
                 events,
                 hrv,

package/dist/cjs/fit_types.d.ts

@@ -9,6 +9,31 @@ export type Unit<T extends string> = Record<T, {
     multiplier: number;
     offset: number;
 }>;
+export interface ParsedRawDeveloperField {
+    global_message_number: number;
+    message_index: number;
+    developer_data_index: number;
+    field_definition_number: number;
+    raw_value: number[];
+}
+export interface ParsedRawFitField {
+    field_definition_number: number;
+    base_type: number;
+    raw_value: number[];
+}
+export interface ParsedRawFitMessageDeveloperField {
+    developer_data_index: number;
+    field_definition_number: number;
+    raw_value: number[];
+}
+export interface ParsedRawFitMessage {
+    global_message_number: number;
+    message_index: number;
+    little_endian: boolean;
+    compressed_timestamp?: number;
+    fields: ParsedRawFitField[];
+    developer_fields: ParsedRawFitMessageDeveloperField[];
+}
 export type Activity = 'manual' | 'auto_multi_sport' | number;
 export type ActivityClass = 'level_max' | 'level' | 'athlete' | number;
 export type ActivityLevel = 'low' | 'medium' | 'high' | number;
@@ -2070,6 +2095,8 @@ export interface ParsedFit {
     protocolVersion?: number;
     profileVersion?: number;
     messages?: ParsedMessages;
+    raw_developer_fields?: ParsedRawDeveloperField[];
+    raw_messages?: ParsedRawFitMessage[];
     file_creator: ParsedFileCreator;
     device_settings: ParsedDeviceSettings;
     dive_summary?: ParsedDiveSummary;

package/dist/cjs/type_generator.js

@@ -175,6 +175,31 @@ function generateUtilities() {
         ]),
     ]));
     nodes.push(unitType);
+    nodes.push(typescript_1.default.factory.createInterfaceDeclaration([typescript_1.default.factory.createModifier(typescript_1.default.SyntaxKind.ExportKeyword)], 'ParsedRawDeveloperField', undefined, undefined, [
+        generateProperty('global_message_number', typescript_1.default.factory.createKeywordTypeNode(typescript_1.default.SyntaxKind.NumberKeyword), false),
+        generateProperty('message_index', typescript_1.default.factory.createKeywordTypeNode(typescript_1.default.SyntaxKind.NumberKeyword), false),
+        generateProperty('developer_data_index', typescript_1.default.factory.createKeywordTypeNode(typescript_1.default.SyntaxKind.NumberKeyword), false),
+        generateProperty('field_definition_number', typescript_1.default.factory.createKeywordTypeNode(typescript_1.default.SyntaxKind.NumberKeyword), false),
+        generateArrayProperty('raw_value', typescript_1.default.factory.createKeywordTypeNode(typescript_1.default.SyntaxKind.NumberKeyword), false),
+    ]));
+    nodes.push(typescript_1.default.factory.createInterfaceDeclaration([typescript_1.default.factory.createModifier(typescript_1.default.SyntaxKind.ExportKeyword)], 'ParsedRawFitField', undefined, undefined, [
+        generateProperty('field_definition_number', typescript_1.default.factory.createKeywordTypeNode(typescript_1.default.SyntaxKind.NumberKeyword), false),
+        generateProperty('base_type', typescript_1.default.factory.createKeywordTypeNode(typescript_1.default.SyntaxKind.NumberKeyword), false),
+        generateArrayProperty('raw_value', typescript_1.default.factory.createKeywordTypeNode(typescript_1.default.SyntaxKind.NumberKeyword), false),
+    ]));
+    nodes.push(typescript_1.default.factory.createInterfaceDeclaration([typescript_1.default.factory.createModifier(typescript_1.default.SyntaxKind.ExportKeyword)], 'ParsedRawFitMessageDeveloperField', undefined, undefined, [
+        generateProperty('developer_data_index', typescript_1.default.factory.createKeywordTypeNode(typescript_1.default.SyntaxKind.NumberKeyword), false),
+        generateProperty('field_definition_number', typescript_1.default.factory.createKeywordTypeNode(typescript_1.default.SyntaxKind.NumberKeyword), false),
+        generateArrayProperty('raw_value', typescript_1.default.factory.createKeywordTypeNode(typescript_1.default.SyntaxKind.NumberKeyword), false),
+    ]));
+    nodes.push(typescript_1.default.factory.createInterfaceDeclaration([typescript_1.default.factory.createModifier(typescript_1.default.SyntaxKind.ExportKeyword)], 'ParsedRawFitMessage', undefined, undefined, [
+        generateProperty('global_message_number', typescript_1.default.factory.createKeywordTypeNode(typescript_1.default.SyntaxKind.NumberKeyword), false),
+        generateProperty('message_index', typescript_1.default.factory.createKeywordTypeNode(typescript_1.default.SyntaxKind.NumberKeyword), false),
+        generateProperty('little_endian', typescript_1.default.factory.createKeywordTypeNode(typescript_1.default.SyntaxKind.BooleanKeyword), false),
+        generateProperty('compressed_timestamp', typescript_1.default.factory.createKeywordTypeNode(typescript_1.default.SyntaxKind.NumberKeyword)),
+        generateArrayProperty('fields', typescript_1.default.factory.createTypeReferenceNode('ParsedRawFitField'), false),
+        generateArrayProperty('developer_fields', typescript_1.default.factory.createTypeReferenceNode('ParsedRawFitMessageDeveloperField'), false),
+    ]));
     return nodes;
 }
 function generateAdditionalFields(msg) {
@@ -258,6 +283,8 @@ function generateFitType() {
         generateProperty('protocolVersion', typescript_1.default.factory.createKeywordTypeNode(typescript_1.default.SyntaxKind.NumberKeyword)),
         generateProperty('profileVersion', typescript_1.default.factory.createKeywordTypeNode(typescript_1.default.SyntaxKind.NumberKeyword)),
         generateProperty('messages', typescript_1.default.factory.createTypeReferenceNode('ParsedMessages')),
+        generateArrayProperty('raw_developer_fields', typescript_1.default.factory.createTypeReferenceNode('ParsedRawDeveloperField')),
+        generateArrayProperty('raw_messages', typescript_1.default.factory.createTypeReferenceNode('ParsedRawFitMessage')),
         ...Object.keys(referenceProperties).map(prop => generateProperty(prop, typescript_1.default.factory.createTypeReferenceNode(snakeToCamel(referenceProperties[prop].replace('?', ''))), referenceProperties[prop].startsWith('?'))),
         ...Object.keys(collectionProperties).map(prop => generateArrayProperty(prop, collectionProperties[prop] === 'unknown'
             ? typescript_1.default.factory.createKeywordTypeNode(typescript_1.default.SyntaxKind.UnknownKeyword)

package/dist/fit-parser.d.ts

@@ -2,6 +2,7 @@ import type { Buffer } from 'buffer';
 import type { ParsedFit } from './fit_types.js';
 export { FitBaseType, FitEncoder } from './fit-encoder.js';
 export type { FitEncoderField, FitEncoderOptions } from './fit-encoder.js';
+export type { ParsedFit, ParsedRawDeveloperField, ParsedRawFitField, ParsedRawFitMessage, ParsedRawFitMessageDeveloperField, } from './fit_types.js';
 export interface FitParserOptions {
     force?: boolean;
     speedUnit?: string;
@@ -10,6 +11,12 @@ export interface FitParserOptions {
     elapsedRecordField?: boolean;
     pressureUnit?: string;
     mode?: 'list' | 'cascade' | 'both';
+    /** Retains exact developer-field bytes for all or selected global message numbers. */
+    includeRawDeveloperFields?: boolean | readonly number[];
+    /** Retains exact native and developer fields for all or selected global message numbers. */
+    includeRawMessages?: boolean | readonly number[];
+    /** Returns only parser metadata and retained raw messages instead of decoded activity collections. */
+    rawMessagesOnly?: boolean;
 }
 type FitParserCallback = (error: string | undefined, data: ParsedFit | undefined) => void;
 export default class FitParser {

package/dist/fit-parser.js

@@ -3,6 +3,7 @@ import { mapDataIntoLap, mapDataIntoSession } from './helper.js';
 export { FitBaseType, FitEncoder } from './fit-encoder.js';
 export default class FitParser {
     constructor(options = {}) {
+        var _a, _b, _c;
         this.options = {
             force: options.force != null ? options.force : true,
             speedUnit: options.speedUnit || 'm/s',
@@ -11,6 +12,9 @@ export default class FitParser {
             elapsedRecordField: options.elapsedRecordField || false,
             pressureUnit: options.pressureUnit || 'bar',
             mode: options.mode || 'list',
+            includeRawDeveloperFields: (_a = options.includeRawDeveloperFields) !== null && _a !== void 0 ? _a : false,
+            includeRawMessages: (_b = options.includeRawMessages) !== null && _b !== void 0 ? _b : false,
+            rawMessagesOnly: (_c = options.rawMessagesOnly) !== null && _c !== void 0 ? _c : false,
         };
     }
     parseAsync(content) {
@@ -26,7 +30,7 @@ export default class FitParser {
         });
     }
     parse(content, callback) {
-        var _a, _b;
+        var _a, _b, _c;
         const blob = content instanceof ArrayBuffer
             ? new Uint8Array(content)
             : new Uint8Array(content.buffer, content.byteOffset, content.byteLength);
@@ -113,6 +117,15 @@ export default class FitParser {
         const time_in_zone = [];
         const activity_metrics = [];
         const user_metrics = [];
+        const rawDeveloperFields = this.options.includeRawDeveloperFields === true
+            || Array.isArray(this.options.includeRawDeveloperFields)
+            ? []
+            : undefined;
+        const rawMessages = this.options.includeRawMessages === true
+            || Array.isArray(this.options.includeRawMessages)
+            ? []
+            : undefined;
+        const messageCountsByGlobalNumber = new Map();
         let loopIndex = headerLength;
         const messageTypes = [];
         const developerFields = [];
@@ -123,12 +136,41 @@ export default class FitParser {
         let lastStopTimestamp;
         let pausedTime = 0;
         while (loopIndex < crcStart) {
-            const { nextIndex, messageType, message } = readRecord(blob, messageTypes, developerFields, loopIndex, this.options, startDate, pausedTime, dataView, decoderState);
+            const { globalMessageNumber, littleEndian, message, messageType, nextIndex, compressedTimestamp, rawFields: recordRawFields, rawDeveloperFields: recordRawDeveloperFields, } = readRecord(blob, messageTypes, developerFields, loopIndex, this.options, startDate, pausedTime, dataView, decoderState, crcStart);
             loopIndex = nextIndex;
+            if (globalMessageNumber !== undefined) {
+                const messageIndex = (_a = messageCountsByGlobalNumber.get(globalMessageNumber)) !== null && _a !== void 0 ? _a : 0;
+                messageCountsByGlobalNumber.set(globalMessageNumber, messageIndex + 1);
+                if (recordRawFields && littleEndian !== undefined) {
+                    rawMessages === null || rawMessages === void 0 ? void 0 : rawMessages.push(Object.assign(Object.assign({ global_message_number: globalMessageNumber, message_index: messageIndex, little_endian: littleEndian }, (compressedTimestamp === undefined
+                        ? {}
+                        : { compressed_timestamp: compressedTimestamp })), { fields: recordRawFields.map(field => ({
+                            field_definition_number: field.fieldDefinitionNumber,
+                            base_type: field.baseType,
+                            raw_value: field.rawValue,
+                        })), developer_fields: (recordRawDeveloperFields !== null && recordRawDeveloperFields !== void 0 ? recordRawDeveloperFields : []).map(field => ({
+                            developer_data_index: field.developerDataIndex,
+                            field_definition_number: field.fieldDefinitionNumber,
+                            raw_value: field.rawValue,
+                        })) }));
+                }
+                recordRawDeveloperFields === null || recordRawDeveloperFields === void 0 ? void 0 : recordRawDeveloperFields.forEach((field) => {
+                    rawDeveloperFields === null || rawDeveloperFields === void 0 ? void 0 : rawDeveloperFields.push({
+                        global_message_number: globalMessageNumber,
+                        message_index: messageIndex,
+                        developer_data_index: field.developerDataIndex,
+                        field_definition_number: field.fieldDefinitionNumber,
+                        raw_value: field.rawValue,
+                    });
+                });
+            }
+            if (this.options.rawMessagesOnly) {
+                continue;
+            }
             if (messageType !== ''
                 && messageType !== 'definition'
                 && message !== undefined) {
-                ((_a = messages[messageType]) !== null && _a !== void 0 ? _a : (messages[messageType] = [])).push(message);
+                ((_b = messages[messageType]) !== null && _b !== void 0 ? _b : (messages[messageType] = [])).push(message);
             }
             switch (messageType) {
                 case 'lap':
@@ -244,6 +286,16 @@ export default class FitParser {
                     break;
             }
         }
+        if (this.options.rawMessagesOnly) {
+            if (rawDeveloperFields) {
+                fitObj.raw_developer_fields = rawDeveloperFields;
+            }
+            if (rawMessages) {
+                fitObj.raw_messages = rawMessages;
+            }
+            callback(undefined, fitObj);
+            return;
+        }
         fitObj.hr_zone = hr_zone;
         fitObj.power_zone = power_zone;
         fitObj.dive_gases = dive_gases;
@@ -263,11 +315,17 @@ export default class FitParser {
         fitObj.activity_metrics = activity_metrics;
         fitObj.user_metrics = user_metrics;
         fitObj.messages = messages;
+        if (rawDeveloperFields) {
+            fitObj.raw_developer_fields = rawDeveloperFields;
+        }
+        if (rawMessages) {
+            fitObj.raw_messages = rawMessages;
+        }
         if (isCascadeNeeded) {
             laps = mapDataIntoLap(laps, 'records', records);
             laps = mapDataIntoLap(laps, 'lengths', lengths);
             sessions = mapDataIntoSession(sessions, laps);
-            fitObj.activity = Object.assign(Object.assign({}, ((_b = fitObj.activity) !== null && _b !== void 0 ? _b : {})), { // ugly but we assume the activity was parsed correctly with all other members correctly
+            fitObj.activity = Object.assign(Object.assign({}, ((_c = fitObj.activity) !== null && _c !== void 0 ? _c : {})), { // ugly but we assume the activity was parsed correctly with all other members correctly
                 sessions,
                 events,
                 hrv,

package/dist/fit_types.d.ts

@@ -9,6 +9,31 @@ export type Unit<T extends string> = Record<T, {
     multiplier: number;
     offset: number;
 }>;
+export interface ParsedRawDeveloperField {
+    global_message_number: number;
+    message_index: number;
+    developer_data_index: number;
+    field_definition_number: number;
+    raw_value: number[];
+}
+export interface ParsedRawFitField {
+    field_definition_number: number;
+    base_type: number;
+    raw_value: number[];
+}
+export interface ParsedRawFitMessageDeveloperField {
+    developer_data_index: number;
+    field_definition_number: number;
+    raw_value: number[];
+}
+export interface ParsedRawFitMessage {
+    global_message_number: number;
+    message_index: number;
+    little_endian: boolean;
+    compressed_timestamp?: number;
+    fields: ParsedRawFitField[];
+    developer_fields: ParsedRawFitMessageDeveloperField[];
+}
 export type Activity = 'manual' | 'auto_multi_sport' | number;
 export type ActivityClass = 'level_max' | 'level' | 'athlete' | number;
 export type ActivityLevel = 'low' | 'medium' | 'high' | number;
@@ -2070,6 +2095,8 @@ export interface ParsedFit {
     protocolVersion?: number;
     profileVersion?: number;
     messages?: ParsedMessages;
+    raw_developer_fields?: ParsedRawDeveloperField[];
+    raw_messages?: ParsedRawFitMessage[];
     file_creator: ParsedFileCreator;
     device_settings: ParsedDeviceSettings;
     dive_summary?: ParsedDiveSummary;

package/dist/type_generator.js

@@ -154,6 +154,31 @@ export function generateUtilities() {
         ]),
     ]));
     nodes.push(unitType);
+    nodes.push(ts.factory.createInterfaceDeclaration([ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)], 'ParsedRawDeveloperField', undefined, undefined, [
+        generateProperty('global_message_number', ts.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword), false),
+        generateProperty('message_index', ts.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword), false),
+        generateProperty('developer_data_index', ts.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword), false),
+        generateProperty('field_definition_number', ts.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword), false),
+        generateArrayProperty('raw_value', ts.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword), false),
+    ]));
+    nodes.push(ts.factory.createInterfaceDeclaration([ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)], 'ParsedRawFitField', undefined, undefined, [
+        generateProperty('field_definition_number', ts.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword), false),
+        generateProperty('base_type', ts.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword), false),
+        generateArrayProperty('raw_value', ts.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword), false),
+    ]));
+    nodes.push(ts.factory.createInterfaceDeclaration([ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)], 'ParsedRawFitMessageDeveloperField', undefined, undefined, [
+        generateProperty('developer_data_index', ts.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword), false),
+        generateProperty('field_definition_number', ts.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword), false),
+        generateArrayProperty('raw_value', ts.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword), false),
+    ]));
+    nodes.push(ts.factory.createInterfaceDeclaration([ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)], 'ParsedRawFitMessage', undefined, undefined, [
+        generateProperty('global_message_number', ts.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword), false),
+        generateProperty('message_index', ts.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword), false),
+        generateProperty('little_endian', ts.factory.createKeywordTypeNode(ts.SyntaxKind.BooleanKeyword), false),
+        generateProperty('compressed_timestamp', ts.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword)),
+        generateArrayProperty('fields', ts.factory.createTypeReferenceNode('ParsedRawFitField'), false),
+        generateArrayProperty('developer_fields', ts.factory.createTypeReferenceNode('ParsedRawFitMessageDeveloperField'), false),
+    ]));
     return nodes;
 }
 function generateAdditionalFields(msg) {
@@ -237,6 +262,8 @@ export function generateFitType() {
         generateProperty('protocolVersion', ts.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword)),
         generateProperty('profileVersion', ts.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword)),
         generateProperty('messages', ts.factory.createTypeReferenceNode('ParsedMessages')),
+        generateArrayProperty('raw_developer_fields', ts.factory.createTypeReferenceNode('ParsedRawDeveloperField')),
+        generateArrayProperty('raw_messages', ts.factory.createTypeReferenceNode('ParsedRawFitMessage')),
         ...Object.keys(referenceProperties).map(prop => generateProperty(prop, ts.factory.createTypeReferenceNode(snakeToCamel(referenceProperties[prop].replace('?', ''))), referenceProperties[prop].startsWith('?'))),
         ...Object.keys(collectionProperties).map(prop => generateArrayProperty(prop, collectionProperties[prop] === 'unknown'
             ? ts.factory.createKeywordTypeNode(ts.SyntaxKind.UnknownKeyword)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fit-file-parser",
   "type": "module",
-  "version": "5.0.2",
+  "version": "5.2.0",
   "private": false,
   "description": "Parse your .FIT files easily, directly from JS (Garmin, Polar, Suunto)",
   "author": {