trackswap 0.0.14 → 0.0.16

package/README.md

@@ -13,7 +13,8 @@
 - 🔄 **多格式支持**: GPX 1.1、FIT、TCX 格式
 - 🎯 **统一转换**: 任意格式之间相互转换
 - 🤖 **自动检测**: 智能识别文件格式
-- 🔧 **插件架构**: 基于插件的可扩展设计
+- 🧩 **扩展系统**: 灵活的扩展架构，支持自定义数据处理
+- 📊 **智能聚合**: 默认启用运动数据聚合（心率、功率、速度等）
 - 🛡️ **类型安全**: 完整的 TypeScript 支持
 - ⚡ **高性能**: 优化的解析和编码算法
 
@@ -69,11 +70,35 @@ const convertedBuffer = await trackSwap.convertFile(
 const parsedData = await trackSwap.parseFile(buffer);
 
 // 🏃‍♂️ 解析并转换为统一的运动数据格式
-const sportData = await trackSwap.parseToSport(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 文件处理
@@ -140,14 +165,14 @@ const result = await trackSwap.convertFile(sourceBuffer, 'fit', 'gpx');
 
 ```typescript
 // 转换为统一的运动数据格式
-const gpxSport = await trackSwap.convertGPXToSport(gpxData);
-const fitSport = await trackSwap.convertFITToSport(fitData);
-const tcxSport = await trackSwap.convertTCXToSport(tcxData);
+const gpxActivity = await trackSwap.convertGPXToActivity(gpxData);
+const fitActivity = await trackSwap.convertFITToActivity(fitData);
+const tcxActivity = await trackSwap.convertTCXToActivity(tcxData);
 
 // 从统一格式转换回具体格式
-const gpxData = await trackSwap.convertSportToGPX(sportData);
-const fitData = await trackSwap.convertSportToFIT(sportData);
-const tcxData = await trackSwap.convertSportToTCX(sportData);
+const gpxData = await trackSwap.convertActivityToGPX(sportData);
+const fitData = await trackSwap.convertActivityToFIT(sportData);
+const tcxData = await trackSwap.convertActivityToTCX(sportData);
 ```
 
 ### 3. 智能解析
@@ -162,8 +187,8 @@ const parsedData = await trackSwap.parseFile(buffer);
 const parsedData = await trackSwap.parseFile(buffer, 'gpx'); // 指定格式
 
 // 🏃‍♂️ 解析为统一格式
-const sportData = await trackSwap.parseToSport(buffer);
-const sportData = await trackSwap.parseToSport(buffer, 'fit'); // 指定格式
+const sportData = await trackSwap.parseToActivity(buffer);
+const sportData = await trackSwap.parseToActivity(buffer, 'fit'); // 指定格式
 ```
 
 ## 🔧 API 参考
@@ -180,7 +205,7 @@ const sportData = await trackSwap.parseToSport(buffer, 'fit'); // 指定格式
 | `parseTCX(buffer)` | 解析 TCX Buffer | `Buffer` | `Promise<TCXFileType>` |
 | `parseTCXString(xml)` | 解析 TCX 字符串 | `string` | `Promise<TCXFileType>` |
 | `parseFile(buffer, type?)` | 统一解析方法 | `Buffer, string?` | `Promise<GPX11Type \| FITFileType \| TCXFileType>` |
-| `parseToSport(buffer, type?)` | 解析为统一格式 | `Buffer, string?` | `Promise<ActivityType>` |
+| `parseToActivity(buffer, type?)` | 解析为统一格式 | `Buffer, string?` | `Promise<ActivityType>` |
 
 #### 编码方法
 
@@ -198,19 +223,19 @@ const sportData = await trackSwap.parseToSport(buffer, 'fit'); // 指定格式
 | 方法 | 说明 | 参数 | 返回值 |
 |------|------|------|--------|
 | `convertFile(buffer, target, source?)` | 统一转换方法 | `Buffer, string, string?` | `Promise<Buffer>` |
-| `convertGPXToSport(data)` | GPX → Sport | `GPX11Type` | `Promise<ActivityType>` |
-| `convertFITToSport(data)` | FIT → Sport | `FITFileType` | `Promise<ActivityType>` |
-| `convertTCXToSport(data)` | TCX → Sport | `TCXFileType` | `Promise<ActivityType>` |
-| `convertSportToGPX(data)` | Sport → GPX | `ActivityType` | `Promise<GPX11Type>` |
-| `convertSportToFIT(data)` | Sport → FIT | `ActivityType` | `Promise<FITFileType>` |
-| `convertSportToTCX(data)` | Sport → TCX | `ActivityType` | `Promise<TCXFileType>` |
+| `convertGPXToActivity(data)` | GPX → Activity | `GPX11Type` | `Promise<ActivityType>` |
+| `convertFITToActivity(data)` | FIT → Activity | `FITFileType` | `Promise<ActivityType>` |
+| `convertTCXToActivity(data)` | TCX → Activity | `TCXFileType` | `Promise<ActivityType>` |
+| `convertActivityToGPX(data)` | Activity → GPX | `ActivityType` | `Promise<GPX11Type>` |
+| `convertActivityToFIT(data)` | Activity → FIT | `ActivityType` | `Promise<FITFileType>` |
+| `convertActivityToTCX(data)` | Activity → TCX | `ActivityType` | `Promise<TCXFileType>` |
 
 #### 工具方法
 
 | 方法 | 说明 | 参数 | 返回值 |
 |------|------|------|--------|
 | `detectFormat(buffer)` | 检测文件格式 | `Buffer` | `'gpx' \| 'fit' \| 'tcx' \| 'unknown'` |
-| `getSportProcessor()` | 获取运动处理器 | - | `SportProcessor` |
+| `getActivityProcessor()` | 获取运动处理器 | - | `ActivityProcessor` |
 | `destroy()` | 清理资源 | - | `Promise<void>` |
 
 ## 🌟 实际应用示例
@@ -262,7 +287,7 @@ async function analyzeTrack(buffer: Buffer) {
   console.log(`文件格式: ${format}`);
   
   // 📊 转换为统一格式进行分析
-  const sportData = await trackSwap.parseToSport(buffer);
+  const sportData = await trackSwap.parseToActivity(buffer);
   
   // 分析数据
   const analysis = {
@@ -285,27 +310,27 @@ async function analyzeTrack(buffer: Buffer) {
 ```typescript
 async function mergeMultiFormatTracks(files: { buffer: Buffer, name: string }[]) {
   const trackSwap = new TrackSwap();
-  const allSportData: ActivityType[] = [];
+  const allActivityData: ActivityType[] = [];
   
   // 🔄 将所有格式转换为统一格式
   for (const file of files) {
     try {
-      const sportData = await trackSwap.parseToSport(file.buffer);
+      const sportData = await trackSwap.parseToActivity(file.buffer);
       sportData.metadata = { ...sportData.metadata, originalFile: file.name };
-      allSportData.push(sportData);
+      allActivityData.push(sportData);
     } catch (error) {
       console.error(`解析失败: ${file.name}`, error);
     }
   }
   
   // 融合数据逻辑
-  const mergedData = mergeSportData(allSportData);
+  const mergedData = mergeActivityData(allActivityData);
   
   // 输出为不同格式
   const results = {
-    gpx: await trackSwap.convertSportToGPX(mergedData),
-    fit: await trackSwap.convertSportToFIT(mergedData),
-    tcx: await trackSwap.convertSportToTCX(mergedData)
+    gpx: await trackSwap.convertActivityToGPX(mergedData),
+    fit: await trackSwap.convertActivityToFIT(mergedData),
+    tcx: await trackSwap.convertActivityToTCX(mergedData)
   };
   
   await trackSwap.destroy();
@@ -327,17 +352,17 @@ TrackSwap 采用模块化架构，核心组件包括：
 │  │ • GPXDecoder/Encoder - GPX 文件处理                     │ │
 │  │ • FITDecoder/Encoder - FIT 文件处理                     │ │
 │  │ • TCXDecoder/Encoder - TCX 文件处理                     │ │
-│  │ • SportProcessor - 统一格式转换处理                      │ │
+│  │ • ActivityProcessor - 统一格式转换处理                      │ │
 │  └─────────────────────────────────────────────────────────┘ │
 │                                                             │
 │  🔄 转换引擎                                                │
 │  ┌─────────────────────────────────────────────────────────┐ │
-│  │ • GPXToSportConverter - GPX → ActivityType            │ │
-│  │ • FITToSportConverter - FIT → ActivityType            │ │
-│  │ • TCXToSportConverter - TCX → ActivityType            │ │
-│  │ • SportToGPXEncoder - ActivityType → GPX              │ │
-│  │ • SportToFITEncoder - ActivityType → FIT              │ │
-│  │ • SportToTCXEncoder - ActivityType → TCX              │ │
+│  │ • GPXToActivityConverter - GPX → ActivityType            │ │
+│  │ • FITToActivityConverter - FIT → ActivityType            │ │
+│  │ • TCXToActivityConverter - TCX → ActivityType            │ │
+│  │ • ActivityToGPXEncoder - ActivityType → GPX              │ │
+│  │ • ActivityToFITEncoder - ActivityType → FIT              │ │
+│  │ • ActivityToTCXEncoder - ActivityType → TCX              │ │
 │  └─────────────────────────────────────────────────────────┘ │
 │                                                             │
 │  🎯 统一接口                                                │
@@ -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/encoder.d.ts

@@ -1,8 +1,8 @@
 import { FITFileType } from "./types.js";
 export interface FITEncoderOptions {
     compact?: boolean;
-    defaultSport?: string;
-    defaultSubSport?: string;
+    defaultActivity?: string;
+    defaultSubActivity?: string;
 }
 export declare class FITEncoder {
     private localNum;

package/dist/FIT/types/sport.d.ts

@@ -1,4 +1,4 @@
-export declare enum Sport {
+export declare enum Activity {
     GENERIC = 0,
     RUNNING = 1,
     CYCLING = 2,

package/dist/FIT/types.d.ts

@@ -110,7 +110,7 @@ export interface SessionMesgType {
     event?: string;
     eventType?: string;
     sport?: string;
-    subSport?: string;
+    subActivity?: string;
     avgCadence?: number;
     maxCadence?: number;
     trigger?: number;

package/dist/TCX/converters.d.ts

@@ -1,6 +1,6 @@
 import { TokenAST } from "../types.js";
 import { BaseTCXConverter } from "./base.js";
-import { TCXContext, ActivityType, ActivityLapType, TrackType, TrackpointType, PositionType, ActivityListType, MultiSportSessionType, AbstractSourceType } from "./types.js";
+import { TCXContext, ActivityType, ActivityLapType, TrackType, TrackpointType, PositionType, ActivityListType, MultiActivitySessionType, AbstractSourceType } from "./types.js";
 export declare class PositionConverter extends BaseTCXConverter {
     name: string;
     supportedTags: string[];
@@ -33,10 +33,10 @@ export declare class ActivityListConverter extends BaseTCXConverter {
     supportedTags: string[];
     convert(ast: TokenAST, context: TCXContext): ActivityListType | undefined;
 }
-export declare class MultiSportSessionConverter extends BaseTCXConverter {
+export declare class MultiActivitySessionConverter extends BaseTCXConverter {
     name: string;
     supportedTags: string[];
-    convert(ast: TokenAST, context: TCXContext): MultiSportSessionType | undefined;
+    convert(ast: TokenAST, context: TCXContext): MultiActivitySessionType | undefined;
 }
 export declare class AbstractSourceConverter extends BaseTCXConverter {
     name: string;

package/dist/TCX/encoder.d.ts

@@ -20,9 +20,9 @@ export declare class TCXEncoder {
     private buildTrackpoint;
     private buildPosition;
     private buildCadence;
-    private buildMultiSportSession;
-    private buildFirstSport;
-    private buildNextSport;
+    private buildMultiActivitySession;
+    private buildFirstActivity;
+    private buildNextActivity;
     private buildWorkouts;
     private buildCourses;
     private buildAuthor;

package/dist/TCX/types.d.ts

@@ -75,7 +75,7 @@ export interface HistoryType {
     Running?: HistoryFolderType;
     Biking?: HistoryFolderType;
     Other?: HistoryFolderType;
-    MultiSport?: HistoryFolderType;
+    MultiActivity?: HistoryFolderType;
     Extensions?: ExtensionsType;
 }
 export interface HistoryFolderType {
@@ -94,10 +94,10 @@ export interface WeekType {
 }
 export interface ActivityListType {
     Activity?: ActivityType[];
-    MultiSportSession?: MultiSportSessionType[];
+    MultiActivitySession?: MultiActivitySessionType[];
 }
 export interface ActivityType {
-    Sport?: "Other" | "Running" | "Biking";
+    Activity?: "Other" | "Running" | "Biking";
     Id: string;
     Lap: ActivityLapType[];
     Notes?: string;
@@ -144,16 +144,16 @@ export interface CadenceType {
 export interface HeartRateInBeatsPerMinuteType {
     Value: number;
 }
-export interface MultiSportSessionType {
+export interface MultiActivitySessionType {
     Id?: string;
-    FirstSport?: FirstSportType;
-    NextSport?: NextSportType[];
+    FirstActivity?: FirstActivityType;
+    NextActivity?: NextActivityType[];
     Notes?: string;
 }
-export interface FirstSportType {
+export interface FirstActivityType {
     Activity?: ActivityType;
 }
-export interface NextSportType {
+export interface NextActivityType {
     Transition?: ActivityLapType;
     Activity?: ActivityType;
 }

package/dist/TrackSwap.d.ts

@@ -4,8 +4,9 @@ import { FITDecoder, FITEncoder } from "./FIT/index.js";
 import { FITFileType } from "./FIT/types.js";
 import { TCXDecoder, TCXEncoder } from "./TCX/index.js";
 import { TCXFileType } from "./TCX/types.js";
-import { SportProcessor } from "./sport/processor.js";
-import { ActivityType } from "./types.js";
+import { ActivityProcessor } from "./activity/processor.js";
+import { FileType } from "./types.js";
+import { TrackSwapExtension } from "./activity/extensions/extensions.js";
 export declare class TrackSwap {
     private gpxDecoder;
     private gpxEncoder;
@@ -13,7 +14,8 @@ export declare class TrackSwap {
     private fitEncoder;
     private tcxDecoder;
     private tcxEncoder;
-    private sportProcessor;
+    private activityProcessor;
+    private extensionManager;
     constructor();
     parseGPX(buffer: Buffer): Promise<GPX11Type | undefined>;
     parseGPXString(xmlString: string): Promise<GPX11Type | undefined>;
@@ -22,27 +24,31 @@ export declare class TrackSwap {
     parseFIT(buffer: Buffer): Promise<FITFileType>;
     encodeFIT(fitData: FITFileType): Promise<Buffer>;
     encodeFITCourse(fitData: FITFileType): Promise<Buffer>;
-    parseTCX(buffer: Buffer): Promise<TCXFileType>;
     parseTCXString(xmlString: string): Promise<TCXFileType>;
+    parseTCX(buffer: Buffer): Promise<TCXFileType>;
     encodeTCX(tcxData: TCXFileType): Promise<Buffer>;
     encodeTCXString(tcxData: TCXFileType): Promise<string>;
-    convertGPXToSport(gpxData: GPX11Type): Promise<ActivityType>;
-    convertFITToSport(fitData: FITFileType): Promise<ActivityType>;
-    convertTCXToSport(tcxData: TCXFileType): Promise<ActivityType>;
-    convertSportToGPX(sportData: ActivityType): Promise<GPX11Type>;
-    convertSportToFIT(sportData: ActivityType): Promise<FITFileType>;
-    convertSportToTCX(sportData: ActivityType): Promise<TCXFileType>;
+    convertGPXToActivity(gpxData: GPX11Type): Promise<FileType>;
+    convertFITToActivity(fitData: FITFileType): Promise<FileType>;
+    convertTCXToActivity(tcxData: TCXFileType): Promise<FileType>;
+    convertActivityToGPX(file: FileType): Promise<GPX11Type>;
+    convertActivityToFIT(file: FileType): Promise<FITFileType>;
+    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>;
-    parseToSport(buffer: Buffer, sourceType?: "gpx" | "fit" | "tcx"): Promise<ActivityType>;
-    getSportProcessor(): SportProcessor;
+    parseToActivity(buffer: Buffer, sourceType?: "gpx" | "fit" | "tcx"): Promise<FileType>;
+    getActivityProcessor(): ActivityProcessor;
     getGPXDecoder(): GPXDecoder;
     getGPXEncoder(): GPXEncoder;
     getFITDecoder(): FITDecoder;
     getFITEncoder(): FITEncoder;
     getTCXDecoder(): TCXDecoder;
     getTCXEncoder(): TCXEncoder;
+    extend(extension: TrackSwapExtension): TrackSwap;
+    removeExtension(extensionName: string): TrackSwap;
+    getExtensions(): TrackSwapExtension[];
+    processWithExtensions(file: FileType): FileType;
     destroy(): Promise<void>;
 }
 export default TrackSwap;