🥮 mooncakes.io

    moonbit-hl7v2

    MoonBit Clinical Message HL7v2 Parser - Hospital LIS/HIS messaging infrastructure

    hl7
    hl7v2
    healthcare
    parser
    medical
    lis
    his
    fhir
    Download zip
    Author
    Version
    0.1.3
    License
    Apache-2.0
    Repository
    Last updated
    2 months ago
    Downloads
    41

    No dependencies

    #moonbit-hl7v2

    moonbit-hl7v2 is a typed, dependency-light HL7 v2 toolkit for MoonBit applications that exchange clinical messages between HIS, LIS, laboratory, scheduling, document, and billing systems.

    The library keeps parsing, typed segment models, validation, serialization, conversion, and framing separate so applications can adopt only the layers they need. MLLP support is a transport-independent frame codec and incremental state machine; it does not provide a TCP/TLS server.

    #Core capabilities

    • HL7 v2 AST parsing with custom delimiters, CR/LF/CRLF normalization, batch parsing, and configurable segment/field limits.
    • Typed models for common header, patient, visit, order, observation, scheduling, document, billing, pharmacy, query, and master-file segments.
    • High-level envelopes for ADT, ORU, ORM, ACK, SIU, MDM, DFT, RDE, RAS, and RDS messages.
    • Structured validation reports with error/warning/info severities, message profiles, segment cardinality, ordering rules, and an extensible terminology registry.
    • MLLP encode/decode, incremental decoding across arbitrary chunks, stream statistics, and framing/message error separation.
    • Canonical serialization, line-ending policies, AST JSON/XML/CSV/NDJSON, minimal FHIR Patient/Observation/Bundle mappings, Markdown summaries, and structural diffs.
    • Batch processing, path selection helpers, AST metrics, redaction utilities, deterministic generators, and a small command-line smoke/benchmark interface.

    #Quick start

    Install the current stable MoonBit toolchain, then run:

    moon version --all
moon update
moon check --target all
moon test --deny-warn
moon run cmd/main -- check

    To consume the published module from Mooncakes:

    moon add plhjbg/moonbit-hl7v2@0.1.3

    A minimal parsing example:

    let raw = "MSH|^~\\&|LIS|HOSPITAL|HIS|CENTER|20260819120000||ADT^A01|MSG00001|P|2.5\rPID|1||10001||DOE^JOHN"

    match @parser.parse_message(raw) {
      Ok(message) => {
        let patient_id = @path.get_value(message, "PID-3.1")
        println("Patient ID: " + patient_id)
      }
      Err(error) => println(error.to_formatted_string())
    }

    Packages are organized under lib/; each package has its own moon.pkg and tests. The module metadata is in moon.mod.

    #CLI

    The executable entry point is cmd/main:

    moon run cmd/main -- help
moon run cmd/main -- check
moon run cmd/main -- parse
moon run cmd/main -- benchmark --iterations 1000

    check parses and validates a generated ADT message, parse prints its AST shape, and benchmark measures a repeated parse/validate/serialize loop. The cross-platform smoke check is reproducible with:

    ./tools/check-cli.ps1

    #Architecture

    raw HL7 / MLLP frame
        |
lib/mllp -------- framing and incremental stream state
        |
lib/escape + lib/parser + lib/types -------- AST and limits
        |
lib/segments -------- typed segment models
        |
lib/messages + lib/batch -------- message and batch envelopes
        |
lib/path + lib/validator + lib/terminology + lib/analytics
        |
lib/serializer + lib/converter + lib/diff + lib/generator
        |
cmd/main -------- stable local CLI entry point

    The core parser is independent of sockets and external clinical terminology databases. lib/terminology contains small documented HL7 tables and allows applications to register local code systems.

    #Benchmark

    The latest local measurement is recorded in docs/benchmarks/latest.md. Recreate it with:

    ./tools/run-benchmark.ps1 -Iterations 1000

    The report records the toolchain, operating system, command, iteration count, successful message count, and the CLI's elapsed timing value. It is a reproducibility record for the current machine, not a universal throughput claim; build time is outside the measured loop.

    The source-size audit is similarly reproducible:

    ./tools/measure-loc.ps1 | ConvertFrom-Json | Format-List

    The script counts .mbt files only, excludes build/cache directories, and reports production and test code separately.

    The current local snapshot reports 10,612 physical lines and 9,103 non-empty, non-comment lines: 8,006 production lines and 1,097 test lines across 61 production files and 31 test files.

    #Tests

    The repository includes unit, round-trip, malformed-input, parser-limit, MLLP chunk-boundary, profile, terminology, batch, converter, CLI-dispatch, and target-independent regression tests. The verification gate is:

    moon check --target all --deny-warn
moon test --deny-warn
moon fmt --check
moon info

    CI runs moon check --target all --deny-warn, moon build --target all, and moon test --target all --deny-warn on Ubuntu, macOS, and Windows.

    Boundary tests cover empty payloads, missing MSH/PID, wrong message triggers, oversized frames and fields, invalid line endings, repeated segments, malformed escape sequences, invalid numeric observations, bad terminology codes, ordering violations, and incomplete MLLP frames.

    #CI

    GitHub Actions runs on Ubuntu, macOS, and Windows. It installs the current stable MoonBit toolchain from the official installer, records moon version --all, updates dependencies, checks and tests all targets, verifies formatting and generated package interfaces, and runs the CLI smoke check on Linux. Workflow files are in .github/workflows.

    #Standards and provenance

    The implementation is written in MoonBit and does not vendor third-party source files, binary assets, or private fixtures. Its data models and wire-format behavior follow the relevant HL7 v2 and FHIR R4 specifications. Test messages are synthetic fixtures maintained in the repository; integrations that require local hospital profiles or terminology systems should provide those inputs separately.

    #Security and data handling

    The library does not open sockets or persist clinical messages. MLLP support is a framing codec and incremental state machine only; applications remain responsible for transport security, access control, retention, and audit logging. Treat HL7 data as sensitive clinical information, apply the configured size limits, and redact messages before sending them to logs, diagnostics, or benchmarks.

    #License

    This project is distributed under the Apache License 2.0.

    Powered by MoonBit

    Site sourceReport issueModulesSkillsCLIBuild queueStatistics

    © 2026 mooncakes.io