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. glion send fires 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.
Quick start
Install Glion and its runtime packages:
npm install @glion/mllp @glion/hl7v2 @glion/cli
Define 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>.
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/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 and unframe() is a stream transform that reassembles inbound frames across reads.
- @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, and glion send for sending an HL7v2 message over MLLP and printing the ACK.
Acknowledgments
- @glion/ack — typed HL7v2 acknowledgment codes and exceptions (Tables 0008/0357/0516); server-side response construction is moving into
@glion/mllp (ADR 0019).
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.
Linting
Linting rules and presets for HL7v2 message quality and conformance.
Presets
Core rules
Profile rules
Utilities
- @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.3 or ORDER.ORC.1 for select, selectAll, value, format, and matches.
- @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 ().
Documentation
- Full documentation at glion.dev.
- Runnable examples in
examples/, each scaffolded with pnpm create glion my-app --example <name>.
- 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.
Verifying a release
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 signatures
Check 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.yml
Add --bundle glion-<version>.sigstore.json to check against the bundle attached to the release instead of the attestation GitHub stores.
Contributing
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
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 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.
