fhir_r4_mapping 0.4.0

Utility Library that Peforms Validation and Mapping Functionality.

fhir_r4_utils

FHIR-FLI Mapping (R4)

A comprehensive implementation of the FHIR Mapping Language for Dart, enabling transformations between different FHIR resources and structures.

Overview

FHIR-FLI Mapping provides tools to parse the FHIR Mapping Language and execute transformations between different FHIR resources and structures. It's designed to work seamlessly with the rest of the FHIR-FLI ecosystem while taking advantage of Dart's strong typing.

Features

• FHIR Mapping Language Parser: Convert mapping language text into StructureMap resources
• Mapping Engine: Execute transformations defined in StructureMaps
• Resource Cache System: Efficiently manage and retrieve canonical resources
• Type-Safe Builders: Create and modify FHIR resources during transformations
• Online Resource Resolution: Automatically fetch resources from external repositories when needed

Installation

dependencies:
  fhir_r4_mapping: ^0.4.0
  fhir_r4: ^0.4.1
  fhir_r4_path: ^0.4.2

Quick Start

Parsing a FHIR Map

import 'package:fhir_r4_mapping/fhir_r4_mapping.dart';

Future<void> main() async {
  // Create the parser
  final parser = await StructureMapParser.create();
  
  // Define a simple mapping
  final mapText = '''
  map "http://example.org/maps/PatientToPersonMap" = PatientToPerson
  uses "http://hl7.org/fhir/StructureDefinition/Patient" as source
  uses "http://hl7.org/fhir/StructureDefinition/Person" as target
  
  group PatientToPerson(source src : Patient, target tgt : Person) {
    src.name -> tgt.name;
    src.gender -> tgt.gender;
    src.birthDate -> tgt.birthDate;
  }
  ''';
  
  // Parse into a StructureMap
  final structureMap = parser.parse(mapText, 'fhirmap');
  print('Successfully parsed map: ${structureMap.id}');
}

Executing a Transformation

import 'package:fhir_r4/fhir_r4.dart';
import 'package:fhir_r4_mapping/fhir_r4_mapping.dart';

Future<void> transformPatient() async {
  // Set up the resource cache
  final resourceCache = OnlineResourceCache();
  
  // Load necessary structure definitions
  resourceCache.saveCanonicalResource(patientStructureDef);
  resourceCache.saveCanonicalResource(personStructureDef);
  
  // Create the engine with your StructureMap
  final mapEngine = await FhirMapEngine.create(resourceCache, structureMap);
  
  // Transform a Patient to a Person
  final result = await mapEngine.transformFromFhir(
    patientResource,
    structureMap,
    null, // No target - create new
  );
  
  // The result is a Person resource
  final person = result as Person;
  print('Transformed patient: ${person.name?.first.family}');
}

Resource Cache System

FHIR-FLI Mapping provides three levels of resource caching:

• ResourceCache: Abstract base class defining the interface
• CanonicalResourceCache: Local in-memory cache
• OnlineResourceCache: Combines local caching with online resolution

// For offline-only operation
final localCache = CanonicalResourceCache();

// For mixed local/online operation
final onlineCache = OnlineResourceCache();

Advanced Usage

Working with Builders

For complex transformations, you can work directly with builders:

final result = await mapEngine.transformBuilder(
  '',  // Default group
  sourceBuilder,
  structureMap,
  targetBuilder,
);

Custom Type Handling

Provide a callback to handle custom resource types:

mapEngine.extendedEmptyFromType = (String type) {
  switch (type.toLowerCase()) {
    case 'mycustomtype': 
      return MyCustomTypeBuilder.empty();
    default: 
      return null;  // Default handling
  }
};

Documentation

For more detailed information, see the official documentation.

License

MIT

Related Packages

• fhir: Core FHIR package for Dart
• fhir_r4: R4 FHIR resources and models
• fhir_path: FHIRPath implementation for Dart