fix(labs): read unitless specific gravity, pH and INR, and any lab category spelling

A urinalysis sent its specific gravity and pH as bare numbers, which
failed as missing_unit and made a normal report a partial success. A
number without a unit is now the unity "1" when its LOINC code names a
specific gravity, a pH or an INR; any other analyte keeps the refusal.

The category check took only FHIR's own "laboratory" and skipped
records a system filed as "LAB" or "Lab Results", although Apple
Health had already classified them as lab results. A code, display or
text containing "lab" now counts; other categories are still skipped.
This commit is contained in:
Marc-André Bombeck committed 2026-11-17 21:28:03 +01:00
1 parent d1db4e59cb
commit 6aad42a384
6 files changed
+124 -19

No files matched your search

@@ -196,6 +196,63 @@ describe("mapFhirLabRecord — R4", () => {
expect(map(resource)).toMatchObject({ kind: "fail", reason });
});
describe("a number printed without a unit", () => {
const loinc = (code: string, text: string) => ({
text,
coding: [{ system: "http://loinc.org", code }],
});
it.each([
["urine specific gravity", loinc("5811-5", "Specific Gravity"), 1.015],
["urine pH", loinc("5803-2", "pH, Urine"), 6],
["INR", loinc("6301-6", "INR"), 1.1],
])("is the unity for %s", (_label, code, value) => {
const r = reading(map(base({ code, valueQuantity: { value } })));
expect(r.value).toBe(value);
expect(r.unit).toBe("1");
});
it("is the unity for a dimensionless integer", () => {
const r = reading(
map(
base({
code: loinc("2756-5", "pH"),
valueQuantity: undefined,
valueInteger: 7,
}),
),
);
expect(r.value).toBe(7);
expect(r.unit).toBe("1");
});
it("still fails for an analyte that has a unit", () => {
expect(
map(
base({
code: loinc("2951-2", "Sodium"),
valueQuantity: { value: 140 },
}),
),
).toMatchObject({ kind: "fail", reason: "missing_unit" });
});
});
it.each([
[{ coding: [{ code: "LAB" }] }],
[{ coding: [{ code: "lab" }] }],
[{ coding: [{ code: "x", display: "Lab Results" }] }],
[{ text: "Laboratory results" }],
])("reads a lab category however the source spells it: %j", (category) => {
expect(map(base({ category: [category] })).kind).toBe("reading");
});
it("still skips a category that is not a lab", () => {
expect(
map(base({ category: [{ coding: [{ code: "vital-signs" }] }] })),
).toMatchObject({ kind: "skip", reason: "not_lab" });
});
it("accepts a resource with no category", () => {
expect(map(base({ category: undefined })).kind).toBe("reading");
});
+28 -10
View File
@@ -30,6 +30,7 @@ import {
parseReferenceRange,
SOURCE_REFERENCE_TEXT_MAX,
} from "@/lib/labs/parse-reference-range";
import { DIMENSIONLESS_UNIT } from "@/lib/labs/dimensionless";
import { LAB_TEXT_LIMITS } from "@/lib/labs/reading-keys";
import { sameLabUnit } from "@/lib/labs/unit-normalise";
@@ -40,7 +41,7 @@ import type {
FhirLabSkipReason,
MappedFhirLab,
} from "./types";
import { labUnitFromFhirQuantity } from "./units";
import { isDimensionlessLoinc, labUnitFromFhirQuantity } from "./units";
/** A reading dated more than a day ahead is a mistake, not a result. */
const FUTURE_SLACK_MS = 86_400_000;
@@ -122,11 +123,20 @@ function memberRefs(resource: Json): string[] {
return refs;
}
/**
* Whether a category names lab results. FHIR's own code is "laboratory", but
* a record reaches the import only because Apple Health already filed it as
* a lab result (or the phone sends lab records alone), and systems spell the
* category their own way ("LAB", "Lab Results"). Any code, display or text
* naming a lab counts; a record whose categories are all something else (vital
* signs, say) is still left out.
*/
function isLaboratory(concept: Json): boolean {
if (str(concept.text)?.toLowerCase() === "laboratory") return true;
return codings(concept).some(
(c) => str(c.code)?.toLowerCase() === "laboratory",
);
const names = [
str(concept.text),
...codings(concept).flatMap((c) => [str(c.code), str(c.display)]),
];
return names.some((name) => name !== null && /lab/i.test(name));
}
function analyteName(code: Json | null): string | null {
@@ -229,12 +239,18 @@ type ValueRead =
| { ok: false; skip?: FhirLabSkipReason; fail?: FhirLabFailureReason }
| null;
function readValue(resource: Json): ValueRead {
/**
* `dimensionless` says the analyte's value has no unit (its LOINC code is a
* specific gravity, a pH or an INR): a bare number is then the unity "1"
* rather than a number whose unit was dropped.
*/
function readValue(resource: Json, dimensionless: boolean): ValueRead {
const bare = dimensionless ? DIMENSIONLESS_UNIT : null;
const quantity = obj(resource.valueQuantity);
if (quantity) {
const value = num(quantity.value);
if (value === null) return { ok: false, skip: "no_value" };
const unit = labUnitFromFhirQuantity(quantity);
const unit = labUnitFromFhirQuantity(quantity) ?? bare;
const comparator = str(quantity.comparator);
if (comparator) {
const printed =
@@ -247,7 +263,9 @@ function readValue(resource: Json): ValueRead {
return { ok: true, value, valueText: null, unit };
}
if (Number.isSafeInteger(resource.valueInteger)) {
return { ok: false, fail: "missing_unit" };
if (!bare) return { ok: false, fail: "missing_unit" };
const value = resource.valueInteger as number;
return { ok: true, value, valueText: null, unit: bare };
}
const text = str(resource.valueString);
if (text) return { ok: true, value: null, valueText: text, unit: null };
@@ -362,7 +380,8 @@ export function mapFhirLabRecord(
return fail("text_too_long");
}
let read = readValue(resource);
const loinc = loincCode(code);
let read = readValue(resource, isDimensionlessLoinc(loinc));
if (read === null && resource.dataAbsentReason !== undefined) {
read = { ok: false, skip: "no_value" };
}
@@ -403,7 +422,6 @@ export function mapFhirLabRecord(
}
if (takenAt.getTime() < EARLIEST) return skip("invalid_date", members);
const loinc = loincCode(code);
const range = referenceRangeOf(resource, read.unit);
return {
+28
View File
@@ -54,3 +54,31 @@ export function labUnitFromFhirQuantity(quantity: {
}
return unit ?? code;
}
/**
* LOINC codes of lab results that are numbers without a unit: specific
* gravity, pH and the INR. A system often sends them as a bare number with
* no unit at all, and for these analytes that is the value, the UCUM unity
* ("1"), not a unit that was dropped. Kept to codes whose meaning is settled;
* an analyte that is not listed keeps the refusal of a number without a unit.
*/
const DIMENSIONLESS_LOINC: ReadonlySet<string> = new Set([
// Specific gravity of urine (test strip, unspecified, refractometry).
"5811-5",
"2965-2",
"53326-5",
// pH of urine (test strip, unspecified), of blood and of arterial blood.
"5803-2",
"2756-5",
"11558-4",
"2744-1",
// INR (platelet-poor plasma, blood, capillary blood).
"6301-6",
"34714-6",
"46418-0",
]);
/** Whether a LOINC code names an analyte whose value has no unit. */
export function isDimensionlessLoinc(code: string | null): boolean {
return code !== null && DIMENSIONLESS_LOINC.has(code.trim());
}
+1 -1
View File
@@ -205,7 +205,7 @@ const fhirLabRecordResult = z
.meta({
id: "FhirLabRecordResult",
description:
"One record's outcome, by its position in the request. `inserted`: written. `duplicate`: the record already holds it, under the same identity (deleted readings included, so a deleted result stays deleted) or as the same reading on the same day from another source. `skipped`: not a reading HealthLog keeps, with `reason` `not_observation` | `not_lab` | `not_final` (preliminary; it is taken once final) | `withdrawn` | `panel_header` | `no_value` | `unsupported_value` | `no_date` | `future_date` | `invalid_date` | `too_large` (a resource over 256 KiB). `failed`: a reading that could not be stored, with `reason` `missing_unit` | `unit_mismatch` (the account's marker is in a unit this one does not convert into) | `text_too_long` | `write_failed` (transient: send it again).",
"One record's outcome, by its position in the request. `inserted`: written. `duplicate`: the record already holds it, under the same identity (deleted readings included, also once the reading or its whole marker is gone, so a deleted result stays deleted) or as the same reading on the same day from another source. `skipped`: not a reading HealthLog keeps, with `reason` `not_observation` | `not_lab` (no category names a lab; a code, display or text containing `lab` in any case counts) | `not_final` (preliminary; it is taken once final) | `withdrawn` | `panel_header` | `no_value` | `unsupported_value` | `no_date` | `future_date` | `invalid_date` | `too_large` (a resource over 256 KiB). `failed`: a reading that could not be stored, with `reason` `missing_unit` (a number without a unit; a specific gravity, a pH or an INR, known by its LOINC code, is read as the unity `1` instead) | `unit_mismatch` (the account's marker is in a unit this one does not convert into) | `text_too_long` | `write_failed` (transient: send it again).",
});
const fhirLabBatchResponse = z