MLLP

HL7 v2 over MLLP, with the hard parts handled.

@cosyte/mllp is an MLLP client and server for Node.js: framing, acknowledgement correlation and reconnects, with zero runtime dependencies and one guarantee it will not trade away. A positive acknowledgement never goes out before your commit succeeds.

@cosyte/mllp
npm install @cosyte/mllp

Need it integrated? Talk to us.

The standard

MLLP is the thin frame around every HL7 v2 message on a socket.

@cosyte/mllp

The transport on its own, as a library you import.

The protocol stops at the frame. Everything that decides whether an interface survives a bad night is left to the integrator, so every integration ends up writing its own acknowledgement correlator and reconnect loop. This is that code, written once and tested.

  • A client, a server, a standalone framing codec, and an in-memory transport so your tests never open a socket.
  • Acknowledgements are correlated to the message they answer. A throw in your commit handler answers AE, never AA.
  • Reconnects and backpressure are handled for you.
  • TLS through node:tls, with certificate verification on by default and mutual TLS available.
  • Checked differentially against Mirth Connect and the Google Cloud Healthcare MLLP adapter, and runDifferential ships so you can aim the same harness at your own engine.
  • An optional ack-from-hl7 bridge builds acknowledgements with @cosyte/hl7.
  • Zero runtime dependencies, with ESM and CommonJS builds.
send-and-acknowledge.tsts
import { createStarterClient, createStarterServer } from "@cosyte/mllp";

const committed: Buffer[] = [];

// Port 0: the OS picks a free port. The host defaults to loopback, 127.0.0.1.
const server = await createStarterServer({
  port: 0,
  onMessage: async (payload) => {
    committed.push(payload); // your durable commit: a throw here answers AE, never AA
  },
});

const client = await createStarterClient({ host: "127.0.0.1", port: server.getStats().port ?? 0 });

const ack = await client.send(
  Buffer.from(
    "MSH|^~\\&|SENDING_APP|SENDING_FAC|RECEIVING_APP|RECEIVING_FAC|20260101120000||ADT^A01|CTRL0001|P|2.5.1\r",
  ),
);

// Log the shape of the acknowledgement, never its field values.
const msa = ack
  .toString("utf8")
  .split("\r")
  .find((segment) => segment.startsWith("MSA|"))
  ?.split("|");
console.log("acknowledgement code:", msa?.[1]);
console.log("MSA-2 echoes the control id sent:", msa?.[2] === "CTRL0001");
console.log("messages committed:", committed.length);

await client.close();
await server.close();

From the @cosyte/mllp README on GitHub, verbatim. Every value in it is synthetic.

Limits

What it does not do.

Its README names what is not built:

  • No batch acknowledgement. A batch envelope, or a frame with more than one MSH, gets a warned, non-positive AE.
  • MLLP Release 2 is not spoken.
  • No queue or replay of unacknowledged messages.
  • No clinical acceptance decision: that stays with your application.
  • No PKI.
  • Epic and Cerner are not part of the verification harness, and no claim is made about either.

The full status and limits, in the README

Alternatives

What else you could use.

Each description comes from the project’s own documentation or npm listing, linked below.

Node.js library

node-hl7-server

An MIT-licensed TypeScript HL7 listener for Node.js that accepts, parses and acknowledges HL7 v2 messages over MLLP, with node-hl7-client for sending.

Source: npm, node-hl7-server

Integration engine

Mirth Connect

NextGen Healthcare's integration engine, and one of the two engines @cosyte/mllp is checked against. From version 4.6 it ships under a single closed-source, proprietary license.

Source: NextGen Healthcare, Mirth Connect downloads

Platform agent

Medplum Agent

An application that runs inside your firewall and connects to devices over HL7/MLLP, ASTM and DICOM, as part of the Medplum platform.

Source: Medplum documentation, Agent

Works with

  • HL7 v2@cosyte/hl7 parses what arrives in the frame, and powers the optional ack-from-hl7 bridge.
  • @cosyte/synthGenerates synthetic HL7 v2 traffic to push through a connection in tests.

Try @cosyte/mllp on your own messages.

It is free and MIT-licensed. If it saves you a day, a star on GitHub helps other engineers find it.

Need it integrated? Talk to us, or see what our integration services cover.