Add HL7 v2 XML parsing and FHIR R4 transformation support

[Copilot]

Extends nodehl7 with two new capabilities: parsing HL7 v2 XML-encoded messages (parseXML) and converting any parsed message to a FHIR R4 Bundle (toFHIR). No new runtime dependencies; XML parsing is implemented via a lightweight built-in tokenizer.

New API

hl7Parser.parseXML(xmlContent, ID, callback?): Promise<Hl7Message>

Parses HL7 v2 XML (namespace urn:hl7-org:v2xml). Returns a standard Hl7Message — fully compatible with all existing methods (get, getSegments, toMappedObject, etc.), same Promise + callback API as parse.

Handles:

• MSH field separator/encoding char extraction from MSH.1/MSH.2
• Multi-component fields → string[], single-component → string (mirrors ER7 ^-split behavior)
• Nested group wrapper elements (e.g. <PATIENT>) via recursive segment extraction

Hl7Message.toFHIR(): Record<string, unknown>

Converts to a FHIR R4 Bundle of type message. Works on both parse() and parseXML() results.

HL7 v2	FHIR
MSH-10	MessageHeader.id
MSH-3/4/5	MessageHeader.source / destination
MSH-9	MessageHeader.eventCoding.code
PID-3/5/7/8/11/13	Patient.identifier / name / birthDate / gender / address / telecom

Dates converted from YYYYMMDD → YYYY-MM-DD; gender codes M/F/O/U → male/female/other/unknown.

const xml = fs.readFileSync('./message.xml', 'utf8');
const message = await hl7parser.parseXML(xml, 'msg-001');

message.get('MSH', 'Version ID');   // '2.5'
message.get('PID', 'Patient name'); // ['SMITH', 'JOHN']

const bundle = message.toFHIR();
// { resourceType: 'Bundle', type: 'message', entry: [{ resource: { resourceType: 'MessageHeader', ... } }, { resource: { resourceType: 'Patient', ... } }] }

Other changes

• package.json: bumped to 2.1.0
• CHANGELOG.md / README.md: updated with new method docs and FHIR field mapping table
• test/testfiles/ADTA01.xml: XML equivalent of the existing ADTA01.adm fixture
• test/testXmlAndFhir.js: 33 new tests covering parsing, FHIR output, error paths, callback API, and toMappedObject interop

Original prompt

Aquí tienes la descripción técnica en inglés de la funcionalidad de soporte para formatos XML y JSON (FHIR), estructurada para que un desarrollador o agente de IA pueda entender el contexto de la librería y lo que se requiere implementar:

Feature Request: HL7 v2 XML Support and FHIR (JSON) Transformation

Background:
The nodehl7 library is a NodeJS tool for parsing HL7 v2.x text-based messages (ER7 format) with full TypeScript support and type-safe segment access [1, 2]. Currently, the documentation explicitly states that it does not support XML formats [1].

Objective:
Extend the library's core capabilities to include parsing of XML-encoded HL7 v2 messages and provide a foundation for exporting these messages into modern JSON-based standards like FHIR.

Technical Specifications for Implementation:

1. XML Parser Module:

   • Develop or integrate an XML parser that can read HL7 v2 XML structures.
   • The parser must map XML elements to the library's existing 81 supported segments (e.g., MSH, PID, OBX) [3-5].
   • It should return a standard Hl7Message object to ensure compatibility with existing methods like message.get(segmentname) [6, 7].

2. FHIR/JSON Transformation:

   • Enhance the current toMappedObject() functionality, which converts segments to JavaScript objects [8, 9], to support FHIR (Fast Healthcare Interoperability Resources) mapping. Do it in a new method with an appropriate name.
   • Implement a new method, such as toFHIR(), that transforms the parsed HL7 data into standardized JSON structures.

3. Consistency and Type Safety:

   • All new parsing logic must maintain the TypeScript definitions and strict type safety that characterize the library [1, 2, 10].
   • The implementation should be compatible with the existing Promise-based API (parse and parseFile methods) [2, 11, 12].

4. Testing Requirements:

   • Add new test cases in the test/ directory to validate XML parsing and FHIR output accuracy [13].
   • Ensure the code maintains current standards for code coverage.

be backward compatible.

when done:

• bump next minor version.
• add changes to changelog and readme files.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.