# Healthcare mistakes

Industry: Healthcare

The healthcare layer reads the date-times of clinical messages. The mistakes around them are the
ones a hand-written reader makes: taking a value with no offset for UTC, padding a year to a
moment, dropping the precision a time stamp carries, treating the null value as an empty field,
reading midnight as the end of the day before, and rounding when writing. FHIR R4 adds its own:
padding a month to a moment, sending a time with no zone, trusting the published regex, mishandling
a leap second and comparing offsets as strings. Every output shown here is what the code returns.

## HL7 version 2

### Reading an HL7 time with no offset as UTC

Severity: critical.

HL7 says a time with no offset is the local time of the sender. Appending Z states a place the message never named, and the event moves by the sender's offset. parseHL7 returns a local time with no instant, and resolveLocal joins it to the zone you name.

Wrong:
```js
const value = "20240615103000"; // no offset
const iso = value.slice(0, 4) + "-" + value.slice(4, 6) + "-" + value.slice(6, 8) + "T" + value.slice(8, 10) + ":" + value.slice(10, 12) + ":" + value.slice(12, 14) + "Z";
new Date(iso).toISOString();
// "2024-06-15T10:30:00.000Z" — three hours out for a lab in Helsinki
```

Right:
```js
import { parseHL7 } from "@northguild/gmt/healthcare/parse";
import { resolveLocal } from "@northguild/gmt/instant/convert";

parseHL7("20240615103000");
// { kind: "local", local: "2024-06-15T10:30:00", precision: "second" }
resolveLocal("2024-06-15T10:30:00", "Europe/Helsinki");
// "2024-06-15T07:30:00Z"
```

### Padding a birth year to midnight on 1 January

Severity: high.

A value of four digits names a year, not a moment. Padding it states a day, a time and a place the sender did not send. parseHL7 keeps the precision and returns no instant.

Wrong:
```js
const birth = "1965";
new Date(Date.UTC(Number(birth), 0, 1)).toISOString();
// "1965-01-01T00:00:00.000Z" — a day and a time nobody sent
```

Right:
```js
import { parseHL7 } from "@northguild/gmt/healthcare/parse";

parseHL7("1965");
// { kind: "partial", local: "1965", offset: "", precision: "year" }
```

### Dropping the degree of precision from a TS

Severity: high.

In an older time stamp the letter after the caret says how much of the value to keep. Dropping it reads the full digits as a time the sender did not give at that precision. parseHL7 cuts the value to the degree.

Wrong:
```js
const [dtm] = "20240615103000^D".split("^");
dtm.slice(0, 4) + "-" + dtm.slice(4, 6) + "-" + dtm.slice(6, 8) + "T" + dtm.slice(8, 10) + ":" + dtm.slice(10, 12) + ":" + dtm.slice(12, 14);
// "2024-06-15T10:30:00" — the sender said the day
```

Right:
```js
import { parseHL7 } from "@northguild/gmt/healthcare/parse";

parseHL7("20240615103000^D");
// { kind: "partial", local: "2024-06-15", offset: "", precision: "day" }
```

### Treating the null value as an empty field

Severity: high.

Two double quotes are the null value, and it clears what is stored. It is different from an empty field, which leaves the stored value alone. A reader that strips quotes cannot tell them apart. parseHL7 returns the null value as its own kind and an empty string as null.

Wrong:
```js
const value = '""';
value.replace(/"/g, "") === "";
// true — dropped as empty, so the stored time is never cleared
```

Right:
```js
import { parseHL7 } from "@northguild/gmt/healthcare/parse";

parseHL7('""');
// { kind: "null" }
parseHL7("");
// null
```

### Reading 0000 as the end of the day before

Severity: medium.

HL7 gives 198807050000 as the midnight of the night that runs from 4 July to 5 July, so 0000 is the start of the stated day. Moving it back to hour 24 of the day before writes a time HL7 does not allow.

Wrong:
```js
const day = new Date(Date.UTC(1988, 6, 5));
day.setUTCDate(day.getUTCDate() - 1);
day.toISOString().slice(0, 10) + "T24:00:00";
// "1988-07-04T24:00:00" — the sender said 5 July
```

Right:
```js
import { parseHL7 } from "@northguild/gmt/healthcare/parse";

parseHL7("198807050000");
// { kind: "local", local: "1988-07-05T00:00:00", precision: "minute" }
```

### Rounding a fraction or the offset when writing

Severity: medium.

Rounding changes what the sender sent, and carrying the digits without the offset loses the place. formatHL7 writes the offset the value has and cuts the fraction to four digits.

Wrong:
```js
const seconds = (45.98765).toFixed(4);
"20240615" + "1030" + seconds;
// "20240615103045.9877" — rounded up, and the offset is gone
```

Right:
```js
import { formatHL7 } from "@northguild/gmt/healthcare/format";

formatHL7("2024-06-15T10:30:45.98765-05:00");
// "20240615103045.9876-0500"
```

## FHIR R4

### Padding a FHIR month or day to a time

Severity: high.

A FHIR date can stop at a year, a month or a day. Handing it to new Date, or adding a time to it, states a midnight the sender did not send, and a range check counts the whole period as its first moment. parseFHIR keeps the precision and pads nothing.

Wrong:
```js
new Date("2024-06").toISOString();
// "2024-06-01T00:00:00.000Z" — a day, a time and a place nobody sent
new Date("2024-06-15").toISOString();
// "2024-06-15T00:00:00.000Z" — a time and a place nobody sent
```

Right:
```js
import { parseFHIR } from "@northguild/gmt/healthcare/parse";

parseFHIR("2024-06");
// { value: "2024-06", precision: "month", offset: "" }
parseFHIR("2024-06-15");
// { value: "2024-06-15", precision: "day", offset: "" }
```

### Accepting a dateTime that has no zone

Severity: critical.

HL7 version 2 leaves a time with no offset to the sender's local time. FHIR does not: if hours and minutes are given, a zone SHALL be given. Appending Z to make it parse invents UTC. parseFHIR returns null, so the sender's error is found and the time is not guessed.

Wrong:
```js
const value = "2024-06-15T10:30:00"; // no zone
new Date(value + "Z").toISOString();
// "2024-06-15T10:30:00.000Z" — a place the resource never named
```

Right:
```js
import { parseFHIR } from "@northguild/gmt/healthcare/parse";
import { isValidFHIR } from "@northguild/gmt/healthcare/validate";

parseFHIR("2024-06-15T10:30:00");
// null
isValidFHIR("2024-06-15T10:30:00", "dateTime");
// false
```

### Treating the R4 regex as validation

Severity: high.

HL7 calls the published regexes informative, and says they may allow a broader set of values than are valid. They accept 30 February. isValidFHIR reads the value as well as its shape.

Wrong:
```js
import { fhirDateTime } from "@northguild/gmt/regex";

fhirDateTime.test("2024-02-30");
// true — there is no 30 February
```

Right:
```js
import { isValidFHIR } from "@northguild/gmt/healthcare/validate";

isValidFHIR("2024-02-30", "dateTime");
// false
```

### Refusing a leap second, or accepting it on any day

Severity: medium.

FHIR allows a second of 60, and the platform's date parser does not. A pattern that allows it accepts it on every day, though one was inserted only at the end of a few. isValidFHIR accepts only the inserted second itself (23:59:60 UTC, at any offset spelling), on a day one was inserted, and refuses a second of 60 anywhere else.

Wrong:
```js
new Date("2016-12-31T23:59:60Z").getTime();
// NaN — refused, though a second was inserted that day
```

Right:
```js
import { isValidFHIR } from "@northguild/gmt/healthcare/validate";

isValidFHIR("2016-12-31T23:59:60Z", "instant");
// true
isValidFHIR("2017-12-31T23:59:60Z", "instant");
// false
```

### Comparing Z, +00:00 and -00:00 as strings

Severity: medium.

Z, +00:00 and -00:00 name the same offset. Compared as strings they are three offsets, and one instant reads as three. parseFHIR reads all three as +00:00 and keeps the spelling sent in value.

Wrong:
```js
"2024-06-15T10:30:00Z".slice(19) === "2024-06-15T10:30:00+00:00".slice(19);
// false — "Z" and "+00:00" are the same offset
```

Right:
```js
import { parseFHIR } from "@northguild/gmt/healthcare/parse";

parseFHIR("2024-06-15T10:30:00Z")?.offset === parseFHIR("2024-06-15T10:30:00+00:00")?.offset;
// true
parseFHIR("2024-06-15T10:30:00-00:00")?.offset;
// "+00:00"
```
