HL7-Parser

HL7 Parser Overview

Our HL7 parser is designed to extract specific data from HL7 string messages. Our approach focuses on a dynamic query-based system rather than pre-generating a fully resolved data structure. Data is only extracted at the moment of access, allowing for immediate processing with additional functions.

To optimize performance, every queried data path is stored in an internal cache to prevent redundant traversal of the message string.

Core Assumptions

To ensure predictable behavior, the following constraints and structures are assumed:

• Maximum Path Depth: Paths are limited to a maximum of 4 levels: Segment, Field, Component, and SubComponent.
• Segment Repetition: Segments may occur multiple times within a single message.
• Field Repetition: Fields may contain repeating values.
• Maximum Path Resolution: The most complex path possible is defined as: Segment[] -> Field[] -> Component -> SubComponent
• Iteration: Loops or sequences may be required when traversing multiple segments or repeating fields.

1. Initialization

To parse an HL7 message, create a new instance of the HL7Parser by passing the raw message string:

const msg = new HL7Parser(hl7Message);

2. Path-Based Data Extraction

Values are retrieved using path strings. The hierarchy (Segment, Field, Component, Sub-component) is traversed using a dash-separated (-) syntax.

const msg = new HL7Parser(hl7Message);

const segment      = msg.get('PID');       // Access Segment level
const field        = msg.get('PID-3');     // Access Field level
const component    = msg.get('PID-3-1');   // Access Component level
const subComponent = msg.get('PID-3-1-1'); // Access Sub-component level

1-Based Selection

Paths follow the official HL7 standard numbering (starting at 1). For example, PV1-1 refers to the first field of the PV1 segment as defined in HL7 Specifications.

3. Handling Array Structures & Indices

HL7 segments and fields often repeat (collections). These can be accessed using square brackets [].

const msg = new HL7Parser(hl7Message);

// Equivalent calls (Defaulting to index 0)
const segmentA = msg.get('PID');
const segmentB = msg.get('PID[0]');

// Accessing the second occurrence of a PID segment
const segmentC = msg.get('PID[1]');

// Accessing repeating fields
const fieldA = msg.get('PID-1');
const fieldB = msg.get('PID-1[0]'); // Identical to fieldA
const fieldC = msg.get('PID-1[1]'); // Accesses the second value of Field 1

Default Index

If no index is explicitly provided, the parser defaults to index 0 (the first occurrence).

4. The Hl7Value Class

The get method always returns an instance of the Hl7Value class or undefined if the path is invalid or no value exists. This wrapper provides convenient methods to handle both raw and processed data.

Methods & Properties

Member	Type	Description
.toString()	Method	Returns the decoded value (resolves HL7 escape sequences like \T\).
.escapedValue()	Method	Returns the raw value exactly as it appears in the message.
.get(path)	Method	Allows relative traversal from the current object's position.
.list	Property	Returns a list of all values available at the current path.

Example: Decoding Escape Sequences

HL7 messages use escape sequences for special characters. The Hl7Value class handles these automatically:

/** Assume PID-1 contains: Mark\T\Söhne **/
const field = msg.get('PID-1');

console.log(field.toString());     // Output: "Mark&Söhne"
console.log(field.escapedValue()); // Output: "Mark\T\Söhne"

danger

The data retrieval can be result in invalid data if the incorrect method is called on wrong levels on different segments. For example, calling toString() on a Component value which has Subcomponents and looks like (Mustermann&Maier\T\Söhne), the unescaped value would be Mustermann&Maier&Söhne. This is invalid data and can only be resolved by knowing the correct level for the desired data.

For data which does not support component or subcomponent level no full path is required. If ABC-1 is defined as simple string type, msg.get('ABC-1') will return the same value as msg.get('ABC-1-1') or msg.get('ABC-1-1-1').

Example: Relative Traversal

You can chain get calls or use relative paths on an existing `Hl7Value instance:

const msg = new HL7Parser(hl7Message);
const field = msg.get('PID-1');

// Extract the first component relative to the selected field
const component = field.get('1');

danger

You as a user have to know on which level you are working.

Example: Loop over Segment or Field Repetitions

const msg = new HL7Parser(hl7Message);
const segment = msg.get('PID');

segment.list.forEach(field => {
  console.log(field.toString());

  // or
  field.list.forEach(component => {
      console.log(component.toString());
  })

  // etc.
})

list details

The array retrieved via .list includes all values of the current path, even if you select a specific index. e.g. PID-1[0].list returns all values of Field 1, including the second occurrence. only the actual value returned by toString() | escapedValue() is the actual value of the second occurrence. the content of the list is again a Hl7Value object for each value. Every value always returns an Array, even if it only contains a single value.