Skip to content

README.md

Latest commit

 

History

History
254 lines (188 loc) · 7.84 KB

README.md

File metadata and controls

254 lines (188 loc) · 7.84 KB

FML Runner

A Kotlin Multiplatform library for compiling and executing FHIR Mapping Language (FML) files to transform healthcare data using FHIR StructureMaps.

Overview

FML Runner provides a shared core business logic implementation using Kotlin Multiplatform, enabling:

  1. Cross-Platform Compilation - FHIR Mapping Language (FML) content compilation using shared Kotlin core
  2. Universal Execution - StructureMap execution with kotlin-fhirpath integration
  3. FHIR Terminology Management - ConceptMaps, ValueSets, CodeSystems with consistent behavior
  4. Bundle Processing - FHIR Bundle operations across all platforms
  5. Performance Optimization - Intelligent caching and shared implementation

Architecture

Shared Core (Kotlin Multiplatform)

  • FML Compiler: Tokenization and parsing logic using Kotlin
  • StructureMap Executor: Transformation engine with kotlin-fhirpath support
  • FHIR Types: Shared data structures and interfaces
  • Terminology Services: Cross-platform resource management

Platform-Specific Features

  • JVM/Android: Native Kotlin performance with full FHIR ecosystem integration
  • JavaScript/Node.js: Compiled Kotlin/JS for web and server-side execution

Building

Prerequisites

  • JDK: 11 or higher
  • Gradle: 8.4 or higher
  • Node.js: 16+ (for JavaScript targets)

Build Commands

# Build all targets (JVM + JavaScript)
gradle build

# Build JVM only
gradle jvmMainClasses

# Build JavaScript only  
gradle jsMainClasses

# Run all tests
gradle test

# Run JVM tests only
gradle jvmTest

# Run JavaScript/Node.js tests only
gradle jsNodeTest

# Clean build artifacts
gradle clean

Usage

From Kotlin/JVM

import org.litlfred.fmlrunner.FmlRunner

val runner = FmlRunner()

// Compile FML
val result = runner.compileFml("""
  map "http://example.org/StructureMap/Patient" = "PatientTransform"
  
  group main(source src, target tgt) {
    src.name -> tgt.fullName;
    src.active -> tgt.isActive;
  }
""")

// Execute transformation
val execResult = runner.executeStructureMap(
  "http://example.org/StructureMap/Patient",
  """{"name": "John Doe", "active": true}"""
)

From JavaScript/Node.js

When built for JavaScript, the same API is available:

const { FmlRunner } = require('fmlrunner');

const runner = new FmlRunner();

// Compile and execute FML
const result = runner.compileFml(`
  map "http://example.org/StructureMap/Patient" = "PatientTransform"
  
  group main(source src, target tgt) {
    src.name -> tgt.fullName;
    src.active -> tgt.isActive;
  }
`);

const execResult = runner.executeStructureMap(
  "http://example.org/StructureMap/Patient",
  JSON.stringify({name: "John Doe", active: true})
);

Development

Project Structure

fmlrunner/
├── src/
│   ├── commonMain/kotlin/          # Shared Kotlin code for all platforms
│   │   └── org/litlfred/fmlrunner/
│   │       ├── FmlRunner.kt        # Main API
│   │       ├── compiler/           # FML compilation logic
│   │       ├── executor/           # StructureMap execution
│   │       ├── terminology/       # FHIR terminology services
│   │       └── types/              # FHIR data types
│   ├── jvmMain/kotlin/             # JVM-specific implementations
│   ├── jsMain/kotlin/              # JavaScript-specific implementations
│   ├── commonTest/kotlin/          # Shared tests
│   ├── jvmTest/kotlin/             # JVM-specific tests
│   └── jsTest/kotlin/              # JavaScript-specific tests
├── build.gradle.kts                # Kotlin Multiplatform build configuration
└── build/                          # Generated build artifacts

Development Workflow

# Install dependencies and setup project
gradle build

# Run all tests (JVM + JavaScript)
gradle jvmTest jsNodeTest

# Start development with auto-rebuild
gradle build --continuous

# Run specific platform tests
gradle jvmTest    # JVM tests only  
gradle jsNodeTest # JavaScript/Node.js tests only

# Generate documentation
gradle dokkaHtml

Key Features

FHIR Mapping Language Support

  • Complete FML parser with proper tokenization and grammar handling using Kotlin
  • Cross-platform compilation - same FML parsing logic on JVM and JavaScript
  • Robust parsing with graceful error recovery and validation

FHIR Terminology Ecosystem

  • ConceptMap operations: CRUD + translation with equivalence mapping
  • ValueSet operations: CRUD + expansion and code validation
  • CodeSystem operations: CRUD + code lookup and validation
  • StructureDefinition management: Cross-platform validation support
  • Bundle processing: Bulk resource operations

Advanced Execution Engine

  • kotlin-fhirpath integration ready for cross-platform FHIRPath evaluation
  • Terminology-aware transformations with ConceptMap integration
  • Validation support with strict/non-strict execution modes
  • Memory-efficient caching for repeated executions

Developer Experience

  • Kotlin Multiplatform: Write once, run on JVM and JavaScript
  • Type Safety: Full Kotlin type definitions across platforms
  • Comprehensive testing: Platform-specific and shared test coverage
  • Performance: Native performance on JVM, optimized JavaScript compilation

Testing

The project includes comprehensive test coverage across platforms:

  • FML Compilation Tests: Parser validation and StructureMap generation
  • Execution Tests: Transformation logic and cross-platform behavior
  • Terminology Tests: ConceptMap, ValueSet, CodeSystem operations
  • Platform Tests: JVM and JavaScript specific functionality

Run specific test suites:

# Run all tests (JVM + JavaScript)
gradle jvmTest jsNodeTest

# Run JVM tests only
gradle jvmTest

# Run JavaScript/Node.js tests only 
gradle jsNodeTest

# Run with verbose output
gradle test --info

# Run specific test class
gradle jvmTest --tests "FmlRunnerTest"

API Reference

Core FmlRunner API

class FmlRunner {
    // Core compilation and execution
    fun compileFml(fmlContent: String): FmlCompilationResult
    fun executeStructureMap(reference: String, inputContent: String): ExecutionResult
    
    // Resource management
    fun registerStructureMap(structureMap: StructureMap): Boolean
    fun getStructureMap(reference: String): StructureMap?
    fun searchStructureMaps(name: String?, status: StructureMapStatus?, url: String?): List<StructureMap>
    
    // Terminology operations
    fun registerConceptMap(conceptMap: ConceptMap)
    fun translateCode(sourceSystem: String, sourceCode: String, targetSystem: String?): List<TranslationResult>
    fun registerValueSet(valueSet: ValueSet) 
    fun validateCodeInValueSet(code: String, system: String?, valueSetUrl: String?): ValidationResult
    fun registerCodeSystem(codeSystem: CodeSystem)
    fun lookupCode(system: String, code: String): LookupResult?
    
    // Bundle operations
    fun processBundle(bundle: Bundle): BundleProcessingResult
    fun getBundleStats(): BundleStats
}

Implementation Status

✅ Complete Kotlin Multiplatform implementation:

  • Robust FML parser with complete tokenization and parsing
  • Cross-platform StructureMap execution engine
  • Comprehensive FHIR terminology services
  • Platform-specific optimizations (JVM + JavaScript)
  • Ready for kotlin-fhirpath integration
  • Comprehensive test coverage across platforms
  • Type-safe APIs with serialization support

Test Results: All platform tests passing (JVM + JavaScript/Node.js)

License

MIT License - see LICENSE file for details.

Contributing

Please refer to the requirements documents in the docs/ directory for implementation guidelines and specifications. All contributions should maintain the existing test coverage and follow the established Kotlin coding patterns.