trackswap 0.2.3 → 0.2.4

package/dist/TCX/base.d.ts

@@ -1,19 +1,52 @@
 import { IPlugin, IConverterPlugin, IMiddlewarePlugin, BaseConverter, BaseMiddleware } from "../core/base.js";
 import { TCXContext, TCXFileType } from "./types.js";
+/**
+ * TCX plugin interface (inherits generic plugin interface)
+ */
 export interface ITCXPlugin extends IPlugin<TCXContext> {
 }
+/**
+ * TCX converter plugin interface (inherits generic converter interface)
+ */
 export interface ITCXConverterPlugin extends IConverterPlugin<TCXContext> {
 }
+/**
+ * TCX middleware plugin interface (inherits generic middleware interface)
+ */
 export interface ITCXMiddlewarePlugin extends IMiddlewarePlugin<TCXContext, TCXFileType> {
 }
+/**
+ * TCX base converter abstract class (inherits generic base converter)
+ */
 export declare abstract class BaseTCXConverter extends BaseConverter<TCXContext> implements ITCXConverterPlugin {
+    /**
+     * Parse TCX heart rate value
+     */
     protected parseHeartRate(value: string | number | undefined): number | undefined;
+    /**
+     * Parse TCX time format (ISO 8601)
+     */
     protected parseTCXTime(value: string | undefined): Date | undefined;
+    /**
+     * Parse TCX distance value (meters)
+     */
     protected parseDistance(value: string | number | undefined): number | undefined;
+    /**
+     * Parse TCX speed value (m/s)
+     */
     protected parseSpeed(value: string | number | undefined): number | undefined;
+    /**
+     * Parse TCX altitude value (meters)
+     */
     protected parseAltitude(value: string | number | undefined): number | undefined;
+    /**
+     * Parse TCX coordinate value (latitude/longitude)
+     */
     protected parseCoordinate(value: string | number | undefined): number | undefined;
 }
+/**
+ * TCX base middleware abstract class (inherits generic base middleware)
+ */
 export declare abstract class BaseTCXMiddleware extends BaseMiddleware<TCXContext, TCXFileType> implements ITCXMiddlewarePlugin {
     onError(error: Error, context: TCXContext): Promise<void>;
 }

package/dist/TCX/converters.d.ts

@@ -1,26 +1,41 @@
 import { TokenAST } from "../types.js";
 import { BaseTCXConverter } from "./base.js";
 import { TCXContext, ActivityType, ActivityLapType, TrackType, TrackpointType, PositionType, ActivityListType, MultiActivitySessionType, AbstractSourceType } from "./types.js";
+/**
+ * Position converter
+ */
 export declare class PositionConverter extends BaseTCXConverter {
     name: string;
     supportedTags: string[];
     convert(ast: TokenAST, context: TCXContext): PositionType | undefined;
 }
+/**
+ * Trackpoint converter
+ */
 export declare class TrackpointConverter extends BaseTCXConverter {
     name: string;
     supportedTags: string[];
     convert(ast: TokenAST, context: TCXContext): TrackpointType | undefined;
 }
+/**
+ * Track converter
+ */
 export declare class TrackConverter extends BaseTCXConverter {
     name: string;
     supportedTags: string[];
     convert(ast: TokenAST, context: TCXContext): TrackType | undefined;
 }
+/**
+ * Activity lap converter
+ */
 export declare class ActivityLapConverter extends BaseTCXConverter {
     name: string;
     supportedTags: string[];
     convert(ast: TokenAST, context: TCXContext): ActivityLapType | undefined;
 }
+/**
+ * Activity converter
+ */
 export declare class ActivityConverter extends BaseTCXConverter {
     name: string;
     supportedTags: string[];
@@ -28,25 +43,43 @@ export declare class ActivityConverter extends BaseTCXConverter {
     private convertTraining;
     private convertCreator;
 }
+/**
+ * Activity list converter
+ */
 export declare class ActivityListConverter extends BaseTCXConverter {
     name: string;
     supportedTags: string[];
     convert(ast: TokenAST, context: TCXContext): ActivityListType | undefined;
 }
+/**
+ * Multi-sport session converter
+ */
 export declare class MultiActivitySessionConverter extends BaseTCXConverter {
     name: string;
     supportedTags: string[];
     convert(ast: TokenAST, context: TCXContext): MultiActivitySessionType | undefined;
 }
+/**
+ * Abstract source converter
+ */
 export declare class AbstractSourceConverter extends BaseTCXConverter {
     name: string;
     supportedTags: string[];
     convert(ast: TokenAST, context: TCXContext): AbstractSourceType | undefined;
 }
+/**
+ * Extensions converter
+ */
 export declare class ExtensionsConverter extends BaseTCXConverter {
     name: string;
     supportedTags: string[];
     convert(ast: TokenAST, context: TCXContext): any | undefined;
+    /**
+     * Flatten extension element, extracting all leaf nodes
+     */
     private flattenExtensionElement;
+    /**
+     * Parse extension value, trying to convert to appropriate type
+     */
     private parseExtensionValue;
 }

package/dist/TCX/decoder.d.ts

@@ -1,6 +1,9 @@
 import { ExtensionsType, TokenAST } from "../types.js";
 import { ITCXConverterPlugin, ITCXMiddlewarePlugin } from "./base.js";
 import { TCXFileType } from "./types.js";
+/**
+ * https://www8.garmin.com/xmlschemas/TrainingCenterDatabasev2.xsd
+ */
 export declare class TCXDecoder {
     private converterPlugins;
     private registeredPlugins;
@@ -9,22 +12,73 @@ export declare class TCXDecoder {
     private initialized;
     private defaultConvertersRegistered;
     constructor();
+    /**
+     * Initialize pipeline - register fixed core processors
+     */
     private initializePipeline;
+    /**
+     * Auto-register default converters - handle standard TCX tags
+     */
     private registerDefaultConverters;
+    /**
+     * Add converter for specified tag, sorted by priority
+     */
     private addConverterForTag;
+    /**
+     * Register converter plugin
+     */
     registerConverter(plugin: ITCXConverterPlugin): Promise<void>;
+    /**
+     * Register middleware plugin - the real extension point
+     */
     registerMiddleware(plugin: ITCXMiddlewarePlugin): Promise<void>;
+    /**
+     * Get converter (returns highest priority one)
+     */
     getConverter(tag: string): ITCXConverterPlugin | undefined;
+    /**
+     * Get all converters for specified tag (sorted by priority)
+     */
     getAllConverters(tag: string): ITCXConverterPlugin[];
+    /**
+     * Remove converter
+     */
     unregisterConverter(pluginName: string): void;
+    /**
+     * Remove middleware
+     */
     unregisterMiddleware(name: string): void;
+    /**
+     * Initialize decoder
+     */
     initialize(): Promise<void>;
+    /**
+     * Destroy decoder
+     */
     destroy(): Promise<void>;
+    /**
+     * Create decode context
+     */
     private createContext;
+    /**
+     * Execute middleware hook
+     */
     private executeMiddlewareHook;
+    /**
+     * Main parse method - fixed pipeline + flexible middleware
+     */
     parseByBuffer(buffer: Buffer): Promise<TCXFileType | undefined>;
+    /**
+     * Convert Extensions (backward compatibility)
+     */
     convertExtensions(extensionsAST: TokenAST): ExtensionsType;
+    /**
+     * @deprecated Use parseByBuffer instead
+     */
     parserByBuffer(buffer: Buffer): Promise<TCXFileType | undefined>;
+    /**
+     * @deprecated Use new plugin system instead
+     */
     parseByString(xmlContent: string): Promise<TCXFileType | undefined>;
 }
 declare const _default: {

package/dist/TCX/encoder.d.ts

@@ -1,46 +1,162 @@
 import { TCXFileType } from "./types.js";
+/**
+ * TCX encoder - encodes TCXFileType data to TCX XML format
+ */
 export declare class TCXEncoder {
     private compact;
+    /**
+     * Constructor
+     * @param options Encoder options
+     */
     constructor(options?: {
         compact?: boolean;
     });
+    /**
+     * Encode TCX data to Buffer
+     */
     encode(tcxData: TCXFileType): Promise<Buffer>;
+    /**
+     * Encode TCX data to XML string
+     */
     encodeToString(tcxData: TCXFileType): string;
+    /**
+     * Build complete TCX XML
+     */
     private buildTCXXML;
+    /**
+     * Compress XML string, remove redundant newlines and spaces
+     */
     private compressXML;
+    /**
+     * Build XML header
+     */
     private buildXMLHeader;
+    /**
+     * Build TCX content
+     */
     private buildTCXContent;
+    /**
+     * Build Folders element
+     */
     private buildFolders;
+    /**
+     * Build History element
+     */
     private buildHistory;
+    /**
+     * Build HistoryFolder element
+     */
     private buildHistoryFolder;
+    /**
+     * Build Activities element
+     */
     private buildActivities;
+    /**
+     * Build single Activity element
+     */
     private buildActivity;
+    /**
+     * Build ActivityLap element
+     */
     private buildActivityLap;
+    /**
+     * Build Track element
+     */
     private buildTrack;
+    /**
+     * Build Trackpoint element
+     */
     private buildTrackpoint;
     private buildGeoCoords;
     private wrapGeoTag;
+    /**
+     * Build Position element
+     */
     private buildPosition;
+    /**
+     * Build Cadence element
+     */
     private buildCadence;
+    /**
+     * Build MultiActivitySession element
+     */
     private buildMultiActivitySession;
+    /**
+     * Build FirstActivity element
+     */
     private buildFirstActivity;
+    /**
+     * Build NextActivity element
+     */
     private buildNextActivity;
+    /**
+     * Build Workouts element
+     */
     private buildWorkouts;
+    /**
+     * Build Courses element
+     */
     private buildCourses;
+    /**
+     * Single TCX Course under Courses
+     */
     private buildCourseElement;
+    /**
+     * Lap inside Course (CourseLap schema subset)
+     */
     private buildCourseLap;
+    /** Course cue point */
     private buildCoursePoint;
+    /**
+     * Build Author element
+     */
     private buildAuthor;
+    /**
+     * Build extensions element
+     */
     private buildExtensions;
+    /**
+     * Recursively build extension content
+     */
     private buildExtensionContent;
+    /**
+     * Format time
+     */
     private formatTime;
+    /**
+     * Add optional element
+     */
     private addOptionalElement;
+    /**
+     * Add optional numeric element
+     */
     private addOptionalNumericElement;
+    /**
+     * Validate coordinate validity
+     */
     private isValidCoordinate;
+    /**
+     * Format coordinate
+     */
     private formatCoordinate;
+    /**
+     * Round number
+     */
     private roundTo;
+    /**
+     * XML escape
+     */
     private escapeXML;
+    /**
+     * XML attribute value escape (specifically for safe escaping of attribute values)
+     */
     private escapeXMLAttribute;
+    /**
+     * Deep clone
+     */
     private deepClone;
+    /**
+     * @deprecated Use encode() instead
+     */
     encoder(node: TCXFileType): Promise<Buffer>;
 }

package/dist/TCX/middleware.d.ts

@@ -1,6 +1,9 @@
 import { Token, TokenAST } from "../types.js";
 import { BaseTCXMiddleware } from "./base.js";
 import { TCXContext } from "./types.js";
+/**
+ * TCX performance monitoring middleware
+ */
 export declare class TCXPerformanceMiddleware extends BaseTCXMiddleware {
     name: string;
     description: string;
@@ -9,12 +12,18 @@ export declare class TCXPerformanceMiddleware extends BaseTCXMiddleware {
     onComplete(result: any, context: TCXContext): Promise<any>;
     private countNodes;
 }
+/**
+ * TCX validation middleware
+ */
 export declare class TCXValidationMiddleware extends BaseTCXMiddleware {
     name: string;
     description: string;
     onComplete(result: any, context: TCXContext): Promise<any>;
     private validateTCX;
 }
+/**
+ * TCX data enhancement middleware
+ */
 export declare class TCXEnhancementMiddleware extends BaseTCXMiddleware {
     name: string;
     description: string;
@@ -22,4 +31,7 @@ export declare class TCXEnhancementMiddleware extends BaseTCXMiddleware {
     private calculateTotalDistance;
     private calculateTotalDuration;
 }
+/**
+ * Register all default middleware
+ */
 export declare function registerDefaultTCXMiddlewares(decoder: any): Promise<void>;

package/dist/TCX/processor.d.ts

@@ -1,37 +1,67 @@
 import { TCXContext } from "./types.js";
 import { ITCXConverterPlugin } from "./base.js";
+/**
+ * TCX pipeline stages
+ */
 export declare enum TCXPipelineStage {
     TOKENIZE = "tokenize",
     AST_GENERATE = "ast-generate",
     CONVERT = "convert",
     COMPLETE = "complete"
 }
+/**
+ * Pipeline processor interface
+ */
 export interface IPipelineProcessor {
     stage: TCXPipelineStage;
     name: string;
     process(context: TCXContext): Promise<TCXContext>;
 }
+/**
+ * Tokenizer - convert XML to Token array
+ */
 export declare class TokenizeProcessor implements IPipelineProcessor {
     stage: TCXPipelineStage;
     name: string;
     process(context: TCXContext): Promise<TCXContext>;
 }
+/**
+ * AST generator - convert Token array to AST tree
+ */
 export declare class AstGenerateProcessor implements IPipelineProcessor {
     stage: TCXPipelineStage;
     name: string;
     process(context: TCXContext): Promise<TCXContext>;
 }
+/**
+ * Converter - convert AST to TCX data structure
+ */
 export declare class ConvertProcessor implements IPipelineProcessor {
     private getConverter;
     stage: TCXPipelineStage;
     name: string;
     constructor(getConverter: (tag: string) => ITCXConverterPlugin | undefined);
     process(context: TCXContext): Promise<TCXContext>;
+    /**
+     * Find TCX root node
+     */
     private findTCXRoot;
+    /**
+     * Convert AST node
+     */
     private convertAST;
+    /**
+     * Generic conversion method
+     */
     private genericConvert;
+    /**
+     * Count AST elements
+     */
     private countElements;
 }
+/**
+ * Completion processor - final processing and cleanup
+ */
 export declare class CompleteProcessor implements IPipelineProcessor {
     stage: TCXPipelineStage;
     name: string;

package/dist/TCX/types.d.ts

@@ -1,5 +1,8 @@
 import { ExtensionsType, Token, TokenAST } from "../types.js";
 import { IProcessingContext } from "../core/base.js";
+/**
+ * TCX file type
+ */
 export interface TCXFileType {
     version?: string;
     creator?: string;
@@ -137,6 +140,10 @@ export interface ActivityLapType {
     Extensions?: any;
 }
 export type TriggerMethodType = "Manual" | "Distance" | "Location" | "Time" | "HeartRate";
+/**
+ * Active (high intensity)
+ * Resting (low intensity)
+ */
 export type IntensityType = "Active" | "Resting";
 export interface CadenceType {
     Low: number;
@@ -154,6 +161,9 @@ export interface MultiActivitySessionType {
 export interface FirstActivityType {
     Activity?: ActivityType;
 }
+/**
+ * Each sport contains an optional transition and a run.
+ */
 export interface NextActivityType {
     Transition?: ActivityLapType;
     Activity?: ActivityType;
@@ -175,6 +185,9 @@ export interface PositionType {
     LatitudeDegrees?: string;
     LongitudeDegrees?: string;
 }
+/**
+ * TCX processing context
+ */
 export interface TCXContext extends IProcessingContext {
     rawData?: Buffer;
     xmlContent?: string;

package/dist/TrackSwap.d.ts

@@ -1,5 +1,9 @@
 import type { CourseEncodeOptions, DecodeOptions, EncodeOptions, TrackDocument, TrackFormat, TrackInput, TrackSwapOptions, TranscodeOptions } from "./document.js";
 import type { FileType } from "./types.js";
+/**
+ * Stateless facade for decoding, encoding and transcoding track documents.
+ * Format-specific behavior lives in adapters; this class only orchestrates them.
+ */
 export declare class TrackSwap {
     private readonly registry;
     private disposed;

package/dist/activity/base.d.ts

@@ -1,42 +1,85 @@
 import { IPlugin, IConverterPlugin, IMiddlewarePlugin, BaseConverter, BaseMiddleware, IProcessingContext } from "../core/base.js";
 import { ActivityType, ActivityRecordType, ActivityLapType, TokenAST, FileType } from "../types.js";
+/**
+ * Activity processing context
+ */
 export interface ActivityContext extends IProcessingContext {
+    /** Original data type */
     sourceFormat: string;
+    /** Original data */
     sourceData: any;
+    /** Conversion result */
     result?: FileType;
+    /** Activity-specific performance statistics */
     performance: {
         startTime: number;
         convertTime?: number;
         endTime?: number;
     };
 }
+/**
+ * Activity encoding context
+ */
 export interface ActivityEncodingContext extends IProcessingContext {
+    /** Target format */
     targetFormat: string;
+    /** Encoding result */
     result?: any;
+    /** Activity encoding specific performance statistics */
     performance: {
         startTime: number;
         encodeTime?: number;
         endTime?: number;
     };
 }
+/**
+ * Activity plugin interface (inherits from generic plugin interface)
+ */
 export interface IActivityPlugin extends IPlugin {
 }
+/**
+ * Activity converter plugin interface (inherits from generic converter interface)
+ */
 export interface IActivityConverterPlugin extends IConverterPlugin {
     convert(ast: TokenAST, context: ActivityContext): FileType | undefined;
 }
+/**
+ * Activity middleware plugin interface (inherits from generic middleware interface)
+ */
 export interface IActivityMiddlewarePlugin extends IMiddlewarePlugin {
     process(context: ActivityContext): Promise<void>;
 }
+/**
+ * Activity encoder plugin interface
+ */
 export interface IActivityEncoderPlugin extends IPlugin<ActivityEncodingContext> {
+    /** Encoding method */
     encode(file: FileType, context: ActivityEncodingContext): any | undefined;
+    /** Whether it supports the format */
     supports(format: string): boolean;
+    /** Priority (the smaller the higher the priority) */
     priority?: number;
 }
+/**
+ * Activity base converter abstract class (inherits from generic base converter)
+ */
 export declare abstract class BaseActivityConverter extends BaseConverter<ActivityContext> implements IActivityConverterPlugin {
+    /**
+     * Convert point array
+     */
     protected convertPoints(points: any[]): ActivityRecordType[];
+    /**
+     * Convert single point
+     */
     protected abstract convertPoint(point: any): ActivityRecordType | undefined;
+    /**
+     * Convert time to timestamp using dayjs
+     */
     protected convertTime(time: Date | string | number | undefined): number | undefined;
 }
+/**
+ * Activity base encoder abstract class
+ */
 export declare abstract class BaseActivityEncoder implements IActivityEncoderPlugin {
     abstract name: string;
     abstract supportedTags: string[];
@@ -52,11 +95,22 @@ export declare abstract class BaseActivityEncoder implements IActivityEncoderPlu
     protected ensureValidCoordinates(lat: number, lon: number): boolean;
     protected round(value: number, precision?: number): number;
 }
+/**
+ * Activity base middleware abstract class (inherits from generic base middleware)
+ */
 export declare abstract class BaseActivityMiddleware extends BaseMiddleware<ActivityContext, ActivityType> implements IActivityMiddlewarePlugin {
     abstract process(context: ActivityContext): Promise<void>;
     onError(error: Error, context: ActivityContext): Promise<void>;
+    /**
+     * Validate ActivityType data
+     */
     protected validateActivityFile(file: FileType): boolean;
     protected validateActivity(activity: ActivityType): boolean;
     protected validateRoute(route: ActivityLapType): boolean;
+    /**
+     * 仅判断有没有 timestamp
+     * @param point
+     * @returns
+     */
     protected validatePoint(point: ActivityRecordType): boolean;
 }