mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-16 23:33:29 +00:00
feat(labs): add structured lab-result store with /api/labs CRUD
Record discrete biomarker readings (HbA1c, LDL, ferritin, TSH, …) with their value, unit, reference range and sample date. The store pairs with the annual blood-panel reminder, which until now had nowhere to record the result it reminds the user to obtain. The list/create/update/delete endpoints narrow userId from the session, build the write data field-by-field, soft-delete via deletedAt, and encrypt the optional note at rest. A neutral three-state reference-range classifier (in-range / below / above / unknown) is computed server-side so every surface renders the same calm verdict. findLatestLabResultForAnalytes exposes the read point the blood-panel reminder consults to mark itself satisfied, without coupling the two.
This commit is contained in:
1 parent
111fa7a323
commit
271cc0dcfa
7 files changed
+825
No files matched your search
@@ -0,0 +1,174 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
|
||||
import {
|
||||
classifyReferenceRange,
|
||||
createLabResultSchema,
|
||||
listLabResultsSchema,
|
||||
updateLabResultSchema,
|
||||
} from "../labs";
|
||||
|
||||
const FUTURE = new Date(Date.now() + 60 * 60 * 1000).toISOString();
|
||||
const RECENT = new Date(Date.now() - 60 * 60 * 1000).toISOString();
|
||||
|
||||
describe("createLabResultSchema", () => {
|
||||
it("accepts a minimal valid reading", () => {
|
||||
const r = createLabResultSchema.safeParse({
|
||||
analyte: "HbA1c",
|
||||
value: 5.4,
|
||||
unit: "%",
|
||||
takenAt: RECENT,
|
||||
});
|
||||
expect(r.success).toBe(true);
|
||||
});
|
||||
|
||||
it("normalises a backdatable takenAt to a Date", () => {
|
||||
const r = createLabResultSchema.safeParse({
|
||||
analyte: "LDL",
|
||||
value: 110,
|
||||
unit: "mg/dL",
|
||||
takenAt: RECENT,
|
||||
});
|
||||
expect(r.success).toBe(true);
|
||||
if (r.success) expect(r.data.takenAt).toBeInstanceOf(Date);
|
||||
});
|
||||
|
||||
it("rejects a future takenAt", () => {
|
||||
const r = createLabResultSchema.safeParse({
|
||||
analyte: "LDL",
|
||||
value: 110,
|
||||
unit: "mg/dL",
|
||||
takenAt: FUTURE,
|
||||
});
|
||||
expect(r.success).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects an empty analyte", () => {
|
||||
const r = createLabResultSchema.safeParse({
|
||||
analyte: " ",
|
||||
value: 1,
|
||||
unit: "%",
|
||||
takenAt: RECENT,
|
||||
});
|
||||
expect(r.success).toBe(false);
|
||||
});
|
||||
|
||||
it("rejects a transposed reference range (low > high)", () => {
|
||||
const r = createLabResultSchema.safeParse({
|
||||
analyte: "Ferritin",
|
||||
value: 50,
|
||||
unit: "ng/mL",
|
||||
referenceLow: 300,
|
||||
referenceHigh: 30,
|
||||
takenAt: RECENT,
|
||||
});
|
||||
expect(r.success).toBe(false);
|
||||
});
|
||||
|
||||
it("accepts a single (upper-only) reference bound", () => {
|
||||
const r = createLabResultSchema.safeParse({
|
||||
analyte: "LDL",
|
||||
value: 110,
|
||||
unit: "mg/dL",
|
||||
referenceHigh: 116,
|
||||
takenAt: RECENT,
|
||||
});
|
||||
expect(r.success).toBe(true);
|
||||
});
|
||||
|
||||
it("normalises an empty-string panel to undefined", () => {
|
||||
const r = createLabResultSchema.safeParse({
|
||||
analyte: "TSH",
|
||||
value: 2,
|
||||
unit: "mIU/L",
|
||||
panel: "",
|
||||
takenAt: RECENT,
|
||||
});
|
||||
expect(r.success).toBe(true);
|
||||
if (r.success) expect(r.data.panel).toBeUndefined();
|
||||
});
|
||||
|
||||
it("rejects a non-finite value", () => {
|
||||
const r = createLabResultSchema.safeParse({
|
||||
analyte: "LDL",
|
||||
value: Number.POSITIVE_INFINITY,
|
||||
unit: "mg/dL",
|
||||
takenAt: RECENT,
|
||||
});
|
||||
expect(r.success).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("updateLabResultSchema", () => {
|
||||
it("accepts an explicit null to clear panel + note", () => {
|
||||
const r = updateLabResultSchema.safeParse({ panel: null, note: null });
|
||||
expect(r.success).toBe(true);
|
||||
if (r.success) {
|
||||
expect(r.data.panel).toBeNull();
|
||||
expect(r.data.note).toBeNull();
|
||||
}
|
||||
});
|
||||
|
||||
it("accepts a partial value-only edit", () => {
|
||||
const r = updateLabResultSchema.safeParse({ value: 5.6 });
|
||||
expect(r.success).toBe(true);
|
||||
});
|
||||
|
||||
it("still enforces the range order when both bounds are supplied", () => {
|
||||
const r = updateLabResultSchema.safeParse({
|
||||
referenceLow: 10,
|
||||
referenceHigh: 1,
|
||||
});
|
||||
expect(r.success).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("listLabResultsSchema", () => {
|
||||
it("defaults limit/offset/sortDir", () => {
|
||||
const r = listLabResultsSchema.safeParse({});
|
||||
expect(r.success).toBe(true);
|
||||
if (r.success) {
|
||||
expect(r.data.limit).toBe(100);
|
||||
expect(r.data.offset).toBe(0);
|
||||
expect(r.data.sortDir).toBe("desc");
|
||||
}
|
||||
});
|
||||
|
||||
it("caps limit at 500", () => {
|
||||
const r = listLabResultsSchema.safeParse({ limit: "9999" });
|
||||
expect(r.success).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("classifyReferenceRange", () => {
|
||||
it("returns unknown when no bounds are given", () => {
|
||||
expect(classifyReferenceRange(5, null, null)).toBe("unknown");
|
||||
expect(classifyReferenceRange(5, undefined, undefined)).toBe("unknown");
|
||||
});
|
||||
|
||||
it("returns in-range inside both bounds", () => {
|
||||
expect(classifyReferenceRange(5, 4, 6)).toBe("in-range");
|
||||
});
|
||||
|
||||
it("treats the bounds as inclusive", () => {
|
||||
expect(classifyReferenceRange(4, 4, 6)).toBe("in-range");
|
||||
expect(classifyReferenceRange(6, 4, 6)).toBe("in-range");
|
||||
});
|
||||
|
||||
it("returns below when under the low bound", () => {
|
||||
expect(classifyReferenceRange(3.9, 4, 6)).toBe("below");
|
||||
});
|
||||
|
||||
it("returns above when over the high bound", () => {
|
||||
expect(classifyReferenceRange(6.1, 4, 6)).toBe("above");
|
||||
});
|
||||
|
||||
it("classifies against a single upper bound", () => {
|
||||
expect(classifyReferenceRange(120, null, 116)).toBe("above");
|
||||
expect(classifyReferenceRange(100, null, 116)).toBe("in-range");
|
||||
});
|
||||
|
||||
it("classifies against a single lower bound", () => {
|
||||
expect(classifyReferenceRange(8, 10, null)).toBe("below");
|
||||
expect(classifyReferenceRange(12, 10, null)).toBe("in-range");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,169 @@
|
||||
/**
|
||||
* v1.17.1 — structured lab-result store.
|
||||
*
|
||||
* A minimal, generic `LabResult` capture path: a self-hoster records a
|
||||
* biomarker reading (HbA1c, LDL, ferritin, TSH, …) with its value, unit,
|
||||
* the lab's reference range, and the sample date. Pairs with the v1.17.1
|
||||
* Vorsorge annual-blood-panel reminder, which otherwise has nowhere to
|
||||
* record the result it reminds the user to obtain.
|
||||
*
|
||||
* The model is intentionally free-form on `analyte` + `unit` (no closed
|
||||
* LOINC enum): a lab report prints whatever name and unit it likes, and a
|
||||
* forced taxonomy would reject real-world values. The optional `panel`
|
||||
* groups analytes that arrived together (e.g. "Großes Blutbild").
|
||||
*/
|
||||
import { z } from "zod/v4";
|
||||
|
||||
import { validateEntryInstant } from "@/lib/validations/entry-instant";
|
||||
|
||||
/**
|
||||
* Far-past floor for a lab sample. A self-hoster legitimately backdates an
|
||||
* old paper report, so the window is generous (50 years) but still rejects
|
||||
* epoch-zero / corrupted-import instants via the shared 1900 floor.
|
||||
*/
|
||||
const LAB_TAKEN_AT_MAX_AGE_MS = 50 * 365.25 * 24 * 60 * 60 * 1000;
|
||||
|
||||
/** Shared `takenAt` field: ISO string → Date, plausibility-bounded. */
|
||||
const takenAtField = validateEntryInstant(
|
||||
z
|
||||
.string()
|
||||
.datetime({ message: "takenAt must be an ISO 8601 datetime" })
|
||||
.transform((s) => new Date(s)),
|
||||
{
|
||||
maxAgeMs: LAB_TAKEN_AT_MAX_AGE_MS,
|
||||
pastMessage: "Sample date is too far in the past",
|
||||
},
|
||||
);
|
||||
|
||||
/** Trimmed, bounded free-text field with a min-length guard. */
|
||||
const requiredText = (max: number) =>
|
||||
z
|
||||
.string()
|
||||
.trim()
|
||||
.min(1)
|
||||
.max(max);
|
||||
|
||||
const optionalPanel = z
|
||||
.string()
|
||||
.trim()
|
||||
.min(1)
|
||||
.max(120)
|
||||
.optional()
|
||||
// An empty-string panel is normalised to "no panel" so the grouping
|
||||
// stays NULL-distinct rather than carrying a blank label.
|
||||
.or(z.literal("").transform(() => undefined));
|
||||
|
||||
const optionalNote = z
|
||||
.string()
|
||||
.trim()
|
||||
.max(2000)
|
||||
.optional()
|
||||
.or(z.literal("").transform(() => undefined));
|
||||
|
||||
/**
|
||||
* Reference bounds are independently optional (a lab may report only an
|
||||
* upper bound, e.g. LDL < 116). When BOTH are present the low bound must
|
||||
* not exceed the high bound — a transposed range is a client error.
|
||||
*/
|
||||
const referenceLow = z.number().finite().optional();
|
||||
const referenceHigh = z.number().finite().optional();
|
||||
|
||||
export const createLabResultSchema = z
|
||||
.object({
|
||||
panel: optionalPanel,
|
||||
analyte: requiredText(120),
|
||||
value: z.number().finite(),
|
||||
unit: requiredText(40),
|
||||
referenceLow,
|
||||
referenceHigh,
|
||||
takenAt: takenAtField,
|
||||
note: optionalNote,
|
||||
})
|
||||
.refine(
|
||||
(d) =>
|
||||
d.referenceLow === undefined ||
|
||||
d.referenceHigh === undefined ||
|
||||
d.referenceLow <= d.referenceHigh,
|
||||
{
|
||||
message: "referenceLow must not exceed referenceHigh",
|
||||
path: ["referenceLow"],
|
||||
},
|
||||
);
|
||||
|
||||
export type CreateLabResultInput = z.infer<typeof createLabResultSchema>;
|
||||
|
||||
/**
|
||||
* Update schema: every field optional (partial edit). `panel` and `note`
|
||||
* accept an explicit `null` to clear the stored value — distinct from an
|
||||
* omitted key, which leaves the column untouched.
|
||||
*/
|
||||
export const updateLabResultSchema = z
|
||||
.object({
|
||||
panel: optionalPanel.or(z.null()),
|
||||
analyte: requiredText(120).optional(),
|
||||
value: z.number().finite().optional(),
|
||||
unit: requiredText(40).optional(),
|
||||
referenceLow: referenceLow.or(z.null()),
|
||||
referenceHigh: referenceHigh.or(z.null()),
|
||||
takenAt: takenAtField.optional(),
|
||||
note: optionalNote.or(z.null()),
|
||||
})
|
||||
.refine(
|
||||
(d) =>
|
||||
d.referenceLow === undefined ||
|
||||
d.referenceLow === null ||
|
||||
d.referenceHigh === undefined ||
|
||||
d.referenceHigh === null ||
|
||||
d.referenceLow <= d.referenceHigh,
|
||||
{
|
||||
message: "referenceLow must not exceed referenceHigh",
|
||||
path: ["referenceLow"],
|
||||
},
|
||||
);
|
||||
|
||||
export type UpdateLabResultInput = z.infer<typeof updateLabResultSchema>;
|
||||
|
||||
/** List query: filter by analyte (exact) + date range, paginate. */
|
||||
export const listLabResultsSchema = z.object({
|
||||
analyte: z.string().trim().min(1).max(120).optional(),
|
||||
panel: z.string().trim().min(1).max(120).optional(),
|
||||
from: z
|
||||
.string()
|
||||
.datetime()
|
||||
.transform((s) => new Date(s))
|
||||
.optional(),
|
||||
to: z
|
||||
.string()
|
||||
.datetime()
|
||||
.transform((s) => new Date(s))
|
||||
.optional(),
|
||||
limit: z.coerce.number().int().min(1).max(500).default(100),
|
||||
offset: z.coerce.number().int().min(0).default(0),
|
||||
sortDir: z.enum(["asc", "desc"]).default("desc"),
|
||||
});
|
||||
|
||||
export type ListLabResultsInput = z.infer<typeof listLabResultsSchema>;
|
||||
|
||||
/**
|
||||
* Reference-range classification. Deliberately a three-state, NEUTRAL
|
||||
* verdict — the badge that renders it must stay calm and informative, NOT
|
||||
* alarming (no red "out of range" tint). `"unknown"` when the lab reported
|
||||
* no usable bounds.
|
||||
*
|
||||
* Bounds are treated as inclusive: a value exactly on the reference limit
|
||||
* reads as in-range, matching how labs print "≤" / "≥" reference notation.
|
||||
*/
|
||||
export type ReferenceRangeStatus = "in-range" | "below" | "above" | "unknown";
|
||||
|
||||
export function classifyReferenceRange(
|
||||
value: number,
|
||||
referenceLow: number | null | undefined,
|
||||
referenceHigh: number | null | undefined,
|
||||
): ReferenceRangeStatus {
|
||||
const hasLow = referenceLow !== null && referenceLow !== undefined;
|
||||
const hasHigh = referenceHigh !== null && referenceHigh !== undefined;
|
||||
if (!hasLow && !hasHigh) return "unknown";
|
||||
if (hasLow && value < (referenceLow as number)) return "below";
|
||||
if (hasHigh && value > (referenceHigh as number)) return "above";
|
||||
return "in-range";
|
||||
}
|
||||
Reference in new issue
Block a user