npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@glion/mllp-client

v0.31.0

Published

Persistent, single-flight MLLP client for HL7v2

Readme

@glion/mllp-client

An HL7v2 MLLP client for Node.js, Bun, Deno, and Cloudflare Workers.

  • 📦 MLLP built in. Framing, message boundaries and acknowledgment matching are handled. You send a parsed message and get one back.
  • 🔄 Predictable connection lifecycle. Timeouts on connecting and on waiting for a reply, connection attempts retried with backoff, and explicit states you can read.
  • ⚡ Thin over TCP. One socket, one message on the wire at a time. Further sends queue in call order. No worker threads, no polling.
  • 🧯 Errors you can act on. Every failure carries a stable code and says whether the connection is still usable.
  • 🧩 Any transport. TCP and TLS on Node.js, Bun, Deno, and Cloudflare Workers included. An in-memory or custom socket plugs in behind the same two-method interface.
  • 🔤 Typed end to end. TypeScript throughout, with parsed HL7v2 going in and coming out.

Install

npm install @glion/mllp-client

Node.js 22 or later. ESM only.

Use

Send a message

import { connect } from "node:net";
import { parseHL7v2 } from "@glion/parser";
import { MllpClient } from "@glion/mllp-client";
import { nodeSocket } from "@glion/mllp-client/node";

await using client = new MllpClient({
  socket: nodeSocket(() => connect({ host: "hl7.example.org", port: 2575 })),
});

const adt = parseHL7v2(
  [
    "MSH|^~\\&|SENDER|FAC|RECV|FAC|20260101120000||ADT^A01|MSG00001|P|2.5",
    "EVN|A01|20260101120000",
    "PID|1||12345^^^MRN||DOE^JOHN||19800101|M",
  ].join("\r")
);

const ack = await client.send(adt);
ack.code; //=> "AA" or "CA"
ack.raw; //=> the acknowledgment as text
ack.tree; //=> the acknowledgment as a tree

send() connects on first use, so connect() is optional. await using closes the client at the end of the block; without it, call close().

Handle a rejection

A NAK means the receiver read your message and refused it — a bad field, a patient it does not know, a message type it does not handle. send() throws, and the connection stays open for the next message.

import { AckException } from "@glion/ack";
import { MllpClientError } from "@glion/mllp-client";

try {
  await client.send(adt);
} catch (error) {
  if (error instanceof AckException) {
    error.code; //=> "AE", "AR", "CE", or "CR"
    error.text; //=> the receiver's reason, when it gave one
  } else if (error instanceof MllpClientError) {
    error.code; //=> e.g. "SEND_TIMEOUT" — see Errors
  }
}

Connect at startup

connect() opens the connection without sending anything. Call it at startup to find out immediately that a host, port, or firewall is wrong, instead of on your first real message.

const client = new MllpClient({
  socket: nodeSocket(() => connect({ host: "hl7.example.org", port: 2575 })),
});
await client.connect();

Calling it twice is safe. On a connected client it returns immediately; while a connection is still opening, it waits for that attempt and shares its result.

Reconnect

A connection that cannot be opened is dialed again. By default the client makes five further attempts, waiting a random time before each: up to 1 s, then 2 s, 4 s, 8 s, and 16 s, so it gives up about 30 seconds after the first failure and closes with the last attempt's error. attempts: Infinity keeps dialing; close() stops it. A send() that arrives while the client is connecting waits for the outcome.

A connection that is lost is not restored. The client closes with the failure, and the message in flight is not sent again: its send() rejects, and whether the receiver got it is the caller's to decide. A client is as disposable as a socket: construct a new one to send again.

const client = new MllpClient({
  socket: nodeSocket(() => connect({ host: "hl7.example.org", port: 2575 })),
  reconnect: {
    attempts: 20,
    delay: (attempt) => {
      logger.warn({ attempt }, "mllp reconnecting");
      return Math.min(30_000, 500 * 2 ** attempt);
    },
  },
});

reconnect: false turns it off: the client dials once.

Options

| Option | Type | Default | Description | | ------------------ | ------------------------------- | --------- | ------------------------------------------------------------------------------------------------------ | | socket | MllpSocket | required | Runtime adapter, such as nodeSocket(() => connect({ host, port })). | | connectTimeoutMs | number | 10000 | Time allowed to open the connection. Exceeded: MllpConnectionTimeoutError. | | sendTimeoutMs | number | 30000 | Time allowed from writing a message to receiving its acknowledgment. Exceeded: MllpSendTimeoutError. | | maxBufferedBytes | number | 16 MiB | Largest reply the client buffers. Exceeded: MllpInvalidResponseError. | | reconnect | MllpReconnectOptions \| false | see below | How the client dials again after a failed attempt. false dials once. |

send(message, { timeoutMs }) overrides sendTimeoutMs for one message.

MllpReconnectOptions:

| Option | Type | Default | Description | | ---------- | ----------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------- | | attempts | number | 5 | Attempts after a failed one before the client closes. Infinity for no limit. | | delay | (attempt: number) => number | full-jitter backoff from 1 s, capped at 30 s | Milliseconds to wait before attempt (from 1). Called only while attempts remain. |

API

new MllpClient(options)

new MllpClient(options: MllpClientOptions): MllpClient

Creates a client for one remote system. Nothing is opened until the first connect() or send().

Parameters — see Options.

Throws MllpInvalidOptionError when a timeout is not a positive number of milliseconds, maxBufferedBytes is not a positive integer, or reconnect.attempts is not a non-negative integer.

const client = new MllpClient({
  socket: nodeSocket(() => connect({ host: "hl7.example.org", port: 2575 })),
  sendTimeoutMs: 10_000,
});

client.send(message, options?)

send(message: Root, options?: { timeoutMs?: number }): Promise<MllpClientResponse>

Sends one message and resolves with the acknowledgment that answers it. Connects first if the client is not connected.

| Parameter | Type | Description | | ------------------- | -------- | -------------------------------------------------------- | | message | Root | A parsed HL7v2 message. Must carry an MSH-10 control ID. | | options.timeoutMs | number | Overrides sendTimeoutMs for this message only. |

Returns an MllpClientResponse:

| Field | Type | Description | | ----------- | ---------------- | --------------------------------------------------- | | code | AckSuccessCode | MSA-1, AA or CA. | | controlId | string | MSA-2: the control ID of the message this answers. | | id | string | The acknowledgment's own MSH-10. | | text | string? | MSA-3, the receiver's diagnostic, when it gave one. | | tree | Root | The acknowledgment, parsed. | | raw | string | The acknowledgment as text. |

Throws

  • AckException — the receiver refused the message. The connection stays open.
  • MllpInvalidMessageError — no MSH-10, or the message could not be serialized. Nothing was sent.
  • MllpInvalidOptionError — timeoutMs is out of range. Nothing was sent.
  • MllpClientClosedError — the client is closed, or closed while this send was waiting its turn.
  • MllpConnectionFailedError, MllpConnectionTimeoutError — the connection could not be opened.
  • MllpSendTimeoutError, MllpConnectionLostError, MllpInvalidResponseError — the exchange failed. These close the connection; see Errors.
  • MllpSendAbortedError — destroy() cut the send off. Delivery is unknown.

Every error carries delivery, not-sent or unknown, the one fact a retry needs; see Errors.

One message is on the wire at a time. A send() arriving while another is in flight waits its turn, and sends go out in the order they were called, so a batch may be fired at once:

const outcomes = await Promise.allSettled(
  batch.map((message) => client.send(message))
);

The queue is in memory and has no bound. timeoutMs runs from the moment the write starts, not from the call. A send still waiting when close() or destroy() is called, or when a failure closes the client, rejects at once with delivery: "not-sent": with MllpClientClosedError, or with the failure itself when the failure is one of not being sent, such as the dial's MllpConnectionFailedError or MllpConnectionTimeoutError, as connect() gets. Nothing behind a failed message goes out. See Does send() queue?.

client.connect()

connect(): Promise<void>

Opens the connection without sending anything, dialing again under the reconnect policy when an attempt fails. Optional — send() connects on first use — but calling it at startup surfaces a wrong host, port, or firewall rule as soon as the policy gives up.

Idempotent. On a connected client it resolves at once; while an attempt is in flight it waits for the outcome and shares it.

Throws the last attempt's MllpConnectionFailedError or MllpConnectionTimeoutError, or MllpClientClosedError when the client is already closed or close() or destroy() cancelled the attempt.

client.close()

close(): Promise<void>

Closes the connection once the message in flight has been acknowledged. New sends, and sends still waiting their turn, are refused from the moment it is called with MllpClientClosedError; the message in flight is never cut off. Await the sends you want delivered before calling it. An attempt to connect stops at once.

Resolves when the connection is down, from any phase. Never throws. Idempotent. The wait is bounded by the in-flight send's own deadline. If the message it waits for fails, the client closes with that failure; otherwise with null, the owner's decision.

process.on("SIGTERM", async () => {
  await client.close();
  process.exit(0);
});

client.destroy(reason?)

destroy(reason?: MllpClientError | null): Promise<void>

Closes the connection now, without waiting for anything in flight. A message in flight rejects with MllpSendAbortedError. An attempt to connect stops at once. The client closes with reason: the close event carries it, and so does cause on every later call's MllpClientClosedError. Omitted or null, the client closed by its owner's decision, as net.Socket.destroy(error) does. Sends waiting their turn are rejected with reason itself when its delivery is not-sent, and with MllpClientClosedError carrying reason otherwise. Arriving while the client is already closing, it cuts the message in flight and joins the ending under way; reason is recorded when no failure is known yet.

Resolves when the connection is down, from any phase. Never throws. Idempotent.

client[Symbol.asyncDispose]()

Calls close(). Lets a client be scoped with await using:

{
  await using client = new MllpClient({ socket });
  await client.send(message);
} // closed here, even if send() threw

client.state

readonly state: MllpClientState

| Value | Meaning | | ------------ | -------------------------------------------------------------------------------- | | idle | Nothing opened yet. The first send() or connect() opens the connection. | | connecting | The connection is being opened, further attempts included. | | connected | Open, with no message in flight. | | sending | A message is on the wire, waiting for its acknowledgment. Further sends wait. | | closing | The client is ending: a message being waited out, or the connection coming down. | | closed | The connection is down. |

A client closes once. After close(), destroy(), a connection the reconnect policy could not open, or a connection that was lost, every call throws MllpClientClosedError; construct a new client to send again.

client.pending

readonly pending: number

How many sends wait their turn, the one in flight excluded. The queue's backlog, for a metric or a backpressure decision; 0 whenever nothing waits.

client.connected

readonly connected: boolean

true in connected and sending, false everywhere else.

client.on(event, listener) / client.off(event, listener)

on<E>(event: E, listener: MllpClientListener<E>): this
off<E>(event: E, listener: MllpClientListener<E>): this

Adds or removes a listener. Both return the client, so calls chain.

| Event | Listener | Fires when | | --------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | connect | () => void | The connection opened. | | close | (error: MllpClientError \| null) => void | The connection is down. Fires once, from any phase, even if it never connected. error is the failure that closed the client, or null when you closed it. |

A lost connection is not an event of its own: it closes the client, so close fires with the failure. Listeners are synchronous, and one that throws propagates to whatever triggered the event.

client
  .on("connect", () => metrics.increment("mllp.connected"))
  .on("close", (error) => {
    logger.warn({ code: error?.code ?? "closed_by_owner" }, "mllp closed");
  });

Runtimes

The client speaks MLLP over a pair of byte streams and knows nothing else about the transport. That whole dependency is MllpSocket — two methods — so supporting a runtime means an adapter, not a fork of the client.

| Runtime | Adapter | Import | TLS | Proven by | | ------------------ | -------------------------------------- | ---------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | Node.js ≥ 22 | nodeSocket | @glion/mllp-client/node | Node's tls.connect() options | Conformance suite in CI, Node 22 and 24 | | Bun | nodeSocket | @glion/mllp-client/node | Node's tls.connect() options | Conformance suite in CI, Bun 1.4 | | Deno | nodeSocket | @glion/mllp-client/node | Node's tls.connect() options | Conformance suite in CI, Deno 2.9 | | Cloudflare Workers | workersSocket | @glion/mllp-client/workers | secureTransport, public trust store only | Integration suite in CI, inside workerd; TCP only, TLS handshake untested (#626) |

Every adapter runs the same conformance suite: the MllpSocket contract case by case, and the client's behaviour over a real socket scenario by scenario. On Node.js, Bun, and Deno it runs twice, over TCP and over TLS. A custom socket can run it too; see tests/integration/conformance/ in the package source.

Node.js

import { nodeSocket } from "@glion/mllp-client/node";

nodeSocket(dial: () => net.Socket, options?: NodeSocketOptions): MllpSocket

A socket over the net.Socket or tls.TLSSocket that dial returns: net.connect() or tls.connect(), with Node's options as given. Each connect() calls dial for a fresh socket, and resolves once the socket is connected, or once the TLS handshake completes for a tls.TLSSocket. dial must return the socket itself, still connecting, not a promise of it; setup that has to wait first, such as a proxy, belongs in a custom socket. nodeSocket() throws INVALID_OPTION when dial is not a function. The same adapter runs on Bun and Deno through their node:net and node:tls compatibility; no separate import is needed there.

| Option | Type | Default | Description | | ----------------- | -------- | ------- | ------------------------------------------------------------- | | gracefulCloseMs | number | 1000 | How long a socket gets to end cleanly before it is destroyed. |

import { connect } from "node:net";

const client = new MllpClient({
  socket: nodeSocket(() => connect({ host: "hl7.example.org", port: 2575 })),
});

The adapter configures nothing on the socket. dial sets what the connection needs, with the runtime's API. A receiver that goes away without closing the connection while it is idle ends the socket only when the socket's keepalive probes fail; without keepalive, the next send() waits out sendTimeoutMs and rejects with SEND_TIMEOUT.

Deno needs --allow-net for the receiver's host and port.

TLS

dial returns tls.connect(), with Node's TLS options:

import { readFileSync } from "node:fs";
import { connect } from "node:tls";

nodeSocket(() =>
  connect({
    host: "10.20.0.15",
    port: 2575,
    ca: readFileSync("hospital-ca.pem"),
    cert: readFileSync("client.pem"),
    key: readFileSync("client-key.pem"),
    servername: "hl7.hospital.internal",
  })
);

A handshake that fails rejects with CONNECTION_FAILED, with Node's TLS error on cause: for example UNABLE_TO_VERIFY_LEAF_SIGNATURE or ERR_TLS_CERT_ALTNAME_INVALID.

A receiver that refuses the client certificate over TLS 1.2 fails the handshake: CONNECTION_FAILED, nothing sent. Over TLS 1.3 it refuses after the handshake, so the connection opens and the first send() rejects with CONNECTION_LOST, delivery unknown.

Cloudflare Workers

import { workersSocket } from "@glion/mllp-client/workers";

workersSocket(dial: () => Socket): MllpSocket

A socket over the one dial returns: connect() from cloudflare:sockets, or a binding's connect(), with the runtime's options as given. Each connect() calls dial for a fresh socket, and resolves once the socket is open. dial must return the socket itself, not a promise of it. secureTransport: "starttls" is not supported. workersSocket() throws INVALID_OPTION when dial is not a function. Import it from the ./workers subpath.

import { connect } from "cloudflare:sockets";
import { MllpClient } from "@glion/mllp-client";
import { workersSocket } from "@glion/mllp-client/workers";

export default {
  async fetch(request: Request): Promise<Response> {
    await using client = new MllpClient({
      socket: workersSocket(() =>
        connect(
          { hostname: "hl7.example.org", port: 2575 },
          { allowHalfOpen: false, secureTransport: "on" }
        )
      ),
    });
    const ack = await client.send(await messageFrom(request));
    return Response.json({ code: ack.code, controlId: ack.controlId });
  },
};

What differs from Node:

  • connect() reaches only endpoints routable from Cloudflare's network. A binding's connect() reaches what the binding routes to.
  • close() resolves as soon as the runtime has ended the socket; there is no grace window.
  • Locally, under Miniflare (wrangler dev or the Vitest integration), connections go through a proxy, so MllpConnectionFailedError.cause carries the proxy's message rather than a socket error code. code is the same in both.
  • Locally, under Miniflare, a secureTransport: "on" connection fails with the proxy's message, whatever certificate the receiver presents. TLS to a receiver works only when the Worker runs on Cloudflare.
  • Cloudflare blocks some destination ports.
  • secureTransport: "on" takes no CA, client certificate, or server name. The receiver must present a publicly trusted certificate for the host dialed, so dial a host name rather than an address.

Custom Socket

You can expand MllpSocket to build a custom socket to one remote system, which the client opens, uses, and ends.

interface MllpSocket {
  connect(signal: AbortSignal): Promise<MllpStreams>;
  close(): Promise<void>;
}

interface MllpStreams {
  readonly readable: ReadableStream<Uint8Array>;
  readonly writable: WritableStream<Uint8Array>;
}

An implementation must satisfy four rules:

  1. connect() rejects with signal.reason when the signal aborts, and a rejection leaves nothing open.
  2. close() never rejects, may be called more than once, and always finishes within a bounded time, even when the receiver never answers.
  3. When the socket ends, a pending read on readable ends or errors. Bytes sent before a clean close arrive first.
  4. The client owns the streams while connected, and releases them before calling close().

An implementation never sees an MLLP frame — framing belongs to the layer above.

Errors

Every failure the client raises extends MllpClientError and carries three fixed things: a code, one word per class for a switch or a log field; a delivery, what became of the message; and a message that never changes. Errors from the layers below arrive on cause, never as the thrown type.

A rejection from the receiver is not an MllpClientError — see AckException.

delivery is the one fact a retry decision needs:

| delivery | Meaning | Codes | | ---------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | not-sent | Nothing reached the wire. The message may be sent again as it is. | INVALID_OPTION, INVALID_MESSAGE, CLOSED, CONNECTION_FAILED, CONNECTION_TIMEOUT | | unknown | The message may have reached the receiver. Sending it again may deliver it twice. | SEND_TIMEOUT, CONNECTION_LOST, SEND_ABORTED, INVALID_RESPONSE |

import { MllpClientError, MllpErrorCode } from "@glion/mllp-client";

try {
  await client.send(message);
} catch (error) {
  if (error instanceof MllpClientError) {
    if (error.delivery === "not-sent") {
      return requeue(message); // safe to send again
    }
    switch (error.code) {
      case MllpErrorCode.INVALID_RESPONSE:
        return quarantine(message); // the receiver answered, unreadably
      default:
        return holdForReview(message); // it may already have been processed
    }
  }
}

The four failures of the wire — CONNECTION_FAILED, CONNECTION_TIMEOUT, SEND_TIMEOUT, CONNECTION_LOST — also extend MllpConnectionError, one instanceof for "the link, not the message".

INVALID_OPTION

MllpInvalidOptionError · delivery not-sent

A constructor option or a per-send timeoutMs is out of range — a timeout that is not a positive number of milliseconds, a maxBufferedBytes that is not a positive integer, or a reconnect.attempts that is not a non-negative integer or Infinity. Also thrown by nodeSocket() and workersSocket() when dial is not a function. The message names which one.

Thrown before anything is opened or sent. A configuration bug, not a runtime condition.

INVALID_MESSAGE

MllpInvalidMessageError · delivery not-sent · field: cause

The message cannot be sent as it stands: no MSH-10 control ID, or it could not be serialized, or a Segment ID or MSH-1/MSH-2 holds a byte MLLP reserves as a frame marker. A reserved byte in a value is written as \Xdd\ and sent.

Nothing reached the wire and the connection is still in step, so the next message can go out on it. Fix or quarantine the message; do not reconnect.

CLOSED

MllpClientClosedError · delivery not-sent · field: cause

The client is closed or closing, so the call cannot be served. Also the error a connect() gets when close() or destroy() cancelled the attempt it was waiting for, and the error a send() gets when the client closed while it was waiting its turn; a send waiting behind a dial that failed gets the dial's error instead.

A client closes once. Construct a new one to send again. When the client closed on a failure, cause is that failure: the last attempt's CONNECTION_FAILED or CONNECTION_TIMEOUT when the reconnect policy gave up, the CONNECTION_LOST, SEND_TIMEOUT, or INVALID_RESPONSE that ended an earlier message, including one close() was waiting out, or the reason given to destroy().

CONNECTION_FAILED

MllpConnectionFailedError · delivery not-sent · field: cause

The socket could not be opened. cause carries the underlying error — ECONNREFUSED, ENOTFOUND, EHOSTUNREACH, or a TLS error such as UNABLE_TO_VERIFY_LEAF_SIGNATURE.

Check host, port, whether a firewall allows the route, and, over TLS, the certificate the receiver presents. Nothing was opened, so there is nothing to close.

CONNECTION_TIMEOUT

MllpConnectionTimeoutError · delivery not-sent · field: timeoutMs

The receiver did not accept the connection within connectTimeoutMs.

Typically a packet-dropping firewall rather than a refused connection — a refusal arrives fast and surfaces as CONNECTION_FAILED. Over TLS, also a receiver that speaks plain TCP and never answers the TLS handshake.

SEND_TIMEOUT

MllpSendTimeoutError · delivery unknown · field: timeoutMs — closes the connection

No acknowledgment arrived within the send timeout.

Whether the receiver got the message is unknown: it may be slow, or it may have processed the message and failed to reply. The connection closes because a late acknowledgment can no longer be told apart from the next message's — see Why does a failed send close the connection?. The client closes with this error; the message is not sent again.

CONNECTION_LOST

MllpConnectionLostError · delivery unknown · field: cause — closes the connection

The link went away mid-send: the receiver hung up, or the network broke. cause carries the stream error when there was one.

Whether the message was received is unknown. The client closes with this error; the message is not sent again.

SEND_ABORTED

MllpSendAbortedError · delivery unknown

destroy() cut off the message in flight. close() never raises this: it waits the message out.

INVALID_RESPONSE

MllpInvalidResponseError · delivery unknown · fields: controlId?, cause — closes the connection

The reply was not a usable acknowledgment of the message that was waiting. Causes, in the order they are checked:

  • the bytes were not valid UTF-8 or not parseable HL7v2;
  • MSA-2 names a different message — usually a late acknowledgment from an earlier timed-out send;
  • MSA-1 is empty or is not one of the six codes of Table 0008;
  • the reply passed maxBufferedBytes before it was complete;
  • the connection closed partway through the reply.

The connection closes because the client can no longer tell which reply answers which message. The client closes with this error.

AckException

From @glion/ack · fields: code, controlId, text, errorCode, severity

Not an MllpClientError. The receiver read the message and refused it, which is an answer rather than a fault — the connection stays open and the next message can go out on it.

| Field | Source | Description | | ----------- | ------ | --------------------------------------------- | | code | MSA-1 | AE, AR, CE, or CR. | | controlId | MSA-2 | The message being refused. | | text | MSA-3 | The receiver's reason, when it gave one. | | errorCode | ERR-3 | HL7v2 Table 0357 error condition, when given. | | severity | ERR-4 | E, W, or I, when given. |

The class is the MSA-1 code: AckApplicationError (AE), AckApplicationReject (AR), AckCommitError (CE), AckCommitReject (CR). An MLLP server built on Glion raises the same types, so both ends of an integration catch the same thing.

FAQs

Why does a failed send close the connection?

MLLP has no correlation of its own. The only thing tying a reply to a message is the receiver echoing your MSH-10 back in MSA-2 — and the only reason that can be trusted is that one message is outstanding at a time.

Once a send times out, that no longer holds. A wrong guess here reports one message's outcome under another message's identity, which in a clinical feed is worse than an error.

Clients that pipeline can survive a timeout, because they keep a table of outstanding control IDs and a background reader to match against it. A lockstep client has no table to fall back on.

The client closes with the failure, and never sends the failed message again — only you know whether the receiver already has it. Construct a new client to go on, as you would open a new socket.

Does send() queue?

Yes, in memory and without a bound. A send() arriving while a message is on the wire waits for that message's acknowledgment, then goes out; sends leave in the order they were called, one at a time, so an A01 fired before its A03 reaches the receiver first. Nothing goes out behind a message whose delivery is unknown: a failure closes the client, and every send still waiting rejects with CLOSED and delivery: "not-sent". A send waiting behind a dial that fails rejects with the dial's error, as connect() does.

The queue exists only in this process. A message waiting in it is not on disk, so a crash loses it without a trace, and a producer faster than the receiver grows it without limit. An interface that must not lose events keeps its own persistent outbound queue and hands the client one message at a time; the client's line is for a batch whose outcomes the caller is awaiting.

Why a socket rather than a host and port?

The client handles MLLP and deliberately handles no transport. Putting the whole runtime dependency behind two methods means the same client runs over TCP, TLS, a Unix socket, or a pair of in-memory streams — and the test suite covers every lifecycle path without opening a port.

Part of Glion

@glion/mllp-client is part of Glion, the application framework for HL7v2. See the Glion README for the full package catalog and architecture.