v21.205 of the JavaScript SDK added type definitions.
https://github.com/garmin/fit-javascript-sdk/tree/main/src/types
Along with the types definitions, the decoder now adheres to the profile for array fields.
- Array fields will always be returned as arrays, even when there is only one element
- Non-array fields will always return a single value, even when there are multuple values
The binary protocol allows for any field to be an array, whereas the profile provides an unenforceable contract of what fields are arrays. That is true for all SDKs.
Previously, the JavaScript SDK would decode a field and then check the array length. If the length as one, then it would return the value at index zero, else it would return an array.
We did not want to carry that behavior forward when adding the type definitions. So now, the decoder references the profile to see if a field is an array or not and returns an array or scalar based on the profile.
While this change has the potential to be a breaking change, we don't think it will. The reason being is, most people should have discovered by now that sometimes a field that was not expected to be an array might be. i.e. any string field and any field with a name that starts with "enhanced", and everyone should have checks in their code to handle this. If so, then that defensive code can be removed.
If this change does break your code, the read() method of the Decoder class has a new legacyArrayMode option. The default is false. Setting the option to true will revert back to the previous behavior. The v21.205 release did not include many profile changes, a few product ids, so the other option is to stay with 21.202 and update to 21.205 at a later time. The new legacyArrayMode option is marked as deprecated since we plan to remove it by EOY26.
Even if you do not use TypeScript, the type definitions should provide better auto-complete and context sensitive help when using the JavaScript SDK.