helios_serde/lib.rs
1//! # Helios FHIR Server Serialization Module
2//!
3//! This crate provides version-agnostic JSON and XML serialization for FHIR resources.
4//!
5//! ## Features
6//!
7//! - **JSON Support**: Thin wrappers around `serde_json` that leverage the existing
8//! `FhirSerde` derive macro for correct FHIR JSON representation. Always available.
9//! - **XML Support**: Custom `serde::Serializer` and `serde::Deserializer` implementations
10//! that stream directly to/from FHIR XML format without materializing JSON intermediates.
11//! Requires the `xml` feature flag: `helios-serde = { features = ["xml"] }`.
12//! - **Version Agnostic**: Works with all FHIR versions (R4, R4B, R5, R6) through the
13//! `Element<V, E>` infrastructure.
14//!
15//! ## Architecture
16//!
17//! The crate uses a streaming approach for maximum performance:
18//!
19//! - **JSON Layer**: Direct delegation to `serde_json` functions
20//! - **XML Layer**: Custom `Serializer`/`Deserializer` trait implementations that:
21//! - Receive serialize/deserialize calls as the resource is traversed
22//! - Buffer minimally (only what's needed for FHIR pattern detection)
23//! - Write/read quick-xml events directly
24//!
25//! ## FHIR JSON ↔ XML Mapping
26//!
27//! The XML implementation handles FHIR's unique serialization patterns:
28//!
29//! | JSON Pattern | XML Pattern |
30//! |--------------|-------------|
31//! | `{"active": true}` | `<active value="true"/>` |
32//! | `{"birthDate": "1974-12-25", "_birthDate": {"id": "123"}}` | `<birthDate id="123" value="1974-12-25"/>` |
33//! | `{"given": ["John", "Doe"]}` | `<given value="John"/><given value="Doe"/>` |
34//! | `{"given": ["A", null], "_given": [null, {"id": "123"}]}` | `<given value="A"/><given id="123"/>` |
35//!
36//! ## Examples
37//!
38//! ### JSON Serialization
39//!
40//! ```ignore
41//! use helios_serde::json::{to_json_string, from_json_str};
42//! use helios_fhir::r4::Patient;
43//!
44//! // Serialize to JSON
45//! let patient = Patient::default();
46//! let json = to_json_string(&patient)?;
47//!
48//! // Deserialize from JSON
49//! let patient: Patient = from_json_str(&json)?;
50//! ```
51//!
52//! ### XML Serialization (Coming Soon)
53//!
54//! ```ignore
55//! use helios_serde::xml::{to_xml_string, from_xml_str};
56//! use helios_fhir::r4::Patient;
57//!
58//! // Serialize to XML
59//! let patient = Patient::default();
60//! let xml = to_xml_string(&patient)?;
61//!
62//! // Deserialize from XML
63//! let patient: Patient = from_xml_str(&xml)?;
64//! ```
65pub mod error;
66pub mod json;
67#[cfg(feature = "xml")]
68pub mod xml;
69
70// Re-export common types and functions
71pub use error::{Result, SerdeError};
72
73// Re-export JSON functions at top level for convenience
74pub use json::{
75 from_json_slice, from_json_str, from_json_value, to_json_string, to_json_string_pretty,
76 to_json_value, to_json_vec,
77};
78
79// Re-export XML functions at top level for convenience
80#[cfg(feature = "xml")]
81pub use xml::{
82 from_xml_reader, from_xml_slice, from_xml_str, to_xml_string, to_xml_vec, to_xml_writer,
83};