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.
- 🚀 Zero-config CLI.
glion devruns your app with live reload during development.glion startruns it in production with graceful shutdown and structured logs.glion sendfires an HL7v2 message over MLLP and prints the ACK. - 🌍 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.
Install Glion and its runtime packages:
npm install @glion/mllp @glion/hl7v2 @glion/cliDefine your app in a single file:
// glion.app.ts
import { parseHL7v2 } from "@glion/hl7v2";
import { Mllp } from "@glion/mllp";
export default new Mllp().parser(parseHL7v2).on("ADT^A01", (ctx) => {
// Handle admit. Reply by returning a Response ({ raw: string }).
// Built-in ACK/NAK generation is landing in @glion/mllp — see ADR 0019.
});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 runnable apps. Scaffold any of them with pnpm create glion my-app --example <name>.
Glion is split into two cooperating layers. Use them together, or pick the parts you need.
The server and tooling that run Glion applications.
- @glion/mllp — a transport-agnostic MLLP (Minimal Lower Layer Protocol) engine with pattern-based routing, middleware, and
unifiedprocessor integration. - @glion/mllp-client — a persistent, single-flight MLLP client: sends HL7v2 messages over one long-lived connection and resolves each with its correlated ACK.
- @glion/mllp-codec — the MLLP frame/unframe pair:
frame()envelopes outbound bytes andunframe()is a stream transform that reassembles inbound frames across reads. - @glion/cli — the
glioncommand for running Glion applications:glion devfor live reload during development,glion startfor production with graceful shutdown and structured logs, andglion sendfor sending an HL7v2 message over MLLP and printing the ACK.
- @glion/ack — typed HL7v2 acknowledgment codes and exceptions (Tables 0008/0357/0516); server-side response construction is moving into
@glion/mllp(ADR 0019).
The parser, plugins, and utilities that process HL7v2 messages as structured data.
- @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
unistspecification. - @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.
Composable plugins that annotate, enrich, and transform the AST.
- @glion/annotate-profile-context — load and attach HL7v2 profile context to
file.datafor 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 (experimental).
- @glion/annotate-profile-tables — annotate primitive values with their entry in the table of the message's HL7v2 version.
- @glion/decode-escapes — read the escape sequences of every value with
escapes.read, for a tree parsed withdecodeEscapes: false. - @glion/encode-escapes — write the escape sequences of every value with
escapes.write, for a tree written withencodeEscapes: false. - @glion/transform-segment-terminator — end every segment with a carriage return, the segment terminator HL7v2 requires, whatever line break it was read with.
- @glion/transform-trim-trailing-fields — remove the empty fields at the end of each segment, so
PID|1|DOE||is written asPID|1|DOE. - @glion/transform-profile-groups — nest segments in the segment groups their event schema defines, such as
PATIENT_RESULTandORDER_OBSERVATION.
Linting rules and presets for HL7v2 message quality and conformance.
- @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.
- @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-terminator — warn when a segment ends with a line feed, or with a carriage return and a line feed, or the last segment has no segment terminator.
- @glion/lint-encoding-characters-required — warn when
MSH-2leaves out a delimiter. - @glion/lint-delimiters-duplicate — report two delimiters that are the same character.
- @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.
- @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.
- @glion/lint-profile-timestamps — flag DT, TM, and DTM values that are not valid dates or times.
- @glion/lint-profile-segment-order — validate segment ordering per the event schema 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.
- @glion/lint-profile-withdrawn — flag values in fields HL7v2 has withdrawn.
- @glion/lint-profile-backward-compatible — flag values in fields HL7v2 keeps only for backward compatibility.
- @glion/utils — shared helpers for delimiter detection, normalization, and other HL7v2-specific operations.
- @glion/util-visit — a visitor for traversing HL7v2 ASTs with each node's ancestors and control flow actions.
- @glion/util-query — canonical path querying with syntax like
MSH.9.3orORDER.ORC.1forselect,selectAll,value,format, andmatches. - @glion/util-charset — encode and decode HL7v2 wire bytes as UTF-8 (fatal — a non-UTF-8 feed fails loudly instead of being silently corrupted).
- @glion/util-semver — tiny, fast HL7v2 version and range comparators.
- @glion/util-timestamp — HL7v2 DT, TM, and DTM parsing and formatting, with precision and calendar checks.
- @glion/util-uid — time-ordered unique IDs for HL7v2 identifier fields, e.g. MSH-10 control IDs (the ULID idea resized to a 20-character default).
- @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).
- Full documentation at glion.dev.
- Runnable examples in
examples/, each scaffolded withpnpm create glion my-app --example <name>. - API reference and detailed usage in each package's README, linked from the Packages section above.
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.
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.
Every @glion/* package and create-glion is published to npm from GitHub Actions with npm provenance, which links each version to the commit and workflow that built it. Each GitHub release that carries a glion-<version>.sigstore.json asset also carries the same tarballs that went to npm, and that file is a Sigstore bundle attesting that the release workflow built them.
Check the registry signatures and provenance of every package installed in a project that uses npm. Run it in CI after npm ci to check every install:
npm audit signaturesCheck a single tarball, downloaded from the release page or fetched with npm pack @glion/parser@<version>:
gh attestation verify glion-parser-<version>.tgz \
--repo rethinkhealth/glion \
--signer-workflow rethinkhealth/glion/.github/workflows/release.ymlAdd --bundle glion-<version>.sigstore.json to check against the bundle attached to the release instead of the attestation GitHub stores.
We welcome contributions! Please see our Contributing Guide for more details.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
To ensure a welcoming and positive environment, we have a Code of Conduct that all contributors and participants are expected to adhere to.
Copyright 2023–2026 Rethink Health, SUARL.
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.
HL7® and Health Level Seven® are registered trademarks of Health Level Seven International. Glion is not an HL7 publication and is neither endorsed nor warranted by HL7; the HL7 standards material redistributed in @glion/profiles is attributed in that package's NOTICE.