trackswap 0.0.15 → 0.0.17

package/README.md

@@ -13,7 +13,8 @@
 - 🔄 **多格式支持**: GPX 1.1、FIT、TCX 格式
 - 🎯 **统一转换**: 任意格式之间相互转换
 - 🤖 **自动检测**: 智能识别文件格式
-- 🔧 **插件架构**: 基于插件的可扩展设计
+- 🧩 **扩展系统**: 灵活的扩展架构，支持自定义数据处理
+- 📊 **智能聚合**: 默认启用运动数据聚合（心率、功率、速度等）
 - 🛡️ **类型安全**: 完整的 TypeScript 支持
 - ⚡ **高性能**: 优化的解析和编码算法
 
@@ -72,8 +73,32 @@ const parsedData = await trackSwap.parseFile(buffer);
 const sportData = await trackSwap.parseToActivity(buffer);
 ```
 
+### 扩展系统
+
+```typescript
+import { TrackSwap } from 'trackswap';
+import { SlopeExtension } from 'trackswap/extensions';
+
+// 🧩 使用扩展增强功能
+const trackSwap = new TrackSwap()
+  .extend(new SlopeExtension()); // 添加坡度计算
+
+// 📊 默认已启用基础指标聚合（心率、功率、速度、踏频等）
+const result = await trackSwap.parseGPX(gpxBuffer);
+// result 包含完整的聚合数据和坡度信息
+
+// 🔗 链式添加多个扩展
+const enhancedTrackSwap = new TrackSwap()
+  .extend(new SlopeExtension())
+  .extend(new CustomExtension());
+```
+
 ## 📖 详细使用指南
 
+### 扩展系统
+
+详细的扩展开发和使用指南请参考：[扩展系统文档](EXTENSIONS.md)
+
 ### 1. 文件解析
 
 #### GPX 文件处理
@@ -387,23 +412,23 @@ TrackSwap 采用模块化架构，核心组件包括：
 ```
 src/
 ├── TrackSwap.ts          # 主入口类
-├── GPX/                  # GPX 模块
-│   ├── decoder.ts
-│   ├── encoder.ts
-│   └── types.ts
-├── FIT/                  # FIT 模块
-│   ├── decoder.ts
-│   ├── encoder.ts
-│   └── types.ts
-├── TCX/                  # TCX 模块
-│   ├── decoder.ts
-│   ├── encoder.ts
-│   └── types.ts
-├── sport/                # 统一转换模块
-│   ├── processor.ts
-│   ├── converters.ts
-│   ├── encoders.ts
-│   └── base.ts
+├── activity/             # 活动处理模块
+│   ├── extensions.ts     # 扩展系统核心
+│   ├── slope-extension.ts # 坡度计算扩展
+│   ├── processor.ts      # 活动处理器
+│   └── pipeline.ts       # 数据处理管道
+├── decoders/             # 解码器模块
+│   ├── GPXDecoder.ts
+│   ├── FITDecoder.ts
+│   └── TCXDecoder.ts
+├── encoders/             # 编码器模块
+│   ├── GPXEncoder.ts
+│   ├── FITEncoder.ts
+│   └── TCXEncoder.ts
+├── converters/           # 格式转换器
+│   ├── GPXConverter.ts
+│   ├── FITConverter.ts
+│   └── TCXConverter.ts
 └── types.ts              # 公共类型定义
 ```
 
@@ -427,4 +452,4 @@ MIT License
 <div align="center">
   <strong>TrackSwap - 让轨迹数据处理变得简单</strong><br>
   🚀 高效 • 🔄 统一 • 🛡️ 安全 • 📈 可扩展
-</div> 
+</div>

package/dist/FIT/decoder.d.ts

@@ -27,7 +27,7 @@ export declare class FITDecoder {
         skipValidation?: boolean;
         enableStats?: boolean;
         userData?: Record<string, any>;
-    }): Promise<FITFileType>;
+    }): Promise<FITFileType | undefined>;
 }
 declare const _default: {
     FITDecoder: typeof FITDecoder;

package/dist/FIT/types.d.ts

@@ -34,7 +34,7 @@ export interface FileCreatorMesgType {
     softwareVersion?: number;
 }
 export interface EventMesgType {
-    timestamp?: string;
+    timestamp?: Date;
     data?: number;
     event?: string;
     eventType?: string;
@@ -79,65 +79,260 @@ export interface UserProfileMesgType {
     temperatureSetting?: string;
 }
 export interface SessionMesgType {
-    timestamp?: string;
-    startTime?: string;
+    messageIndex?: number;
+    timestamp: Date;
+    event: string;
+    eventType: string;
+    startTime: Date;
     startPositionLat?: number;
     startPositionLong?: number;
+    sport?: string;
+    subSport?: string;
     totalElapsedTime?: number;
     totalTimerTime?: number;
     totalDistance?: number;
     totalCycles?: number;
-    necLat?: number;
-    necLong?: number;
-    swcLat?: number;
-    swcLong?: number;
-    totalWork?: number;
-    messageIndex?: number;
+    totalStrides?: number;
+    totalStrokes?: number;
     totalCalories?: number;
     totalFatCalories?: number;
     avgSpeed?: number;
+    enhancedAvgSpeed?: number;
     maxSpeed?: number;
+    enhancedMaxSpeed?: number;
+    avgHeartRate?: number;
+    maxHeartRate?: number;
+    avgCadence?: number;
+    avgRunningCadence?: number;
+    maxCadence?: number;
+    maxRunningCadence?: number;
     avgPower?: number;
     maxPower?: number;
     totalAscent?: number;
     totalDescent?: number;
+    totalTrainingEffect?: number;
     firstLapIndex?: number;
     numLaps?: number;
+    eventGroup?: number;
+    trigger?: string;
+    necLat?: number;
+    necLong?: number;
+    swcLat?: number;
+    swcLong?: number;
+    numLengths?: number;
     normalizedPower?: number;
     trainingStressScore?: number;
     intensityFactor?: number;
+    leftRightBalance?: number;
+    endPositionLat?: number;
+    endPositionLong?: number;
+    avgStrokeCount?: number;
+    avgStrokeDistance?: number;
+    swimStroke?: string;
+    poolLength?: number;
     thresholdPower?: number;
-    event?: string;
-    eventType?: string;
-    sport?: string;
-    subActivity?: string;
-    avgCadence?: number;
-    maxCadence?: number;
-    trigger?: number;
-    totalStrokes?: number;
-    enhancedAvgSpeed?: number;
-    enhancedMaxSpeed?: number;
+    poolLengthUnit?: string;
+    numActiveLengths?: number;
+    totalWork?: number;
+    avgAltitude?: number;
+    enhancedAvgAltitude?: number;
+    maxAltitude?: number;
+    enhancedMaxAltitude?: number;
+    gpsAccuracy?: number;
+    avgGrade?: number;
+    avgPosGrade?: number;
+    avgNegGrade?: number;
+    maxPosGrade?: number;
+    maxNegGrade?: number;
+    avgTemperature?: number;
+    maxTemperature?: number;
+    minTemperature?: number;
+    totalMovingTime?: number;
+    avgPosVerticalSpeed?: number;
+    avgNegVerticalSpeed?: number;
+    maxPosVerticalSpeed?: number;
+    maxNegVerticalSpeed?: number;
+    minHeartRate?: number;
+    timeInHrZone?: number[];
+    timeInSpeedZone?: number[];
+    timeInCadenceZone?: number[];
+    timeInPowerZone?: number[];
+    avgLapTime?: number;
+    bestLapIndex?: number;
+    minAltitude?: number;
+    enhancedMinAltitude?: number;
+    playerScore?: number;
+    opponentScore?: number;
+    opponentName?: string;
+    strokeCount?: number[];
+    zoneCount?: number[];
+    maxBallSpeed?: number;
+    avgBallSpeed?: number;
+    avgVerticalOscillation?: number;
+    avgStanceTimePercent?: number;
+    avgStanceTime?: number;
+    avgFractionalCadence?: number;
+    maxFractionalCadence?: number;
+    totalFractionalCycles?: number;
+    avgTotalHemoglobinConc?: number;
+    minTotalHemoglobinConc?: number;
+    maxTotalHemoglobinConc?: number;
+    avgSaturatedHemoglobinPercent?: number;
+    minSaturatedHemoglobinPercent?: number;
+    maxSaturatedHemoglobinPercent?: number;
+    avgLeftTorqueEffectiveness?: number;
+    avgRightTorqueEffectiveness?: number;
+    avgLeftPedalSmoothness?: number;
+    avgRightPedalSmoothness?: number;
+    avgCombinedPedalSmoothness?: number;
+    sportProfileName?: string;
+    sportIndex?: number;
+    timeStanding?: number;
+    standCount?: number;
+    avgLeftPco?: number;
+    avgRightPco?: number;
+    avgLeftPowerPhase?: number[];
+    avgLeftPowerPhasePeak?: number[];
+    avgRightPowerPhase?: number[];
+    avgRightPowerPhasePeak?: number[];
+    avgPowerPosition?: number[];
+    maxPowerPosition?: number[];
+    avgCadencePosition?: number[];
+    maxCadencePosition?: number[];
+    avgLevMotorPower?: number;
+    maxLevMotorPower?: number;
+    levBatteryConsumption?: number;
+    avgVerticalRatio?: number;
+    avgStanceTimeBalance?: number;
+    avgStepLength?: number;
+    totalAnaerobicTrainingEffect?: number;
+    avgVam?: number;
+    avgDepth?: number;
+    maxDepth?: number;
+    surfaceInterval?: number;
+    startCns?: number;
+    endCns?: number;
+    startN2?: number;
+    endN2?: number;
+    avgRespirationRate?: number;
+    maxRespirationRate?: number;
+    minRespirationRate?: number;
+    enhancedAvgRespirationRate?: number;
+    enhancedMaxRespirationRate?: number;
+    enhancedMinRespirationRate?: number;
+    o2Toxicity?: number;
+    diveNumber?: number;
+    trainingLoadPeak?: number;
+    totalGrit?: number;
+    totalFlow?: number;
+    jumpCount?: number;
+    avgGrit?: number;
+    avgFlow?: number;
+    workoutFeel?: number;
+    workoutRpe?: number;
+    avgSpo2?: number;
+    avgStress?: number;
+    sdrrHrv?: number;
+    rmssdHrv?: number;
+    totalFractionalAscent?: number;
+    totalFractionalDescent?: number;
+    avgCoreTemperature?: number;
+    minCoreTemperature?: number;
+    maxCoreTemperature?: number;
     lapMesgs?: LapMesgType[];
 }
 export interface RecordMesgType {
-    timestamp?: string;
+    timestamp: Date;
     positionLat?: number;
     positionLong?: number;
     altitude?: number;
+    enhancedAltitude?: number;
+    heartRate?: number;
+    cadence?: number;
     distance?: number;
-    accumulatedPower?: number;
     speed?: number;
+    enhancedSpeed?: number;
     power?: number;
-    cadence?: number;
-    heartRate?: number;
+    compressedSpeedDistance?: Uint8Array;
+    grade?: number;
+    resistance?: number;
+    timeFromCourse?: number;
+    cycleLength?: number;
     temperature?: number;
-    enhancedAltitude?: number;
-    enhancedSpeed?: number;
-    [key: string]: number | string | undefined | any;
+    speed1s?: number;
+    cycles?: number;
+    totalCycles?: number;
+    compressedAccumulatedPower?: number;
+    accumulatedPower?: number;
+    leftRightBalance?: number;
+    gpsAccuracy?: number;
+    verticalSpeed?: number;
+    calories?: number;
+    verticalOscillation?: number;
+    stanceTimePercent?: number;
+    stanceTime?: number;
+    activityType?: string;
+    leftTorqueEffectiveness?: number;
+    rightTorqueEffectiveness?: number;
+    leftPedalSmoothness?: number;
+    rightPedalSmoothness?: number;
+    combinedPedalSmoothness?: number;
+    time128?: number;
+    strokeType?: string;
+    zone?: number;
+    ballSpeed?: number;
+    cadence256?: number;
+    fractionalCadence?: number;
+    totalHemoglobinConc?: number;
+    totalHemoglobinConcMin?: number;
+    totalHemoglobinConcMax?: number;
+    saturatedHemoglobinPercent?: number;
+    saturatedHemoglobinPercentMin?: number;
+    saturatedHemoglobinPercentMax?: number;
+    deviceIndex?: number;
+    leftPco?: number;
+    rightPco?: number;
+    leftPowerPhase?: number;
+    leftPowerPhasePeak?: number;
+    rightPowerPhase?: number;
+    rightPowerPhasePeak?: number;
+    batterySoc?: number;
+    motorPower?: number;
+    verticalRatio?: number;
+    stanceTimeBalance?: number;
+    stepLength?: number;
+    cycleLength16?: number;
+    absolutePressure?: number;
+    depth?: number;
+    nextStopDepth?: number;
+    nextStopTime?: number;
+    timeToSurface?: number;
+    ndlTime?: number;
+    cnsLoad?: number;
+    n2Load?: number;
+    respirationRate?: number;
+    enhancedRespirationRate?: number;
+    grit?: number;
+    flow?: number;
+    currentStress?: number;
+    ebikeTravelRange?: number;
+    ebikeBatteryLevel?: number;
+    ebikeAssistMode?: number;
+    ebikeAssistLevelPercent?: number;
+    airTimeRemaining?: number;
+    pressureSac?: number;
+    volumeSac?: number;
+    rmv?: number;
+    ascentRate?: number;
+    po2?: number;
+    coreTemperature?: number;
 }
 export interface LapMesgType {
-    timestamp?: string;
-    startTime?: string;
+    messageIndex: number;
+    timestamp?: Date;
+    event?: string;
+    eventType?: string;
+    startTime?: Date;
     startPositionLat?: number;
     startPositionLong?: number;
     endPositionLat?: number;
@@ -146,30 +341,124 @@ export interface LapMesgType {
     totalTimerTime?: number;
     totalDistance?: number;
     totalCycles?: number;
-    totalWork?: number;
-    messageIndex?: number;
+    totalStrides?: number;
+    totalStrokes?: number;
     totalCalories?: number;
     totalFatCalories?: number;
     avgSpeed?: number;
+    enhancedAvgSpeed?: number;
     maxSpeed?: number;
+    enhancedMaxSpeed?: number;
+    avgHeartRate?: number;
+    maxHeartRate?: number;
+    avgCadence?: number;
+    avgRunningCadence?: number;
+    maxCadence?: number;
+    maxRunningCadence?: number;
     avgPower?: number;
     maxPower?: number;
     totalAscent?: number;
     totalDescent?: number;
-    normalizedPower?: number;
-    event?: string;
-    eventType?: string;
-    avgCadence?: number;
-    maxCadence?: number;
+    intensity?: string;
     lapTrigger?: string;
     sport?: string;
-    totalStrokes?: number;
-    enhancedAvgSpeed?: number;
-    enhancedMaxSpeed?: number;
+    eventGroup?: number;
+    numLengths?: number;
+    normalizedPower?: number;
+    leftRightBalance?: number;
+    firstLengthIndex?: number;
+    avgStrokeDistance?: number;
+    swimStroke?: string;
+    subSport?: string;
+    numActiveLengths?: number;
+    totalWork?: number;
+    avgAltitude?: number;
+    enhancedAvgAltitude?: number;
+    maxAltitude?: number;
+    enhancedMaxAltitude?: number;
+    gpsAccuracy?: number;
+    avgGrade?: number;
+    avgPosGrade?: number;
+    avgNegGrade?: number;
+    maxPosGrade?: number;
+    maxNegGrade?: number;
+    avgTemperature?: number;
+    maxTemperature?: number;
+    totalMovingTime?: number;
+    avgPosVerticalSpeed?: number;
+    avgNegVerticalSpeed?: number;
+    maxPosVerticalSpeed?: number;
+    maxNegVerticalSpeed?: number;
+    minHeartRate?: number;
+    timeInHrZone?: number[];
+    timeInSpeedZone?: number[];
+    timeInCadenceZone?: number[];
+    timeInPowerZone?: number[];
+    repetitionNum?: number;
+    minAltitude?: number;
+    enhancedMinAltitude?: number;
+    wktStepIndex?: number;
+    opponentScore?: number;
+    strokeCount?: number[];
+    zoneCount?: number[];
+    avgVerticalOscillation?: number;
+    avgStanceTimePercent?: number;
+    avgStanceTime?: number;
+    avgFractionalCadence?: number;
+    maxFractionalCadence?: number;
+    totalFractionalCycles?: number;
+    playerScore?: number;
+    avgTotalHemoglobinConc?: number;
+    minTotalHemoglobinConc?: number;
+    maxTotalHemoglobinConc?: number;
+    avgSaturatedHemoglobinPercent?: number;
+    minSaturatedHemoglobinPercent?: number;
+    maxSaturatedHemoglobinPercent?: number;
+    avgLeftTorqueEffectiveness?: number;
+    avgRightTorqueEffectiveness?: number;
+    avgLeftPedalSmoothness?: number;
+    avgRightPedalSmoothness?: number;
+    avgCombinedPedalSmoothness?: number;
+    timeStanding?: number;
+    standCount?: number;
+    avgLeftPco?: number;
+    avgRightPco?: number;
+    avgLeftPowerPhase?: number[];
+    avgLeftPowerPhasePeak?: number[];
+    avgRightPowerPhase?: number[];
+    avgRightPowerPhasePeak?: number[];
+    avgPowerPosition?: number[];
+    maxPowerPosition?: number[];
+    avgCadencePosition?: number[];
+    maxCadencePosition?: number[];
+    avgLevMotorPower?: number;
+    maxLevMotorPower?: number;
+    levBatteryConsumption?: number;
+    avgVerticalRatio?: number;
+    avgStanceTimeBalance?: number;
+    avgStepLength?: number;
+    avgVam?: number;
+    avgDepth?: number;
+    maxDepth?: number;
+    minTemperature?: number;
+    enhancedAvgRespirationRate?: number;
+    enhancedMaxRespirationRate?: number;
+    avgRespirationRate?: number;
+    maxRespirationRate?: number;
+    totalGrit?: number;
+    totalFlow?: number;
+    jumpCount?: number;
+    avgGrit?: number;
+    avgFlow?: number;
+    totalFractionalAscent?: number;
+    totalFractionalDescent?: number;
+    avgCoreTemperature?: number;
+    minCoreTemperature?: number;
+    maxCoreTemperature?: number;
     recordMesgs?: RecordMesgType[];
 }
 export interface ActivityMesgType {
-    timestamp?: string;
+    timestamp?: Date;
     totalTimerTime?: number;
     numSessions?: number;
     type?: string;

package/dist/TrackSwap.d.ts

@@ -19,7 +19,7 @@ export declare class TrackSwap {
     parseGPXString(xmlString: string): Promise<GPX11Type | undefined>;
     encodeGPX(gpxData: GPX11Type): Promise<Buffer>;
     encodeGPXString(gpxData: GPX11Type): string;
-    parseFIT(buffer: Buffer): Promise<FITFileType>;
+    parseFIT(buffer: Buffer): Promise<FITFileType | undefined>;
     encodeFIT(fitData: FITFileType): Promise<Buffer>;
     encodeFITCourse(fitData: FITFileType): Promise<Buffer>;
     parseTCXString(xmlString: string): Promise<TCXFileType>;
@@ -34,8 +34,8 @@ export declare class TrackSwap {
     convertActivityToTCX(file: FileType): Promise<TCXFileType>;
     convertFile(sourceFile: Buffer, targetType: "gpx" | "fit" | "tcx", sourceType?: "gpx" | "fit" | "tcx"): Promise<Buffer>;
     detectFormat(buffer: Buffer): "gpx" | "fit" | "tcx" | "unknown";
-    parseFile(buffer: Buffer, sourceType?: "gpx" | "fit" | "tcx"): Promise<GPX11Type | FITFileType | TCXFileType>;
-    parseToActivity(buffer: Buffer, sourceType?: "gpx" | "fit" | "tcx"): Promise<FileType>;
+    parseFile(buffer: Buffer, sourceType?: "gpx" | "fit" | "tcx"): Promise<GPX11Type | FITFileType | TCXFileType | undefined>;
+    parseToActivity(buffer: Buffer, sourceType?: "gpx" | "fit" | "tcx"): Promise<FileType | undefined>;
     getActivityProcessor(): ActivityProcessor;
     getGPXDecoder(): GPXDecoder;
     getGPXEncoder(): GPXEncoder;