# parseFHIR

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
parseFHIR(value: string): FhirDateTime | null
```

Reads a FHIR R4 `date`, `dateTime` or `instant` string (R4 Datatypes §2.24.0.1) as it is written, and returns what it states: the input, its precision and its offset.

| Precision  | Form                          | Example                         |
| ---------- | ----------------------------- | ------------------------------- |
| `year`     | `YYYY`                        | `2024`                          |
| `month`    | `YYYY-MM`                     | `2024-06`                       |
| `day`      | `YYYY-MM-DD`                  | `2024-06-15`                    |
| `second`   | `YYYY-MM-DDThh:mm:ss±hh:mm`   | `2015-02-07T13:28:17-05:00`     |
| `fraction` | seconds with a decimal part   | `2015-02-07T13:28:17.239+02:00` |

- Precision is kept, never padded: `2024-06` is a month, not 1 June.
- A time needs seconds and a zone (`Z` or `±hh:mm`, from `-14:00` to `+14:00`). `24:00` is refused.
- `Z`, `+00:00` and `-00:00` all read as `offset: "+00:00"` (XSD 1.0, the source of FHIR's XML types, gives them one meaning); `value` keeps the input's spelling. A year, month or day has `offset: ""`.
- A month or day that does not exist (`2023-02-29`) is `null`.
- A second of `60` is valid only on an inserted leap second (as `isLeapSecond`).
- A fraction is at most nine digits. R4's pattern allows any length, but Temporal holds nanoseconds and a value GMT cannot hold is not called valid (XSD 1.0 lets a processor set such a limit if it documents it).
- Disambiguation: none. Every time FHIR carries has an offset, so there is no wall time to resolve. The matching validator is `isValidFHIR`, and the writer is `formatFHIR`.

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `value` | `string` | - A FHIR `date`, `dateTime` or `instant` string. |

## Returns

The value, its precision and its offset, or `null` when the input is not a FHIR value.

## Types

### FhirDateTime

A FHIR `date`, `dateTime` or `instant` value, read as sent.

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

| Member | Type | Description |
| --- | --- | --- |
| `value` | `string` | The input, unchanged: nothing is padded and the offset is spelled as sent. |
| `precision` | `"year"` \| `"month"` \| `"day"` \| `"second"` \| `"fraction"` ([`FhirPrecision`](/gmt/reference/types/FhirPrecision/)) | The finest field the value writes. |
| `offset` | `string` | `±HH:MM` (`Z` and `-00:00` read as `+00:00`), or `""` for a year, month or day. |

## Related types

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

## Examples

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

parseFHIR("2024-06") // { value: "2024-06", precision: "month", offset: "" }
```

## Source

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