# formatFHIR

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
formatFHIR(value: string, type: FhirDateType, options?: FhirFormatOptions): string
```

Write an ISO 8601 string as a FHIR R4 `date`, `dateTime` or `instant`: the inverse of `parseFHIR`.

- FHIR R4 Datatypes §2.24.0.1 limits each type: `date` is `YYYY`, `YYYY-MM` or `YYYY-MM-DD` with no time zone; `dateTime` adds a time that SHALL carry seconds and a zone; `instant` is at least to the second and SHALL include a zone.

  | Type | Precisions written | Default precision |
  | --- | --- | --- |
  | `date` | year, month, day | the input's, or day for an input with a time |
  | `dateTime` | year, month, day, second, fraction | the input's |
  | `instant` | second, fraction | the input's |

- It cuts and never rounds, so the result never names a later second, day or month than the input's own wall clock. `options.precision` only lowers the precision; a finer one returns `""`.
- Under `date`, the result is the wall-clock date at the input's own offset (`2024-06-15T23:30:00-05:00` is `2024-06-15`), because §2.24.0.1 forbids a zone on a `date`.
- The designator is written as the input spells it (`Z`, `+00:00` and `-00:00` stay as written; `+05:30:00` is written `+05:30`). The fraction always uses `.`.
- A second of `60` returns `""`: §2.24.0.1 says "applications producing them MAY choose to avoid encoding leap seconds".
- There is no hour or minute precision, and nothing is zero-filled: a value written to the hour or minute, with or without an offset, is written only when cut to a day or coarser (`2024-06-15T23-05:00` is `2024-06-15` under `date`). An hour-only time is ISO 8601-1 §5.3.1.3 reduced precision, which Temporal reads.
- An offset that is not a whole number of minutes returns `""` (`+02:00:30`; Monrovia before 1972, `Africa/Monrovia`, was −0:44:30). This applies under `date` too, even though a `date` never writes the offset.
- Disambiguation: none, in the vocabulary of `LOCAL_TIME_RESOLUTION.md`. A wall time with no offset is written only as a date. In a repeated hour at the end of DST, the offset decides which one is written.
- 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.
- Never throws: any failure, for input of any type, is `""`. The matching reader is `parseFHIR`.

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `value` | `string` | ISO 8601 date, date-time, or date-time with an offset |
| `type` | `FhirDateType` | The FHIR type to write |

## Options

**options**

How much of the value is written

<a id="fhirformatoptions"></a>

Options for `formatFHIR`.

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

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `precision?` | `"year"` \| `"month"` \| `"day"` \| `"second"` \| `"fraction"` ([`FhirPrecision`](/gmt/reference/types/FhirPrecision/)) | the input's precision, or `"day"` under `date` for an input finer than a day | The precision to write, no finer than the input's. |

## Returns

the FHIR value, or `""` when the value cannot be written as `type`

## Related types

- [`FhirDateType`](/gmt/reference/types/FhirDateType/)
- [`FhirPrecision`](/gmt/reference/types/FhirPrecision/)

## Examples

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

formatFHIR("2024-06-15T23:30:00-05:00", "date") // "2024-06-15"
```

## Source

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