@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/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/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 self-contained type-safe builders from HL7v2 schema:

# Generate all files for specified message types into output folder
bun src/hl7v2/codegen.ts ./output ADT_A01 BAR_P01

# This generates:
#   ./output/types.ts    - Core types (FieldValue, HL7v2Segment, HL7v2Message)
#   ./output/fields.ts   - DataType interfaces and segment builders
#   ./output/messages.ts - Message builders for specified message types

Generated code includes:

• Core types (types.ts) - FieldValue, HL7v2Segment, HL7v2Message, getComponent()
• DataType interfaces (fields.ts) - XPN, CX, HD, etc. with typed properties
• Segment builders (fields.ts) - PIDBuilder, MSHBuilder with fluent setters/getters
• Message builders (messages.ts) - ADT_A01Builder with segment orchestration
• Converter functions (fields.ts) - fromXPN, fromCX for parsing support

The generated code is self-contained and doesn't depend on src/hl7v2/.

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
├── types.ts                 # Generated core types
├── fields.ts                # Generated ADT_A01 segment builders
└── 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.