trackswap 0.2.3 → 0.2.4

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import { LapMesgType, LengthMesgType, RecordMesgType, SessionMesgType } from "./FIT/types.js";
+import { LapMesgType, LengthMesgType, RecordMesgType, SetMesgType, SessionMesgType } from "./FIT/types.js";
 export interface Token {
     type: "open" | "close" | "text";
     tag: string;
@@ -14,19 +14,41 @@ export interface TokenAST {
 export interface AttributeType {
     [key: string]: string;
 }
+/**
+ * The latitude of the point. Decimal degrees, WGS84 datum.
+ * @type {number} -90.0 <= value <= 90.0
+ */
 export type LatitudeType = number;
+/**
+ * The longitude of the point. Decimal degrees, WGS84 datum.
+ * @type {number} -180.0 <= value < 180.0
+ */
 export type LongitudeType = number;
+/**
+ * Used for bearing, heading, course. Units are decimal degrees, true (not magnetic).
+ * @type {number} 0.0 <= value < 360.0
+
+ */
 export type DegreesType = number;
 export interface ExtensionsType {
     [key: string]: string | number | undefined | ExtensionsType;
 }
+/**
+ * Parse File Type
+ */
 export interface FileType {
     metadata?: {
         originType: "GPX" | "FIT" | "TCX" | "HIJSON";
         fileName?: string;
         fileType?: string;
     };
+    /**
+     * 描述 gpx points
+     */
     points?: ActivityRecordType[];
+    /**
+     * 描述 gpx routes、 tcx course
+     */
     routes?: ActivityLapType[];
     activities?: ActivityType[];
     userProfile?: UserProfileType;
@@ -50,28 +72,84 @@ export interface UserProfileType {
     elevSetting?: string;
     weightSetting?: string;
 }
+/**
+ * Activity Type 直接继承自 FIT 的 session message，
+ *
+ * gpx -> trk
+ * fit -> session
+ * tcx -> Activity
+ * 对应 gpx 的 trk ， fit 的 sessions, tcx 的 Activity
+ */
 export interface ActivityType extends SessionMesgType {
+    /**
+     * 活动索引
+     */
     index: number;
+    /**
+     * 结束时间
+     */
     endTime?: Date;
     laps?: ActivityLapType[];
+    /** Ordered strength-training active/rest phases for this activity. */
+    strengthSets?: ActivityStrengthSetType[];
+    /** GPX trk/name or an equivalent source activity title. */
     activityName?: string;
+    /** GPX trk/cmt. */
     comment?: string;
+    /** GPX trk/desc. */
     description?: string;
+    /** GPX trk/src. */
     source?: string;
+    /** GPX trk/link values. */
     links?: ActivityLinkType[];
+    /** GPX trk/number. */
     activityNumber?: number;
+    /** Original GPX trk/extensions payload. */
     gpxExtensions?: ExtensionsType;
 }
+export interface ActivityStrengthExerciseType {
+    /** FIT exercise category, for example `deadlift` or `cardio`. */
+    category: string | number;
+    /** Raw category-specific FIT exercise-name enum value. */
+    categorySubtype?: number;
+    /** Stable Garmin FIT profile name, for example `straightLegDeadlift`. */
+    name?: string;
+}
+export interface ActivityStrengthSetType extends SetMesgType {
+    /** Stable zero-based order inside the activity. */
+    index: number;
+    /** Category/subtype pairs projected into portable exercise labels. */
+    exercises: ActivityStrengthExerciseType[];
+}
 export interface ActivityLinkType {
     href?: string;
     text?: string;
     type?: string;
 }
+/**
+ * Activity Record Type 直接继承自 FIT 的 record message，
+ * 将 其他文件类型的数据向 FIT 结构对齐
+ */
 export interface ActivityRecordType extends RecordMesgType {
+    /**
+     *  lap 索引
+     */
     lapIndex: number;
+    /**
+     * 记录索引
+     */
     index: number;
+    /**
+     * Horizontal dilution of precision.
+     */
     hdop?: number;
+    /**
+     * Vertical dilution of precision.
+     */
     vdop?: number;
+    /**
+     * Position dilution of precision.
+     */
     pdop?: number;
     course?: number;
     magvar?: number;
@@ -87,22 +165,45 @@ export interface ActivityRecordType extends RecordMesgType {
     ageofdgpsdata?: number;
     dgpsid?: number;
     gpxExtensions?: ExtensionsType;
+    /**
+     * 转弯角度
+     */
     turn?: number;
+    /**
+     * 记录描述
+     */
     description?: string;
 }
 export interface ActivityLengthType extends LengthMesgType {
     index: number;
 }
+/**
+ * Segments & fit(lap) & tcx(lap)
+ */
 export interface ActivityLapType extends LapMesgType {
+    /**
+     * 活动索引
+     */
     index: number;
+    /**
+     * 结束时间
+     */
     endTime?: Date;
+    /** TCX Course / GPX rte 等路线的展示名称（可选） */
     routeName?: string;
+    /** GPX rte/cmt. */
     comment?: string;
+    /** GPX rte/desc. */
     description?: string;
+    /** GPX rte/src. */
     source?: string;
+    /** GPX rte/link values. */
     links?: ActivityLinkType[];
+    /** GPX rte/number. */
     routeNumber?: number;
+    /** GPX rte/type. */
     routeType?: string;
+    /** Original GPX rte or trkseg extensions payload. */
     gpxExtensions?: ExtensionsType;
     records: ActivityRecordType[];
     lengths: ActivityLengthType[];

package/dist/util.d.ts

@@ -20,6 +20,15 @@ export declare const convertGPXExtensionsMapping: {
     "gpxx:Temperature": string;
     "gpxx:Depth": string;
 };
+/**
+ * Convert semicircles (FIT wire/SDK units, scale 1 in Garmin JS profile) to decimal degrees.
+ * @garmin/fitsdk decoder applies scale/offset per field; record position fields remain semicircles (units string), not pre-converted degrees.
+ */
 export declare const semicirclesToDegrees: (semicircles: number) => number;
+/** FIT sint32 semicircle field: invalid when all bits set (Garmin profile). */
 export declare const FIT_SEMICIRCLE_INVALID_SINT32 = 2147483647;
+/**
+ * Raw FIT semicircle from SDK (scale 1 "semicircles" units) → decimal degrees.
+ * Treats FIT invalid sentinel as absent. Preserves 0° (equator / prime meridian).
+ */
 export declare function normalizeFitSemicircleToDegrees(raw: unknown, precision?: number): number | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackswap",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "A typed, adapter-based toolkit for decoding, normalizing and transcoding FIT, GPX and TCX data.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -42,10 +42,11 @@
     "test:fit-coords": "npm run build:dev && node scripts/verify-fit-coordinates.mjs",
     "test:tcx-course": "npm run build:dev && node scripts/tcx-course-smoke.mjs",
     "test:routes-fit": "npm run build:dev && node scripts/routes-only-fit-smoke.mjs",
-    "test": "npm run test:architecture && npm run test:health && npm run test:garmin-parity",
+    "test": "npm run test:architecture && npm run test:health && npm run test:garmin-parity && npm run test:fit-structure",
     "test:architecture": "esbuild test/architecture.test.ts --bundle --platform=node --target=node18 --format=esm --outfile=/tmp/trackswap-architecture.test.mjs && node /tmp/trackswap-architecture.test.mjs",
     "test:health": "esbuild test/health-fit.test.ts --bundle --platform=node --target=node18 --format=esm --outfile=/tmp/trackswap-health-fit.test.mjs && node /tmp/trackswap-health-fit.test.mjs",
     "test:garmin-parity": "esbuild test/garmin-sdk-parity.test.ts --bundle --platform=node --target=node18 --format=esm --outfile=/tmp/trackswap-garmin-sdk-parity.test.mjs && node /tmp/trackswap-garmin-sdk-parity.test.mjs",
+    "test:fit-structure": "esbuild test/fit-structure.test.ts --bundle --platform=node --target=node18 --format=esm --outfile=/tmp/trackswap-fit-structure.test.mjs && node /tmp/trackswap-fit-structure.test.mjs",
     "test:package": "node scripts/verify-package.mjs",
     "prepublishOnly": "npm run build"
   },
@@ -86,7 +87,7 @@
     "typescript": "^5.8.3"
   },
   "dependencies": {
-    "@garmin/fitsdk": "^21.195.0",
+    "@garmin/fitsdk": "21.212.0",
     "dayjs": "^1.11.13",
     "geolib": "^3.3.4",
     "htmlparser2": "^10.0.0"