# parseHL7

Industry: Healthcare

:::caution[Unreleased]
Not in `@northguild/gmt` 1.21.0 on npm yet. It is on `main` and ships in the next release.
:::

## Signature

```ts
parseHL7(value: string): Hl7DateTime | null
```

Read an HL7 v2 date-time (`DTM`, or the older `TS`) as what it states: a moment, the sender's local time, or a span.

- HL7 v2.5.1 2.A.22 (headed 2.A.1.22 in the hl7.eu v2.5.1 copy) defines the `DTM` `YYYY[MM[DD[HH[MM[SS[.S[S[S[S]]]]]]]]][+/-ZZZZ]`; 2.A.77 the `TS`, a `DTM` then `^` and a degree of precision.

  | `kind` | when | members |
  | --- | --- | --- |
  | `"instant"` | an offset and a minute or finer | `instant`, `offset`, `local`, `precision` |
  | `"local"` | no offset and a minute or finer | `local`, `precision` |
  | `"partial"` | year, month, day or hour | `local`, `offset` (`""` when none), `precision` |
  | `"null"` | the string `""` | none |

- No offset is the sender's local time: 2.A.22, "if the time zone is not included, the time zone defaults to that of the local time zone of the sender". It is never read as UTC; supply the sender's zone to `resolveLocal`.
- A partial value has no instant: padding a year or a day to a moment states a fact the sender did not send.
- The degree of precision only lowers (2.A.77.2: it "may not indicate greater precision"), by cutting, never rounding. `S` on a fractional value cuts the fraction.
- `0000` is the start of the stated day (2.A.22, `198807050000`: "Midnight of the night extending from July 4 to July 5, 1988"), not the end of the day before.
- `+0000` and `-0000` are both UTC (2.A.22), read as `+00:00`.
- `""` (two double quote marks) is the null value and differs from `''` (ch. 2 §2.5.3: "is different from omitting an optional data field"); `''` returns `null`.
- A lone `TS` carries no MSH-2, so `^` separates its components, the separator Figure 2-1 recommends (ch. 2 §2.5.4). When a feed's MSH-2 names another, the caller re-joins that `TS` with `^` first.
- GMT reads TS.1 as exactly a DTM and TS.2 as exactly a Table 0529 code (or empty) and rejects anything else inside them, so `2024&X` and `2024^D&X` return `null`; that is GMT's strict-kind rule, not an HL7 rule.
- Components after TS.2 are present but not expected and are ignored (ch. 2 §2.6.2; a later version adds them at the end, §2.8.1 and §2.8.2), so `20240615^D^X` reads as `20240615^D`. An empty component is not present (§2.6.2), so `20240615^D^` reads as `20240615^D` and `""^` as the null value, while `^D` returns `null`. An ignored component still cannot hold `|`, `~` or a C0 control character (a carriage return ends the segment), so `20240615^D^X|Y` returns `null`; a subcomponent (`&`), an escape sequence (`\F\`, §2.7) and white space are text and are ignored.
- Second `60` and hour `24` are rejected, as is any day the month lacks.
- Returns `null` on invalid input and for any value that is not a string. Never throws.

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `value` | `string` | HL7 v2 `DTM` or `TS` string |

## Returns

the reading, or `null` on invalid input

## Types

### Hl7DateTime

An HL7 v2 date-time (`DTM`, 2.A.22; or `TS`, 2.A.77) read as what it states. What the sender did not send is not invented: a value with no offset has no instant, and a year or a day has no moment.

```ts
import type { Hl7DateTime } from "@northguild/gmt";
```

```ts
type Hl7DateTime =
  | {
      /** An offset and a precision of a minute or finer: a moment in time. */
      kind: "instant";
      /**
       * UTC, ISO 8601 ending in `Z`, as `toOffsetInstant` writes it (a sent fraction of `.1000`
       * is `.1Z`; `local` keeps `.1000`).
       */
      instant: string;
      /** `±HH:MM`, as sent; `+0000` and `-0000` both read `+00:00`. */
      offset: string;
      /**
       * The wall clock as sent, ISO 8601 extended, at the precision sent; seconds always written
       * (`2024-06-15T10:30:00`, `2024-06-15T10:30:00.1234`).
       */
      local: string;
      /** The digits sent, or the `TS` degree of precision when it lowers them. */
      precision: Hl7MomentPrecision;
    }
  | {
      /** No offset and a precision of a minute or finer: the sender's local time. */
      kind: "local";
      /**
       * The wall clock as sent, ISO 8601 extended, at the precision sent; seconds always written
       * (`2024-06-15T10:30:00`, `2024-06-15T10:30:00.1234`). Ready for `resolveLocal` once you
       * supply the sender's zone; HL7 2.A.22: "if the time zone is not included, the time zone
       * defaults to that of the local time zone of the sender".
       */
      local: string;
      /** The digits sent, or the `TS` degree of precision when it lowers them. */
      precision: Hl7MomentPrecision;
    }
  | {
      /**
       * Year, month, day or hour precision, with or without an offset: no single moment, so no
       * instant.
       */
      kind: "partial";
      /**
       * The wall clock as sent, ISO 8601 extended, at the precision sent: `2024`, `2024-06`,
       * `2024-06-15`, `2024-06-15T10`.
       */
      local: string;
      /**
       * `±HH:MM`, as sent; `+0000` and `-0000` both read `+00:00`; or `""` when the value
       * carried none.
       */
      offset: string;
      /** The digits sent, or the `TS` degree of precision when it lowers them. */
      precision: Hl7PartialPrecision;
    }
  | {
      /**
       * The HL7 null value `""` (two double quote marks), ch. 2 §2.5.3: "is different from
       * omitting an optional data field". The old value "should be changed to null".
       */
      kind: "null";
    };
```

## Related types

- [`Hl7MomentPrecision`](/gmt/reference/types/Hl7MomentPrecision/)
- [`Hl7PartialPrecision`](/gmt/reference/types/Hl7PartialPrecision/)

## Examples

```ts
import { parseHL7 } from "@northguild/gmt/healthcare/parse";

parseHL7("20240615103000-0500") // { kind: "instant", instant: "2024-06-15T15:30:00Z", offset: "-05:00", local: "2024-06-15T10:30:00", precision: "second" }
```

## Source

[healthcare/parse/parseHL7.ts](https://github.com/northguild/gmt/blob/main/packages/gmt/src/healthcare/parse/parseHL7.ts)
