formatHL7
Signature
Section titled “Signature”formatHL7(value: string, options?: Hl7FormatOptions): stringWrite an ISO 8601 string as an HL7 v2 date-time (DTM): the inverse of parseHL7.
-
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]and says “the number of characters populated (excluding the time zone specification) specifies the precision”.Input form Written precision Example result 2024year 20242024-06month 2024062024-06-15day 202406152024-06-15T10hour 20240615102024-06-15T10:30/…:00/…:00.fminute / second / fraction 202406151030/20240615103000/20240615103000.fthe same with Zor±HH:MMas written, then ±HHMM20240615103000-0500 -
The precision is read from the form the input is written in;
options.precisiononly lowers it, and a finer one returns"". A value is cut to its precision and never rounded, so the result never names a later minute, hour or day than the input. A fraction is cut to four digits, the most 2.A.22 allows. -
It never writes
TS: v2.6 2.A.77 says it was “withdrawn and removed from the standard as of v 2.6”, so the result never holds^. -
A value with no offset writes none, and the HL7 value then means 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”). To send a facility’s wall clock with its offset, pass that wall clock written with the zone’s offset (
2024-06-15T10:30:00-05:00). -
The offset written is the one the value carries;
Zwrites+0000. It is never dropped and never rounded: an offset that is not a whole number of minutes returns"". -
Zand-00:00(RFC 9557 §2.2: UTC known, local offset unknown) write+0000; HL7 has no spelling for an unknown offset (2.A.22: “+0000 or -0000 both represent UTC”). -
A date with an offset is not ISO 8601 and returns
"". An hour with one is ISO 8601-1 §5.3.1.3 reduced precision and is written (2024-06-15T10-05:00is2024061510-0500). To write a date with its offset, pass the instant withprecision:formatHL7("2024-06-15T10:30:00-05:00", { precision: "day" })is20240615-0500. -
Disambiguation: none. The function never converts a wall time without an offset to an instant.
-
Annotations: none is read. A bracket of any kind (a zone,
[u-ca=iso8601],[foo=bar]) returns""; write the wall clock with the zone’s offset instead. -
A minute-precision
localfromparseHL7reads back with:00seconds; to write the same digits, pass{ precision: result.precision }. -
A year outside 0000–9999 returns
"". -
Never throws: any failure, for input of any type, is
"".
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
value | string | ISO 8601 date, date-time, or date-time with an offset |
Options
Section titled “Options”options
How much of the value is written
Options for formatHL7.
import type { Hl7FormatOptions } from "@northguild/gmt";| Option | Type | Default | Description |
|---|---|---|---|
precision? | Hl7PartialPrecision | Hl7MomentPrecision (Hl7Precision) | the precision of the input | Lowers the precision written; never raises it. The precision is read from the form the input is written in, and a value lower than that cuts the digits (never rounds). |
Returns
Section titled “Returns”the DTM, or "" when the value cannot be written
Hl7Precision
Section titled “Hl7Precision”The precision of an HL7 v2 date-time, coarsest first. HL7 v2.5.1 ch. 2A 2.A.22 (headed 2.A.1.22 in the hl7.eu v2.5.1 copy): “The number of characters populated (excluding the time zone specification) specifies the precision”. The characters before the offset, per member:
import type { Hl7Precision } from "@northguild/gmt";Hl7PartialPrecision | Hl7MomentPrecisionRelated types
Section titled “Related types”Examples
Section titled “Examples”import { formatHL7 } from "@northguild/gmt/healthcare/format";
formatHL7("2024-06-15T10:30:00-05:00") // "20240615103000-0500"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.