@atomic-ehr/hl7v2

A TypeScript library for parsing and generating HL7v2 messages with type-safe, schema-driven builders.

Features

• Parse HL7v2 wire format to typed internal representation
• Generate HL7v2 messages using fluent, type-safe builders
• Schema-driven code generation from HL7v2 specification
• Zero dependencies - pure TypeScript implementation

Installation

bun install

Quick Start

Parsing HL7v2 Messages

import { parseMessage } from "./src/hl7v2/parse";

const wire = `MSH|^~\\&|HOSPITAL|FAC|||20231201||ADT^A01|MSG001|P|2.5.1
PID|1||12345^^^HOSP^MR||Smith^John||19800515|M`;

const message = parseMessage(wire);

// Access segments
const pid = message.find(s => s.segment === "PID");
console.log(pid?.fields[5]); // { 1: "Smith", 2: "John" }

Building HL7v2 Messages

import { ADT_A01Builder } from "./example/adt-a01-messages";
import { formatMessage } from "./src/hl7v2/format";

const message = new ADT_A01Builder()
  .msh(msh => msh
    .set_msh_3_sendingApplication({ namespace_1: "HOSPITAL" })
    .set_msh_9_messageType({ code_1: "ADT", event_2: "A01" })
  )
  .pid(pid => pid
    .set_pid_3_identifier([{ value_1: "12345", type_5: "MR" }])
    .set_pid_5_name([{ family_1: { family_1: "Smith" }, given_2: "John" }])
  )
  .build();

const wireFormat = formatMessage(message);

Using Typed Getters

import { PIDBuilder } from "./example/adt-a01-fields";

// After parsing, use getters to extract typed data
const pid = new PIDBuilder();
(pid as any).seg = parsedPidSegment;

const names = pid.get_pid_5_name();
// names[0].family_1?.family_1 => "Smith"
// names[0].given_2 => "John"

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Wire Format   │────▶│    Internal     │────▶│   Wire Format   │
│  (pipe-delim)   │     │ Representation  │     │  (pipe-delim)   │
└─────────────────┘     └─────────────────┘     └─────────────────┘
    parseMessage()           HL7v2Message         formatMessage()

Internal Representation

Messages use a minimal, JSON-friendly structure:

type FieldValue = string | FieldValue[] | { [key: number]: FieldValue };

interface HL7v2Segment {
  segment: string;           // "MSH", "PID", etc.
  fields: Record<number, FieldValue>;
}

type HL7v2Message = HL7v2Segment[];

Code Generation

The codegen.ts generates type-safe builders from HL7v2 schema:

# Generate segment builders (fields.ts)
bun src/hl7v2/codegen.ts ADT_A01 > output/fields.ts

# Generate message builders (messages.ts)
bun src/hl7v2/codegen.ts ADT_A01 --messages > output/messages.ts

Generated code includes:

• DataType interfaces (XPN, CX, HD, etc.) with typed properties
• Segment builders (PIDBuilder, MSHBuilder) with fluent setters/getters
• Message builders (ADT_A01Builder) with segment orchestration
• Converter functions (fromXPN, fromCX) for parsing support

Project Structure

src/hl7v2/
├── types.ts      # Core types: FieldValue, HL7v2Segment, HL7v2Message
├── parse.ts      # Wire format → Internal representation
├── format.ts     # Internal representation → Wire format
├── codegen.ts    # Schema-driven code generator
├── fields.ts     # Generated segment builders (BAR_P01)
└── messages.ts   # Generated message builders (BAR_P01)

schema/
├── messages/     # Message structure definitions
├── segments/     # Segment field definitions
├── fields/       # Field metadata
├── dataTypes/    # Complex type components
└── structure/    # Message type → structure mapping

example/
├── adt-a01-example.ts       # Building ADT^A01 message
├── parse-to-fhir-example.ts # Parsing to FHIR Patient
├── adt-a01-fields.ts        # Generated ADT_A01 builders
└── adt-a01-messages.ts      # Generated ADT_A01 message builder

Running Examples

# Build and format an ADT^A01 message
bun example/adt-a01-example.ts

# Parse ADT^A01 and extract FHIR Patient
bun example/parse-to-fhir-example.ts

Testing

bun test

Credits

Created by Nikolai Ryzhikov. Sponsored by Health Samurai.

HL7v2 schema metadata derived from redox-hl7-v2 by Redox Engine.

License

MIT License - see LICENSE for details.