@garmin/fitsdk 21.202.0 → 21.205.0

package/src/profile.js

@@ -5,15 +5,15 @@
 // Transfer (FIT) Protocol License.
 /////////////////////////////////////////////////////////////////////////////////////////////
 // ****WARNING****  This file is auto-generated!  Do NOT edit this file.
-// Profile Version = 21.202.0Release
-// Tag = production/release/21.202.0-0-g9a57aebc
+// Profile Version = 21.205.0Release
+// Tag = production/release/21.205.0-0-gb3c261eb
 /////////////////////////////////////////////////////////////////////////////////////////////
 
 
 const Profile = {
     version: {
         major: 21,
-        minor: 202,
+        minor: 205,
         patch: 0,
         type: "Release"
     },
@@ -20950,7 +20950,7 @@ const Profile = {
                 array: true,
                 scale: 1000,
                 offset: 0,
-                units: "degC",
+                units: "C",
                 bits: [],
                     components: [],
                     isAccumulated: false,
@@ -25104,10 +25104,14 @@ types: {
        4759: "instinct3Solar50mm",
        4775: "tactix8Amoled",
        4776: "tactix8Solar",
+       4814: "fr170Music",
+       4815: "fr170",
        4825: "approachJ1",
        4879: "d2Mach2",
+       4916: "fr702026",
        4678: "instinctCrossoverAmoled",
        4944: "d2AirX15",
+       5056: "d2Mach2Pro",
        10007: "sdm4", // SDM4 footpod
        10014: "edgeRemote",
        20533: "tacxTrainingAppWin",

package/src/stream.js

@@ -5,8 +5,8 @@
 // Transfer (FIT) Protocol License.
 /////////////////////////////////////////////////////////////////////////////////////////////
 // ****WARNING****  This file is auto-generated!  Do NOT edit this file.
-// Profile Version = 21.202.0Release
-// Tag = production/release/21.202.0-0-g9a57aebc
+// Profile Version = 21.205.0Release
+// Tag = production/release/21.205.0-0-gb3c261eb
 /////////////////////////////////////////////////////////////////////////////////////////////
 
 
@@ -14,55 +14,32 @@ import FIT from "./fit.js";
 import UtilsInternal from "./utils-internal.js";
 
 class Stream {
-    static LITTLE_ENDIAN = true;
-    static BIG_ENDIAN = false;
-
     #position = 0;
     #arrayBuffer = null;
+    #dataView = null;
     #textDecoder = new TextDecoder("utf-8", { fatal: false, ignoreBOM: true });
     #crcCalculator = null;
+    #legacyArrayMode = false;
 
-    /**
-     * Convenience method for creating a Stream from a byte array
-     * @param {Array<number>} data An array of bytes
-     * @returns {Stream} A new Stream object
-     * @static
-     */
     static fromByteArray(data) {
         const buf = new Uint8Array(data);
         return this.fromArrayBuffer(buf.buffer);
     }
 
-    /**
-     * Convenience method for creating a Stream from a Node Buffer
-     * @param {Buffer} buffer - Node Buffer of bytes
-     * @returns {Stream} A new Stream object
-     * @static
-     */
     static fromBuffer(buffer) {
         const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
         return this.fromArrayBuffer(arrayBuffer);
     }
 
-    /**
-     * Convenience method for creating a Stream from an ArrayBuffer
-     * @param {ArrayBuffer} arrayBuffer - An ArrayBuffer of bytes
-     * @returns {Stream} A new Stream object
-     * @static
-     */
     static fromArrayBuffer(arrayBuffer) {
         const stream = new Stream(arrayBuffer);
         return stream;
     }
 
-    /**
-     * Creates a Stream containing a FIT file
-     * @constructor
-     * @param {ArrayBuffer} stream - ArrayBuffer containing a FIT file
-     */
     constructor(arrayBuffer) {
         this.#position = 0;
         this.#arrayBuffer = arrayBuffer;
+        this.#dataView = new DataView(arrayBuffer);
     }
 
     get length() {
@@ -85,6 +62,14 @@ class Stream {
         this.#crcCalculator = crcCalculator;
     }
 
+    get legacyArrayMode() {
+        return this.#legacyArrayMode;
+    }
+
+    set legacyArrayMode(legacyArrayMode) {
+        this.#legacyArrayMode = legacyArrayMode;
+    }
+
     reset() {
         this.seek(0);
     }
@@ -98,9 +83,7 @@ class Stream {
     }
 
     peekByte() {
-        const arrayBuffer = this.#arrayBuffer.slice(this.#position, this.#position + 1);
-        const dataView = new DataView(arrayBuffer);
-        return dataView.getUint8(0);
+        return this.#dataView.getUint8(this.#position);
     }
 
     readByte() {
@@ -160,14 +143,27 @@ class Stream {
         return this.readValue(FIT.BaseType.FLOAT64, 8, { convertInvalidToNull: false, ...opts });
     }
 
-    readString(strlen) {
-        return this.readValue(FIT.BaseType.STRING, strlen);
+    readString(strlen, opts = {}) {
+        return this.readValue(FIT.BaseType.STRING, strlen, opts);
     }
 
-    readValue(baseType, size, { endianness = Stream.LITTLE_ENDIAN, convertInvalidToNull = true } = {}) {
-        const baseTypeSize = FIT.BaseTypeDefinitions[baseType].size;
-        const baseTypeInvalid = FIT.BaseTypeDefinitions[baseType].invalid;
+    asUint8Array() {
+        return new Uint8Array(this.#arrayBuffer);
+    }
 
+    readValue(
+        baseType,
+        size,
+        {
+            littleEndian = true,
+            convertInvalidToNull = true,
+            isArray = false
+        } = {}) {
+        const baseTypeDef = FIT.BaseTypeDefinitions[baseType];
+        const baseTypeSize = baseTypeDef.size;
+        const baseTypeInvalid = baseTypeDef.invalid;
+
+        const startPos = this.#position;
         const bytes = this.readBytes(size);
 
         if (size % baseTypeSize !== 0) {
@@ -186,73 +182,94 @@ class Stream {
                 return null;
             }
 
-            return strings.length === 1 ? strings[0] : strings;
-        }
+            if (this.#legacyArrayMode) {
+                return strings.length === 1 ? strings[0] : strings;
+            }
 
-        const dataView = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-        let values = [];
+            return strings[0];
+        }
 
         const count = size / baseTypeSize;
 
-        for (let i = 0; i < count; i++) {
+        if (count === 1) {
+            const value = this.#readSingleValue(baseType, startPos, littleEndian);
+
+            if (convertInvalidToNull && value === baseTypeInvalid) {
+                return null;
+            }
 
-            switch (baseType) {
-                case FIT.BaseType.BYTE:
-                case FIT.BaseType.ENUM:
-                case FIT.BaseType.UINT8:
-                case FIT.BaseType.UINT8Z:
-                    values.push(dataView.getUint8(i * baseTypeSize));
-                    break;
-
-                case FIT.BaseType.SINT8:
-                    values.push(dataView.getInt8(i * baseTypeSize));
-                    break;
-
-                case FIT.BaseType.UINT16:
-                case FIT.BaseType.UINT16Z:
-                    values.push(dataView.getUint16(i * baseTypeSize, endianness));
-                    break;
-
-                case FIT.BaseType.SINT16:
-                    values.push(dataView.getInt16(i * baseTypeSize, endianness));
-                    break;
-
-                case FIT.BaseType.UINT32:
-                case FIT.BaseType.UINT32Z:
-                    values.push(dataView.getUint32(i * baseTypeSize, endianness));
-                    break;
-
-                case FIT.BaseType.SINT32:
-                    values.push(dataView.getInt32(i * baseTypeSize, endianness));
-                    break;
-
-                case FIT.BaseType.UINT64:
-                case FIT.BaseType.UINT64Z:
-                    values.push(dataView.getBigUint64(i * baseTypeSize, endianness));
-                    break;
-                case FIT.BaseType.SINT64:
-                    values.push(dataView.getBigInt64(i * baseTypeSize, endianness));
-                    break;
-
-                case FIT.BaseType.FLOAT32:
-                    values.push(dataView.getFloat32(i * baseTypeSize, endianness));
-                    break;
-
-                case FIT.BaseType.FLOAT64:
-                    values.push(dataView.getFloat64(i * baseTypeSize, endianness));
-                    break;
+            if (!this.#legacyArrayMode && !isArray) {
+                return value;
             }
+
+            return UtilsInternal.sanitizeValues([value], { legacyArrayMode: this.#legacyArrayMode, isArray });
         }
 
-        if (baseType === FIT.BaseType.BYTE) {
-            return UtilsInternal.onlyInvalidValues(values, baseTypeInvalid) ? null : values;
+        let values = [];
+
+        for (let i = 0; i < count; i++) {
+            values.push(this.#readSingleValue(baseType, startPos + i * baseTypeSize, littleEndian));
         }
 
         if (convertInvalidToNull) {
-            values = values.map(value => value === baseTypeInvalid ? null : value);
+            if (UtilsInternal.onlyInvalidValues(values, baseTypeInvalid)) {
+                return null;
+            }
+
+            if (baseType !== FIT.BaseType.BYTE) {
+                values = values.map(value => value === baseTypeInvalid ? null : value);
+            }
         }
 
-        return UtilsInternal.sanitizeValues(values);
+        return UtilsInternal.sanitizeValues(
+            values,
+            {
+                legacyArrayMode: this.#legacyArrayMode,
+                isArray
+            });
+    }
+
+    #readSingleValue(baseType, offset, littleEndian) {
+        switch (baseType) {
+            case FIT.BaseType.BYTE:
+            case FIT.BaseType.ENUM:
+            case FIT.BaseType.UINT8:
+            case FIT.BaseType.UINT8Z:
+                return this.#dataView.getUint8(offset);
+
+            case FIT.BaseType.SINT8:
+                return this.#dataView.getInt8(offset);
+
+            case FIT.BaseType.UINT16:
+            case FIT.BaseType.UINT16Z:
+                return this.#dataView.getUint16(offset, littleEndian);
+
+            case FIT.BaseType.SINT16:
+                return this.#dataView.getInt16(offset, littleEndian);
+
+            case FIT.BaseType.UINT32:
+            case FIT.BaseType.UINT32Z:
+                return this.#dataView.getUint32(offset, littleEndian);
+
+            case FIT.BaseType.SINT32:
+                return this.#dataView.getInt32(offset, littleEndian);
+
+            case FIT.BaseType.UINT64:
+            case FIT.BaseType.UINT64Z:
+                return this.#dataView.getBigUint64(offset, littleEndian);
+
+            case FIT.BaseType.SINT64:
+                return this.#dataView.getBigInt64(offset, littleEndian);
+
+            case FIT.BaseType.FLOAT32:
+                return this.#dataView.getFloat32(offset, littleEndian);
+
+            case FIT.BaseType.FLOAT64:
+                return this.#dataView.getFloat64(offset, littleEndian);
+
+            default:
+                throw new Error(`Unsupported FIT base type: ${baseType}`);
+        }
     }
 }
 

package/src/types/crc-calculator.d.ts

@@ -0,0 +1,34 @@
+/////////////////////////////////////////////////////////////////////////////////////////////
+// Copyright 2026 Garmin International, Inc.
+// Licensed under the Flexible and Interoperable Data Transfer (FIT) Protocol License; you
+// may not use this file except in compliance with the Flexible and Interoperable Data
+// Transfer (FIT) Protocol License.
+/////////////////////////////////////////////////////////////////////////////////////////////
+// ****WARNING****  This file is auto-generated!  Do NOT edit this file.
+// Profile Version = 21.205.0Release
+// Tag = production/release/21.205.0-0-gb3c261eb
+/////////////////////////////////////////////////////////////////////////////////////////////
+
+
+/** Computes the 16-bit CRC used to validate FIT file headers and file data. */
+export class CrcCalculator {
+    constructor();
+    /** The current running CRC value. */
+    readonly crc: number;
+    /**
+     * Feeds a range of bytes into the running CRC.
+     * @param buf - The byte array to process.
+     * @param start - Inclusive start index within `buf`.
+     * @param end - Exclusive end index within `buf`.
+     * @returns The updated CRC value.
+     */
+    addBytes(buf: Uint8Array, start: number, end: number): number;
+    /**
+     * Computes the CRC for a range of bytes without requiring an instance.
+     * @param buf - The byte array to process.
+     * @param start - Inclusive start index within `buf`.
+     * @param end - Exclusive end index within `buf`.
+     * @returns The computed CRC value.
+     */
+    static calculateCRC(buf: Uint8Array, start: number, end: number): number;
+}

package/src/types/decoder.d.ts

@@ -0,0 +1,140 @@
+/////////////////////////////////////////////////////////////////////////////////////////////
+// Copyright 2026 Garmin International, Inc.
+// Licensed under the Flexible and Interoperable Data Transfer (FIT) Protocol License; you
+// may not use this file except in compliance with the Flexible and Interoperable Data
+// Transfer (FIT) Protocol License.
+/////////////////////////////////////////////////////////////////////////////////////////////
+// ****WARNING****  This file is auto-generated!  Do NOT edit this file.
+// Profile Version = 21.205.0Release
+// Tag = production/release/21.205.0-0-gb3c261eb
+/////////////////////////////////////////////////////////////////////////////////////////////
+
+
+import { Stream } from "./stream";
+import { Mesg } from "./mesg";
+import { FitMessages, DeveloperDataIdMesg, FieldDescriptionMesg } from "./mesgs";
+
+/** Decodes FIT binary data from a {@link Stream}. */
+export class Decoder {
+    /**
+     * Creates a FIT File Decoder.
+     * @param stream - Stream representing the FIT file to decode.
+     */
+    constructor(stream: Stream);
+
+    /**
+     * Inspects the file header to determine if the input stream is a FIT file.
+     * @param stream - The stream to inspect.
+     * @returns `true` if the stream is a FIT file.
+     */
+    static isFIT(stream: Stream): boolean;
+
+    /**
+     * Inspects the file header to determine if the input stream is a FIT file.
+     * @returns `true` if the stream is a FIT file.
+     */
+    isFIT(): boolean;
+
+    /**
+     * Checks that the input stream is a FIT file and verifies both the header and file CRC values.
+     * @returns `true` if the stream passes the {@link isFIT} and CRC checks.
+     */
+    checkIntegrity(): boolean;
+
+    /**
+     * Read the messages from the stream.
+     * @param options - Read options. See {@link DecoderOptions}.
+     * @returns Object containing decoded messages, profile version, and any errors.
+     */
+    read(options?: DecoderOptions): { messages: FitMessages; profileVersion: ProfileVersion; errors: Error[] };
+}
+
+/** Describes a single field within a MesgDefinition. */
+export interface FieldDefinition {
+    /** Field definition number identifying the field within its message. */
+    fieldDefinitionNumber: number;
+    /** Size in bytes of the field. */
+    size: number;
+    /** FIT base type identifier for this field's values. */
+    baseType: number;
+    /** The invalid value for this field's base type. */
+    invalidValue: number;
+    /** Byte size of a single element of this field's base type. */
+    baseTypeSize: number;
+}
+
+/** Describes a single developer-defined field within a raw FIT message definition record. */
+export interface DeveloperFieldDefinition {
+    /** Developer field definition number, scoped to the developer data index. */
+    fieldDefinitionNumber: number;
+    /** Size in bytes of the field. */
+    size: number;
+    /** Index identifying the developer application that defined this field. */
+    developerDataIndex: number;
+}
+
+/** The definition record for a FIT message*/
+export interface MesgDefinition {
+    /** Raw record header byte. */
+    recordHeader: number;
+    /** Local message number used to map messages to a definition. */
+    localMesgNum: number;
+    /** Reserved byte from the definition record. */
+    reserved: number;
+    /** Architecture byte: `0` = little-endian, `1` = big-endian. */
+    architecture: number;
+    /** Endianness derived from `architecture` (`true` == little-endian or `false` == big-endian). */
+    endianness: boolean;
+    /** Global message number identifying the message type in the FIT profile. */
+    globalMessageNumber: number;
+    /** Number of fields in the message. */
+    numFields: number;
+    /** Array of field definitions for the message. */
+    fieldDefinitions: FieldDefinition[];
+    /** Developer field definitions for the message. */
+    developerFieldDefinitions: DeveloperFieldDefinition[];
+    /** Total size in bytes of the combined fields. */
+    messageSize: number;
+    /** Total size in bytes of the combined developer fields. */
+    developerDataSize: number;
+}
+
+/** Options controlling how {@link Decoder.read} decodes the FIT stream. */
+export interface DecoderOptions {
+    /** Callback invoked for each decoded message. */
+    mesgListener?: (mesgNum: number, mesg: Mesg) => void;
+    /** Callback invoked for each decoded message definition. */
+    mesgDefinitionListener?: (mesgDefinition: MesgDefinition) => void;
+    /** Callback invoked for each developer field description. */
+    fieldDescriptionListener?: (key: number, developerDataIdMesg: DeveloperDataIdMesg, fieldDescriptionMesg: FieldDescriptionMesg) => void;
+    /** Expand sub fields. Default: `true`. */
+    expandSubFields?: boolean;
+    /** Expand component fields. Default: `true`. */
+    expandComponents?: boolean;
+    /** Apply scale and offset to numeric fields. Default: `true`. */
+    applyScaleAndOffset?: boolean;
+    /** Convert type values to their string representations. Default: `true`. */
+    convertTypesToStrings?: boolean;
+    /** Convert FIT epoch timestamps to `Date` objects. Default: `true`. */
+    convertDateTimesToDates?: boolean;
+    /** Include fields not in the profile. Default: `false`. */
+    includeUnknownData?: boolean;
+    /** Merge HR messages into record messages. Requires `applyScaleAndOffset` and `expandComponents`. Default: `true`. */
+    mergeHeartRates?: boolean;
+    /** Decode memo glob messages. Default: `false`. */
+    decodeMemoGlobs?: boolean;
+    /** Skip the FIT file header. Default: `false`. */
+    skipHeader?: boolean;
+    /** Decode data bytes only, no header or CRC. Default: `false`. */
+    dataOnly?: boolean;
+    /** @deprecated Default: `false`. */
+    legacyArrayMode?: boolean;
+}
+
+/** The FIT profile version embedded in a FIT file header. */
+export interface ProfileVersion {
+    /** Major version number. */
+    major: number;
+    /** Minor version number (tenths). */
+    minor: number;
+}

package/src/types/encoder.d.ts

@@ -0,0 +1,69 @@
+/////////////////////////////////////////////////////////////////////////////////////////////
+// Copyright 2026 Garmin International, Inc.
+// Licensed under the Flexible and Interoperable Data Transfer (FIT) Protocol License; you
+// may not use this file except in compliance with the Flexible and Interoperable Data
+// Transfer (FIT) Protocol License.
+/////////////////////////////////////////////////////////////////////////////////////////////
+// ****WARNING****  This file is auto-generated!  Do NOT edit this file.
+// Profile Version = 21.205.0Release
+// Tag = production/release/21.205.0-0-gb3c261eb
+/////////////////////////////////////////////////////////////////////////////////////////////
+
+
+import { Encodable, Mesg } from "./mesg";
+import { DeveloperDataIdMesg, FieldDescriptionMesg } from "./mesgs";
+
+export interface FieldDescription {
+    /** The Developer Data Id message. */
+    developerDataIdMesg: DeveloperDataIdMesg;
+    /** The Field Description message. */
+    fieldDescriptionMesg: FieldDescriptionMesg;
+}
+
+/** Options for constructing an {@link Encoder}. */
+export interface EncoderOptions {
+    /** Developer field descriptions keyed by developer data index. Equivalent to calling {@link Encoder.addDeveloperField} for each entry. */
+    fieldDescriptions?: Record<number, FieldDescription>;
+}
+
+/** Encodes FIT messages into a binary FIT file. */
+export class Encoder {
+    /**
+     * Creates a FIT File Encoder.
+     * @param options - Encoder options. See {@link EncoderOptions}.
+     */
+    constructor(options?: EncoderOptions);
+
+    /**
+     * Closes the encoder and returns the encoded file data.
+     * @returns A `Uint8Array` containing the encoded FIT file.
+     */
+    close(): Uint8Array;
+
+    /**
+     * Encodes a message into the file.
+     * @param mesg - The message data, must include a `mesgNum` property.
+     * @returns `this`.
+     */
+    writeMesg(mesg: Encodable<Mesg>): this;
+
+    /**
+     * Encodes a message into the file.
+     * Can be used directly as a {@link DecoderOptions.mesgListener} callback.
+     * @param mesgNum - The message number.
+     * @param mesg - The message data.
+     * @returns `this`.
+     */
+    onMesg(mesgNum: number, mesg: Mesg): this;
+
+    /**
+     * Adds a Developer Data Field Description and associated Developer Data Id Message to the Encoder.
+     * Does not write these messages to the output stream.
+     * Can be used directly as a {@link DecoderOptions.fieldDescriptionListener} callback.
+     * @param key - The key associated with this developer field pairing.
+     * @param developerDataIdMesg - The Developer Data Id message.
+     * @param fieldDescriptionMesg - The Field Description message.
+     * @returns `this`.
+     */
+    addDeveloperField(key: number, developerDataIdMesg: DeveloperDataIdMesg, fieldDescriptionMesg: FieldDescriptionMesg): this;
+}

package/src/types/mesg.d.ts

@@ -0,0 +1,35 @@
+/////////////////////////////////////////////////////////////////////////////////////////////
+// Copyright 2026 Garmin International, Inc.
+// Licensed under the Flexible and Interoperable Data Transfer (FIT) Protocol License; you
+// may not use this file except in compliance with the Flexible and Interoperable Data
+// Transfer (FIT) Protocol License.
+/////////////////////////////////////////////////////////////////////////////////////////////
+// ****WARNING****  This file is auto-generated!  Do NOT edit this file.
+// Profile Version = 21.205.0Release
+// Tag = production/release/21.205.0-0-gb3c261eb
+/////////////////////////////////////////////////////////////////////////////////////////////
+
+
+import Types from "./types";
+
+/** A FIT field value — a scalar or array of one of the primitive FIT base types. */
+export type FieldValue =
+    | string
+    | number
+    | boolean
+    | bigint
+    | Date
+    | (string | number | boolean | bigint | Date)[];
+
+/** Developer-defined fields keyed by developer field key. */
+export type DeveloperFields = { [developerFieldKey: string]: FieldValue | undefined };
+
+/** Base interface for all decoded FIT messages. */
+export interface Mesg {
+    /** Global FIT message number identifying the message type. */
+    mesgNum?: Types.MesgNum;
+    /** Developer-defined field values attached to this message. */
+    developerFields?: DeveloperFields;
+}
+
+export type Encodable<T extends Mesg> = T & Required<Pick<Mesg, 'mesgNum'>>;