# formatHL7

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
formatHL7(value: string, options?: Hl7FormatOptions): string
```

Write 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 `DTM` `YYYY[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 |
  | --- | --- | --- |
  | `2024` | year | `2024` |
  | `2024-06` | month | `202406` |
  | `2024-06-15` | day | `20240615` |
  | `2024-06-15T10` | hour | `2024061510` |
  | `2024-06-15T10:30` / `…:00` / `…:00.f` | minute / second / fraction | `202406151030` / `20240615103000` / `20240615103000.f` |
  | the same with `Z` or `±HH:MM` | as written, then `±HHMM` | `20240615103000-0500` |

- The precision is read from the form the input is written in; `options.precision` only 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; `Z` writes `+0000`. It is never dropped and never rounded: an offset that is not a whole number of minutes returns `""`.
- `Z` and `-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:00` is `2024061510-0500`). To write a date with its offset, pass the instant with `precision`: `formatHL7("2024-06-15T10:30:00-05:00", { precision: "day" })` is `20240615-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 `local` from `parseHL7` reads back with `:00` seconds; 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

| Parameter | Type | Description |
| --- | --- | --- |
| `value` | `string` | ISO 8601 date, date-time, or date-time with an offset |

## Options

**options**

How much of the value is written

<a id="hl7formatoptions"></a>

Options for `formatHL7`.

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

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `precision?` | `Hl7PartialPrecision` \| `Hl7MomentPrecision` ([`Hl7Precision`](#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

the `DTM`, or `""` when the value cannot be written

## Types

### 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](https://www.hl7.eu/HL7v2x/v251/std251/ch02a.html)): "The number of characters populated (excluding the time zone specification) specifies the precision". The characters before the offset, per member:

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

```ts
Hl7PartialPrecision | Hl7MomentPrecision
```

## Related types

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

## Examples

```ts
import { formatHL7 } from "@northguild/gmt/healthcare/format";

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

## Source

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