trackswap 0.2.3 → 0.2.5

package/dist/activity/converters.d.ts

@@ -4,37 +4,94 @@ import { ActivityRecordType } from "../types.js";
 import { WptType } from "../GPX/types.js";
 import { RecordMesgType } from "../FIT/types.js";
 import { TrackpointType } from "../TCX/types.js";
+/**
+ * GPX to Activity converter
+ */
 export declare class GPXToActivityConverter extends BaseActivityConverter {
     name: string;
     supportedTags: string[];
     convert(ast: TokenAST, context: ActivityContext): FileType | undefined;
     private convertGPX;
+    /**
+     * 将 Wpt 转为 ActivityRecordType
+     * @param point
+     * @param idx
+     * @returns
+     */
     protected convertPoint(point: WptType, idx?: number, lapIdx?: number): ActivityRecordType;
+    /**
+     * 将 trk 转为 Activity
+     * @param trk
+     * @param idx
+     * @returns
+     */
     private convertTrk2Activity;
+    /**
+     * 将 trkseg 转为 lap
+     * @param seg
+     * @param idx
+     * @returns
+     */
     private convertTrackSeg2Lap;
     private convertRoute2Lap;
     private convertPoints2Lap;
+    /**
+     * 将 GPX 的 wpt[] 转为 ActivityRecordType 数组
+     * @param wpts
+     * @returns
+     */
     private convertWpts2Points;
     private convertGPXExtensions;
     private autoNumber;
 }
+/**
+ * FIT to ActivityType converter
+ */
 export declare class FITToActivityConverter extends BaseActivityConverter {
     name: string;
     supportedTags: string[];
     convert(ast: TokenAST, context: ActivityContext): FileType | undefined;
     private convertFIT;
+    private convertFITStrengthSets;
+    /**
+     * 将 FIT 的 recordMesg 转为 ActivityRecordType
+     * @param point
+     * @param idx
+     * @returns
+     */
     protected convertPoint(point: RecordMesgType, idx?: number, lapIdx?: number): ActivityRecordType | undefined;
+    /**
+     *
+     * @param laps
+     * @returns
+     */
     private convertFITLap2Trackseg;
     private convertLap2Points;
 }
+/**
+ * TCX to ActivityType converter
+ */
 export declare class TCXToActivityConverter extends BaseActivityConverter {
     name: string;
     supportedTags: string[];
     convert(ast: TokenAST, context: ActivityContext): FileType | undefined;
     private convertTCX;
+    /**
+     * TCX Course → FileType.routes（每条 Course 对应一条 route lap）
+     */
     private convertTCXCourseToRoute;
     private convertTCXCoursePointToRecord;
+    /**
+     * 将 tcx 的 activity 转为 ActivityType
+     * @param activity
+     */
     private convertTCXActivityToActivity;
+    /**
+     * 将 TCX Lap 转为 ActivityLapType
+     * @param lap
+     * @param idx
+     * @returns
+     */
     private convertTCXLap2Lap;
     protected convertPoint(point: TrackpointType, idx?: number, lapIdx?: number): ActivityRecordType;
 }

package/dist/activity/encoders.d.ts

@@ -3,32 +3,66 @@ import { FileType } from "../types.js";
 import { GPX11Type } from "../GPX/types.js";
 import { FITFileType } from "../FIT/types.js";
 import { TCXFileType } from "../TCX/types.js";
+/**
+ * ActivityType to GPX encoder
+ */
 export declare class ActivityToGPXEncoder extends BaseActivityEncoder {
     name: string;
     supportedTags: string[];
     encode(file: FileType, context: ActivityEncodingContext): GPX11Type | undefined;
+    /** GPX trkpt/wpt/rtept require finite coordinates in range. */
     private hasValidGpxCoordinates;
+    /** Count sample rows that have no usable lat/lon for GPX geometry. */
     private countRecordsMissingGpxCoordinates;
+    /**
+     * 将 ActivityPoint 转为 GPX 的 WPT Type 与 GPX1.1 映射
+     * @param points
+     * @return gpx
+     */
     private convertRecords2Wpts;
     private convertRoute2GPXRoute;
+    /**
+     * 转换 ActivityType 到 GPX TrkType
+     * @param track
+     * @returns
+     */
     private convertActivity2GPXTrack;
+    /**
+     *
+     * @param point
+     * @returns
+     */
     private extractGPXExtensions;
 }
+/**
+ * ActivityType to FIT encoder
+ */
 export declare class ActivityToFITEncoder extends BaseActivityEncoder {
     name: string;
     supportedTags: string[];
     encode(file: FileType, context: ActivityEncodingContext): FITFileType | undefined;
+    /**
+     * 仅含路线（无 session 活动）时，合成单 session + 多 lap，供活动型 FIT 编码器写入。
+     */
     private convertRoutesToSyntheticSession;
     private convertActivity2FITSession;
     private convertLap2FITLap;
     private convertPoint2FITRecord;
 }
+/**
+ * ActivityType to TCX encoder
+ */
 export declare class ActivityToTCXEncoder extends BaseActivityEncoder {
     name: string;
     supportedTags: string[];
     encode(file: FileType, context: ActivityEncodingContext): TCXFileType | undefined;
     private convertActivity2TCXActivity;
     private convertLap2TCXLap;
+    /**
+     * 将 ActivityPoint 转为 TCX TrackpointType
+     * @param records
+     * @returns
+     */
     private convertRecords2TCXTrack;
     private convertPoint2TCXTrackpoint;
     private validTimestamp;

package/dist/activity/metrics/MetricsCalculator.d.ts

@@ -1,4 +1,7 @@
 import { ActivityType, ActivityLapType, ActivityRecordType } from "../../types.js";
+/**
+ * 指标计算结果接口
+ */
 interface MetricsRecordsResult extends Partial<ActivityLapType> {
     records: ActivityRecordType[];
 }
@@ -7,12 +10,39 @@ interface MetricsLapsResult extends Partial<ActivityType> {
     laps: ActivityLapType[];
 }
 export declare class MetricsAggregator {
+    /**
+     * record 数据聚合计算器 将 record 通过计算后输出
+     */
     calculateRecordsAggMetrics(records: ActivityRecordType[]): MetricsRecordsResult | undefined;
+    /**
+     * 将 laps 数据聚合起来，返回给 Activity
+     * @param laps
+     * @returns
+     */
     calculateLapAggMetrics(laps: ActivityLapType[]): MetricsLapsResult | undefined;
+    /**
+     * 对 record 数据进行预处理
+     * 由于 record 数据来自 FIT、TCX、GPX 可能存在缺失、异常等问题，所以需要提前对数据进行清洗和补全
+     */
     private preprocessRecords;
+    /**
+     * 计算两点间距离（使用 geolib 的高精度算法）
+     * @param prevPoint 前一个点
+     * @param currPoint 当前点
+     * @returns 距离（米），如果无法计算则返回 undefined
+     */
     private calculatePointDistanceByPosition;
+    /**
+     * 计算瞬时速度
+     */
     private calculateInstantSpeed;
+    /**
+     * 计算累计功率（功）
+     */
     private calculateAccumulatedPower;
+    /**
+     * 计算两点爬升和下降
+     */
     private calculateElevationChanges;
 }
 export {};

package/dist/activity/processor.d.ts

@@ -3,17 +3,48 @@ import { FileType } from "../types.js";
 import { GPX11Type } from "../GPX/types.js";
 import { FITFileType } from "../FIT/types.js";
 import { TCXFileType } from "../TCX/types.js";
+/**
+ * Activity processor
+ * Responsible for managing conversion and encoding processes
+ */
 export declare class ActivityProcessor {
     private converters;
     private encoders;
     constructor();
+    /**
+     * Register default converters
+     */
     private registerDefaultConverters;
+    /**
+     * Register default encoders
+     */
     private registerDefaultEncoders;
+    /**
+     * Register converter
+     */
     registerConverter(converter: IActivityConverterPlugin): void;
+    /**
+     * Register encoder
+     */
     registerEncoder(encoder: IActivityEncoderPlugin): void;
+    /**
+     * Convert native format to FileType
+     */
     convertToActivity(sourceData: GPX11Type | FITFileType | TCXFileType, sourceFormat: "gpx" | "fit" | "tcx"): Promise<FileType>;
+    /**
+     * Encode ActivityType to native format
+     */
     encodeActivity(file: FileType, targetFormat: "gpx" | "fit" | "tcx"): Promise<GPX11Type | FITFileType | TCXFileType>;
+    /**
+     * Find converter
+     */
     private findConverter;
+    /**
+     * Find encoder
+     */
     private findEncoder;
+    /**
+     * Destroy processor, clean up resources
+     */
     destroy(): Promise<void>;
 }

package/dist/core/base.d.ts

@@ -1,39 +1,76 @@
 import { ExtensionsType, Token, TokenAST } from "../types.js";
+/**
+ * Generic plugin interface
+ */
 export interface IPlugin<TContext = any> {
+    /** Plugin name */
     name: string;
+    /** Plugin version */
     version?: string;
+    /** Plugin description */
     description?: string;
+    /** Dependencies on other plugins */
     dependencies?: string[];
+    /** Supported tags */
     supportedTags?: string[];
+    /** Plugin initialization */
     initialize?(context: TContext): Promise<void> | void;
+    /** Plugin destruction */
     destroy?(context: TContext): Promise<void> | void;
+    /** Plugin validation */
     validate?(context: TContext): Promise<boolean> | boolean;
 }
+/**
+ * Generic converter plugin interface
+ */
 export interface IConverterPlugin<TContext = any> extends IPlugin<TContext> {
+    /** Conversion method */
     convert(ast: TokenAST, context: TContext): any | undefined;
+    /** Whether it supports the tag */
     supports(tag: string): boolean;
+    /** Priority (lower number = higher priority) */
     priority?: number;
 }
+/**
+ * Generic middleware plugin interface
+ */
 export interface IMiddlewarePlugin<TContext = any, TResult = any> extends IPlugin<TContext> {
+    /** Priority (lower number = higher priority) */
     priority?: number;
+    /** Execute during tokenize stage */
     onTokenize?(tokens: Token[], context: TContext): Promise<Token[]> | Token[];
+    /** Execute during AST generation stage */
     onAstGenerate?(ast: TokenAST, context: TContext): Promise<TokenAST> | TokenAST;
+    /** Execute during conversion stage */
     onConvert?(result: any, context: TContext): Promise<any> | any;
+    /** Execute during completion stage */
     onComplete?(result: TResult, context: TContext): Promise<TResult> | TResult;
+    /** Error handling */
     onError?(error: Error, context: TContext): Promise<void> | void;
 }
+/**
+ * Generic processing context
+ */
 export interface IProcessingContext {
+    /** Metadata storage */
     metadata: Map<string, any>;
+    /** Error list */
     errors: Error[];
+    /** Warning list */
     warnings: string[];
+    /** Processing statistics */
     stats: {
         startTime: number;
         endTime?: number;
         processedTokens: number;
         convertedElements: number;
     };
+    /** User-defined data */
     userData?: Record<string, any>;
 }
+/**
+ * Generic base converter abstract class
+ */
 export declare abstract class BaseConverter<TContext extends IProcessingContext = IProcessingContext> implements IConverterPlugin<TContext> {
     abstract name: string;
     abstract supportedTags: string[];
@@ -55,9 +92,18 @@ export declare abstract class BaseConverter<TContext extends IProcessingContext
     protected getChildValue(ast: TokenAST, tag: string): string | undefined;
     protected getChildByTag(ast: TokenAST, tag: string): TokenAST | undefined;
     protected getChildrenByTag(ast: TokenAST, tag: string): TokenAST[];
+    /**
+     * Generic Extensions processing method
+     */
     protected convertExtensions(extensionsAST: TokenAST): ExtensionsType;
+    /**
+     * Recursively convert Extensions content
+     */
     protected convertExtensionContent(extension: TokenAST): any;
 }
+/**
+ * Generic base middleware abstract class
+ */
 export declare abstract class BaseMiddleware<TContext extends IProcessingContext = IProcessingContext, TResult = any> implements IMiddlewarePlugin<TContext, TResult> {
     abstract name: string;
     version: string;

package/dist/core/builtin-adapters.d.ts

@@ -5,6 +5,7 @@ import { ActivityProcessor } from "../activity/processor.js";
 import type { AdapterDecodeResult, FITCourseAdapter, TrackFormatAdapter } from "./format-adapter.js";
 import type { DecodeOptions, TrackFormat } from "../document.js";
 import type { FileType } from "../types.js";
+export declare function assertFITActivityRecordParity(native: FITFileType, activity: FileType | undefined): void;
 export declare function detectBuiltInFormat(input: Buffer): TrackFormat | undefined;
 declare abstract class BuiltInAdapter<TNative> implements TrackFormatAdapter<TNative> {
     abstract readonly format: TrackFormat;

package/dist/core/xml-utils.d.ts

@@ -1,17 +1,41 @@
 import { Token } from "../types.js";
+/**
+ * XML parsing utility class
+ */
 export declare class XMLUtils {
+    /**
+     * Convert XML content to Token array
+     */
     static tokenizeXML(xmlContent: string): Token[];
+    /**
+     * Compress XML string (remove extra whitespace)
+     */
     static compressXML(xmlContent: string): string;
+    /**
+     * Format XML string (add indentation)
+     */
     static formatXML(xmlContent: string, indentSize?: number): string;
+    /**
+     * Validate XML format
+     */
     static validateXML(xmlContent: string): {
         isValid: boolean;
         error?: string;
     };
+    /**
+     * Extract XML declaration information
+     */
     static extractXMLDeclaration(xmlContent: string): {
         version?: string;
         encoding?: string;
         standalone?: string;
     };
+    /**
+     * Escape XML special characters
+     */
     static escapeXML(text: string): string;
+    /**
+     * Unescape XML special characters
+     */
     static unescapeXML(text: string): string;
 }

package/dist/errors.d.ts

@@ -1,5 +1,5 @@
 import type { TrackFormat } from "./document.js";
-export type TrackSwapErrorCode = "FORMAT_UNKNOWN" | "FORMAT_UNSUPPORTED" | "DECODE_FAILED" | "ACTIVITY_NOT_FOUND" | "ENCODE_FAILED" | "ADAPTER_CONFLICT" | "DISPOSED";
+export type TrackSwapErrorCode = "FORMAT_UNKNOWN" | "FORMAT_UNSUPPORTED" | "DECODE_FAILED" | "FIT_ACTIVITY_DATA_LOSS" | "ACTIVITY_NOT_FOUND" | "ENCODE_FAILED" | "ADAPTER_CONFLICT" | "DISPOSED";
 export declare class TrackSwapError extends Error {
     readonly code: TrackSwapErrorCode;
     readonly format?: TrackFormat;

package/dist/fit-debug.d.ts

@@ -1,3 +1,6 @@
+/**
+ * FIT pipeline verbose logging (disabled unless TRACKSWAP_FIT_DEBUG=1 or TRACKSWAP_DEBUG=1).
+ */
 export declare function fitDebugEnabled(): boolean;
 export declare function fitDebugLog(...args: unknown[]): void;
 export declare function fitDebugWarn(...args: unknown[]): void;