Skip to main content
Version: v0.1.5

@cosyte/transform

Turn a parsed HL7 v2 message into FHIR R4, mapped from the HL7 Version 2 to FHIR Implementation Guide, without reading the 900-page v2 spec and without hand-writing a ConceptMap.

@cosyte/transform is the healthcare transformation layer of the Cosyte suite. Unlike the parsers, it is a consumer: it takes already-parsed @cosyte/hl7 composites and produces validated @cosyte/fhir model nodes, grounded on the official HL7 Version 2 to FHIR Implementation Guide (hl7.fhir.uv.v2mappings).

"Validated" there means a small internal required-element check before a resource ships, which is a floor and not a conformance claim. How far the output actually conforms is measured separately, against pinned FHIR R4 4.0.1 definitions and a pinned profile package, over the guide's own published test messages, and the outcome is published in the repository as documentation/conformance/report.md. Read that before relying on the word "validated": today it says none of the seven published messages produces a Bundle that is clean against R4 plus those profiles, and it lists every finding.

Status: the 0.1 line, published to npm. While the package is below 1.0, a breaking change ships in a minor version and is called out in the changelog. See Installation. This release ships the six safety-critical datatype converters and the value-free diagnostic channel, and message-level assembly via toFhir(msg) for HL7 v2 ADT → Patient + Encounter (+ AL1 → AllergyIntolerance, DG1 → Condition, PR1 → Procedure and IN1 → Coverage), ORU^R01 → DiagnosticReport + Observation, the order-entry graph ORM_O01 / OML_O21 → ServiceRequest and RXO → MedicationRequest (with an order's TQ1 → the schedule it carries, dosageInstruction.timing or occurrenceTiming), and the thin IG singles VXU_V04 → Immunization, SIU_S12 → Appointment, and MDM_T02 → DocumentReference, plus terminology value translation of coded fields: route/site, appointment type, order priority, substitution, and the AL1 allergy tables, translated through their IG mappedVia ConceptMaps. A narrow reverse path also ships, FHIR → v2: toV2Patient(patient, trigger) and toV2Observation(observation, trigger) emit a complete v2 message carrying a PID or an OBX, lossy by design and never a round-trip. Deeper terminology, profiles, and any wider FHIR → v2 conversion are not implemented.

The fail-safe rule​

Every conversion is grounded on the IG: an unmapped code, an ambiguous datatype, a v2 timestamp with no timezone, or an unresolvable assigning authority becomes a typed, value-free diagnostic, never a silent default, never a fabricated value, never a guessed UTC offset.

Install​

npm install @cosyte/transform @cosyte/hl7 @cosyte/fhir

@cosyte/hl7 and @cosyte/fhir are peer dependencies: the transform maps between the models they own, so you install them alongside it. All three are on npm, and the command above installs them together. Installation has the detail.

Next​