parseHL7
Signature
Section titled “Signature”parseHL7(value: string): Hl7DateTime | nullRead 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
DTMYYYY[MM[DD[HH[MM[SS[.S[S[S[S]]]]]]]]][+/-ZZZZ]; 2.A.77 theTS, aDTMthen^and a degree of precision.kindwhen 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.
Son a fractional value cuts the fraction. -
0000is 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. -
+0000and-0000are 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”);''returnsnull. -
A lone
TScarries 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 thatTSwith^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&Xand2024^D&Xreturnnull; 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^Xreads as20240615^D. An empty component is not present (§2.6.2), so20240615^D^reads as20240615^Dand""^as the null value, while^Dreturnsnull. An ignored component still cannot hold|,~or a C0 control character (a carriage return ends the segment), so20240615^D^X|Yreturnsnull; a subcomponent (&), an escape sequence (\F\, §2.7) and white space are text and are ignored. -
Second
60and hour24are rejected, as is any day the month lacks. -
Returns
nullon invalid input and for any value that is not a string. Never throws.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
value | string | HL7 v2 DTM or TS string |
Returns
Section titled “Returns”the reading, or null on invalid input
Hl7DateTime
Section titled “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.
import type { Hl7DateTime } from "@northguild/gmt";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
Section titled “Related types”Examples
Section titled “Examples”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
Section titled “Source”© 2026 NorthGuild · Licences
Code examples: MIT-0. Packages: MIT. Third-party data and components: their own licences, credited where they appear. Everything else: © 2026 NorthGuild, all rights reserved.