Files
faceclaw/app/health/health-types.ts
T

238 lines
7.5 KiB
TypeScript

/**
* The health record shapes, normalised for storage and display.
*
* These mirror `RingProtocol.kt`'s `HourlyRecord` / `StepsRecord` /
* `SleepRecord` (on the `ring-health-protocol` branch) but deliberately are
* NOT the same types: the Java types are wire-shaped - raw hour indices, raw
* stage ids, ring-relative timestamps, a per-page anchor that may be absent.
* Everything here is already resolved into wall-clock time, or explicitly
* marked as not resolvable. The conversion is `fromRingRecords()` in
* `health-ingest.ts`, which is the only place that has to know about the wire.
*
* Keeping the two apart is what lets this app's storage and UI be built and
* tested with no BLE anywhere near them.
*/
/** The five metrics the phone view can graph. */
export type SeriesMetric = "heartRate" | "spo2" | "hrv" | "steps" | "sleep";
/** Metrics stored as bucketed samples. Sleep is per-session and excluded. */
export type SampleMetric = "heartRate" | "spo2" | "hrv" | "steps" | "calories";
export const SAMPLE_METRICS: readonly SampleMetric[] = [
"heartRate",
"spo2",
"hrv",
"steps",
"calories",
];
/** Metrics whose bucket value is a SUM over the bucket, not a measurement. */
export const CUMULATIVE_METRICS: readonly SampleMetric[] = ["steps", "calories"];
export function isCumulative(metric: SampleMetric): boolean {
return CUMULATIVE_METRICS.includes(metric);
}
export const HOUR_MS = 3_600_000;
export const TEN_MINUTES_MS = 600_000;
/** Point observation, not a ten-minute average. Distinct from hourly buckets. */
export const HEART_RATE_MEASUREMENT_SPAN_MS = 1;
export function isHeartRateMeasurement(sample: HealthSample): boolean {
return sample.metric === "heartRate" && sample.spanMs === HEART_RATE_MEASUREMENT_SPAN_MS;
}
export const DAY_MS = 86_400_000;
/**
* One stored bucket.
*
* `min`/`max`/`avg` are what the ring reports for the physiological metrics.
* For the cumulative ones (steps, calories) the ring reports a single count
* per bucket, so all three carry that count and `total` carries it as well -
* which keeps one shape for everything and lets a rollup sum `total` while
* banding `min`/`max` without special-casing the reader.
*
* `startMs` is the LOCAL wall-clock start of the bucket. A record whose time
* could not be resolved (a backlog page with no anchor; see the decode doc's
* section 4) is not stored at all rather than stored with an invented time -
* see `health-ingest.ts`.
*/
export type HealthSample = {
metric: SampleMetric;
startMs: number;
spanMs: number;
min: number;
max: number;
avg: number;
total: number;
};
/**
* One sleep session.
*
* All five duration fields come from NAMED byte offsets in the record and need
* no stage-id mapping (see `sleep-stages.ts`). `segments` is the hypnogram and
* carries RAW stage ids - resolve them through `stageNameForId`, never inline.
*
* `timeResolved` matters and is not decoration: the decode found that the
* ring's `start_ts`/`end_ts` are ring-relative seconds, not Unix time, and
* that nothing in the record dates the session (decode section 6, "genuinely
* unresolved"). Even's own app gets this wrong - one exported row is stamped
* 1979. When we cannot anchor a session we say so rather than plotting it at a
* time we made up.
*/
export type SleepSession = {
/** Local midnight of the day the session is attributed to (the wake-up day). */
dayStartMs: number;
startMs: number;
endMs: number;
totalSec: number;
wakeSec: number;
remSec: number;
lightSec: number;
deepSec: number;
segments: readonly SleepSegment[];
/** False when startMs/endMs are ring-relative and could not be anchored. */
timeResolved: boolean;
};
export type SleepSegment = {
/** RAW ring stage id, 0-3. Resolve via `stageNameForId`. */
stageId: number;
halfMinutes: number;
};
/**
* One night's stage breakdown, in seconds, positioned on the day axis.
*
* This is what the diverging nightly sleep chart plots (week / month / 3
* months). It is a separate shape from `RollupPoint` because a night is not a
* rollup of anything - it has four named parts that stack, three up and one
* down, and flattening it to a single `sum` is exactly the information the
* redesigned chart exists to stop throwing away.
*/
export type SleepNight = {
/** Local midnight of the day the session is attributed to (the wake-up day). */
startMs: number;
/** False when no session was recorded for this day - drawn as a gap. */
hasData: boolean;
deepSec: number;
remSec: number;
lightSec: number;
wakeSec: number;
};
/** A min/max/avg/sum rollup over some window. `count` is buckets contributing. */
export type Rollup = {
min: number;
max: number;
avg: number;
sum: number;
count: number;
};
/** A rollup positioned on the time axis - what the charts actually plot. */
export type RollupPoint = Rollup & {
/** Local wall-clock start of the window this rollup covers. */
startMs: number;
spanMs: number;
};
export function emptyRollup(): Rollup {
return { min: 0, max: 0, avg: 0, sum: 0, count: 0 };
}
/** Combine samples into one rollup. Returns null when nothing contributed. */
export function rollupOf(samples: readonly HealthSample[]): Rollup | null {
if (samples.length === 0) return null;
let min = Number.POSITIVE_INFINITY;
let max = Number.NEGATIVE_INFINITY;
let sum = 0;
let weighted = 0;
for (const sample of samples) {
if (sample.min < min) min = sample.min;
if (sample.max > max) max = sample.max;
sum += sample.total;
weighted += sample.avg;
}
return {
min,
max,
avg: weighted / samples.length,
sum,
count: samples.length,
};
}
export const METRIC_LABELS: Readonly<Record<SeriesMetric, string>> = {
heartRate: "Heart rate",
spo2: "Blood oxygen",
hrv: "HRV",
steps: "Steps",
sleep: "Sleep",
};
export const METRIC_UNITS: Readonly<Record<SeriesMetric, string>> = {
heartRate: "bpm",
spo2: "%",
hrv: "ms",
steps: "",
sleep: "h",
};
/**
* The same two maps over SampleMetric rather than SeriesMetric.
*
* These exist because the two enums differ at both ends: the phone GRAPHS
* sleep (which is not a sample metric) and the glasses drill-down walks
* calories (which is not a series metric, because the phone never got a
* calories chart). A screen that iterates the sample metrics needs a label for
* all five, so it gets its own map instead of special-casing the missing one.
*/
export const SAMPLE_METRIC_LABELS: Readonly<Record<SampleMetric, string>> = {
heartRate: "Heart rate",
spo2: "Blood oxygen",
hrv: "HRV",
steps: "Steps",
calories: "Calories",
};
export const SAMPLE_METRIC_UNITS: Readonly<Record<SampleMetric, string>> = {
heartRate: "bpm",
spo2: "%",
hrv: "ms",
steps: "",
calories: "kcal",
};
/** The short form the glance uses, where a column is ~300px wide. */
export const SAMPLE_METRIC_SHORT_LABELS: Readonly<Record<SampleMetric, string>> = {
heartRate: "HR",
spo2: "SpO2",
hrv: "HRV",
steps: "Steps",
calories: "Calories",
};
/** Local midnight of the day containing `ms`. */
export function startOfLocalDay(ms: number): number {
const date = new Date(ms);
date.setHours(0, 0, 0, 0);
return date.getTime();
}
/** Local top-of-hour containing `ms`. */
export function startOfLocalHour(ms: number): number {
const date = new Date(ms);
date.setMinutes(0, 0, 0);
return date.getTime();
}
/** `YYYY-MM`, in local time - the storage shard key. */
export function monthKey(ms: number): string {
const date = new Date(ms);
const month = `${date.getMonth() + 1}`.padStart(2, "0");
return `${date.getFullYear()}-${month}`;
}