Sports Lib normalizes GPX, TCX, FIT, and service-specific JSON into shared activity and route models. Activity imports and native JSON hydration consistently fill missing speed-derived pace summaries on events, activities, and laps while preserving applicable explicit values except Diving-group terrain summaries. Supported activity aliases are normalized to canonical types, including Diving-group Snorkeling and Mermaiding. The API reference documents the supported consumer API; implementation adapters and parsers remain available for compatibility but are intentionally outside this reference.
Regenerated multi-activity events carry the positive Recovery Time reported by their chronologically final activity.
They do not combine child recovery estimates or promote an earlier estimate when the final activity has none.
Provider-neutral Health and sleep Data* classes cover movement, energy, cardiovascular values, wellness, body
composition, sleep stages, sleep scores, and sleep-qualified vital aggregates. Their canonical tokens, units, display
formatting, aliases, and JSON behavior are documented in the metrics guide; provider transport and persistence remain
consumer responsibilities.
Canonical kilogram DataWeight values also support an independent optional WeightUnits.Pounds display preference.
Older settings remain in kilograms. This can format planned external loads without adding a workout-specific metric
or changing stored Weight JSON. See the metrics guide.
The opt-in FIT workout-reference reader exposes standard FIT
training-file references, embedded workout summaries and paired SuuntoPlus Guide IDs as serializable DataBare
classes with unversioned references or definitions values. These are nonnumeric source metadata, separate from
normal activity JSON; consumers own account validation,
privacy and completion matching. Developer indexes and field numbers resolve dynamically; unsupported exporters and
malformed metadata have distinct diagnostics, and unrelated developer errors or malformed optional session fields do
not discard independent valid reference groups. Ambiguous Guide groups are rejected rather than partially paired.
Activity-aware cadence semantics produce stroke rate for swimming, rowing, and paddle sports. Consumers that store event
summaries separately from activities can explicitly canonicalize those projections with
normalizeActivityMetricSemanticsForStats after determining the contributing activity types.
Activity groups distinguish generic and inline skating from Ice Skating, retain flight altitude metrics with vertical speed for aerial activities, and classify motorized and adaptive-mobility activities without deriving training stress or durability evidence.
FIT creator attribution prefers file_id metadata and recovers only missing identity fields from a device_info row
explicitly marked as the creator or local device. Compacted device metadata retains that identity row even when it has
no timestamp, while timed battery calculations remain unchanged.
FIT imports retain parser-scaled record depth samples in canonical meters and native session/lap dive summaries plus
decompression, gas-consumption, tissue-load, PO₂, ascent-rate, and air-time-remaining record streams. Ordered FIT gas,
tank-summary, and tank-update records are available separately through ActivityInterface.getDiveSourceRecords() and
round-trip through the native ActivityJSONInterface.diveSourceRecords field. These values follow the FIT profile
without record-to-summary calculation, interpolation, clamping, gas/tank linking, or gas/tank flattening. Depth,
average/maximum depth, next-stop depth, and dive-rate display variants follow the first swim-pace preference, using
meters and meters per second for /100m or feet and feet per second for /100yd. Dive depths display to three decimal
places, rates to three, SAC/RMV values to two, and PO₂ retains both FIT decimal places.
Garmin single-gas, multi-gas, and gauge sub-sports import as Scuba Diving; apnea sub-sports import as Free Diving.
FIT session and lap intensity enums are retained as the string-valued Intensity stat. Diving-group activities do not
retain or derive terrain ascent, descent, altitude min/max/avg, or grade min/max/avg summaries, including when older
native JSON is restored or an all-diving event summary is regenerated. Mixed event summaries use terrain values only
from non-diving activities. Their vertical movement is represented by depth; raw altitude and grade streams remain
available when provided by the source.
Install the package:
npm install @sports-alliance/sports-lib
When parsing GPX in Node.js, also install a DOM parser implementation:
npm install @xmldom/xmldom
Version 21 provides module-preserving ESM and CommonJS output through the existing package-root API. Bundlers can remove
unrelated importers and utilities when focused exports are used; the SportsLib facade continues to expose the complete
format surface in the initial bundle. Startup-sensitive consumers should use focused root imports. Upgrading does not
require reparsing activities or routes, regenerating summaries, or migrating native JSON and persisted metrics.
Use the navigation to browse the curated API, including SportsLib, activity parsing options, route parsing options, streams, and the JSON contracts.
analyzeActivityDurability produces deterministic durability evidence when an activity has enough eligible source data. Its steady aerobic adapter supports standard mountain biking but records Enduro MTB and Downhill Cycling as explicit unsupported contexts. samplePowerCurveAtDuration and comparePowerCurveWindows support power-curve comparisons without extrapolating beyond known samples. Parsing retains power streams and power curves but does not infer athlete CP/W′ or persist three-dimensional strain from one workout. buildPowerDurationEnvelope and fitThreeDimensionalCapacityModel instead use a dated, same-activity-type history to produce a confidence-gated CP/W′/Pmax snapshot; calculateThreeDimensionalStrain scores a workout only when the caller supplies a complete ready model. Follow the rolling capacity and scoring recipe and the complete research and implementation guide.
Capacity diagnostics separately report usable curves and the distinct activities that supplied each component's retained envelope anchors, so consumers can disclose concentrated evidence without treating it as a different fit.
calculateThreeDimensionalImpulseResponse applies independently calibrated fitness-fatigue responses to the three daily load series. fitThreeDimensionalImpulseResponseParameters adds bounded, chronologically validated calibration when callers provide dated daily strain loads and independent CP/W′/Pmax observations; it deliberately returns no generic athlete model when evidence or held-out fit quality is inadequate. Follow the practical response-calibration recipe before integrating it.