fhirpath_support

The helios-fhirpath-support crate serves as a bridge module that provides essential types and traits for integration between the FHIRPath evaluator, it's associated functions, and also the FHIR model code in the fhir module, and it's generated code that is created by fhir_macro.

Purpose and Scope

helios-fhirpath-support acts as a communication layer that allows:

• FHIRPath evaluator to work with unified result types
• FHIR data structures to convert into FHIRPath-compatible formats
• Code generation macros to produce FHIRPath-aware implementations
• Type conversion system to handle data transformation of primitive types

The crate provides the shared vocabulary that all other components use when working with FHIRPath expressions and FHIR data.

Architecture and Design

Core Responsibility

As a bridge module, fhirpath_support:

1. Defines Common Types: Provides EvaluationResult and EvaluationError that serve as the universal data exchange format
2. Enables Conversions: Offers the IntoEvaluationResult trait for converting FHIR types to FHIRPath results
3. Ensures Consistency: Guarantees that all components use the same result representation
4. Minimizes Dependencies: Keeps a lean dependency footprint to avoid circular dependencies

Key Types

EvaluationResult

The central data type representing any value that can result from FHIRPath expression evaluation:

pub enum EvaluationResult {
    Empty,                              // FHIRPath empty result
    Boolean(bool),                      // true/false values
    String(String),                     // Text values
    Decimal(Decimal),                   // High-precision numbers
    Integer(i64),                       // Whole numbers
    Date(String),                       // Date values (ISO format)
    DateTime(String),                   // DateTime values (ISO format)
    Time(String),                       // Time values (ISO format)
    Quantity(Decimal, String),          // Value with unit (e.g., "5.4 mg")
    Collection {                        // Arrays/lists of values
        items: Vec<EvaluationResult>,
        has_undefined_order: bool,
    },
    Object(HashMap<String, EvaluationResult>), // Key-value structures
}

EvaluationError

Comprehensive error handling for FHIRPath evaluation failures:

pub enum EvaluationError {
    TypeError(String),                  // Type mismatch errors
    InvalidArgument(String),            // Function argument errors
    UndefinedVariable(String),          // Variable resolution errors
    InvalidOperation(String),           // Operation errors
    InvalidArity(String),               // Function arity errors
    InvalidIndex(String),               // Array indexing errors
    DivisionByZero,                     // Math errors
    ArithmeticOverflow,                 // Overflow errors
    InvalidRegex(String),               // Regex compilation errors
    InvalidTypeSpecifier(String),       // Type specifier errors
    SingletonEvaluationError(String),   // Collection cardinality errors
    SemanticError(String),              // Semantic validation errors
    Other(String),                      // Generic errors
}

IntoEvaluationResult Trait

The universal conversion interface that enables any FHIR type to become a FHIRPath result:

pub trait IntoEvaluationResult {
    fn to_evaluation_result(&self) -> EvaluationResult;
}

Usage Across the Codebase

1. FHIRPath Evaluator Integration (crates/fhirpath)

Primary Consumer: The fhirpath crate is the main consumer of fhirpath_support, importing it in virtually every module:

// Used in all FHIRPath function modules
use helios_fhirpath_support::{EvaluationError, EvaluationResult};

Modules using fhirpath_support:

• evaluator.rs - Core expression evaluation engine
• aggregate_function.rs - aggregate() function implementation
• boolean_functions.rs - Boolean logic operations
• collection_functions.rs - Collection manipulation functions
• conversion_functions.rs - Type conversion functions
• date_arithmetic.rs - Date/time arithmetic operations
• extension_function.rs - FHIR extension access
• polymorphic_access.rs - Choice element handling
• trace_function.rs - Debug tracing functionality
• truncate_function.rs - Decimal truncation
• type_function.rs - Type reflection operations
• And many more...

Public Re-export: The fhirpath crate re-exports EvaluationResult for external consumers:

pub use helios_fhirpath_support::EvaluationResult;

2. FHIR Data Structure Integration (crates/fhir)

FHIR Type Conversion: The main fhir crate imports fhirpath_support to enable FHIR data structures to work with FHIRPath:

use helios_fhirpath_support::{EvaluationResult, IntoEvaluationResult};

Purpose: Enables FHIR resources, data types, and elements to be seamlessly converted into FHIRPath-compatible formats for expression evaluation.

3. Code Generation Integration (crates/fhir_macro)

Macro-Generated Implementations: The fhir_macro crate uses fhirpath_support extensively to generate FHIRPath-aware code:

/// Derives the `fhirpath_support::IntoEvaluationResult` trait.
impl fhirpath_support::IntoEvaluationResult for GeneratedType {
    fn to_evaluation_result(&self) -> fhirpath_support::EvaluationResult {
        // Generated conversion logic
    }
}

Generated Code Features:

• Automatic IntoEvaluationResult implementations for all FHIR types
• Object serialization to EvaluationResult::Object
• Enum handling for choice types
• Field access and property resolution

Implementation Features

Type System Integration

FHIRPath Type Mapping: Maps FHIR primitive types to appropriate FHIRPath representations:

• FHIR boolean → EvaluationResult::Boolean
• FHIR string/code/uri → EvaluationResult::String
• FHIR integer → EvaluationResult::Integer
• FHIR decimal → EvaluationResult::Decimal (high-precision)
• FHIR date/dateTime/time → EvaluationResult::Date/DateTime/Time
• FHIR arrays → EvaluationResult::Collection
• FHIR complex types → EvaluationResult::Object

Conversion Implementations

Built-in Conversions: Provides implementations for Rust standard types:

impl IntoEvaluationResult for String { /* ... */ }
impl IntoEvaluationResult for bool { /* ... */ }
impl IntoEvaluationResult for i32 { /* ... */ }
impl IntoEvaluationResult for i64 { /* ... */ }
impl IntoEvaluationResult for f64 { /* ... */ }
impl IntoEvaluationResult for Decimal { /* ... */ }
impl<T> IntoEvaluationResult for Option<T> { /* ... */ }
impl<T> IntoEvaluationResult for Vec<T> { /* ... */ }
impl<T> IntoEvaluationResult for Box<T> { /* ... */ }

Advanced Features

Equality and Ordering: Implements proper comparison semantics for FHIRPath:

• Decimal normalization for precise comparison
• Collection order handling
• Object comparison with sorted keys
• Hash implementation for set operations

Boolean Conversion: Sophisticated boolean logic handling:

• Standard boolean values
• String-to-boolean conversion ("true"/"false", "t"/"f", "yes"/"no", "1"/"0")
• Empty result handling
• Collection singleton evaluation

Utility Methods: Rich API for working with evaluation results:

• count() - FHIRPath-compliant item counting
• to_boolean() - FHIRPath boolean conversion rules
• to_string_value() - String representation
• type_name() - Runtime type identification
• is_collection() - Type checking utilities

Dependencies

Minimal and Focused: The crate maintains a lean dependency profile:

• rust_decimal - High-precision decimal arithmetic required for FHIR's precise numeric requirements
• Standard Library - HashMap, collections, and basic types

No FHIR Dependencies: Intentionally avoids depending on FHIR types to prevent circular dependencies and maintain clean separation of concerns.

Development Patterns

Bridge Pattern Implementation

The crate exemplifies the bridge pattern by:

1. Abstracting Representations: Provides a unified result type that abstracts over different FHIR data formats
2. Enabling Conversion: Offers a standard interface for converting between representations
3. Facilitating Communication: Ensures all components speak the same "language" when exchanging data
4. Maintaining Independence: Allows different parts of the system to evolve independently

Extension Points

New Type Support: Adding support for new FHIRPath types requires:

1. Adding variant to EvaluationResult
2. Implementing conversion logic
3. Updating comparison and utility methods
4. Adding appropriate error handling

New Conversion Sources: Supporting new FHIR types requires:

1. Implementing IntoEvaluationResult for the type
2. Handling the conversion logic appropriately
3. Testing the conversion behavior

Testing and Quality

The crate's types implement comprehensive trait support:

• Debug - For debugging and error reporting
• Clone - For value copying and manipulation
• PartialEq/Eq - For value comparison and testing
• PartialOrd/Ord - For sorting and ordering operations
• Hash - For set operations and deduplication

All implementations follow FHIRPath specification requirements for type behavior and conversion rules.

Status and Future

fhirpath_support is a mature, stable component that successfully bridges the FHIRPath evaluator with the FHIR type system. As the foundation for data exchange in the FHIRPath ecosystem, it maintains:

• Backward Compatibility - API stability for dependent crates
• Performance - Efficient conversion and comparison operations
• Correctness - FHIRPath specification compliance
• Extensibility - Clean extension points for new features

Future enhancements focus on:

• Additional FHIRPath type support as the specification evolves
• Performance optimizations for large data sets
• Enhanced error reporting and diagnostics
• Improved conversion utilities for complex scenarios

The crate serves as the essential foundation that enables the entire FHIRPath implementation to function as a cohesive, interoperable system.