HL7v2

Warning

Active Development: This project is under active development and is not recommended for use in production workloads. APIs and features may change without notice.

@rethinlhealth/hl7v2 is a tool that transforms HL7v2 messages with plugins using the unified framework. These plugins can inspect, transform, and validate the HL7v2 messages. You can use @rethinkhealth/hl7v2 on the server, the client, deno, etc.

Intro

@rethinlhealth/hl7v2 is an ecosystem of plugins that work with HL7v2 as structured data, specifically ASTs (abstract syntax trees). ASTs make it easy for programs to deal with HL7v2. We call those programs plugins. Plugins inspect and change trees. You can use the many existing plugins or you can make your own.

The unified framework is a powerful and proven tool for building parsers, transformers, and compilers for structured text formats. It is widely used in the JavaScript/TypeScript ecosystem for processing formats like Markdown, HTML, and more. HL7v2 messages, while unique to healthcare, share many characteristics with these formats: they are line-oriented, hierarchical, and benefit from being represented as abstract syntax trees (ASTs).

By leveraging unified for HL7v2 parsing, we gain:

• Structured Parsing: HL7v2 messages are notoriously difficult to work with as plain text. Parsing them into ASTs makes it much easier to analyze, transform, and validate messages programmatically.
• Consistency: unified provides a consistent interface for parsing, transforming, and serializing data, making it easier for developers to work with HL7v2 alongside other formats.
• Interoperability: The unified ecosystem is mature and well-documented, allowing HL7v2 tools to interoperate with a wide range of existing plugins and utilities.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

npm install @rethinkhealth/hl7v2

Use

import { parseHL7v2 } from '@rethinkhealth/hl7v2';

const hl7v2 = `MSH|^~\\&|SendingApp|SendingFac|ReceivingApp|ReceivingFac|202406101200||ADT^A01|123456|P|2.5
PID|1||123456^^^Hospital^MR||Doe^John^^^^^L||19800101|M|||123 Main St^^Metropolis^NY^10001||555-1234`;

const tree = parseHL7v2.parse(hl7v2);

console.error(reporter(file))
console.log(String(file)));

Packages

The @rethinkhealth/hl7v2 ecosystem is organized as a set of modular packages, each focused on a specific aspect of HL7v2 message processing. These packages are designed to work together or independently, depending on your needs.

Core Packages

• @rethinkhealth/hl7v2: main entry point for HL7v2 message parsing, transformation, and validation. It provides a unified interface for working with HL7v2 messages as ASTs.

• @rethinkhealth/hl7v2-parser: a unified-compatible parser that converts HL7v2 message text into a structured AST. It handles delimiter detection, segment/field/component parsing, and position tracking. This package is used internally by @rethinkhealth/hl7v2, but can be used standalone for custom workflows.

• @rethinkhealth/hl7v2-jsonify: serializes HL7v2 ASTs to JSON. This is useful for integrating HL7v2 data with modern web APIs and applications.

• @rethinkhealth/hl7v2-ast: defines the TypeScript types and interfaces for the HL7v2 AST structure. Ensures type safety and consistency across all packages in the ecosystem.

• @rethinkhealth/hl7v2-cli: a command-line tool for parsing, validating, and transforming HL7v2 messages. Useful for quick inspection, conversion, and automation in CI/CD pipelines.

Plugins

Plugins are composable functions that extend or modify the behavior of the HL7v2 processor. Plugins can add support for new syntaxes, transform the abstract syntax tree (AST), or integrate with external tools.

• @rethinkhealth/hl7v2-decode-escapes: decodes HL7v2 escape sequences (e.g., \F\, \S\, \T\, etc.) into their literal values, ensuring message content is interpreted correctly.

Utilities

Utilities are supporting packages that provide common helper functions and low-level tools used throughout the HL7v2 ecosystem. Utilities help ensure consistency, reduce duplication, and simplify maintenance across all related packages.

• @rethinkhealth/hl7v2-utils: shared utilities for delimiter detection, normalization, and other HL7v2-specific helpers.

Contributing

We welcome contributions! Please see our Contributing Guide for more details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code of Conduct

To ensure a welcoming and positive environment, we have a Code of Conduct that all contributors and participants are expected to adhere to.

License

Copyright 2025 Rethink Health, SUARL. All rights reserved.

This program is licensed to you under the terms of the MIT License. This program is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the LICENSE file for details.