mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-16 15:23:29 +00:00
refactor(rollups): move WMY and cumulative readers
- src/lib/measurements/rollup-read-wmy.ts → src/lib/rollups/measurement-read-wmy.ts - src/lib/measurements/rollup-read-cumulative.ts → src/lib/rollups/measurement-read-cumulative.ts - co-located tests follow the source files - cumulative module's sibling import of apple-health-mapping promoted to the @/lib alias since that mapping stays in src/lib/measurements/ Importers updated: 2 sites for WMY (health-score + summaries-slice), zero external sites for cumulative (only co-located test reads it). Pure relocation.
This commit is contained in:
1 parent
b7da526cbb
commit
8cfb1715b4
6 files changed
+5
-5
No files matched your search
@@ -0,0 +1,136 @@
|
||||
/**
|
||||
* v1.4.39 W-SUM — unit tests for the cumulative-day-sum reader helpers.
|
||||
*
|
||||
* `prisma.measurementRollup.findMany` is mocked so the tests pin the
|
||||
* exact `where` shape the consumer sends (cumulative type set,
|
||||
* granularity, since-bound) and the legacy-NULL fallback semantics of
|
||||
* `resolveBucketSum`.
|
||||
*/
|
||||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
const mocks = vi.hoisted(() => ({
|
||||
findMany: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/db", () => ({
|
||||
prisma: {
|
||||
measurementRollup: {
|
||||
findMany: mocks.findMany,
|
||||
},
|
||||
},
|
||||
}));
|
||||
|
||||
import { prisma } from "@/lib/db";
|
||||
import {
|
||||
isCumulativeType,
|
||||
readCumulativeDaySums,
|
||||
resolveBucketSum,
|
||||
} from "../measurement-read-cumulative";
|
||||
|
||||
beforeEach(() => {
|
||||
mocks.findMany.mockReset();
|
||||
});
|
||||
|
||||
describe("isCumulativeType", () => {
|
||||
it("recognises the five cumulative HK types", () => {
|
||||
expect(isCumulativeType("ACTIVITY_STEPS")).toBe(true);
|
||||
expect(isCumulativeType("ACTIVE_ENERGY_BURNED")).toBe(true);
|
||||
expect(isCumulativeType("FLIGHTS_CLIMBED")).toBe(true);
|
||||
expect(isCumulativeType("WALKING_RUNNING_DISTANCE")).toBe(true);
|
||||
expect(isCumulativeType("TIME_IN_DAYLIGHT")).toBe(true);
|
||||
});
|
||||
|
||||
it("rejects spot metrics", () => {
|
||||
expect(isCumulativeType("WEIGHT")).toBe(false);
|
||||
expect(isCumulativeType("BLOOD_PRESSURE_SYS")).toBe(false);
|
||||
expect(isCumulativeType("PULSE")).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("readCumulativeDaySums", () => {
|
||||
it("queries the rollup table with the cumulative type + DAY granularity", async () => {
|
||||
const since = new Date("2026-04-15T00:00:00.000Z");
|
||||
const rows = [
|
||||
{
|
||||
bucketStart: new Date("2026-04-15T00:00:00.000Z"),
|
||||
sumValue: 8120,
|
||||
count: 4,
|
||||
mean: 2030,
|
||||
},
|
||||
{
|
||||
bucketStart: new Date("2026-04-16T00:00:00.000Z"),
|
||||
sumValue: 12480,
|
||||
count: 5,
|
||||
mean: 2496,
|
||||
},
|
||||
];
|
||||
mocks.findMany.mockResolvedValueOnce(rows);
|
||||
|
||||
const out = await readCumulativeDaySums("user-1", "ACTIVITY_STEPS", since);
|
||||
|
||||
expect(out).toHaveLength(2);
|
||||
expect(out[0]).toMatchObject({
|
||||
bucketStart: new Date("2026-04-15T00:00:00.000Z"),
|
||||
sumValue: 8120,
|
||||
count: 4,
|
||||
mean: 2030,
|
||||
});
|
||||
// Single round-trip — eliminates the legacy per-type chunked
|
||||
// findMany loop in analytics A2.
|
||||
expect(prisma.measurementRollup.findMany).toHaveBeenCalledTimes(1);
|
||||
const args = mocks.findMany.mock.calls[0][0];
|
||||
expect(args.where).toMatchObject({
|
||||
userId: "user-1",
|
||||
type: "ACTIVITY_STEPS",
|
||||
granularity: "DAY",
|
||||
bucketStart: { gte: since },
|
||||
});
|
||||
expect(args.orderBy).toEqual({ bucketStart: "asc" });
|
||||
});
|
||||
|
||||
it("propagates legacy NULL sum_value rows so the caller can fall back", async () => {
|
||||
mocks.findMany.mockResolvedValueOnce([
|
||||
{
|
||||
bucketStart: new Date("2026-04-15T00:00:00.000Z"),
|
||||
sumValue: null,
|
||||
count: 3,
|
||||
mean: 1500,
|
||||
},
|
||||
]);
|
||||
|
||||
const [row] = await readCumulativeDaySums(
|
||||
"user-1",
|
||||
"ACTIVITY_STEPS",
|
||||
new Date("2026-04-15T00:00:00.000Z"),
|
||||
);
|
||||
expect(row.sumValue).toBeNull();
|
||||
// Algebraic fallback parity: pre-v1.4.39 buckets still surface
|
||||
// a usable daily total during the boot-backfill convergence
|
||||
// window.
|
||||
expect(resolveBucketSum(row)).toBe(4500);
|
||||
});
|
||||
});
|
||||
|
||||
describe("resolveBucketSum", () => {
|
||||
it("returns sumValue when populated", () => {
|
||||
expect(
|
||||
resolveBucketSum({
|
||||
bucketStart: new Date(),
|
||||
sumValue: 7500,
|
||||
count: 3,
|
||||
mean: 2500,
|
||||
}),
|
||||
).toBe(7500);
|
||||
});
|
||||
|
||||
it("falls back to mean * count when sumValue is null (legacy row)", () => {
|
||||
expect(
|
||||
resolveBucketSum({
|
||||
bucketStart: new Date(),
|
||||
sumValue: null,
|
||||
count: 3,
|
||||
mean: 2500,
|
||||
}),
|
||||
).toBe(7500);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,362 @@
|
||||
/**
|
||||
* v1.4.39 W-WMY — unit tests for the WEEK / MONTH / YEAR rollup
|
||||
* readers and the auto-router that picks the largest granularity
|
||||
* that still resolves a requested window.
|
||||
*
|
||||
* `prisma.measurementRollup.findMany` is mocked at the module level
|
||||
* so the test pins:
|
||||
* - each per-granularity reader filters by the correct
|
||||
* `granularity` literal,
|
||||
* - empty rollups return `null` so the caller can branch on
|
||||
* coverage miss,
|
||||
* - the auto-router walks YEAR → MONTH → WEEK → DAY and stops at
|
||||
* the first granularity whose floor the window clears AND which
|
||||
* has coverage,
|
||||
* - `aggregateWmyBuckets` composes `count / min / max / mean / sum`
|
||||
* linearly across coarser buckets (the same compositional
|
||||
* contract `rollup-read.ts:aggregateBuckets` carries for DAY).
|
||||
*
|
||||
* Integration coverage against a real Postgres lives outside this
|
||||
* file — the writer's `STDDEV_POP / REGR_SLOPE` semantics are pinned
|
||||
* in `tests/integration/measurement-rollups.test.ts` already.
|
||||
*/
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
const mocks = vi.hoisted(() => ({
|
||||
findMany: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("@/lib/db", () => ({
|
||||
prisma: {
|
||||
measurementRollup: {
|
||||
findMany: mocks.findMany,
|
||||
},
|
||||
},
|
||||
}));
|
||||
|
||||
import {
|
||||
aggregateWmyBuckets,
|
||||
readBestGranularityRollups,
|
||||
readMonthRollups,
|
||||
readWeekRollups,
|
||||
readYearRollups,
|
||||
type RollupBucketRow,
|
||||
} from "../measurement-read-wmy";
|
||||
|
||||
const { findMany } = mocks;
|
||||
|
||||
function bucket(
|
||||
bucketStart: string,
|
||||
partial: Partial<RollupBucketRow> = {},
|
||||
): RollupBucketRow {
|
||||
return {
|
||||
bucketStart: new Date(bucketStart),
|
||||
count: 10,
|
||||
mean: 82,
|
||||
sd: 1,
|
||||
slope: -0.01,
|
||||
r2: 0.3,
|
||||
sumValue: null,
|
||||
minValue: 80,
|
||||
maxValue: 84,
|
||||
...partial,
|
||||
};
|
||||
}
|
||||
|
||||
beforeEach(() => {
|
||||
findMany.mockReset();
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
|
||||
describe("readWeekRollups", () => {
|
||||
it("returns the WEEK buckets for (userId, type, since)", async () => {
|
||||
const rows = [
|
||||
bucket("2026-04-27T00:00:00.000Z"),
|
||||
bucket("2026-05-04T00:00:00.000Z", { mean: 81 }),
|
||||
];
|
||||
findMany.mockResolvedValueOnce(rows);
|
||||
const since = new Date("2026-04-20T00:00:00.000Z");
|
||||
|
||||
const result = await readWeekRollups("user-1", "WEIGHT", since);
|
||||
|
||||
expect(result).not.toBeNull();
|
||||
expect(result).toHaveLength(2);
|
||||
expect(result?.[0].mean).toBe(82);
|
||||
expect(result?.[1].mean).toBe(81);
|
||||
const args = findMany.mock.calls[0][0];
|
||||
expect(args.where.granularity).toBe("WEEK");
|
||||
expect(args.where.userId).toBe("user-1");
|
||||
expect(args.where.type).toBe("WEIGHT");
|
||||
expect(args.where.bucketStart.gte).toBe(since);
|
||||
expect(args.orderBy).toEqual({ bucketStart: "asc" });
|
||||
});
|
||||
|
||||
it("returns null when the WEEK window has no coverage", async () => {
|
||||
findMany.mockResolvedValueOnce([]);
|
||||
const result = await readWeekRollups(
|
||||
"user-1",
|
||||
"WEIGHT",
|
||||
new Date("2026-04-20T00:00:00.000Z"),
|
||||
);
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("readMonthRollups", () => {
|
||||
it("returns the MONTH buckets and pins the granularity filter", async () => {
|
||||
findMany.mockResolvedValueOnce([bucket("2026-04-01T00:00:00.000Z")]);
|
||||
const result = await readMonthRollups(
|
||||
"user-2",
|
||||
"PULSE",
|
||||
new Date("2026-01-01T00:00:00.000Z"),
|
||||
);
|
||||
expect(result).toHaveLength(1);
|
||||
expect(findMany.mock.calls[0][0].where.granularity).toBe("MONTH");
|
||||
});
|
||||
|
||||
it("returns null on coverage miss", async () => {
|
||||
findMany.mockResolvedValueOnce([]);
|
||||
const result = await readMonthRollups(
|
||||
"user-2",
|
||||
"PULSE",
|
||||
new Date("2026-01-01T00:00:00.000Z"),
|
||||
);
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("readYearRollups", () => {
|
||||
it("returns the YEAR buckets and pins the granularity filter", async () => {
|
||||
findMany.mockResolvedValueOnce([bucket("2025-01-01T00:00:00.000Z")]);
|
||||
const result = await readYearRollups(
|
||||
"user-3",
|
||||
"WEIGHT",
|
||||
new Date("2023-01-01T00:00:00.000Z"),
|
||||
);
|
||||
expect(result).toHaveLength(1);
|
||||
expect(findMany.mock.calls[0][0].where.granularity).toBe("YEAR");
|
||||
});
|
||||
|
||||
it("returns null on coverage miss", async () => {
|
||||
findMany.mockResolvedValueOnce([]);
|
||||
const result = await readYearRollups(
|
||||
"user-3",
|
||||
"WEIGHT",
|
||||
new Date("2023-01-01T00:00:00.000Z"),
|
||||
);
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("readBestGranularityRollups", () => {
|
||||
it("returns null on a non-positive window", async () => {
|
||||
expect(await readBestGranularityRollups("user", "WEIGHT", 0)).toBeNull();
|
||||
expect(await readBestGranularityRollups("user", "WEIGHT", -10)).toBeNull();
|
||||
expect(await readBestGranularityRollups("user", "WEIGHT", NaN)).toBeNull();
|
||||
expect(findMany).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("routes a 90-day window to DAY (every coarser floor is too low)", async () => {
|
||||
findMany.mockResolvedValueOnce([bucket("2026-04-01T00:00:00.000Z")]);
|
||||
const result = await readBestGranularityRollups("user", "WEIGHT", 90);
|
||||
expect(result).not.toBeNull();
|
||||
expect(result?.granularity).toBe("DAY");
|
||||
expect(findMany).toHaveBeenCalledTimes(1);
|
||||
expect(findMany.mock.calls[0][0].where.granularity).toBe("DAY");
|
||||
});
|
||||
|
||||
it("routes a 365-day window to MONTH (clears the 62-day MONTH floor)", async () => {
|
||||
findMany.mockResolvedValueOnce([bucket("2026-01-01T00:00:00.000Z")]);
|
||||
const result = await readBestGranularityRollups("user", "WEIGHT", 365);
|
||||
expect(result).not.toBeNull();
|
||||
expect(result?.granularity).toBe("MONTH");
|
||||
expect(findMany).toHaveBeenCalledTimes(1);
|
||||
expect(findMany.mock.calls[0][0].where.granularity).toBe("MONTH");
|
||||
});
|
||||
|
||||
it("routes a 1095-day window to YEAR (clears the 730-day YEAR floor)", async () => {
|
||||
findMany.mockResolvedValueOnce([bucket("2024-01-01T00:00:00.000Z")]);
|
||||
const result = await readBestGranularityRollups("user", "WEIGHT", 1095);
|
||||
expect(result).not.toBeNull();
|
||||
expect(result?.granularity).toBe("YEAR");
|
||||
expect(findMany).toHaveBeenCalledTimes(1);
|
||||
expect(findMany.mock.calls[0][0].where.granularity).toBe("YEAR");
|
||||
});
|
||||
|
||||
it("falls back to MONTH when YEAR has no coverage", async () => {
|
||||
// 1095-day window asks for YEAR first; coverage miss → MONTH.
|
||||
findMany
|
||||
.mockResolvedValueOnce([]) // YEAR miss
|
||||
.mockResolvedValueOnce([bucket("2024-01-01T00:00:00.000Z")]); // MONTH hit
|
||||
|
||||
const result = await readBestGranularityRollups("user", "WEIGHT", 1095);
|
||||
|
||||
expect(result?.granularity).toBe("MONTH");
|
||||
expect(findMany.mock.calls[0][0].where.granularity).toBe("YEAR");
|
||||
expect(findMany.mock.calls[1][0].where.granularity).toBe("MONTH");
|
||||
});
|
||||
|
||||
it("falls all the way through to DAY when every coarser tier misses", async () => {
|
||||
findMany
|
||||
.mockResolvedValueOnce([]) // YEAR miss
|
||||
.mockResolvedValueOnce([]) // MONTH miss
|
||||
.mockResolvedValueOnce([]) // WEEK miss
|
||||
.mockResolvedValueOnce([bucket("2024-01-01T00:00:00.000Z")]); // DAY hit
|
||||
|
||||
const result = await readBestGranularityRollups("user", "WEIGHT", 1095);
|
||||
|
||||
expect(result?.granularity).toBe("DAY");
|
||||
expect(findMany).toHaveBeenCalledTimes(4);
|
||||
});
|
||||
|
||||
it("returns null when no granularity carries any coverage", async () => {
|
||||
findMany.mockResolvedValue([]);
|
||||
const result = await readBestGranularityRollups("user", "WEIGHT", 1095);
|
||||
expect(result).toBeNull();
|
||||
// YEAR, MONTH, WEEK, DAY all probed.
|
||||
expect(findMany).toHaveBeenCalledTimes(4);
|
||||
});
|
||||
});
|
||||
|
||||
describe("aggregateWmyBuckets", () => {
|
||||
it("returns the empty-window shape on no rows", () => {
|
||||
expect(aggregateWmyBuckets([])).toEqual({
|
||||
count: 0,
|
||||
min: null,
|
||||
max: null,
|
||||
mean: null,
|
||||
sum: null,
|
||||
});
|
||||
});
|
||||
|
||||
it("sums count + folds min/max + weights mean across MONTH buckets", () => {
|
||||
// Two MONTH buckets — same compositional contract as DAY because
|
||||
// `count / min / max / mean` are linearly composable across any
|
||||
// bucket granularity.
|
||||
// April: count=10, mean=82, min=79, max=84
|
||||
// May: count=20, mean=80, min=77, max=83
|
||||
// ⇒ totalCount=30, min=77, max=84,
|
||||
// mean = (10×82 + 20×80) / 30 = 80.6666…
|
||||
const rows: RollupBucketRow[] = [
|
||||
bucket("2026-04-01T00:00:00.000Z", {
|
||||
count: 10,
|
||||
mean: 82,
|
||||
minValue: 79,
|
||||
maxValue: 84,
|
||||
}),
|
||||
bucket("2026-05-01T00:00:00.000Z", {
|
||||
count: 20,
|
||||
mean: 80,
|
||||
minValue: 77,
|
||||
maxValue: 83,
|
||||
}),
|
||||
];
|
||||
const result = aggregateWmyBuckets(rows);
|
||||
expect(result.count).toBe(30);
|
||||
expect(result.min).toBe(77);
|
||||
expect(result.max).toBe(84);
|
||||
expect(result.mean).toBeCloseTo((10 * 82 + 20 * 80) / 30, 5);
|
||||
});
|
||||
|
||||
it("sums cumulative sumValue when every bucket carries one", () => {
|
||||
const rows: RollupBucketRow[] = [
|
||||
bucket("2026-04-01T00:00:00.000Z", { sumValue: 12_500 }),
|
||||
bucket("2026-05-01T00:00:00.000Z", { sumValue: 8_200 }),
|
||||
];
|
||||
const result = aggregateWmyBuckets(rows);
|
||||
expect(result.sum).toBe(20_700);
|
||||
});
|
||||
|
||||
it("returns null sum when no bucket carries sumValue (pre-W-SUM data)", () => {
|
||||
const rows: RollupBucketRow[] = [
|
||||
bucket("2026-04-01T00:00:00.000Z", { sumValue: null }),
|
||||
bucket("2026-05-01T00:00:00.000Z", { sumValue: null }),
|
||||
];
|
||||
expect(aggregateWmyBuckets(rows).sum).toBeNull();
|
||||
});
|
||||
|
||||
it("treats sumValue NaN/Infinity as missing", () => {
|
||||
const rows: RollupBucketRow[] = [
|
||||
bucket("2026-04-01T00:00:00.000Z", { sumValue: 100 }),
|
||||
bucket("2026-05-01T00:00:00.000Z", {
|
||||
// simulate a Postgres NaN slipping through serialisation.
|
||||
sumValue: Number.NaN,
|
||||
}),
|
||||
];
|
||||
// Only the finite sumValue contributes.
|
||||
expect(aggregateWmyBuckets(rows).sum).toBe(100);
|
||||
});
|
||||
});
|
||||
|
||||
/**
|
||||
* v1.4.40 W-WMY-WIRE — granularity-routing parity across the v1.4.40
|
||||
* consumers (summaries-slice + health-score-fast-path). Both consumers
|
||||
* now call `readBestGranularityRollups` for their long-window probes;
|
||||
* this pins:
|
||||
* - 90 d → DAY (every coarser floor too high — DAY is canonical
|
||||
* for the trailing quarter regardless of consumer),
|
||||
* - 365 d → MONTH (clears MONTH floor 181 d, short of YEAR floor
|
||||
* 731 d) — the granularity health-score-fast-path's weight long-
|
||||
* window read and summaries-slice's year-ago baseline both
|
||||
* consume,
|
||||
* - 1095 d → YEAR (clears the 731-day YEAR floor) — the v1.5
|
||||
* multi-year trend card target.
|
||||
*
|
||||
* The parity assertion ensures the routing contract is a single
|
||||
* source of truth: any future floor adjustment forces both consumers
|
||||
* to re-pin in lock-step rather than silently diverging.
|
||||
*/
|
||||
describe("readBestGranularityRollups — cross-consumer routing parity", () => {
|
||||
it("pins the 90 / 365 / 1095 day routing targets the consumers depend on", async () => {
|
||||
// Three sequential probes with non-empty results so the router
|
||||
// stops at the first matching tier per window.
|
||||
findMany
|
||||
.mockResolvedValueOnce([bucket("2026-02-15T00:00:00.000Z")]) // 90d → DAY
|
||||
.mockResolvedValueOnce([bucket("2025-08-01T00:00:00.000Z")]) // 365d → MONTH
|
||||
.mockResolvedValueOnce([bucket("2024-01-01T00:00:00.000Z")]); // 1095d → YEAR
|
||||
|
||||
const ninety = await readBestGranularityRollups("user", "WEIGHT", 90);
|
||||
const yearLong = await readBestGranularityRollups("user", "WEIGHT", 365);
|
||||
const threeYear = await readBestGranularityRollups("user", "WEIGHT", 1095);
|
||||
|
||||
expect(ninety?.granularity).toBe("DAY");
|
||||
expect(yearLong?.granularity).toBe("MONTH");
|
||||
expect(threeYear?.granularity).toBe("YEAR");
|
||||
// Each consumer-relevant window only fires one round-trip on the
|
||||
// happy path; the per-tier walk is reserved for coverage-miss
|
||||
// scenarios already pinned above.
|
||||
expect(findMany).toHaveBeenCalledTimes(3);
|
||||
expect(findMany.mock.calls[0][0].where.granularity).toBe("DAY");
|
||||
expect(findMany.mock.calls[1][0].where.granularity).toBe("MONTH");
|
||||
expect(findMany.mock.calls[2][0].where.granularity).toBe("YEAR");
|
||||
});
|
||||
|
||||
it("aggregates MONTH buckets to a byte-identical mean compared to the underlying DAY buckets", async () => {
|
||||
// The compositional contract `count / mean` are linearly
|
||||
// composable across granularities — pin it by simulating "MONTH
|
||||
// routing for a 365-day window" vs "DAY routing for the same
|
||||
// window" against the same underlying counts/means and asserting
|
||||
// the count-weighted mean agrees.
|
||||
//
|
||||
// MONTH bucket (consolidated): count=30, mean=80
|
||||
// DAY buckets (per-day refresh): count=10/mean=82 + count=20/mean=79
|
||||
// ⇒ DAY-derived mean = (10*82 + 20*79) / 30 = 80.0
|
||||
// Both must agree numerically — the routing helper's choice is a
|
||||
// performance optimisation, not a math change.
|
||||
const monthBuckets: RollupBucketRow[] = [
|
||||
bucket("2025-08-01T00:00:00.000Z", { count: 30, mean: 80 }),
|
||||
];
|
||||
const dayBuckets: RollupBucketRow[] = [
|
||||
bucket("2025-08-05T00:00:00.000Z", { count: 10, mean: 82 }),
|
||||
bucket("2025-08-20T00:00:00.000Z", { count: 20, mean: 79 }),
|
||||
];
|
||||
const monthAgg = aggregateWmyBuckets(monthBuckets);
|
||||
const dayAgg = aggregateWmyBuckets(dayBuckets);
|
||||
|
||||
expect(monthAgg.count).toBe(dayAgg.count);
|
||||
expect(monthAgg.mean).toBeCloseTo(dayAgg.mean ?? Number.NaN, 5);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,120 @@
|
||||
/**
|
||||
* v1.4.39 W-SUM — read helpers for cumulative-metric daily sums.
|
||||
*
|
||||
* The v1.4.36 read path consumes the rollup table for spot-metric means
|
||||
* via `rollup-read.ts`. Cumulative HK types (steps, flights, distance,
|
||||
* daylight, active-energy) need the per-day SUM rather than the MEAN —
|
||||
* every row is a partial-day slice from HealthKit, so MEAN understates
|
||||
* the daily total by the per-bucket sample count.
|
||||
*
|
||||
* The v1.4.39 schema scaffolding (migration 0072) added `sum_value` to
|
||||
* `measurement_rollups`. The writer in `rollups.ts` populates it on
|
||||
* every fold (including for non-cumulative types — the cost is one
|
||||
* extra `SUM` in the existing aggregator). The legacy-NULL backfill
|
||||
* runs through `enqueueBootTimeRollupBackfill` so existing rows
|
||||
* converge on the next worker boot.
|
||||
*
|
||||
* Callers fall back to `mean * count` when `sumValue` is null. The
|
||||
* shortcut is mathematically exact for a single source per day:
|
||||
*
|
||||
* sum = mean × count = (Σvalue / count) × count = Σvalue
|
||||
*
|
||||
* Multiple sources for the same `(user, type, day)` mix into the same
|
||||
* bucket today — the source-priority resolution that
|
||||
* `pickCanonicalSourceRows` runs in JS happens AFTER the rollup
|
||||
* aggregate is built. The W8c per-source rollup deferred to v1.5 fixes
|
||||
* that; until then, the cumulative read paths trust the bucket sum as
|
||||
* the canonical daily total and the iOS drain (which collapses per
|
||||
* source via `dailyStatsExternalId`) keeps Marc's tenant on the
|
||||
* single-source-per-day path.
|
||||
*/
|
||||
import { prisma } from "@/lib/db";
|
||||
import type { MeasurementType } from "@/generated/prisma/client";
|
||||
import { CUMULATIVE_HK_TYPES } from "@/lib/measurements/apple-health-mapping";
|
||||
|
||||
/**
|
||||
* Cumulative measurement types the rollup `sum_value` column serves.
|
||||
* Re-exported from the canonical Apple Health mapping so the
|
||||
* consumer-side gate stays in one place.
|
||||
*
|
||||
* Audit anchor: `.planning/round-v1438-perf-analysis.md` §3
|
||||
* "Cumulative daily sums" + §5 P3.
|
||||
*/
|
||||
export type CumulativeType =
|
||||
| "ACTIVITY_STEPS"
|
||||
| "ACTIVE_ENERGY_BURNED"
|
||||
| "FLIGHTS_CLIMBED"
|
||||
| "WALKING_RUNNING_DISTANCE"
|
||||
| "TIME_IN_DAYLIGHT";
|
||||
|
||||
/**
|
||||
* `true` when `type` is one of the cumulative HK types whose daily
|
||||
* total the rollup `sum_value` column carries.
|
||||
*/
|
||||
export function isCumulativeType(type: MeasurementType): type is CumulativeType {
|
||||
return CUMULATIVE_HK_TYPES.has(type);
|
||||
}
|
||||
|
||||
/** One DAY-bucket row read from `measurement_rollups`. */
|
||||
export interface CumulativeDaySumRow {
|
||||
bucketStart: Date;
|
||||
/**
|
||||
* Per-bucket SUM. `null` only when the bucket pre-dates the v1.4.39
|
||||
* writer change AND the boot-time backfill has not yet converged on
|
||||
* this user. Callers fall back to `mean * count` for the null case.
|
||||
*/
|
||||
sumValue: number | null;
|
||||
count: number;
|
||||
mean: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Read every DAY bucket for `(userId, type)` since `since`. Returns
|
||||
* rows ascending by `bucketStart`. Pre-v1.4.39 rows surface here with
|
||||
* `sumValue = null`; the caller decides whether to fall back to
|
||||
* `mean * count` or skip them.
|
||||
*
|
||||
* Bounded to the cumulative-type set so a misuse (passing a spot
|
||||
* metric) is a type error rather than a silent SUM on the wrong
|
||||
* column. The query is a plain `findMany` against the
|
||||
* `(userId, type, granularity, bucketStart)` composite primary key —
|
||||
* single round-trip, fully indexed.
|
||||
*/
|
||||
export async function readCumulativeDaySums(
|
||||
userId: string,
|
||||
type: CumulativeType,
|
||||
since: Date,
|
||||
): Promise<CumulativeDaySumRow[]> {
|
||||
const rows = await prisma.measurementRollup.findMany({
|
||||
where: {
|
||||
userId,
|
||||
type: type as MeasurementType,
|
||||
granularity: "DAY",
|
||||
bucketStart: { gte: since },
|
||||
},
|
||||
orderBy: { bucketStart: "asc" },
|
||||
select: {
|
||||
bucketStart: true,
|
||||
sumValue: true,
|
||||
count: true,
|
||||
mean: true,
|
||||
},
|
||||
});
|
||||
return rows.map((r) => ({
|
||||
bucketStart: r.bucketStart,
|
||||
sumValue: r.sumValue,
|
||||
count: r.count,
|
||||
mean: r.mean,
|
||||
}));
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve a per-bucket cumulative total. Reads `sumValue` when the
|
||||
* v1.4.39 writer has populated it; falls back to `mean * count` for
|
||||
* legacy NULL rows so the chart never paints a hole during the boot-
|
||||
* backfill convergence window.
|
||||
*/
|
||||
export function resolveBucketSum(row: CumulativeDaySumRow): number {
|
||||
if (row.sumValue !== null) return row.sumValue;
|
||||
return row.mean * row.count;
|
||||
}
|
||||
@@ -0,0 +1,290 @@
|
||||
/**
|
||||
* v1.4.39 W-WMY — WEEK / MONTH / YEAR rollup readers.
|
||||
*
|
||||
* Background — the read-side gap
|
||||
* ------------------------------
|
||||
* Every measurement write fans out via `recomputeBucketsForMeasurement`
|
||||
* into a synchronous DAY upsert plus pg-boss-queued WEEK / MONTH / YEAR
|
||||
* recomputes. The boot-time backfill (`enqueueBootTimeRollupBackfill`)
|
||||
* mints the full WEEK / MONTH / YEAR history once per uncovered user.
|
||||
*
|
||||
* As of v1.4.38 the only reader that consults `measurement_rollups`
|
||||
* (`rollup-read.ts`, plus the per-fast-path branches in
|
||||
* `summaries-slice`, `comprehensive-aggregator`, etc.) caps at DAY and
|
||||
* a trailing 90-day window. The WEEK / MONTH / YEAR buckets sit in
|
||||
* Postgres as pure write amplification — populated every write,
|
||||
* surfaced nowhere on read. The v1.4.38 perf audit
|
||||
* (`.planning/round-v1438-perf-analysis.md` §2 + §5 P6) calls this out
|
||||
* as the largest unused investment in the rollup tier.
|
||||
*
|
||||
* What this module adds
|
||||
* ---------------------
|
||||
* Helpers that read the trailing N-bucket window for a single
|
||||
* `(userId, type)` pair at a chosen granularity, plus an auto-router
|
||||
* that picks the largest granularity that still resolves the requested
|
||||
* window. The shape returned is identical to `readRollupBuckets` so
|
||||
* callers can interleave WEEK / MONTH / YEAR rows with DAY rows
|
||||
* downstream without branching on the source granularity.
|
||||
*
|
||||
* Compositional contract
|
||||
* ----------------------
|
||||
* `count / min / max / mean / sumValue` are linearly composable across
|
||||
* any granularity — aggregating these stats over WEEK buckets returns
|
||||
* the same numbers as aggregating the underlying DAY buckets or the
|
||||
* raw measurements. `sd / slope / r2` are NOT linearly composable; the
|
||||
* routed callers either fall back to live SQL for those or accept the
|
||||
* per-bucket stat as-is. The auto-router is a granularity selector
|
||||
* only — it does not attempt to reconstruct slope across coarser
|
||||
* buckets.
|
||||
*
|
||||
* Coverage-miss semantics
|
||||
* -----------------------
|
||||
* Each reader returns `null` when the requested granularity yields
|
||||
* zero rows for `(userId, type, since)`. The caller decides whether
|
||||
* that is a real "no data" case (the user has not logged this type in
|
||||
* the window) or a coverage miss the boot-backfill / worker has not
|
||||
* caught up on. The default policy is to fall back to a finer
|
||||
* granularity (MONTH → WEEK → DAY) before giving up — see
|
||||
* `readBestGranularityRollups`.
|
||||
*
|
||||
* Scope vs. `rollup-read.ts`
|
||||
* --------------------------
|
||||
* `rollup-read.ts` carries the existing DAY-only aggregator. This
|
||||
* module is deliberately separate so the WEEK / MONTH / YEAR wiring
|
||||
* is reviewable in isolation and so the v1.4.39 W-SUM agent's
|
||||
* concurrent edits to the writer side don't collide with the reader
|
||||
* additions.
|
||||
*/
|
||||
import type {
|
||||
MeasurementType,
|
||||
RollupGranularity,
|
||||
} from "@/generated/prisma/client";
|
||||
|
||||
import { prisma } from "@/lib/db";
|
||||
|
||||
/**
|
||||
* Normalised bucket row returned by every WMY reader. Mirrors the
|
||||
* shape `readRollupBuckets` returns plus the `sumValue` column the
|
||||
* v1.4.39 W-SUM agent added to `MeasurementRollup`. `sumValue` is
|
||||
* `null` for rows that pre-date the column's introduction; the boot
|
||||
* backfill fills it in alongside the other stats.
|
||||
*/
|
||||
export interface RollupBucketRow {
|
||||
bucketStart: Date;
|
||||
count: number;
|
||||
mean: number;
|
||||
sd: number | null;
|
||||
slope: number | null;
|
||||
r2: number | null;
|
||||
sumValue: number | null;
|
||||
minValue: number;
|
||||
maxValue: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Per-granularity "this is the smallest window the granularity can
|
||||
* meaningfully resolve" floor. Used by `readBestGranularityRollups`
|
||||
* to route a requested window into the coarsest tier that still
|
||||
* carries enough buckets for the caller to do something useful.
|
||||
*
|
||||
* - DAY → any window — 90 daily buckets for a 90-day window
|
||||
* is already trivially cheap and the trend resolution
|
||||
* is canonical
|
||||
* - WEEK → > 90 days (~13 weekly buckets for a quarter)
|
||||
* - MONTH → > 180 days (~6 monthly buckets, enough trend signal
|
||||
* for a half-year view; smaller windows benefit more
|
||||
* from DAY-bucket granularity than coarse-grained
|
||||
* averaging)
|
||||
* - YEAR → > 730 days (≥ 2 yearly buckets — anything below 2 y
|
||||
* collapses to one bucket and carries no slope signal)
|
||||
*
|
||||
* The pinned routing the v1.5 multi-year trend card relies on:
|
||||
* 90 d → DAY (90 buckets)
|
||||
* 365 d → MONTH (12 buckets)
|
||||
* 1095 d → YEAR (3 buckets)
|
||||
*
|
||||
* The floors are conservative on purpose — coarser tiers only
|
||||
* activate when the row-count savings actually justify trading the
|
||||
* finer trend resolution.
|
||||
*/
|
||||
const GRANULARITY_FLOORS: Array<{
|
||||
granularity: RollupGranularity;
|
||||
minWindowDays: number;
|
||||
}> = [
|
||||
{ granularity: "YEAR", minWindowDays: 731 },
|
||||
{ granularity: "MONTH", minWindowDays: 181 },
|
||||
{ granularity: "WEEK", minWindowDays: 91 },
|
||||
{ granularity: "DAY", minWindowDays: 0 },
|
||||
];
|
||||
|
||||
/**
|
||||
* Read the trailing WEEK buckets for `(userId, type)` since `since`.
|
||||
* Returns `null` when no buckets exist in the window — the caller
|
||||
* decides whether to fall back to a finer granularity or to live SQL.
|
||||
*/
|
||||
export async function readWeekRollups(
|
||||
userId: string,
|
||||
type: MeasurementType,
|
||||
since: Date,
|
||||
): Promise<RollupBucketRow[] | null> {
|
||||
return readGranularity(userId, type, "WEEK", since);
|
||||
}
|
||||
|
||||
/**
|
||||
* Read the trailing MONTH buckets for `(userId, type)` since `since`.
|
||||
* Returns `null` on coverage miss.
|
||||
*/
|
||||
export async function readMonthRollups(
|
||||
userId: string,
|
||||
type: MeasurementType,
|
||||
since: Date,
|
||||
): Promise<RollupBucketRow[] | null> {
|
||||
return readGranularity(userId, type, "MONTH", since);
|
||||
}
|
||||
|
||||
/**
|
||||
* Read the trailing YEAR buckets for `(userId, type)` since `since`.
|
||||
* Returns `null` on coverage miss.
|
||||
*/
|
||||
export async function readYearRollups(
|
||||
userId: string,
|
||||
type: MeasurementType,
|
||||
since: Date,
|
||||
): Promise<RollupBucketRow[] | null> {
|
||||
return readGranularity(userId, type, "YEAR", since);
|
||||
}
|
||||
|
||||
/**
|
||||
* Pick the largest granularity that can still resolve the requested
|
||||
* `windowDays` window — WEEK for >14 d, MONTH for >62 d, YEAR for
|
||||
* >730 d. Falls back to a finer granularity on coverage miss so a
|
||||
* user with WEEK / MONTH coverage but no YEAR buckets (e.g. a tenant
|
||||
* who joined less than two years ago) still gets a usable trend
|
||||
* series.
|
||||
*
|
||||
* Returns the granularity the helper resolved against plus the row
|
||||
* shape `readWeekRollups` / `readMonthRollups` / `readYearRollups`
|
||||
* return. `null` when no granularity yields any buckets in the
|
||||
* window — the caller is expected to short-circuit to "no data" or
|
||||
* to live SQL.
|
||||
*/
|
||||
export async function readBestGranularityRollups(
|
||||
userId: string,
|
||||
type: MeasurementType,
|
||||
windowDays: number,
|
||||
): Promise<{
|
||||
granularity: RollupGranularity;
|
||||
rows: RollupBucketRow[];
|
||||
} | null> {
|
||||
if (!Number.isFinite(windowDays) || windowDays <= 0) return null;
|
||||
const since = new Date(Date.now() - windowDays * 24 * 60 * 60 * 1000);
|
||||
// Walk the floors from coarsest to finest and return the first
|
||||
// granularity whose floor the window clears AND which has coverage
|
||||
// for `(userId, type, since)`. The `if rows == null` fall-through
|
||||
// is what makes the helper resilient to partial coverage.
|
||||
for (const floor of GRANULARITY_FLOORS) {
|
||||
if (windowDays < floor.minWindowDays) continue;
|
||||
const rows = await readGranularity(userId, type, floor.granularity, since);
|
||||
if (rows && rows.length > 0) {
|
||||
return { granularity: floor.granularity, rows };
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Linearly compose `count / min / max / mean / sum` across an array
|
||||
* of bucket rows. Mirrors `rollup-read.ts:aggregateBuckets` but
|
||||
* carries `sumValue` so cumulative-metric callers (steps, energy,
|
||||
* distance) can read the window total without re-deriving from
|
||||
* `mean * count`. SD / slope / r2 are intentionally omitted — those
|
||||
* stats do not compose across coarser buckets and the consumers that
|
||||
* need them stay on live SQL.
|
||||
*/
|
||||
export function aggregateWmyBuckets(rows: RollupBucketRow[]): {
|
||||
count: number;
|
||||
min: number | null;
|
||||
max: number | null;
|
||||
mean: number | null;
|
||||
sum: number | null;
|
||||
} {
|
||||
if (rows.length === 0) {
|
||||
return { count: 0, min: null, max: null, mean: null, sum: null };
|
||||
}
|
||||
let totalCount = 0;
|
||||
let sumWeighted = 0;
|
||||
let sumCumulative = 0;
|
||||
let sawSum = false;
|
||||
let min = Infinity;
|
||||
let max = -Infinity;
|
||||
for (const row of rows) {
|
||||
totalCount += row.count;
|
||||
sumWeighted += row.count * row.mean;
|
||||
if (row.sumValue !== null && Number.isFinite(row.sumValue)) {
|
||||
sumCumulative += row.sumValue;
|
||||
sawSum = true;
|
||||
}
|
||||
if (row.minValue < min) min = row.minValue;
|
||||
if (row.maxValue > max) max = row.maxValue;
|
||||
}
|
||||
if (totalCount === 0) {
|
||||
return { count: 0, min: null, max: null, mean: null, sum: null };
|
||||
}
|
||||
return {
|
||||
count: totalCount,
|
||||
min: Number.isFinite(min) ? min : null,
|
||||
max: Number.isFinite(max) ? max : null,
|
||||
mean: sumWeighted / totalCount,
|
||||
sum: sawSum ? sumCumulative : null,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Internal — shared `findMany` projection. Returns `null` when the
|
||||
* window has zero rows so the caller can branch on coverage miss
|
||||
* without a separate count round-trip.
|
||||
*/
|
||||
async function readGranularity(
|
||||
userId: string,
|
||||
type: MeasurementType,
|
||||
granularity: RollupGranularity,
|
||||
since: Date,
|
||||
): Promise<RollupBucketRow[] | null> {
|
||||
// Bounded `findMany`: `(userId, type, granularity, bucketStart)`
|
||||
// is the composite primary key so the planner picks the index path
|
||||
// every time. `bucketStart >= since` is the same shape
|
||||
// `readRollupBuckets` uses; we don't carry an upper bound because
|
||||
// the helpers are always reading "trailing window to now".
|
||||
const rows = await prisma.measurementRollup.findMany({
|
||||
where: {
|
||||
userId,
|
||||
type,
|
||||
granularity,
|
||||
bucketStart: { gte: since },
|
||||
},
|
||||
orderBy: { bucketStart: "asc" },
|
||||
select: {
|
||||
bucketStart: true,
|
||||
count: true,
|
||||
mean: true,
|
||||
sd: true,
|
||||
slope: true,
|
||||
r2: true,
|
||||
sumValue: true,
|
||||
minValue: true,
|
||||
maxValue: true,
|
||||
},
|
||||
});
|
||||
if (rows.length === 0) return null;
|
||||
return rows.map((r) => ({
|
||||
bucketStart: r.bucketStart,
|
||||
count: r.count,
|
||||
mean: r.mean,
|
||||
sd: r.sd,
|
||||
slope: r.slope,
|
||||
r2: r.r2,
|
||||
sumValue: r.sumValue,
|
||||
minValue: r.minValue,
|
||||
maxValue: r.maxValue,
|
||||
}));
|
||||
}
|
||||
Reference in new issue
Block a user