@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.

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 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 :

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

npm install --save @claudebernard/fhir-mapper

Mappers list

Below the list of all mappers currently comprised in this library :

• A Dosage mapper exported as dosageMapper.
• A Patient mapper exported as patientMapper.
• A Medication mapper exported as medicationMapper.
• A MedicationRequest mapper exported as medicationRequestMapper.

Mappers details

Dosage mapper : functions

- fhirToBcb

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 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

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

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

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

const bcbDosages = [];

// ...

const fhirDosages = dosageMapper.bcbToFhir(bcbDosages);

// ...

- fhirToCb

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

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

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

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, 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 |

Codifications and mappers

Pathologies and allergies already coded in a Claude Bernard code system are read as is, their display being used as the label : amm-pathologies and ICD-10 Condition resources, and products-ingredients AllergyIntolerance resources. The optional allergiesMapper and snomedPathologiesMapper are only needed for codings expressed in another system, SNOMED CT typically ; an error is reported when such a coding is found and the matching mapper is missing.

The wanted coding is looked up by system, not by position, so a Condition or an AllergyIntolerance may carry several codings without the mapping picking the wrong one.

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

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 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

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

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

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

const bcbPatient = [];

// ...

const fhirPatient = patientMapper.bcbToFhir(bcbPatient);

// ...

- fhirTocb

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 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

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

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

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

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

Creates a FHIR Bundle containing Medication resources from BCB codes. Each Medication is paired with a MedicationRequest that references it. Those MedicationRequest resources are blank : they carry no dosageInstruction, only the mandatory status, intent, medication and subject fields.

Both resources get a UUID v4 as id, so their ids differ from one call to the next. Only the Bundle id stays deterministic, derived from the codes it contains. Each Bundle entry carries a fullUrl built as <ResourceType>/<id> :

{
  "fullUrl": "Medication/d813a438-a3ea-4608-ba50-d19a69e59569",
  "resource": {
    "resourceType": "Medication",
    "id": "d813a438-a3ea-4608-ba50-d19a69e59569",
    "code": { "coding": [{ "system": "https://platform.claudebernard.fr/fhir/CodeSystem/bcb-code", "code": "BCB001" }] }
  }
}

Usage

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

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

if (response.result) {
    // Bundle with the Medication resources first, then their MedicationRequest resources
    console.log(response.result.entry?.length); // 6 : 3 medications + 3 medication requests
}

- createMedicationsFromCIP13Codes / createMedicationsFromCISCodes

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

Similar functions for creating medications from CIP13 and CIS codes respectively. They also add a blank MedicationRequest per Medication.

- createMedicationsFromProducts / createMedicationFromProduct

function createMedicationsFromProducts(products: Product[]): MappingResponse<Bundle> {}
function createMedicationFromProduct(product: Product): Medication | undefined {}

Same as createMedicationsFromBcbCodes, but starting from the Product objects returned by the BCB APIs (@claudebernard/types), so the medication labels are kept along with the codes. Each Medication carries one Coding per code the Product holds — code for the bcb-code, properties.codes.cip13 (or code13) for the cip13-code, properties.codes.cis for the cis-code — each with the product label as display, and the same label as the CodeableConcept text :

{
  "resourceType": "Medication",
  "id": "95175bcb-f3cf-4eb8-83be-7956554cd0b8",
  "code": {
    "coding": [
      { "system": "https://platform.claudebernard.fr/fhir/CodeSystem/bcb-code", "code": "76461", "display": "JANUMET 50 mg/1000 mg, comprimé pelliculé" },
      { "system": "http://terminology.hl7.org/CodeSystem/cip13-code", "code": "3400957312114", "display": "JANUMET 50 mg/1000 mg, comprimé pelliculé" },
      { "system": "http://terminology.hl7.org/CodeSystem/cis-code", "code": "66010671", "display": "JANUMET 50 mg/1000 mg, comprimé pelliculé" }
    ],
    "text": "JANUMET 50 mg/1000 mg, comprimé pelliculé"
  }
}

The label is read from labels.label, falling back on labels.longLabel then labels.shortLabel, depending on which fields the API in use fills ; the HTML flavoured fields (labelHtml & co) are never used. Unlike the other creation functions, the Bundle id is a UUID v4 as well, so it differs from one call to the next. A Product carrying none of the three codes is skipped and reported in the errors field of the response ; createMedicationFromProduct returns undefined for it.

Usage

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

const response = medicationMapper.createMedicationsFromProducts(products);

if (response.result) {
    // Bundle with the Medication resources first, then their MedicationRequest resources
    console.log(response.result.entry?.length);
}

- extractBcbCodesFromMedications / extractCIP13CodesFromMedications / extractCISCodesFromMedications

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

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

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

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

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

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

Usage

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, later entries live in the repository root changelog.

Development

npm ci
npm test     # jest
npm run lint # eslint
npm run build

License

Copyright of Cegedim. See LICENSE for details.