endurance-coach 0.1.0 → 1.0.0

package/dist/expander/expander.js

@@ -0,0 +1,339 @@
+/**
+ * Core Expander
+ *
+ * Converts compact training plans to expanded format for HTML rendering.
+ */
+import { parseWorkoutRef, parseWeekRange } from "../schema/compact-plan.js";
+import { interpolate, evaluateExpression, createContext } from "../templates/index.js";
+import { calculateAthleteZones } from "./zones.js";
+// ============================================================================
+// Date Utilities
+// ============================================================================
+/**
+ * Get the day of week name from a Date.
+ */
+function getDayOfWeekName(date) {
+    const days = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+    return days[date.getDay()];
+}
+/**
+ * Format a Date as ISO date string (YYYY-MM-DD).
+ */
+function formatDate(date) {
+    return date.toISOString().split("T")[0];
+}
+/**
+ * Add days to a date.
+ */
+function addDays(date, days) {
+    const result = new Date(date);
+    result.setDate(result.getDate() + days);
+    return result;
+}
+/**
+ * Calculate the start date of the plan from the event date and total weeks.
+ */
+function calculateStartDate(eventDate, totalWeeks, firstDayOfWeek) {
+    const event = new Date(eventDate);
+    // Go back totalWeeks * 7 days from event date
+    const start = addDays(event, -(totalWeeks * 7));
+    // Adjust to the first day of the week
+    const targetDay = firstDayOfWeek === "monday" ? 1 : 0;
+    const currentDay = start.getDay();
+    const diff = currentDay - targetDay;
+    const adjustedDiff = diff < 0 ? diff + 7 : diff;
+    return addDays(start, -adjustedDiff);
+}
+/**
+ * Map compact day abbreviation to day index (0-6, starting from Sunday).
+ */
+function dayAbbrevToIndex(abbrev) {
+    const mapping = {
+        Sun: 0,
+        Mon: 1,
+        Tue: 2,
+        Wed: 3,
+        Thu: 4,
+        Fri: 5,
+        Sat: 6,
+    };
+    return mapping[abbrev] ?? -1;
+}
+/**
+ * Get the offset from the first day of week to a specific day.
+ */
+function getDayOffset(dayAbbrev, firstDayOfWeek) {
+    const dayIndex = dayAbbrevToIndex(dayAbbrev);
+    const firstDayIndex = firstDayOfWeek === "monday" ? 1 : 0;
+    let offset = dayIndex - firstDayIndex;
+    if (offset < 0)
+        offset += 7;
+    return offset;
+}
+// ============================================================================
+// Workout Expansion
+// ============================================================================
+/**
+ * Parse a workout reference and extract the template ID and parameters.
+ */
+function parseWorkoutReference(ref) {
+    return parseWorkoutRef(ref);
+}
+/**
+ * Expand a single workout from its template reference.
+ */
+export function expandWorkout(ref, workoutId, context, templates) {
+    const parsed = parseWorkoutReference(ref);
+    const template = templates.get(parsed.templateId);
+    if (!template) {
+        // Create a placeholder workout for unknown templates
+        return {
+            id: workoutId,
+            sport: "run",
+            type: "unknown",
+            name: `Unknown: ${parsed.templateId}`,
+            humanReadable: `Template not found: ${parsed.templateId}`,
+            completed: false,
+        };
+    }
+    // Build the full context with template params
+    const paramContext = buildParamContext(template, parsed.params);
+    const fullContext = {
+        ...context,
+        ...paramContext,
+    };
+    // Interpolate the human-readable description
+    const humanReadable = interpolate(template.humanReadable, fullContext);
+    // Calculate duration
+    let durationMinutes;
+    if (template.estimatedDuration !== undefined) {
+        if (typeof template.estimatedDuration === "number") {
+            durationMinutes = template.estimatedDuration;
+        }
+        else {
+            const result = evaluateExpression(template.estimatedDuration, fullContext);
+            if (typeof result === "number") {
+                durationMinutes = result;
+            }
+            else {
+                const parsed = parseFloat(result);
+                if (!isNaN(parsed)) {
+                    durationMinutes = parsed;
+                }
+            }
+        }
+    }
+    return {
+        id: workoutId,
+        sport: template.sport,
+        type: template.type,
+        name: template.name,
+        durationMinutes,
+        primaryZone: template.targetZone,
+        rpe: template.rpe,
+        humanReadable,
+        completed: false,
+    };
+}
+/**
+ * Build parameter context from template defaults and provided params.
+ */
+function buildParamContext(template, providedParams) {
+    const context = {};
+    if (!template.params) {
+        return context;
+    }
+    const paramNames = Object.keys(template.params);
+    // Apply defaults first
+    for (const [name, def] of Object.entries(template.params)) {
+        if (def.default !== undefined) {
+            context[name] = def.default;
+        }
+    }
+    // Override with provided params (positional)
+    for (let i = 0; i < providedParams.length && i < paramNames.length; i++) {
+        context[paramNames[i]] = providedParams[i];
+    }
+    return context;
+}
+// ============================================================================
+// Week Expansion
+// ============================================================================
+/**
+ * Expand a single week from the compact format.
+ */
+function expandWeek(compactWeek, weekStartDate, context, templates, firstDayOfWeek) {
+    const days = [];
+    let totalMinutes = 0;
+    const bySport = {};
+    // Create all 7 days of the week
+    for (let dayOffset = 0; dayOffset < 7; dayOffset++) {
+        const date = addDays(weekStartDate, dayOffset);
+        const dayOfWeek = getDayOfWeekName(date);
+        days.push({
+            date: formatDate(date),
+            dayOfWeek,
+            workouts: [],
+        });
+    }
+    // Populate workouts from the schedule
+    for (const [dayAbbrev, workoutRefs] of Object.entries(compactWeek.workouts)) {
+        const dayOffset = getDayOffset(dayAbbrev, firstDayOfWeek);
+        if (dayOffset < 0 || dayOffset >= 7)
+            continue;
+        const day = days[dayOffset];
+        const refs = Array.isArray(workoutRefs) ? workoutRefs : [workoutRefs];
+        for (let i = 0; i < refs.length; i++) {
+            const ref = refs[i];
+            const workoutId = `week${compactWeek.week}-${dayAbbrev.toLowerCase()}-${i + 1}`;
+            const workout = expandWorkout(ref, workoutId, context, templates);
+            day.workouts.push(workout);
+            // Update summary stats
+            if (workout.durationMinutes) {
+                totalMinutes += workout.durationMinutes;
+                const sport = workout.sport;
+                if (!bySport[sport]) {
+                    bySport[sport] = { sessions: 0, hours: 0 };
+                }
+                bySport[sport].sessions += 1;
+                bySport[sport].hours += workout.durationMinutes / 60;
+            }
+        }
+    }
+    // Round hours to 1 decimal place
+    for (const sport of Object.keys(bySport)) {
+        bySport[sport].hours = Math.round(bySport[sport].hours * 10) / 10;
+    }
+    const summary = {
+        totalHours: Math.round((totalMinutes / 60) * 10) / 10,
+        bySport,
+    };
+    return {
+        weekNumber: compactWeek.week,
+        startDate: formatDate(weekStartDate),
+        endDate: formatDate(addDays(weekStartDate, 6)),
+        phase: compactWeek.phase,
+        focus: compactWeek.focus || "",
+        targetHours: compactWeek.targetHours || summary.totalHours,
+        days,
+        summary,
+        isRecoveryWeek: compactWeek.isRecoveryWeek || false,
+    };
+}
+// ============================================================================
+// Phase Expansion
+// ============================================================================
+/**
+ * Expand phases from compact format.
+ */
+function expandPhases(compact) {
+    return compact.phases.map((phase) => {
+        const weeks = parseWeekRange(phase.weeks);
+        const startWeek = Math.min(...weeks);
+        const endWeek = Math.max(...weeks);
+        return {
+            name: phase.name,
+            startWeek,
+            endWeek,
+            focus: phase.focus,
+            weeklyHoursRange: { low: 0, high: 0 }, // Will be calculated from weeks
+            keyWorkouts: phase.keyWorkouts || [],
+            physiologicalGoals: [],
+        };
+    });
+}
+// ============================================================================
+// Main Expander
+// ============================================================================
+/**
+ * Expand a compact plan into the full format for HTML rendering.
+ */
+export function expandPlan(compact, templates, options = {}) {
+    const firstDayOfWeek = compact.athlete.firstDayOfWeek || "monday";
+    const totalWeeks = compact.weeks.length;
+    // Calculate start date
+    const startDate = options.startDate || calculateStartDate(compact.athlete.eventDate, totalWeeks, firstDayOfWeek);
+    // Build interpolation context
+    const zonesForContext = compact.athlete.zones?.hr
+        ? {
+            hr: {
+                lthr: compact.athlete.zones.hr.lthr,
+                maxHR: compact.athlete.zones.hr.maxHR,
+                restingHR: compact.athlete.zones.hr.restingHR,
+            },
+        }
+        : undefined;
+    const context = createContext(compact.athlete.paces, zonesForContext);
+    // Calculate zones
+    const zones = calculateAthleteZones(compact.athlete.zones?.hr, compact.athlete.paces);
+    // Expand phases
+    const phases = expandPhases(compact);
+    // Expand weeks
+    const weeks = [];
+    for (let i = 0; i < compact.weeks.length; i++) {
+        const compactWeek = compact.weeks[i];
+        const weekStartDate = addDays(startDate, i * 7);
+        const expandedWeek = expandWeek(compactWeek, weekStartDate, context, templates, firstDayOfWeek);
+        weeks.push(expandedWeek);
+    }
+    // Calculate phase hour ranges from actual weeks
+    for (const phase of phases) {
+        const phaseWeeks = weeks.filter((w) => w.weekNumber >= phase.startWeek && w.weekNumber <= phase.endWeek);
+        if (phaseWeeks.length > 0) {
+            const hours = phaseWeeks.map((w) => w.summary.totalHours);
+            phase.weeklyHoursRange = {
+                low: Math.min(...hours),
+                high: Math.max(...hours),
+            };
+        }
+    }
+    // Build metadata
+    const now = new Date().toISOString();
+    const meta = {
+        id: `plan-${Date.now()}`,
+        athlete: compact.athlete.name,
+        event: compact.athlete.event,
+        eventDate: compact.athlete.eventDate,
+        planStartDate: formatDate(startDate),
+        planEndDate: formatDate(addDays(startDate, totalWeeks * 7 - 1)),
+        createdAt: now,
+        updatedAt: now,
+        totalWeeks,
+        generatedBy: "Endurance Coach",
+    };
+    // Build preferences
+    const unit = compact.athlete.unit || "km";
+    const preferences = {
+        swim: "meters",
+        bike: unit === "mi" ? "miles" : "kilometers",
+        run: unit === "mi" ? "miles" : "kilometers",
+        firstDayOfWeek,
+    };
+    return {
+        version: "1.0",
+        meta,
+        preferences,
+        zones,
+        phases,
+        weeks,
+        raceStrategy: compact.raceStrategy ? { ...compact.raceStrategy } : undefined,
+    };
+}
+/**
+ * Validate that all workout references in a compact plan have corresponding templates.
+ */
+export function validateWorkoutRefs(compact, templates) {
+    const errors = [];
+    for (const week of compact.weeks) {
+        for (const [day, refs] of Object.entries(week.workouts)) {
+            const refArray = Array.isArray(refs) ? refs : [refs];
+            for (const ref of refArray) {
+                const parsed = parseWorkoutReference(ref);
+                if (!templates.has(parsed.templateId)) {
+                    errors.push(`Week ${week.week}, ${day}: Unknown template "${parsed.templateId}"`);
+                }
+            }
+        }
+    }
+    return errors;
+}

package/dist/expander/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Expander Module
+ *
+ * Re-exports all expander-related types and functions.
+ */
+export type { ExpandedPlan, ExpandedWeek, ExpandedDay, ExpandedWorkout, ExpandedPhase, ExpandedWeekSummary, ExpandedHRZones, ExpandedHRZone, ExpandedPaceZones, ExpandedPaceZone, ExpandedAthleteZones, ExpandedPlanMeta, ExpandedUnitPreferences, ExpansionOptions, } from "./types.js";
+export { expandPlan, expandWorkout, validateWorkoutRefs } from "./expander.js";
+export { calculateHRZones, calculatePaceZones, calculateAthleteZones, parsePace, formatPace, getHRZoneForValue, getPaceZoneForValue, } from "./zones.js";

package/dist/expander/index.js

@@ -0,0 +1,9 @@
+/**
+ * Expander Module
+ *
+ * Re-exports all expander-related types and functions.
+ */
+// Core expander
+export { expandPlan, expandWorkout, validateWorkoutRefs } from "./expander.js";
+// Zone calculations
+export { calculateHRZones, calculatePaceZones, calculateAthleteZones, parsePace, formatPace, getHRZoneForValue, getPaceZoneForValue, } from "./zones.js";

package/dist/expander/types.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Expander Types
+ *
+ * Types for the plan expansion process - converting compact plans to expanded format.
+ */
+import type { Sport } from "../schema/compact-plan.js";
+/**
+ * A fully expanded workout with all variables interpolated.
+ */
+export interface ExpandedWorkout {
+    id: string;
+    sport: Sport;
+    type: string;
+    name: string;
+    description?: string;
+    durationMinutes?: number;
+    primaryZone?: string;
+    rpe?: string;
+    humanReadable: string;
+    completed: boolean;
+}
+/**
+ * A day in the expanded plan.
+ */
+export interface ExpandedDay {
+    date: string;
+    dayOfWeek: string;
+    workouts: ExpandedWorkout[];
+}
+/**
+ * Summary statistics for a training week.
+ */
+export interface ExpandedWeekSummary {
+    totalHours: number;
+    bySport: {
+        [sport: string]: {
+            sessions: number;
+            hours: number;
+        };
+    };
+}
+/**
+ * A week in the expanded plan.
+ */
+export interface ExpandedWeek {
+    weekNumber: number;
+    startDate: string;
+    endDate: string;
+    phase: string;
+    focus: string;
+    targetHours: number;
+    days: ExpandedDay[];
+    summary: ExpandedWeekSummary;
+    isRecoveryWeek: boolean;
+}
+/**
+ * A calculated heart rate zone.
+ */
+export interface ExpandedHRZone {
+    zone: number;
+    name: string;
+    percentLow: number;
+    percentHigh: number;
+    hrLow: number;
+    hrHigh: number;
+}
+/**
+ * Full heart rate zone configuration.
+ */
+export interface ExpandedHRZones {
+    lthr: number;
+    maxHR?: number;
+    restingHR?: number;
+    zones: ExpandedHRZone[];
+}
+/**
+ * A calculated pace zone.
+ */
+export interface ExpandedPaceZone {
+    zone: string;
+    name: string;
+    pace: string;
+    paceSeconds: number;
+}
+/**
+ * Full pace zone configuration.
+ */
+export interface ExpandedPaceZones {
+    thresholdPace: string;
+    thresholdPaceSeconds: number;
+    zones: ExpandedPaceZone[];
+}
+/**
+ * All athlete zones after calculation.
+ */
+export interface ExpandedAthleteZones {
+    run?: {
+        hr?: ExpandedHRZones;
+        pace?: ExpandedPaceZones;
+    };
+    bike?: {
+        hr?: ExpandedHRZones;
+    };
+    maxHR?: number;
+    restingHR?: number;
+}
+/**
+ * A training phase in the expanded plan.
+ */
+export interface ExpandedPhase {
+    name: string;
+    startWeek: number;
+    endWeek: number;
+    focus: string;
+    weeklyHoursRange: {
+        low: number;
+        high: number;
+    };
+    keyWorkouts: string[];
+    physiologicalGoals: string[];
+}
+/**
+ * Metadata for the expanded plan.
+ */
+export interface ExpandedPlanMeta {
+    id: string;
+    athlete: string;
+    event: string;
+    eventDate: string;
+    planStartDate: string;
+    planEndDate: string;
+    createdAt: string;
+    updatedAt: string;
+    totalWeeks: number;
+    generatedBy: string;
+}
+/**
+ * Unit preferences for the expanded plan.
+ */
+export interface ExpandedUnitPreferences {
+    swim: "meters" | "yards";
+    bike: "kilometers" | "miles";
+    run: "kilometers" | "miles";
+    firstDayOfWeek: "monday" | "sunday";
+}
+/**
+ * The complete expanded training plan.
+ * This format is consumed by the HTML renderer.
+ */
+export interface ExpandedPlan {
+    version: "1.0";
+    meta: ExpandedPlanMeta;
+    preferences: ExpandedUnitPreferences;
+    zones: ExpandedAthleteZones;
+    phases: ExpandedPhase[];
+    weeks: ExpandedWeek[];
+    raceStrategy?: Record<string, unknown>;
+}
+/**
+ * Options for the expansion process.
+ */
+export interface ExpansionOptions {
+    /** The start date for the plan (defaults to calculating from event date) */
+    startDate?: Date;
+    /** Whether to validate template references */
+    validateTemplates?: boolean;
+    /** Whether to include structured workout data (for device export) */
+    includeStructure?: boolean;
+}

package/dist/expander/types.js

@@ -0,0 +1,6 @@
+/**
+ * Expander Types
+ *
+ * Types for the plan expansion process - converting compact plans to expanded format.
+ */
+export {};

package/dist/expander/zones.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Zone Calculator
+ *
+ * Calculates training zone ranges from threshold values.
+ * Uses standard physiological percentages for zone calculations.
+ */
+import type { HRZoneConfig, AthletePaces } from "../schema/compact-plan.js";
+import type { ExpandedHRZones, ExpandedHRZone, ExpandedPaceZones, ExpandedPaceZone, ExpandedAthleteZones } from "./types.js";
+/**
+ * Calculate heart rate zones from LTHR.
+ *
+ * Uses the standard 5-zone model with percentages of LTHR.
+ */
+export declare function calculateHRZones(config: HRZoneConfig): ExpandedHRZones;
+/**
+ * Parse a pace string into seconds per unit.
+ *
+ * @example
+ * parsePace("5:30/km") // { seconds: 330, unit: "km" }
+ * parsePace("8:00/mi") // { seconds: 480, unit: "mi" }
+ * parsePace("5:30") // { seconds: 330, unit: undefined }
+ */
+export declare function parsePace(pace: string): {
+    seconds: number;
+    unit?: string;
+};
+/**
+ * Format seconds back to a pace string.
+ *
+ * @example
+ * formatPace(330, "km") // "5:30/km"
+ * formatPace(480) // "8:00"
+ */
+export declare function formatPace(seconds: number, unit?: string): string;
+/**
+ * Calculate pace zones from threshold pace.
+ */
+export declare function calculatePaceZones(thresholdPace: string): ExpandedPaceZones;
+/**
+ * Calculate all athlete zones from compact plan inputs.
+ */
+export declare function calculateAthleteZones(hrConfig?: HRZoneConfig, paces?: AthletePaces): ExpandedAthleteZones;
+/**
+ * Get the HR zone for a given heart rate.
+ */
+export declare function getHRZoneForValue(hr: number, zones: ExpandedHRZones): ExpandedHRZone | undefined;
+/**
+ * Get the pace zone for a given pace.
+ */
+export declare function getPaceZoneForValue(paceSeconds: number, zones: ExpandedPaceZones): ExpandedPaceZone | undefined;