Skip to main content
Version: v0.1.0

@cosyte/transform

Turn a parsed HL7 v2 message into valid FHIR R4, without reading the 900-page v2 spec, without hand-writing a ConceptMap, and without ever being handed a confident wrong FHIR value.

@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: pre-alpha (0.0.x). The package is published on npm, but it cannot be installed from npm yet: 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. The v2→FHIR direction is feature-complete for the IG-covered message set. 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 promise​

Every conversion is grounded on the IG and is fail-safe: 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. That command does not work yet: @cosyte/fhir is not on the registry, so npm fails with ERESOLVE and refuses to resolve that peer. Until it publishes, consume this package from source or a workspace link. Installation has the detail.

Next​