fit-file-parser 6.1.2 → 6.2.1

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Change Log
 
+## 6.2.1 - 2026-10-10
+
+### Added
+
+- Add the opt-in `strict` parser option to require complete files and records,
+  valid definitions, and no trailing bytes in every parsing API. Checksum
+  validation remains controlled by `force`.
+
+### Fixed
+
+- Apply the same recovery policy to `parseFilesAsync()`, `parseAsync()`, and
+  callback parsing. The all-file API now accepts missing CRC bytes with
+  `force: true` when `strict` is disabled, and ignores a non-FIT suffix.
+- Keep existing decoder behavior, recovery, and output when `strict` is not
+  requested, including handling of malformed records and definitions.
+- Apply additional definition and record bounds checks only in strict mode.
+
+### Compatibility
+
+- `force` still defaults to `true`; `strict` defaults to `false`.
+- `strict: true` requires exactly one file for `parseAsync()` and callback
+  parsing, or complete concatenated files for `parseFilesAsync()`.
+- Temperature mappings and unit conversions are unchanged.
+
+## 6.2.0 - 2026-10-10
+
+### Added
+
+- Add `parseFilesAsync()` to return every complete FIT file in concatenated
+  input as a separate result, with independent decoder state and file order.
+- Decode documented session and lap swimming summaries, segment and gear-shift
+  counts, lap bounds, metabolic calories, and grade-adjusted speed.
+- Retain every battery sample in `batteries` and `messages.battery`, including
+  timestamp and capacity percentage when present.
+- Add `--all-files` to the external corpus checker to validate appended files.
+
+### Fixed
+
+- Preserve exact bytes for developer fields without usable names in opt-in
+  `unmapped_messages`, including fields whose descriptions have been cached.
+- Recover unsigned-byte record temperatures from 0 through 126 with normal
+  unit conversion, while retaining their original bytes in opt-in output.
+- Reject records and definitions extending beyond the declared data section
+  when using the complete-file `parseFilesAsync()` API.
+
+### Compatibility
+
+- Existing `parseAsync()` and callback APIs retain their single-file output
+  and recovery behavior. Newly supported fields and battery collections are
+  additive.
+- `parseFilesAsync()` returns a one-element array for ordinary FIT input and
+  rejects incomplete files or trailing non-FIT data, even with `force: true`.
+  CRC validation follows the caller's `force` option for every file.
+- Unsigned temperature bytes from 127 through 255 and other undocumented or
+  incompatible fields remain undecoded and available through opt-in retention.
+
 ## 6.1.2 - 2026-09-22
 
 ### Changed

package/PROFILE.md

@@ -31,6 +31,23 @@ complete raw representation of selected messages can continue to use
 `includeRawMessages`; `unmapped_messages` stores only the fields the maintained
 table cannot decode.
 
+The unsigned-byte record-temperature interoperability recovery also retains
+the original byte here, even when its unambiguous value is decoded.
+
+## Focused interoperability additions
+
+Session fields 79, 80, 106, 107, 108, and 211; lap fields 27–30, 73, 90, 96,
+97, 155, and 161; and battery message 104 fields 2 and 253 were checked against
+independently observed wire definitions in the external FIT corpus and the
+redistributable interoperability definitions for
+[session](https://github.com/muktihari/fit/blob/126e1a11233f87b7f139254d991bc3d2d952b62c/profile/mesgdef/session_gen.go),
+[lap](https://github.com/muktihari/fit/blob/126e1a11233f87b7f139254d991bc3d2d952b62c/profile/mesgdef/lap_gen.go),
+and [battery](https://github.com/muktihari/fit/blob/126e1a11233f87b7f139254d991bc3d2d952b62c/profile/mesgdef/battery_gen.go).
+The focused mappings expose swimming summaries, segment and shift counts,
+lap bounds, metabolic calories, grade-adjusted speed, and battery samples.
+Synthetic regression tests pin identifiers, wire types, scales, units, invalid
+sentinels, and collection behavior. Other battery fields remain unmapped.
+
 ## Updating the table
 
 Every mapping change requires focused regression coverage. Do not guess
@@ -45,7 +62,13 @@ npm run profile:check
 npm run check
 npm run compatibility:check -- /path/to/reference-package /path/to/fit-corpus
 npm run corpus:check -- ../FIT-test-files --allow-force-recovery
+npm run corpus:check -- ../FIT-test-files --allow-force-recovery --all-files
 ```
 
 `src/fit_types.ts` is generated from the maintained table and must not be
 edited manually.
+
+`--all-files` validates every appended FIT file through `parseFilesAsync()` and
+reports both parsed FIT file counts and concatenated input counts. Recovery
+counts apply to whole inputs; unmapped summaries count each parsed FIT file
+separately in this mode.

package/README.md

@@ -11,6 +11,7 @@ including developer-defined data.
 ## Features
 
 - Parse Node.js `Buffer` and standard `ArrayBuffer` inputs.
+- Parse concatenated FIT files as separate results with `parseFilesAsync()`.
 - Choose flat lists, nested activity data, or both output shapes.
 - Convert speed, length, temperature, and pressure fields to preferred units.
 - Decode developer fields while preserving record alignment when descriptions
@@ -33,7 +34,7 @@ npm install fit-file-parser
 
 ## Profile coverage
 
-The static profile contains 126 messages, 1,444 fields, 200 types, and 4,403
+The static profile contains 127 messages, 1,462 fields, 200 types, and 4,406
 mapped values. Pass `includeUnmappedMessages: true` to retain fields outside
 that maintained surface by number and exact bytes; applications that need all
 bytes for recognized messages can also opt into `raw_messages`.
@@ -62,6 +63,38 @@ console.log({
 })
 ```
 
+### Concatenated FIT files
+
+Some exports append several complete FIT files into one input. Use
+`parseFilesAsync()` to return a `ParsedFit[]` in file order:
+
+```javascript
+const files = await new FitParser({ force: false }).parseFilesAsync(content)
+for (const file of files) {
+  console.log(file.sessions?.length ?? 0)
+}
+```
+
+Each result has independent message definitions, developer descriptions,
+timestamps, and activity collections. Results are never merged. A single FIT
+file returns a one-element array. All parsing APIs share the same `force` and
+`strict` options. By default, complete fields in a partial final record can be
+recovered, and a non-FIT suffix after parsed files is ignored. With `force: true`,
+missing CRC bytes are also accepted, including when the next FIT header starts
+at the declared data boundary or after one CRC byte. The parser never scans
+record payloads for guessed file boundaries.
+
+Use `{ force: false, strict: true }` to require complete files and records,
+valid checksums, and no trailing bytes. `{ force: true, strict: true }` enforces
+the same structure while tolerating known checksum failures. Any file that
+cannot be parsed rejects the whole call with an `Error`. Empty input, invalid
+headers, and declared data beyond the available input
+remain errors in every mode.
+
+The existing `parseAsync()` and callback APIs return the first FIT file only.
+With `strict: true`, they require exactly one file; use `parseFilesAsync()` for
+strict validation of concatenated input.
+
 ### Callback API
 
 ```javascript
@@ -86,8 +119,9 @@ readFile('./activity.fit', (readError, content) => {
 })
 ```
 
-Parser errors are strings. `parseAsync()` rejects with the same value that the
-callback API receives as its first argument.
+The callback reports validation errors as strings. `parseAsync()` rejects with
+those values; decoder failures can reject with an `Error`. `parseFilesAsync()`
+consistently rejects with an `Error`.
 
 ## Parser options
 
@@ -97,6 +131,7 @@ All options are optional.
 | --------------------------- | --------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
 | `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. |
+| `strict`                    | `true`, `false`                         | `false`   | Requires CRC bytes, complete records, valid definitions, and no trailing bytes. CRC validation remains controlled by `force`.                  |
 | `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.                                                                         |
@@ -110,6 +145,24 @@ All options are optional.
 too short, have an invalid header size or signature, or declare data beyond the
 available bytes are rejected in both modes.
 
+`strict: false` keeps the existing decoder behavior, including its handling of
+malformed records and definitions. `parseAsync()` and callback callers keep
+their current defaults, recovery, and output. `parseFilesAsync()` uses that
+same decoder independently for each file.
+
+`strict: true` adds definition and record bounds checks so CRC bytes cannot be
+decoded as measurements. Full raw-message retention (`includeRawMessages`)
+continues to require complete records as it did before this option was added.
+
+Choose options according to the input you accept:
+
+| Options                          | Policy                                                    |
+| -------------------------------- | --------------------------------------------------------- |
+| Default                          | Best effort, including missing or invalid CRCs.           |
+| `{ force: false }`               | Validate CRCs while keeping existing field recovery.      |
+| `{ force: true, strict: true }`  | Require complete structure while tolerating invalid CRCs. |
+| `{ force: false, strict: true }` | Require complete structure and valid CRCs.                |
+
 ### Lossless developer fields
 
 By default, developer fields retain the existing decoded, name-keyed output.
@@ -148,8 +201,8 @@ message numbers.
 
 Set `includeUnmappedMessages: true` to return fields that are absent from the
 maintained profile or belong to an unknown global message in
-`unmapped_messages`. Only unmapped fields are retained, so normal known fields
-are not duplicated:
+`unmapped_messages`. Fields without usable developer names are also retained.
+Normal known fields are not duplicated:
 
 ```javascript
 const data = await new FitParser({ includeUnmappedMessages: true })
@@ -169,6 +222,20 @@ Each entry uses the same wire-level field representation as `raw_messages`.
 This opt-in ensures a newer FIT field cannot disappear merely because it
 does not yet have a reviewed semantic mapping.
 
+For record temperature encoded as one unsigned byte, values from 0 through
+126 can be decoded as Celsius before the selected temperature conversion.
+Values from 127 through 255 remain undecoded. This narrow interoperability
+recovery preserves the original unsigned byte in `unmapped_messages` when
+enabled, including values that also receive a decoded temperature.
+
+### Battery samples
+
+`batteries` retains every battery message in file order, including its
+timestamp and capacity percentage when present. These samples are also
+available in `messages.battery`. Undocumented battery fields remain available
+through `includeUnmappedMessages`; the parser does not infer their device
+association or calculate battery consumption.
+
 ### Lossless selected messages
 
 Set `includeRawMessages` when a consumer needs native FIT numeric codes rather

package/dist/binary.js

@@ -305,6 +305,7 @@ function applyOptions(data, field, options, fields) {
         case 'enhanced_speed':
         case 'vertical_speed':
         case 'avg_speed':
+        case 'avg_grade_adjusted_speed':
         case 'max_speed':
         case 'speed1s':
         case 'ball_speed':
@@ -423,14 +424,14 @@ 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) {
+        if ((options.strict || 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)
+        if ((options.strict || retainsRawMessages(options))
             && ((recordHeader & 16) !== 0
                 || blob[startIndex + 1] !== 0
                 || blob[startIndex + 2] > 1
@@ -443,7 +444,7 @@ export function readRecord(blob, messageTypes, developerFields, startIndex, opti
             : 0;
         const definitionEnd = nativeDefinitionsEnd
             + (hasDeveloperData ? 1 + numberOfDeveloperDataFields * 3 : 0);
-        if (retainsRawMessages(options) && definitionEnd > dataEnd) {
+        if ((options.strict || retainsRawMessages(options)) && definitionEnd > dataEnd) {
             throw new Error('Invalid FIT developer definition bounds');
         }
         const mTypeDef = {
@@ -465,7 +466,12 @@ export function readRecord(blob, messageTypes, developerFields, startIndex, opti
             const fieldSize = blob[fDefIndex + 1];
             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);
+            // Narrow producer interoperability case: only the shared, non-sentinel
+            // temperature range is decoded below. All original bytes remain unmapped.
+            const unsignedTemperature = mTypeDef.globalMessageNumber === 20
+                && fieldNumber === 13 && fieldSize === 1
+                && profileBaseType === 'sint8' && wireType === 'uint8';
+            const profileCompatible = unsignedTemperature || areProfileBaseTypesCompatible(profileBaseType, wireType);
             const fDef = {
                 type: profileCompatible ? type : wireType,
                 rawType: wireType,
@@ -524,7 +530,7 @@ export function readRecord(blob, messageTypes, developerFields, startIndex, opti
     const rawDeveloperFields = includeRawDeveloperFields || includeRawMessage ? [] : undefined;
     const unmappedFields = options.includeUnmappedMessages ? [] : undefined;
     const unmappedDeveloperFields = options.includeUnmappedMessages ? [] : undefined;
-    if (retainsRawMessages(options)) {
+    if (options.strict || 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) {
@@ -539,7 +545,11 @@ export function readRecord(blob, messageTypes, developerFields, startIndex, opti
             rawData[i] = InvalidFieldData;
             continue;
         }
-        if ((rawFields || (unmappedFields && !isOutputFieldName(fDef.name)))
+        const unsignedTemperature = messageType.globalMessageNumber === 20
+            && fDef.fDefNo === 13 && fDef.size === 1
+            && fDef.type === 'sint8' && fDef.rawType === 'uint8';
+        const preserveNative = !isOutputFieldName(fDef.name) || unsignedTemperature;
+        if ((rawFields || (unmappedFields && preserveNative))
             && readDataFromIndex + fDef.size <= dataEnd) {
             const rawField = {
                 fieldDefinitionNumber: fDef.fDefNo,
@@ -547,11 +557,13 @@ export function readRecord(blob, messageTypes, developerFields, startIndex, opti
                 rawValue: Array.from(blob.subarray(readDataFromIndex, readDataFromIndex + fDef.size)),
             };
             rawFields === null || rawFields === void 0 ? void 0 : rawFields.push(rawField);
-            if (!isOutputFieldName(fDef.name)) {
+            if (preserveNative) {
                 unmappedFields === null || unmappedFields === void 0 ? void 0 : unmappedFields.push(rawField);
             }
         }
-        const data = readData(blob, dataView, fDef, readDataFromIndex);
+        const data = unsignedTemperature && blob[readDataFromIndex] >= 127
+            ? InvalidFieldData
+            : readData(blob, dataView, fDef, readDataFromIndex);
         if (data !== InvalidFieldData
             && !isInvalidValue(data, fDef.type)
             && !isInvalidBaseTypeValue(data, fDef.baseTypeNo)) {
@@ -573,20 +585,21 @@ 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;
-        let rawDeveloperField;
-        if ((rawDeveloperFields
-            || (unmappedDeveloperFields && developerFieldDef.resolvedFieldDef === undefined))
+        // Resolve before deciding whether raw retention is needed. A resolved
+        // description can still have no usable output name, including after cache use.
+        const fDef = resolveDeveloperFieldDefinition(developerFieldDef, messageType.littleEndian, developerFields, options);
+        const preserveDeveloper = !fDef || !isOutputFieldName(fDef.name);
+        if ((rawDeveloperFields || (unmappedDeveloperFields && preserveDeveloper))
             && readDataFromIndex + developerFieldDef.size <= dataEnd) {
-            rawDeveloperField = {
+            const rawDeveloperField = {
                 developerDataIndex: developerFieldDef.developerDataIndex,
                 fieldDefinitionNumber: developerFieldDef.fieldDefinitionNumber,
                 rawValue: Array.from(blob.subarray(readDataFromIndex, readDataFromIndex + developerFieldDef.size)),
             };
             rawDeveloperFields === null || rawDeveloperFields === void 0 ? void 0 : rawDeveloperFields.push(rawDeveloperField);
-        }
-        const fDef = resolveDeveloperFieldDefinition(developerFieldDef, messageType.littleEndian, developerFields, options);
-        if (!fDef && rawDeveloperField) {
-            unmappedDeveloperFields === null || unmappedDeveloperFields === void 0 ? void 0 : unmappedDeveloperFields.push(rawDeveloperField);
+            if (preserveDeveloper) {
+                unmappedDeveloperFields === null || unmappedDeveloperFields === void 0 ? void 0 : unmappedDeveloperFields.push(rawDeveloperField);
+            }
         }
         if (fDef) {
             const data = readData(blob, dataView, fDef, readDataFromIndex);
@@ -652,7 +665,7 @@ export function readRecord(blob, messageTypes, developerFields, startIndex, opti
     if (isCompressedTimestamp) {
         const previousTimestamp = decoderState.lastTimestamp;
         if (previousTimestamp === undefined) {
-            if (!options.force) {
+            if (!options.force || options.strict) {
                 throw new Error('Compressed timestamp requires a previous timestamp');
             }
         }

package/dist/cjs/binary.js

@@ -311,6 +311,7 @@ function applyOptions(data, field, options, fields) {
         case 'enhanced_speed':
         case 'vertical_speed':
         case 'avg_speed':
+        case 'avg_grade_adjusted_speed':
         case 'max_speed':
         case 'speed1s':
         case 'ball_speed':
@@ -429,14 +430,14 @@ 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) {
+        if ((options.strict || 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)
+        if ((options.strict || retainsRawMessages(options))
             && ((recordHeader & 16) !== 0
                 || blob[startIndex + 1] !== 0
                 || blob[startIndex + 2] > 1
@@ -449,7 +450,7 @@ function readRecord(blob, messageTypes, developerFields, startIndex, options, st
             : 0;
         const definitionEnd = nativeDefinitionsEnd
             + (hasDeveloperData ? 1 + numberOfDeveloperDataFields * 3 : 0);
-        if (retainsRawMessages(options) && definitionEnd > dataEnd) {
+        if ((options.strict || retainsRawMessages(options)) && definitionEnd > dataEnd) {
             throw new Error('Invalid FIT developer definition bounds');
         }
         const mTypeDef = {
@@ -471,7 +472,12 @@ function readRecord(blob, messageTypes, developerFields, startIndex, options, st
             const fieldSize = blob[fDefIndex + 1];
             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);
+            // Narrow producer interoperability case: only the shared, non-sentinel
+            // temperature range is decoded below. All original bytes remain unmapped.
+            const unsignedTemperature = mTypeDef.globalMessageNumber === 20
+                && fieldNumber === 13 && fieldSize === 1
+                && profileBaseType === 'sint8' && wireType === 'uint8';
+            const profileCompatible = unsignedTemperature || areProfileBaseTypesCompatible(profileBaseType, wireType);
             const fDef = {
                 type: profileCompatible ? type : wireType,
                 rawType: wireType,
@@ -530,7 +536,7 @@ function readRecord(blob, messageTypes, developerFields, startIndex, options, st
     const rawDeveloperFields = includeRawDeveloperFields || includeRawMessage ? [] : undefined;
     const unmappedFields = options.includeUnmappedMessages ? [] : undefined;
     const unmappedDeveloperFields = options.includeUnmappedMessages ? [] : undefined;
-    if (retainsRawMessages(options)) {
+    if (options.strict || 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) {
@@ -545,7 +551,11 @@ function readRecord(blob, messageTypes, developerFields, startIndex, options, st
             rawData[i] = InvalidFieldData;
             continue;
         }
-        if ((rawFields || (unmappedFields && !isOutputFieldName(fDef.name)))
+        const unsignedTemperature = messageType.globalMessageNumber === 20
+            && fDef.fDefNo === 13 && fDef.size === 1
+            && fDef.type === 'sint8' && fDef.rawType === 'uint8';
+        const preserveNative = !isOutputFieldName(fDef.name) || unsignedTemperature;
+        if ((rawFields || (unmappedFields && preserveNative))
             && readDataFromIndex + fDef.size <= dataEnd) {
             const rawField = {
                 fieldDefinitionNumber: fDef.fDefNo,
@@ -553,11 +563,13 @@ function readRecord(blob, messageTypes, developerFields, startIndex, options, st
                 rawValue: Array.from(blob.subarray(readDataFromIndex, readDataFromIndex + fDef.size)),
             };
             rawFields === null || rawFields === void 0 ? void 0 : rawFields.push(rawField);
-            if (!isOutputFieldName(fDef.name)) {
+            if (preserveNative) {
                 unmappedFields === null || unmappedFields === void 0 ? void 0 : unmappedFields.push(rawField);
             }
         }
-        const data = readData(blob, dataView, fDef, readDataFromIndex);
+        const data = unsignedTemperature && blob[readDataFromIndex] >= 127
+            ? InvalidFieldData
+            : readData(blob, dataView, fDef, readDataFromIndex);
         if (data !== InvalidFieldData
             && !isInvalidValue(data, fDef.type)
             && !isInvalidBaseTypeValue(data, fDef.baseTypeNo)) {
@@ -579,20 +591,21 @@ 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;
-        let rawDeveloperField;
-        if ((rawDeveloperFields
-            || (unmappedDeveloperFields && developerFieldDef.resolvedFieldDef === undefined))
+        // Resolve before deciding whether raw retention is needed. A resolved
+        // description can still have no usable output name, including after cache use.
+        const fDef = resolveDeveloperFieldDefinition(developerFieldDef, messageType.littleEndian, developerFields, options);
+        const preserveDeveloper = !fDef || !isOutputFieldName(fDef.name);
+        if ((rawDeveloperFields || (unmappedDeveloperFields && preserveDeveloper))
             && readDataFromIndex + developerFieldDef.size <= dataEnd) {
-            rawDeveloperField = {
+            const rawDeveloperField = {
                 developerDataIndex: developerFieldDef.developerDataIndex,
                 fieldDefinitionNumber: developerFieldDef.fieldDefinitionNumber,
                 rawValue: Array.from(blob.subarray(readDataFromIndex, readDataFromIndex + developerFieldDef.size)),
             };
             rawDeveloperFields === null || rawDeveloperFields === void 0 ? void 0 : rawDeveloperFields.push(rawDeveloperField);
-        }
-        const fDef = resolveDeveloperFieldDefinition(developerFieldDef, messageType.littleEndian, developerFields, options);
-        if (!fDef && rawDeveloperField) {
-            unmappedDeveloperFields === null || unmappedDeveloperFields === void 0 ? void 0 : unmappedDeveloperFields.push(rawDeveloperField);
+            if (preserveDeveloper) {
+                unmappedDeveloperFields === null || unmappedDeveloperFields === void 0 ? void 0 : unmappedDeveloperFields.push(rawDeveloperField);
+            }
         }
         if (fDef) {
             const data = readData(blob, dataView, fDef, readDataFromIndex);
@@ -658,7 +671,7 @@ function readRecord(blob, messageTypes, developerFields, startIndex, options, st
     if (isCompressedTimestamp) {
         const previousTimestamp = decoderState.lastTimestamp;
         if (previousTimestamp === undefined) {
-            if (!options.force) {
+            if (!options.force || options.strict) {
                 throw new Error('Compressed timestamp requires a previous timestamp');
             }
         }

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

@@ -7,7 +7,10 @@ export { getFitCoursePointId, getFitGarminProductDisplayName, getFitGarminProduc
 export { FitMessageReaderError, fitTimestampToUnixMilliseconds, getFitBaseTypeId, readFitMessages, readFitStringField, readFitUnsignedField, } from './raw-message-reader.js';
 export type { FitMessageReaderErrorCode, FitMessageReaderIssue, FitMessageReaderIssueCode, FitMessageReaderOptions, FitMessageReaderResult, FitRawDeveloperField, FitRawField, FitRawMessage, } from './raw-message-reader.js';
 export interface FitParserOptions {
+    /** Skips CRC validation and enables supported best-effort recovery. Defaults to true. */
     force?: boolean;
+    /** Requires complete files and records, and rejects trailing bytes. Defaults to false. */
+    strict?: boolean;
     speedUnit?: string;
     lengthUnit?: string;
     temperatureUnit?: string;
@@ -28,5 +31,13 @@ export default class FitParser {
     private readonly options;
     constructor(options?: FitParserOptions);
     parseAsync(content: ArrayBuffer | Buffer<ArrayBuffer>): Promise<ParsedFit>;
+    /**
+     * Parses FIT files in input order with independent decoder state. Uses the
+     * same force and strict policies as parseAsync; strict mode rejects trailing
+     * bytes, while the default ignores a non-FIT suffix after parsed files.
+     * Rejects with an Error when any file cannot be parsed.
+     */
+    parseFilesAsync(content: ArrayBuffer | Buffer<ArrayBuffer>): Promise<ParsedFit[]>;
     parse(content: ArrayBuffer | Buffer<ArrayBuffer>, callback: FitParserCallback): void;
+    private parseFile;
 }