@claudebernard/fhir-mapper/README.md

A simple FHIR / BCB resource mapper to help stay interoperable while still using the Claude Bernard intelligence

# @claudebernard/fhir-mapper
This library will be composed of several bidirectional mapping entities between Claude Bernard (alias BCB) interfaces and FHIR specifications.

Each mapper will contain at the very least a _fhirToBcb_ and a _bcbToFhir_ functions, will return a **MappingResponse** object and is expected to work offline as long as the codification mappers you provide don't call any APIs.

```ts
interface MappingResponse<T = unknown> {
    result: T | undefined;
    errors?: MappingError[];
}
type MappingError = {
    field: string;
    message: string;
}
```

Some of those mappers can accept optional **CodificationFunction** parameters which are meant to provide a way for the user to be able to choose how the mapping between a fhir resource's [Coding](https://www.hl7.org/fhir/datatypes.html#Coding) field and the corresponding Claude Bernard class codification property is done.

Of course, if the value of the respective fields is not provided or if they use the Claude Bernard codification already, those parameters should be omitted.

**CodificationFunction** type :

```ts
type CodificationFunction = ((coding: Coding) => SimpleCodification[] | Promise<SimpleCodification[]>) | undefined;

type SimpleCodification = {
    code: string;
    label: string;
};
```
The **CodificationFunction** type expects a fhir r5 **Coding** resource as input and must return an array of **SimpleCodification** objects (or a Promise resolving to such an array). This allows you to use either synchronous or asynchronous logic (e.g., API calls) in your codification mappers. If your codification will map to a single value, return a single-element array. If no mapping is found, return an empty array.

**Note:** All mapping functions that accept a `CodificationFunction` (such as `fhirToBcb`, `fhirToCb` etc.) are now asynchronous and must be called with `await` or handled as Promises, even if your mappers are synchronous.

## Dependencies
The library uses the _@types/fhir_ lib to gain access to fhir r5 official objects and methods.

## Peer Dependencies
The library uses the @claudebernard/types lib for common object structures used by other Claude Bernard tools and apps.

## Installation

```sh
npm install --save @claudebernard/fhir-mapper
```

## Mappers list

Below the list of all mappers currently comprised in this library :
- A [**Dosage**](https://www.hl7.org/fhir/dosage.html#Dosage) mapper exported as _dosageMapper_.
- A [**Patient**](https://www.hl7.org/fhir/patient.html#Patient) mapper exported as _patientMapper_.
- A [**Medication**](https://www.hl7.org/fhir/medication.html#Medication) mapper exported as _medicationMapper_.
- A [**MedicationRequest**](https://www.hl7.org/fhir/medicationrequest.html#MedicationRequest) mapper exported as _medicationRequestMapper_.

## Mappers details

### Dosage mapper : functions

#### - fhirToBcb


```ts
async function fhirToBcb(
    dosageInstructions: Dosage[],
    indicationMapper?: CodificationFunction,
    routeMapper?: CodificationFunction,
    intakeMapper?: CodificationFunction
): Promise<MappingResponse<BCBPosologieStructuree2>[]> {}
```

The function takes 4 parameters : 
- 1 mandatory parameter 'dosageInstructions' which will be the fhir r5 [Dosage](https://www.hl7.org/fhir/dosage.html#Dosage) resources that need to be mapped.
- 3 optional parameters of type **CodificationFunction**.

Those optional parameters are meant to be used to map fhir (asNeededFor, route, doseAndRate) fields to (codeIndication, codeVoie, codeUnitePrise) **BCBPosologieStructuree2** class properties.

##### Usage

```ts
import { dosageMapper } from '@claudebernard/fhir-mapper';
// other imports ... 

const fhirDosages = [];

// synchronous codification mapper
const routeMapper = (coding : Coding) => {
    // some logic implemented by yourself ...
    return {
        code : routeCode,
        label : routeLabel
    }
}

// asynchronous codification mapper
const indicationMapper = async (coding: Coding) => {
    // await someApiCall(coding)
    return {
        code: routeCode,
        label: routeLabel
    }
}

// ...

const bcbDosages = await dosageMapper.fhirToBcb(fhirDosages, indicationMapper, routeMapper, undefined);

// ...
```

#### - bcbToFhir

```ts
function bcbToFhir(bcbDosages: BCBPosologieStructuree2[]): MappingResponse<Dosage>[] {} 
```

This function takes only one parameter, an array of **BCBPosologieStructuree2** objects and returns a **MappingResponse** containing the corresponding fhir **Dosage** resources.

It will for now by default keep the Claude Bernard codification for the **Coding** fields in the output fhir **Dosage** resources.

##### Usage

```ts
import { dosageMapper } from '@claudebernard/fhir-mapper';
// other imports ... 

const bcbDosages = [];

// ...

const fhirDosages = dosageMapper.bcbToFhir(bcbDosages);

// ...
```

#### - fhirToCb

```ts
async function fhirToCb(dosageInstructions: Dosage[]): Promise<MappingResponse<CBPosologyBean>[]> {}
```

Converts FHIR Dosage instructions to CB (Claude Bernard) Posology Bean format. This function uses the existing fhirToBcb conversion and then transforms the result to CB format.

##### Usage

```ts
import { dosageMapper } from '@claudebernard/fhir-mapper';

const fhirDosages = /* array of FHIR Dosage instructions */;
const cbResults = await dosageMapper.fhirToCb(fhirDosages);

cbResults.forEach(response => {
    if (response.result) {
        console.log(response.result.posologyLabel);
    }
});
```

#### - cbToFhir

```ts
function cbToFhir(cbPosologies: CBPosologyBean[]): MappingResponse<Dosage>[] {}
```

Converts CB Posology Bean format to FHIR Dosage instructions. This function transforms CB format to BCB format and then uses the existing bcbToFhir conversion.

##### Usage

```ts
import { dosageMapper } from '@claudebernard/fhir-mapper';

const cbPosologies = /* array of CBPosologyBean */;
const fhirResults = dosageMapper.cbToFhir(cbPosologies);

fhirResults.forEach(response => {
    if (response.result) {
        console.log(response.result.text);
    }
});
```

#### Dosage mapper : current limitations 
Even though the mapper works and allows us to transform Dosage resources in Claude Bernard resources, there are some caveats : - some fields are currently unmapped due to a lack of overlap between the two structures.
- some fields are only partially mapped due to the fact that on one side (fhir) they are arrays and on the other (claude bernard), they are unitary values.

## Claude Bernard codifications
Below is listed the different Claude Bernard coding systems or valuesets that will be used internally by the mappers.
- https://platform.claudebernard.fr/fhir/CodeSystem/dosage-routes
- https://platform.claudebernard.fr/fhir/CodeSystem/dosage-intake-units
- https://platform.claudebernard.fr/fhir/CodeSystem/amm-pathologies

### Patient mapper : functions

#### - fhirToBcb

```ts
async function fhirToBcb(
  fhirPatient: BundleEntry[],
  allergiesMapper?: CodificationFunction,
  snomedPathologiesMapper?: CodificationFunction,
): Promise<MappingResponse<BCBPatient>> {}
```
The function takes 3 parameters : 
- 1 mandatory parameter 'fhirPatient' which will be an array of r5 [BundleEntry](https://www.hl7.org/fhir/bundle.html) resources that need to be mapped.
- 2 optional parameters of type **CodificationFunction**.

Those optional parameters are meant to be used to map fhir (Condition.code.coding, AllergyIntolerance.code.coding) fields to (lstPathologiesAMM, lstIdComposantAllergie) **BCBPatient** class properties.

##### Usage

```ts
import { patientMapper } from '@claudebernard/fhir-mapper';
// other imports ... 

const fhirPatient = [];
const allergiesMapper = (coding : Coding) => {
    // some logic implemented by yourself ...
    return [
        {
            code : allergyCode,
            label : allergyLabel
        }
    ];
}

const snomedPathologiesMapper = async (coding : Coding) => {
    // await someApiCall(coding)
    return [
        {
            code : pathologyCode,
            label : pathologyLabel
        }
    ];
}

// ...

const bcbPatient = await patientMapper.fhirToBcb(fhirPatient, allergiesMapper, snomedPathologiesMapper);

// ...
```

#### - bcbToFhir

```ts
function bcbToFhir(
  bcbPatient: BCBPatient,
): MappingResponse<BundleEntry[]> {}
```
The function takes 1 parameter of type BCBPatient and returns a **MappingResponse** containing the an array of the corresponding fhir **BundleEntry** resources.

##### Usage

```ts
import { patientMapper } from '@claudebernard/fhir-mapper';
// other imports ... 

const bcbPatient = [];

// ...

const fhirPatient = patientMapper.bcbToFhir(bcbPatient);

// ...
```

#### - fhirTocb

```ts
async function fhirTocb(
  fhirPatient: BundleEntry[],
  allergiesMapper?: CodificationFunction,
  snomedPathologiesMapper?: CodificationFunction,
): Promise<MappingResponse<BCBPatient>> {}
```
The function takes 3 parameters : 
- 1 mandatory parameter 'fhirPatient' which will be an array of r5 [BundleEntry](https://www.hl7.org/fhir/bundle.html) resources that need to be mapped.
- 2 optional parameters of type **CodificationFunction**.

Those optional parameters are meant to be used to map fhir (Condition.code.coding, AllergyIntolerance.code.coding) fields to (lstPathologiesAMM, lstIdComposantAllergie) **CBPatient** class properties.

##### Usage

```ts
import { patientMapper } from '@claudebernard/fhir-mapper';
// other imports ... 

const fhirPatient = [];
const allergiesMapper = (coding : Coding) => {
    // some api call or logic implemented by yourself ...
    return {
        code : allergyCode,
        label : allergyLabel
    }
}

const snomedPathologiesMapper = (coding : Coding) => {
    // some api call or logic implemented by yourself ...
    return [
        {
            code : pathologyCode,
            label : pathologyLabel
        }
    ];
}

// ...

const cbPatient = await patientMapper.fhirToCb(fhirPatient, allergiesMapper, snomedPathologiesMapper);

// ...
```

#### - cbToFhir

```ts
function cbToFhir(
  cbPatient: CBPatient,
): MappingResponse<BundleEntry[]> {}
```
The function takes 1 parameter of type BCBPatient and returns a **MappingResponse** containing the an array of the corresponding fhir **BundleEntry** resources.

##### Usage

```ts
import { patientMapper } from '@claudebernard/fhir-mapper';
// other imports ... 

const cbPatient = [];

// ...

const fhirPatient = patientMapper.cbToFhir(cbPatient);

// ...
```

### Medication mapper : functions

The medication mapper provides utilities for creating and extracting medication codes from FHIR Bundle resources. It supports BCB codes, CIP13 codes, and CIS codes.

#### - createMedicationsFromBcbCodes

```ts
function createMedicationsFromBcbCodes(codes: string[]): MappingResponse<Bundle> {}
```

Creates a FHIR Bundle containing Medication resources from BCB codes.

##### Usage

```ts
import { medicationMapper } from '@claudebernard/fhir-mapper';

const bcbCodes = ['BCB001', 'BCB002', 'BCB003'];
const response = medicationMapper.createMedicationsFromBcbCodes(bcbCodes);

if (response.result) {
    // Bundle with Medication resources
    console.log(response.result.entry?.length); // 3 medications
}
```

#### - createMedicationsFromCIP13Codes / createMedicationsFromCISCodes

```ts
function createMedicationsFromCIP13Codes(codes: string[]): MappingResponse<Bundle> {}
function createMedicationsFromCISCodes(codes: string[]): MappingResponse<Bundle> {}
```

Similar functions for creating medications from CIP13 and CIS codes respectively.

#### - extractBcbCodesFromMedications / extractCIP13CodesFromMedications / extractCISCodesFromMedications

```ts
function extractBcbCodesFromMedications(bundle: Bundle): string[] {}
function extractCIP13CodesFromMedications(bundle: Bundle): string[] {}
function extractCISCodesFromMedications(bundle: Bundle): string[] {}
```

Extract specific types of medication codes from a FHIR Bundle containing Medication resources.

##### Usage

```ts
import { medicationMapper } from '@claudebernard/fhir-mapper';

const bundle = /* your FHIR Bundle */;
const bcbCodes = medicationMapper.extractBcbCodesFromMedications(bundle);
const cip13Codes = medicationMapper.extractCIP13CodesFromMedications(bundle);
```

### MedicationRequest mapper : functions

The medication request mapper handles conversion of dosage instructions between FHIR MedicationRequest resources and BCB format, focusing purely on dosage conversion.

#### - fhirToBcb

```ts
async function fhirToBcb(bundle: Bundle): Promise<MappingResponse<BCBPosologieStructuree2>[]> {}
```

Extracts and converts dosage instructions from MedicationRequest resources in a Bundle to BCB format using the dosage-mapper.

##### Usage

```ts
import { medicationRequestMapper } from '@claudebernard/fhir-mapper';

const bundle = /* FHIR Bundle with MedicationRequest resources */;
const bcbDosages = await medicationRequestMapper.fhirToBcb(bundle);

// Array of BCB dosage mapping responses
bcbDosages.forEach(response => {
    if (response.result) {
        console.log(response.result.libellePosologie);
    }
});
```

#### - bcbToFhir

```ts
function bcbToFhir(bcbDosages: BCBPosologieStructuree2[]): MappingResponse<Bundle> {}
```

Creates a FHIR Bundle with a MedicationRequest resource containing the converted dosage instructions from BCB format.

##### Usage

```ts
import { medicationRequestMapper } from '@claudebernard/fhir-mapper';

const bcbDosages = /* array of BCBPosologieStructuree2 */;
const response = medicationRequestMapper.bcbToFhir(bcbDosages);

if (response.result) {
    // Bundle with MedicationRequest containing converted dosage instructions
    const medReq = response.result.entry?.[0]?.resource as MedicationRequest;
    console.log(medReq.dosageInstruction?.length);
}
```

## Browser support
- [x] Chrome
- [x] Firefox
- [x] Safari
- [x] Microsoft Edge

## License

Copyright of Cegedim. See [LICENSE](LICENSE.md) for details.