@pond-ts/fit 0.31.0

package/dist/units.d.ts

@@ -0,0 +1,41 @@
+/** Display-edge unit conversion. The model stores SI; UI converts here. */
+export declare const METERS_PER_MILE = 1609.344;
+export declare const METERS_PER_FOOT = 0.3048;
+export declare const metersToMiles: (m: number) => number;
+export declare const metersToFeet: (m: number) => number;
+/** Seconds → "h:mm:ss" or "m:ss". */
+export declare function formatDuration(totalSeconds: number): string;
+export type DistanceUnit = 'mi' | 'km';
+export type ElevationUnit = 'ft' | 'm';
+export type TemperatureUnit = 'F' | 'C';
+export type SpeedPaceUnit = 'imperial' | 'metric';
+export interface UnitPreferences {
+    distance: DistanceUnit;
+    elevation: ElevationUnit;
+    temperature: TemperatureUnit;
+    speedPace: SpeedPaceUnit;
+}
+/** US defaults — the archive's origin. Each axis is independently overridable. */
+export declare const DEFAULT_UNITS: UnitPreferences;
+/** Distance: metres → display number in the chosen unit. */
+export declare function convertDistance(meters: number, unit: DistanceUnit): number;
+/** Elevation: metres → display number in the chosen unit. */
+export declare function convertElevation(meters: number, unit: ElevationUnit): number;
+/** Temperature: °C → display number in the chosen unit. */
+export declare function convertTemperature(celsius: number, unit: TemperatureUnit): number;
+/** Speed: m/s → display number (mph or km/h). */
+export declare function convertSpeed(metersPerSecond: number, unit: SpeedPaceUnit): number;
+/** The label shown next to a converted value, e.g. for axis ticks / stat tiles. */
+export declare function distanceUnitLabel(unit: DistanceUnit): string;
+export declare function elevationUnitLabel(unit: ElevationUnit): string;
+export declare function temperatureUnitLabel(unit: TemperatureUnit): string;
+export declare function speedUnitLabel(unit: SpeedPaceUnit): string;
+export declare function paceUnitLabel(unit: SpeedPaceUnit): string;
+/**
+ * Seconds-per-kilometre → "m:ss/km" (default) or "m:ss/mi" when `unit` is
+ * imperial. Rounds total seconds *first* then splits, so a pace rounding up to
+ * a full minute carries (119.88 → "2:00/km", never "1:60/km"). Same
+ * round-then-split discipline as {@link formatDuration}.
+ */
+export declare function formatPace(secondsPerKm: number, unit?: SpeedPaceUnit): string;
+//# sourceMappingURL=units.d.ts.map

package/dist/units.js

@@ -0,0 +1,69 @@
+/** Display-edge unit conversion. The model stores SI; UI converts here. */
+export const METERS_PER_MILE = 1609.344;
+export const METERS_PER_FOOT = 0.3048;
+export const metersToMiles = (m) => m / METERS_PER_MILE;
+export const metersToFeet = (m) => m / METERS_PER_FOOT;
+/** Seconds → "h:mm:ss" or "m:ss". */
+export function formatDuration(totalSeconds) {
+    const s = Math.round(totalSeconds);
+    const h = Math.floor(s / 3600);
+    const m = Math.floor((s % 3600) / 60);
+    const sec = s % 60;
+    const pad = (n) => String(n).padStart(2, '0');
+    return h > 0 ? `${h}:${pad(m)}:${pad(sec)}` : `${m}:${pad(sec)}`;
+}
+/** US defaults — the archive's origin. Each axis is independently overridable. */
+export const DEFAULT_UNITS = {
+    distance: 'mi',
+    elevation: 'ft',
+    temperature: 'F',
+    speedPace: 'imperial',
+};
+/** Distance: metres → display number in the chosen unit. */
+export function convertDistance(meters, unit) {
+    return unit === 'km' ? meters / 1000 : metersToMiles(meters);
+}
+/** Elevation: metres → display number in the chosen unit. */
+export function convertElevation(meters, unit) {
+    return unit === 'm' ? meters : metersToFeet(meters);
+}
+/** Temperature: °C → display number in the chosen unit. */
+export function convertTemperature(celsius, unit) {
+    return unit === 'F' ? celsius * 1.8 + 32 : celsius;
+}
+/** Speed: m/s → display number (mph or km/h). */
+export function convertSpeed(metersPerSecond, unit) {
+    return unit === 'metric' ? metersPerSecond * 3.6 : metersPerSecond * 2.236936;
+}
+/** The label shown next to a converted value, e.g. for axis ticks / stat tiles. */
+export function distanceUnitLabel(unit) {
+    return unit;
+}
+export function elevationUnitLabel(unit) {
+    return unit;
+}
+export function temperatureUnitLabel(unit) {
+    return unit === 'F' ? '°F' : '°C';
+}
+export function speedUnitLabel(unit) {
+    return unit === 'metric' ? 'km/h' : 'mph';
+}
+export function paceUnitLabel(unit) {
+    return unit === 'metric' ? '/km' : '/mi';
+}
+/**
+ * Seconds-per-kilometre → "m:ss/km" (default) or "m:ss/mi" when `unit` is
+ * imperial. Rounds total seconds *first* then splits, so a pace rounding up to
+ * a full minute carries (119.88 → "2:00/km", never "1:60/km"). Same
+ * round-then-split discipline as {@link formatDuration}.
+ */
+export function formatPace(secondsPerKm, unit = 'metric') {
+    const perUnit = unit === 'imperial'
+        ? secondsPerKm * (METERS_PER_MILE / 1000)
+        : secondsPerKm;
+    const s = Math.round(perUnit);
+    const m = Math.floor(s / 60);
+    const sec = s % 60;
+    return `${m}:${String(sec).padStart(2, '0')}${paceUnitLabel(unit)}`;
+}
+//# sourceMappingURL=units.js.map

package/dist/zones/index.d.ts

@@ -0,0 +1,32 @@
+import type { ZoneDef } from '../profile/index.js';
+/** One zone's time + share. `hi` is `Infinity` for the open top. */
+export interface ZoneTime {
+    /** 1-based zone number (Z1 = the lowest band). */
+    zone: number;
+    label: string;
+    /** Inclusive lower edge, in the value axis (watts / bpm / m·s⁻¹). */
+    lo: number;
+    /** Upper edge; `Infinity` for the top zone. */
+    hi: number;
+    seconds: number;
+    /** Share of total in-zone time, [0, 1]. */
+    fraction: number;
+}
+/**
+ * Time spent in each zone, bucketing `values` by the ascending `edges` and
+ * summing per-sample `dt`. pond `byColumn({ edges, inclusive: '(]' })` over the
+ * value axis — Coggan-style **inclusive-upper** bins natively (a sample exactly
+ * on a boundary counts in the lower zone), no ε-nudge. Non-finite values are
+ * dropped (can't be placed); sub-zero clamps to the bottom zone. pond 0.30 made
+ * the floor edge of `'(]'` inclusive (the `include_lowest` convention), so a 0
+ * sample (a stop / coast) lands in zone 1 with the edges passed as-is — no
+ * floor-push needed (F-inclusive-floor, resolved in 0.30).
+ */
+export declare function zoneDistributionByValue(values: ArrayLike<number>, dt: ArrayLike<number>, zones: ZoneDef): ZoneTime[];
+/** Time in each HR zone (bpm axis). `hrZones` from `profile.profileAsOf`. */
+export declare function hrZoneDistribution(timeSec: Float64Array, heartrate: ArrayLike<number>, hrZones: ZoneDef): ZoneTime[];
+/** Time in each pace zone. We bucket the **speed** channel (m/s) against
+ *  speed-axis edges (Z1 = slowest) so a stop doesn't blow the reciprocal up;
+ *  the UI labels the bands as paces. `paceZones` from `profile.profileAsOf`. */
+export declare function paceZoneDistribution(timeSec: Float64Array, speed: ArrayLike<number>, paceZones: ZoneDef): ZoneTime[];
+//# sourceMappingURL=index.d.ts.map

package/dist/zones/index.js

@@ -0,0 +1,61 @@
+/**
+ * Time-in-zone over a **value axis** — the engine behind the power, heart-rate,
+ * and pace zone distributions. Each is "how long did this channel spend in each
+ * band," i.e. bucket the per-sample value by the zone edges and sum each
+ * sample's duration. That's pond `byColumn` over the value column, summing a
+ * gap-clamped `dt` weight — the same shape the power distribution uses,
+ * generalized so HR and pace share one tested core.
+ */
+import { TimeSeries } from 'pond-ts';
+import { intervals } from '../intervals.js';
+const BIN_SCHEMA = [
+    { name: 'time', kind: 'time' },
+    // optional so a non-finite sample rides as `undefined` and byColumn drops it.
+    { name: 'val', kind: 'number', required: false },
+    { name: 'dt', kind: 'number' },
+];
+const SENTINEL = 1e9; // the open-top edge ZoneDef carries
+/**
+ * Time spent in each zone, bucketing `values` by the ascending `edges` and
+ * summing per-sample `dt`. pond `byColumn({ edges, inclusive: '(]' })` over the
+ * value axis — Coggan-style **inclusive-upper** bins natively (a sample exactly
+ * on a boundary counts in the lower zone), no ε-nudge. Non-finite values are
+ * dropped (can't be placed); sub-zero clamps to the bottom zone. pond 0.30 made
+ * the floor edge of `'(]'` inclusive (the `include_lowest` convention), so a 0
+ * sample (a stop / coast) lands in zone 1 with the edges passed as-is — no
+ * floor-push needed (F-inclusive-floor, resolved in 0.30).
+ */
+export function zoneDistributionByValue(values, dt, zones) {
+    const { edges, labels } = zones;
+    const rows = [];
+    for (let i = 0; i < values.length; i++) {
+        const v = values[i];
+        rows.push([i, Number.isFinite(v) ? Math.max(0, v) : undefined, dt[i] ?? 0]);
+    }
+    const bins = new TimeSeries({
+        name: 'zones',
+        schema: BIN_SCHEMA,
+        rows,
+    }).byColumn('val', { edges, inclusive: '(]' }, { seconds: { from: 'dt', using: 'sum' } });
+    const secs = bins.map((b) => b.seconds ?? 0);
+    const total = secs.reduce((a, b) => a + b, 0) || 1;
+    return labels.map((label, z) => ({
+        zone: z + 1,
+        label,
+        lo: edges[z],
+        hi: (edges[z + 1] ?? SENTINEL) >= SENTINEL ? Infinity : edges[z + 1],
+        seconds: secs[z] ?? 0,
+        fraction: (secs[z] ?? 0) / total,
+    }));
+}
+/** Time in each HR zone (bpm axis). `hrZones` from `profile.profileAsOf`. */
+export function hrZoneDistribution(timeSec, heartrate, hrZones) {
+    return zoneDistributionByValue(heartrate, intervals(timeSec), hrZones);
+}
+/** Time in each pace zone. We bucket the **speed** channel (m/s) against
+ *  speed-axis edges (Z1 = slowest) so a stop doesn't blow the reciprocal up;
+ *  the UI labels the bands as paces. `paceZones` from `profile.profileAsOf`. */
+export function paceZoneDistribution(timeSec, speed, paceZones) {
+    return zoneDistributionByValue(speed, intervals(timeSec), paceZones);
+}
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@pond-ts/fit",
+  "version": "0.31.0",
+  "private": false,
+  "description": "Fitness & activity domain library on pond-ts — quantities, canonical activity series, and analytics (geo, power, zones, splits)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pjm17971/pond-ts.git",
+    "directory": "packages/fit"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/cjs-fallback.cjs"
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\"",
+    "prepack": "cp ../../README.md ./README.md && cp ../../LICENSE ./LICENSE && cp ../../CHANGELOG.md ./CHANGELOG.md && npm run build && cp cjs-fallback.cjs dist/cjs-fallback.cjs && find dist -name '*.map' -delete",
+    "test": "npm run test:type && npm run test:runtime",
+    "test:type": "tsc -p tsconfig.types.json",
+    "test:runtime": "vitest run",
+    "verify": "npm run format:check && npm run build && npm test"
+  },
+  "peerDependencies": {
+    "pond-ts": "^0.31.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  }
+}