@claudebernard/node-fhir-mapper 2.1.2

package/LICENSE.md

@@ -0,0 +1 @@
+# License

package/README.md

@@ -0,0 +1,512 @@
+# @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 : FHIR representation
+
+The patient mapping uses the same FHIR representation as the Java library
+[`mvn-fhir-mapper`](../mvn-fhir-mapper/README.md), so that a bundle produced by one can be read
+back by the other.
+
+| BCB / CB field | FHIR resource | Code |
+| --- | --- | --- |
+| `age` (months), `sexe` / `gender` | `Patient` (`birthDate`, `gender`) | — |
+| `poids` / `weight` | `Observation` | LOINC `29463-7` |
+| `taille` / `height` | `Observation` | LOINC `8302-2` |
+| `grossesse` / `pregnancy` | `Observation` | LOINC `82810-3` |
+| `weeksOfPregnancy` | `Observation.valueQuantity`, or gestational age as a fallback | LOINC `82810-3`, `18185-9` |
+| `allaitement` / `breastfeeding` | `Observation` | LOINC `63895-7` |
+| `clairanceCreatinine` / `creatinineClearance` | `Observation` | any code of the accepted clearance list |
+| `gfr` | `Observation` | any code of the accepted GFR lists |
+| `creatininemieMol` / `molCreatinine` | `Observation` | LOINC `14682-9` |
+| `creatininemieMg` / `mglCreatinine` | `Observation` | LOINC `2160-0` |
+| `insuffisanceHepatique` / `hepaticStage` | Child-Pugh `Observation` | LOINC `98152-2` + SNOMED class |
+| `lstPathologiesAMM` / `ammPathologies` | `Condition` | `.../CodeSystem/amm-pathologies` |
+| `lstPathologiesCIM10` | `Condition` | `http://hl7.org/fhir/sid/icd-10` |
+| `lstIdComposantAllergie` / `allergies` | `AllergyIntolerance` | `.../CodeSystem/products-ingredients` |
+
+#### Hepatic insufficiency
+
+The Child-Pugh `Observation` carries the numeric score in `valueQuantity` and the class as a
+SNOMED CT coding in a `component` (`710065009` / `710066005` / `710067001` for stages A / B / C).
+When reading, the component is inspected first, then a direct `valueCodeableConcept`, then the
+score (`< 7` → A, `7-9` → B, `>= 10` → C).
+
+> **Breaking change.** Up to version 2.1.1 the hepatic insufficiency was written as an ICD-10
+> `Condition` (`K72.90` / `K72.91` / `K72.92`). It is now written as the Child-Pugh `Observation`
+> described above. Reading still accepts the ICD-10 `Condition` as a fallback, so bundles produced
+> by earlier versions remain readable, but consumers reading the output of `bcbToFhir` / `cbToFhir`
+> must be updated.
+
+#### Renal function
+
+Creatinine clearance and GFR are recognised through the same extended LOINC code lists as
+`mvn-fhir-mapper`. An absolute GFR observation is used as is; otherwise a GFR normalized to
+1.73 m² is converted to an absolute value using the body surface area (Du Bois formula), which
+requires both weight and height to be present in the bundle.
+
+### 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
+
+## Versioning
+
+This package carries the version of the `fhir-monorepo` repository — one version, tag and changelog
+for the whole repo. Published versions are therefore sparse: a release only reaches npm when this
+package actually changed. Releases up to `2.2.4` were cut from the former standalone
+`npmjs-bcb-fhir-mapper` repository; their history is kept in [CHANGELOG.md](CHANGELOG.md), later
+entries live in the repository root changelog.
+
+## Development
+
+```sh
+npm ci
+npm test     # jest
+npm run lint # eslint
+npm run build
+```
+
+## License
+
+Copyright of Cegedim. See [LICENSE](LICENSE.md) for details.
+