glion

Getting Started

Glion is an open-source application framework for building HL7v2 integrations. It includes a structured parser, a plugin ecosystem for validation and transformation, and a production-ready MLLP server.

Features

• 🚀 Zero-config CLI. glion dev runs your app with live reload during development. glion start runs it in production with graceful shutdown and structured logs.
• 🌍 MLLP server. A standards-compliant HL7v2 server with pattern-based routing (ADT^A01, ADT^*, wildcards), middleware composition, and first-class ACK/NAK responses. Streaming TCP with back-pressure. Runs on Node, Bun, and Deno.
• 🧰 Parser and plugin ecosystem. A unified-based parser that produces typed ASTs with lossless round-tripping, plus 25+ plugins for annotation, linting, encoding, and transformation.
• ⛑️ Profile validation. Validate against HL7-published profiles for fields, data types, table values, and segment order — automatically selected by the version in MSH-12.

Quick start

Install Glion and its runtime packages:

npm install @glion/mllp @glion/hl7v2 @glion/mllp-ack @glion/cli

Define your app in a single file:

// glion.app.ts
import { parseHL7v2 } from "@glion/hl7v2";
import { Mllp } from "@glion/mllp";
import { ackMiddleware } from "@glion/mllp-ack";

export default new Mllp()
  .parser(parseHL7v2)
  .use(ackMiddleware())
  .on("ADT^A01", () => {
    // Handle admit — ackMiddleware sends the AA automatically.
  });

Run npm dev to start the app with live reload during development. Run npm start to run it in production with graceful shutdown and structured logs.

See examples/ for zero-config, explicit-config, and low-level transport examples.

Packages

Glion is split into two cooperating layers. Use them together, or pick the parts you need.

Runtime

The server and tooling that run Glion applications.

Server & transport

• @glion/mllp — a transport-agnostic MLLP (Minimal Lower Layer Protocol) engine with pattern-based routing, middleware, and unified processor integration.
• @glion/cli — the glion command for running Glion applications: glion dev for live reload during development, glion start for production with graceful shutdown and structured logs.

Acknowledgments

• @glion/ack — build standards-compliant HL7v2 acknowledgment messages (AA, AE, AR) with typed error classes.
• @glion/mllp-ack — MLLP middleware that automatically generates ACK/NAK responses and maps handler exceptions to the right acknowledgment code.

Unified

The parser, plugins, and utilities that process HL7v2 messages as structured data.

Core

• @glion/hl7v2 — the main content pipeline with sensible defaults for parsing, annotating, linting, and serializing HL7v2 messages.
• @glion/parser — a unified-compatible parser that converts HL7v2 text into a structured AST with delimiter detection and position tracking.
• @glion/ast — TypeScript types for the HL7v2 AST, implementing the unist specification.
• @glion/builder — programmatic construction of HL7v2 AST nodes, useful for tests, fixtures, and synthetic messages.
• @glion/to-hl7v2 — serialize AST nodes back to HL7v2 message text, preserving delimiters.
• @glion/jsonify — serialize HL7v2 ASTs to a simplified JSON representation.

Plugins

Composable plugins that annotate, enrich, and transform the AST.

• @glion/annotate-delimiters — annotate file.data with the HL7v2 delimiters derived from MSH-1 and MSH-2.
• @glion/annotate-profile-context — load and attach HL7v2 profile context to file.data for downstream plugins.
• @glion/annotate-profile-segments — annotate segment nodes with profile metadata.
• @glion/annotate-profile-fields — annotate field nodes with profile metadata.
• @glion/annotate-profile-datatypes — annotate field repetitions, components, and subcomponents with datatype profile metadata.
• @glion/annotate-profile-fields-code-systems — annotate field-level coded values with UTG code system metadata.
• @glion/decode-escapes — decode HL7v2 escape sequences (\F\, \S\, \T\, \Xdd\, \.br\) into their literal values.
• @glion/encode-escapes — encode delimiter characters in subcomponent values as HL7v2 escape sequences before serialization.

Linting

Linting rules and presets for HL7v2 message quality and conformance.

Presets

• @glion/preset-lint-recommended — bundles all core HL7v2 lint rules for a comprehensive baseline.
• @glion/preset-lint-profile-recommended — bundles all profile-based lint rules that validate messages against HL7v2 version-specific profiles.
• @glion/preset-annotate-profile-recommended — bundles all profile annotation plugins for a complete enrichment pipeline.

Core rules

• @glion/lint-required-message-header — ensure every message includes a required header segment such as MSH.
• @glion/lint-max-message-size — report when a message exceeds a configurable maximum size in bytes or segment count.
• @glion/lint-no-trailing-empty-field — flag empty fields at the end of a segment, which can cause ambiguity or interoperability issues.
• @glion/lint-segment-header-length — validate that segment headers are exactly three characters, as required by the HL7v2 specification.
• @glion/lint-message-version — warn when a message version is unsupported or outside expected constraints.

Profile rules

• @glion/lint-profile-required-fields — validate that required fields per the HL7v2 profile are present and non-empty.
• @glion/lint-profile-required-components — validate that required components within composite data types are present.
• @glion/lint-profile-field-max-length — enforce field value maximum lengths defined in the HL7v2 profile.
• @glion/lint-profile-field-repetition — flag non-repeatable fields that contain multiple repetitions.
• @glion/lint-profile-table-values — validate coded values against HL7v2 table definitions (UTG).
• @glion/lint-profile-events-segments-order — validate segment ordering per the message structure definition.
• @glion/lint-profile-extra-fields — flag segments that contain fields beyond the maximum sequence defined in the profile.
• @glion/lint-profile-extra-components — flag composite fields that contain more components than the datatype profile defines.

Utilities

• @glion/utils — shared helpers for delimiter detection, normalization, and other HL7v2-specific operations.
• @glion/util-visit — a visitor pattern for traversing HL7v2 ASTs with full path context, metadata extraction, and control flow actions.
• @glion/util-query — canonical path querying with syntax like MSH-9.3 or ORDER-ORC-1 for select, selectAll, value, set, and matches.
• @glion/util-semver — tiny, fast HL7v2 version and range comparators.
• @glion/util-timestamp — HL7v2 timestamp parsing, formatting, and conversion with precision tracking.
• @glion/profiles — HL7v2 version-specific profile definitions (fields, data types, tables, segments) with LRU-cached loading, used by the profile-based lint rules.
• @glion/config — configuration schema and loader for HL7v2 processing (.hl7v2rc.json).

Documentation

• Full documentation at glion.dev.
• Runnable examples in examples/ covering zero-config, explicit-config, and low-level transport usage.
• API reference and detailed usage in each package's README, linked from the Packages section above.

Status

Glion is pre-1.0. APIs in published packages are stabilizing but may still change in minor releases. We recommend pinning exact versions in production applications.

Packages were previously published under @rethinkhealth/hl7v2-* and were renamed to @glion/*. The unscoped glion command is published as @glion/cli pending npm name approval.

Preview releases

Every pull request and every commit on main publishes preview packages to pkg.pr.new. Install an unreleased fix or feature by its commit SHA, without waiting for a Changesets release:

pnpm add https://pkg.pr.new/@glion/parser@<commit-sha>

Replace @glion/parser with any published @glion/* package. Preview URLs are surfaced as a bot comment on each open PR. See ADR 0016 for rationale and scope.

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 2026 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.