@glion/mllp-client 0.16.0 → 0.20.0

package/dist/index.js

@@ -1,3 +1,843 @@
-import { i as MllpClientErrorCode, r as MllpClientError } from "./client.js";
-import { n as nodeConnect, t as MllpClient } from "./node.js";
-export { MllpClient, MllpClientError, MllpClientErrorCode, nodeConnect };
+import { n as MllpClientError, r as MllpErrorCode, t as MllpInvalidOptionError } from "./chunks/mllp-invalid-option-error.js";
+import { MllpCodecError, frame, unframe } from "@glion/mllp-codec";
+import { AckApplicationError, AckApplicationReject, AckCode, AckCommitError, AckCommitReject, isAckNakCode, isAckSuccessCode } from "@glion/ack";
+import { value } from "@glion/util-query";
+import { parseHL7v2 } from "@glion/parser";
+import { toHl7v2 } from "@glion/to-hl7v2";
+import { decodeBytes, encodeBytes } from "@glion/util-charset";
+/**
+* Maximum timeout `setTimeout` supports, in milliseconds (2^31 − 1). Larger
+* values, including `Infinity`, are rejected: the platform would clamp them
+* to about 1 ms.
+*/
+const MAX_TIMEOUT_MS = 2 ** 31 - 1;
+//#endregion
+//#region src/errors/mllp-client-closed-error.ts
+/**
+* The call cannot be served: the client is closed, by `close()`, by
+* `destroy()`, or by a failure. The failure is on `cause`.
+*/
+var MllpClientClosedError = class extends MllpClientError {
+	name = "MllpClientClosedError";
+	code = MllpErrorCode.CLOSED;
+	delivery = "not-sent";
+	constructor(cause = null) {
+		super(cause === null ? "The client is closed — construct a new MllpClient to send again." : "The client closed on a failure, see cause — construct a new MllpClient to send again.", { cause: cause ?? void 0 });
+	}
+};
+//#endregion
+//#region src/errors/mllp-connection-error.ts
+/**
+* A failure of the wire: the connection could not be opened, gave no reply in
+* time, or was lost. Raised by the layer that holds the socket; the client
+* relays it unchanged.
+*/
+var MllpConnectionError = class extends MllpClientError {};
+//#endregion
+//#region src/errors/mllp-connection-failed-error.ts
+/**
+* The connection could not be opened: the host was unreachable, refused the
+* connection, or failed DNS or TLS. The socket's error is on `cause`.
+*/
+var MllpConnectionFailedError = class extends MllpConnectionError {
+	name = "MllpConnectionFailedError";
+	code = MllpErrorCode.CONNECTION_FAILED;
+	delivery = "not-sent";
+	constructor(cause) {
+		super("Connecting failed — check that the host is reachable and the port is listening.", { cause });
+	}
+};
+//#endregion
+//#region src/errors/mllp-connection-timeout-error.ts
+/**
+* The remote system did not accept the connection within `connectTimeoutMs`.
+* The host may be down, overloaded, or silently dropping packets.
+*/
+var MllpConnectionTimeoutError = class extends MllpConnectionError {
+	name = "MllpConnectionTimeoutError";
+	code = MllpErrorCode.CONNECTION_TIMEOUT;
+	delivery = "not-sent";
+	timeoutMs;
+	constructor(timeoutMs) {
+		super("Connecting timed out — check that the host is reachable and the port is listening.");
+		this.timeoutMs = timeoutMs;
+	}
+};
+//#endregion
+//#region src/errors/mllp-connection-lost-error.ts
+/**
+* The connection was lost during a send: the remote system hung up, or the
+* network broke. The remote system may or may not have received the message.
+* A stream error, when there was one, is on `cause`.
+*/
+var MllpConnectionLostError = class extends MllpConnectionError {
+	name = "MllpConnectionLostError";
+	code = MllpErrorCode.CONNECTION_LOST;
+	delivery = "unknown";
+	constructor(cause) {
+		super("The connection was lost while a message was waiting for its acknowledgment — the remote system may or may not have received it; resend only if the message is safe to repeat.", { cause });
+	}
+};
+//#endregion
+//#region src/errors/mllp-invalid-message-error.ts
+/**
+* The message cannot be sent as-is: it has no MSH-10 control ID, it could not
+* be serialized, or it contains a byte MLLP reserves. Nothing was written; the
+* reason is on `cause`. Fix the message and send again.
+*/
+var MllpInvalidMessageError = class extends MllpClientError {
+	name = "MllpInvalidMessageError";
+	code = MllpErrorCode.INVALID_MESSAGE;
+	delivery = "not-sent";
+	constructor(cause) {
+		super("The message could not be prepared for sending; nothing was written.", { cause });
+	}
+};
+//#endregion
+//#region src/errors/mllp-invalid-response-error.ts
+/**
+* The reply was not a usable acknowledgment of the message that was waiting:
+* it could not be decoded, its acknowledgment code was missing or unknown, or
+* it answered a different message. The connection is ended. The reason is on
+* `cause`.
+*/
+var MllpInvalidResponseError = class extends MllpClientError {
+	name = "MllpInvalidResponseError";
+	code = MllpErrorCode.INVALID_RESPONSE;
+	delivery = "unknown";
+	/** MSH-10 of the message that was waiting, when the thrower knew it. */
+	controlId;
+	constructor(cause, controlId) {
+		super("The reply is not a usable acknowledgment of the message that was waiting — the connection has been closed.", { cause });
+		this.controlId = controlId;
+	}
+};
+//#endregion
+//#region src/utils.ts
+/** The value at `path`, or `""` when the field is absent. */
+function read(tree, path) {
+	return value(tree, path)?.value ?? "";
+}
+//#endregion
+//#region src/errors/nak-exception.ts
+/**
+* The exception a NAK carries. Not an {@link MllpClientError}: the remote
+* system understood the message and refused it, and the class is the one
+* `@glion/ack` defines for that MSA-1 code.
+*
+* @module
+*/
+/** The `@glion/ack` exception class for each NAK code. */
+const NAK_EXCEPTIONS = {
+	[AckCode.ApplicationError]: AckApplicationError,
+	[AckCode.ApplicationReject]: AckApplicationReject,
+	[AckCode.CommitError]: AckCommitError,
+	[AckCode.CommitReject]: AckCommitReject
+};
+/** MSA-3, ERR-3, and ERR-4 as one sentence, or a note that none were given. */
+function nakMessage(code, nak) {
+	const said = [];
+	if (nak.text !== void 0) said.push(nak.text);
+	if (nak.errorCode !== void 0) said.push(`ERR-3 ${nak.errorCode}`);
+	if (nak.severity !== void 0) said.push(`ERR-4 ${nak.severity}`);
+	const reason = said.length === 0 ? "It gave no reason." : `${said.join("; ")}.`;
+	return `The remote system did not accept message ${nak.controlId} (MSA-1 ${code}). ${reason}`;
+}
+/**
+* The exception a NAK of `code` carries, read from `tree`.
+*
+* `code` picks the class; MSA-2 gives `controlId`, ERR-3 `errorCode`, ERR-4
+* `severity`, and MSA-3 (or ERR-8) `text`.
+*/
+function nakException(tree, code) {
+	const nak = {
+		controlId: read(tree, "MSA-2[1].1.1"),
+		errorCode: read(tree, "ERR-3[1].1.1") || void 0,
+		severity: read(tree, "ERR-4[1].1.1") || void 0,
+		text: read(tree, "MSA-3[1].1.1") || read(tree, "ERR-8[1].1.1") || void 0
+	};
+	return new NAK_EXCEPTIONS[code](nakMessage(code, nak), nak);
+}
+//#endregion
+//#region src/errors/mllp-send-aborted-error.ts
+/**
+* `destroy()` cut off the message in flight. The remote system may or may not
+* have received it.
+*/
+var MllpSendAbortedError = class extends MllpClientError {
+	name = "MllpSendAbortedError";
+	code = MllpErrorCode.SEND_ABORTED;
+	delivery = "unknown";
+	constructor() {
+		super("The send was cut off by destroy() — the remote system may or may not have received the message; resend only if the message is safe to repeat.");
+	}
+};
+//#endregion
+//#region src/errors/mllp-send-timeout-error.ts
+/**
+* No acknowledgment arrived within the send timeout. The connection is ended.
+* Whether the remote system received the message is unknown.
+*/
+var MllpSendTimeoutError = class extends MllpConnectionError {
+	name = "MllpSendTimeoutError";
+	code = MllpErrorCode.SEND_TIMEOUT;
+	delivery = "unknown";
+	timeoutMs;
+	constructor(timeoutMs) {
+		super("No acknowledgment arrived within the send timeout — the connection has been closed, because a late acknowledgment could not be matched safely.");
+		this.timeoutMs = timeoutMs;
+	}
+};
+//#endregion
+//#region src/assertions.ts
+/**
+* Option validation, and the client's invariants. Each option `assert*`
+* throws {@link MllpInvalidOptionError} for an option a caller passed out of
+* range, before anything happens. {@link assertPhase} throws for a phase the
+* client cannot be in where it is asserted: a bug.
+*
+* @module
+*/
+function assertTimeoutMs(option, ms) {
+	if (!Number.isFinite(ms) || ms <= 0 || ms > MAX_TIMEOUT_MS) throw new MllpInvalidOptionError(`${option} must be a number of milliseconds between 1 and ${MAX_TIMEOUT_MS}.`);
+}
+function assertByteCap(bytes) {
+	if (!Number.isInteger(bytes) || bytes <= 0) throw new MllpInvalidOptionError("maxBufferedBytes must be a positive integer.");
+}
+/** `state` is in `phase`; `where` names the site for the report. */
+function assertPhase(state, phase, where) {
+	if (state.phase !== phase) throw new Error(`${where} found the client ${state.phase}. This is a bug in @glion/mllp-client; please report it.`);
+}
+function assertReconnectAttempts(attempts) {
+	if (!(attempts === Number.POSITIVE_INFINITY) && (!Number.isInteger(attempts) || attempts < 0)) throw new MllpInvalidOptionError("reconnect.attempts must be a non-negative integer, or Infinity.");
+}
+//#endregion
+//#region src/events.ts
+/**
+* The listeners of a client.
+*
+* A listener that throws propagates to whoever triggered the event, the same
+* as Node's `EventEmitter`.
+*/
+var MllpClientEmitter = class {
+	#listeners = /* @__PURE__ */ new Map();
+	/** Adds a listener for `event`, and returns the client so calls chain. */
+	on(event, listener) {
+		const listeners = this.#listeners.get(event) ?? /* @__PURE__ */ new Set();
+		listeners.add(listener);
+		this.#listeners.set(event, listeners);
+		return this;
+	}
+	/** Removes a listener added with {@link on}. */
+	off(event, listener) {
+		this.#listeners.get(event)?.delete(listener);
+		return this;
+	}
+	/** Calls every listener for `event`, in the order they were added. */
+	emit(event, ...args) {
+		for (const listener of this.#listeners.get(event) ?? []) listener(...args);
+	}
+};
+//#endregion
+//#region src/messages.ts
+/**
+* Encoding a message to send, and decoding the acknowledgment that answers it.
+* Pure.
+*
+* @module
+*/
+/**
+* `tree` as the message to send, in canonical HL7v2.
+*
+* @throws {MllpInvalidMessageError} The message has no MSH-10, or it could not
+*   be serialized or encoded.
+*/
+function encode(tree) {
+	const controlId = read(tree, "MSH-10[1].1.1");
+	if (controlId === "") throw new MllpInvalidMessageError("the message has no MSH-10 control ID, so its acknowledgment could not be matched");
+	try {
+		return {
+			bytes: encodeBytes(toHl7v2(tree)),
+			controlId
+		};
+	} catch (error) {
+		throw new MllpInvalidMessageError(error);
+	}
+}
+/**
+* `bytes` as the acknowledgment of the message `controlId` identifies.
+*
+* MSA-2 is checked before MSA-1 is read: an accept or a NAK is reported only
+* for the message it answers. MSH-9 and the HL7 version are not checked
+* (#668).
+*
+* @throws {AckException} MSA-1 refused the message. The remote system
+*   understood it.
+* @throws {MllpInvalidResponseError} Not a usable acknowledgment of this
+*   message: unreadable bytes, an MSA-1 outside Table 0008, or an MSA-2
+*   naming another message.
+*/
+function decode(bytes, controlId) {
+	let raw;
+	let tree;
+	try {
+		raw = decodeBytes(bytes);
+		tree = parseHL7v2(raw);
+	} catch (error) {
+		throw new MllpInvalidResponseError(error, controlId);
+	}
+	const answers = read(tree, "MSA-2[1].1.1");
+	if (answers !== controlId) throw new MllpInvalidResponseError(`MSA-2 is "${answers}", so it answers a different message — usually a late acknowledgment from an earlier timed-out send.`, controlId);
+	const code = read(tree, "MSA-1[1].1.1");
+	if (isAckNakCode(code)) throw nakException(tree, code);
+	if (!isAckSuccessCode(code)) throw new MllpInvalidResponseError(code === "" ? "MSA-1 is empty, so accept or reject cannot be determined." : `MSA-1 is "${code}", which is not one of AA, AE, AR, CA, CE, or CR.`, controlId);
+	return {
+		code,
+		controlId: answers,
+		id: read(tree, "MSH-10[1].1.1"),
+		raw,
+		text: read(tree, "MSA-3[1].1.1") || void 0,
+		tree
+	};
+}
+//#endregion
+//#region src/queue.ts
+function createQueue() {
+	const entries = [];
+	let empty = null;
+	return {
+		async drained() {
+			if (entries.length === 0) return;
+			empty ??= Promise.withResolvers();
+			await empty.promise;
+		},
+		enter() {
+			const { promise, resolve, reject } = Promise.withResolvers();
+			const entry = {
+				reject,
+				resolve: () => resolve(null),
+				wait: entries.length === 0 ? null : promise
+			};
+			entries.push(entry);
+			return entry;
+		},
+		leave(turn) {
+			const place = entries.indexOf(turn);
+			if (place === -1) throw new Error("A turn left the queue twice. This is a bug in @glion/mllp-client; please report it.");
+			entries.splice(place, 1);
+			if (place === 0) entries[0]?.resolve();
+			if (entries.length === 0) {
+				empty?.resolve();
+				empty = null;
+			}
+		},
+		get pending() {
+			return Math.max(0, entries.length - 1);
+		},
+		rejectWaiting(error) {
+			for (const entry of entries.slice(1)) entry.reject(error);
+		}
+	};
+}
+//#endregion
+//#region src/reconnect.ts
+/** Ceiling of the first default wait, in milliseconds. Doubles per attempt. */
+const BACKOFF_BASE_MS = 1e3;
+/** Ceiling of every default wait, in milliseconds. */
+const BACKOFF_CAP_MS = 3e4;
+/**
+* Full-jitter exponential backoff: a wait drawn uniformly from zero to
+* `min(30 s, 1 s × 2^(attempt − 1))`.
+*/
+function defaultReconnectDelay(attempt) {
+	const ceiling = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * 2 ** (attempt - 1));
+	return Math.floor(Math.random() * ceiling);
+}
+/** Resolves after `ms`, or at once when `signal` aborts first. Never rejects. */
+function sleep(ms, signal) {
+	if (signal.aborted) return Promise.resolve();
+	return new Promise((resolve) => {
+		const done = () => {
+			clearTimeout(timer);
+			signal.removeEventListener("abort", done);
+			resolve();
+		};
+		const timer = setTimeout(done, ms);
+		signal.addEventListener("abort", done, { once: true });
+	});
+}
+//#endregion
+//#region src/session.ts
+/**
+* One session over a socket: the message layer over its bytes. A message
+* written here is framed, and bytes read here are unframed.
+*
+* @module
+*/
+/**
+* Opens `socket` and takes ownership of its streams.
+*
+* @throws {MllpConnectionTimeoutError} No socket within `timeoutMs`.
+* @throws {MllpConnectionFailedError} The socket failed to open, or `signal`
+*   cancelled the attempt; the adapter's rejection is on `cause`.
+*/
+async function openSocketStreams(socket, signal, opts) {
+	const timeout = AbortSignal.timeout(opts.timeoutMs);
+	let streams;
+	try {
+		streams = await socket.connect(AbortSignal.any([signal, timeout]));
+	} catch (error) {
+		if (timeout.aborted) throw new MllpConnectionTimeoutError(opts.timeoutMs);
+		throw new MllpConnectionFailedError(error);
+	}
+	try {
+		return {
+			reader: streams.readable.pipeThrough(unframe({ maxBufferedBytes: opts.maxBufferedBytes })).getReader(),
+			writer: streams.writable.getWriter()
+		};
+	} catch (error) {
+		await socket.close();
+		throw new MllpConnectionFailedError(error);
+	}
+}
+/**
+* Starts opening a session over `socket`, and hands it back at once. The
+* session ends itself when `signal` aborts.
+*
+* Never throws: every failure, an adapter's synchronous throw included,
+* reaches `ready`. Nothing is left open on any path: an attempt that fails or
+* is cancelled closes the socket before `ready` rejects.
+*/
+function createSession(socket, opts, signal) {
+	const abort = new AbortController();
+	const streams = openSocketStreams(socket, abort.signal, opts);
+	let closing = null;
+	const cancel = () => void destroy();
+	const ready = (async () => {
+		signal?.addEventListener("abort", cancel, { once: true });
+		try {
+			await streams;
+		} catch (error) {
+			signal?.removeEventListener("abort", cancel);
+			throw error;
+		}
+		if (closing !== null) {
+			await closing;
+			throw new MllpConnectionFailedError(abort.signal.reason);
+		}
+	})();
+	const destroy = () => {
+		closing ??= (async () => {
+			abort.abort();
+			signal?.removeEventListener("abort", cancel);
+			const [opened] = await Promise.allSettled([streams]);
+			if (opened.status === "fulfilled") {
+				opened.value.reader.releaseLock();
+				opened.value.writer.releaseLock();
+				await socket.close();
+			}
+		})();
+		return closing;
+	};
+	const exchange = async (message, timeoutMs) => {
+		let framed;
+		try {
+			framed = frame(message);
+		} catch (error) {
+			throw new MllpInvalidMessageError(error);
+		}
+		await ready;
+		let timedOut = false;
+		const deadline = setTimeout(() => {
+			timedOut = true;
+			destroy();
+		}, timeoutMs);
+		try {
+			const { reader, writer } = await streams;
+			await writer.write(framed);
+			const reply = await reader.read();
+			if (reply.done) throw new MllpConnectionLostError();
+			return reply.value;
+		} catch (error) {
+			if (timedOut) throw new MllpSendTimeoutError(timeoutMs);
+			if (abort.signal.aborted) throw new MllpSendAbortedError();
+			throw error instanceof MllpCodecError || error instanceof MllpConnectionLostError ? error : new MllpConnectionLostError(error);
+		} finally {
+			clearTimeout(deadline);
+		}
+	};
+	return {
+		destroy,
+		exchange,
+		ready
+	};
+}
+//#endregion
+//#region src/client.ts
+/**
+* Sends HL7v2 messages to one remote system over MLLP and returns each
+* message's acknowledgment.
+*
+* One client owns one socket and puts one message on the wire at a time.
+* `send()` writes the message, waits for the acknowledgment, checks that it
+* answers this message, and resolves with it. A send arriving while another
+* is in flight waits its turn; sends go out in the order they were called.
+*
+* ```ts
+* import { MllpClient } from "@glion/mllp-client";
+* import { nodeSocket } from "@glion/mllp-client/node";
+*
+* await using client = new MllpClient({
+*   socket: nodeSocket({ host: "hl7.example.org", port: 2575 }),
+* });
+*
+* const ack = await client.send(adtMessage);
+* ack.code; // "AA" or "CA"
+* ```
+*
+* ## Lifecycle
+*
+* `send()` connects on first use; `connect()` opens the connection ahead of
+* time. `state` reports the phase. A connection that fails to open is dialed
+* again under the `reconnect` policy. A connection that is lost closes the
+* client: the message in flight rejects and is not sent again. After
+* `close()`, or once the client has closed on a failure, every call rejects
+* with {@link MllpClientClosedError}.
+*
+* ## Errors
+*
+* When the remote system answers `AE`, `AR`, `CE`, or `CR`, `send()` rejects
+* with the matching `@glion/ack` exception and the connection stays open.
+*/
+var MllpClient = class extends MllpClientEmitter {
+	#socket;
+	#connect;
+	#policy;
+	#sendTimeoutMs;
+	#state = { phase: "idle" };
+	#queue = createQueue();
+	/**
+	* @throws {MllpInvalidOptionError} A timeout, byte cap, or attempt count is
+	*   out of range.
+	*/
+	constructor(opts) {
+		super();
+		const connectTimeoutMs = opts.connectTimeoutMs ?? 1e4;
+		const maxBufferedBytes = opts.maxBufferedBytes ?? 16777216;
+		const attempts = opts.reconnect === false ? 0 : opts.reconnect?.attempts ?? 5;
+		const delay = opts.reconnect === false ? defaultReconnectDelay : opts.reconnect?.delay ?? defaultReconnectDelay;
+		this.#sendTimeoutMs = opts.sendTimeoutMs ?? 3e4;
+		assertTimeoutMs("connectTimeoutMs", connectTimeoutMs);
+		assertTimeoutMs("sendTimeoutMs", this.#sendTimeoutMs);
+		assertByteCap(maxBufferedBytes);
+		assertReconnectAttempts(attempts);
+		this.#socket = opts.socket;
+		this.#connect = {
+			maxBufferedBytes,
+			timeoutMs: connectTimeoutMs
+		};
+		this.#policy = {
+			attempts,
+			delay
+		};
+	}
+	/**
+	* The current phase: `idle`, `connecting`, `connected`, `sending`,
+	* `closing`, or `closed`.
+	*/
+	get state() {
+		return this.#state.phase;
+	}
+	/** How many sends wait their turn, the one in flight excluded. */
+	get pending() {
+		return this.#queue.pending;
+	}
+	/** Whether the connection is open. True in both `connected` and `sending`. */
+	get connected() {
+		const { phase } = this.#state;
+		return phase === "connected" || phase === "sending";
+	}
+	/**
+	* Opens the connection ahead of the first `send()`, dialing again under the
+	* `reconnect` policy when an attempt fails.
+	*
+	* Idempotent: a connected client resolves at once, and a call arriving while
+	* an attempt is in flight waits for that attempt and shares its outcome.
+	*
+	* @throws {MllpConnectionFailedError} The last attempt could not open the
+	*   socket.
+	* @throws {MllpConnectionTimeoutError} The last attempt did not open in time.
+	* @throws {MllpClientClosedError} The client is closed, or `close()` or
+	*   `destroy()` arrived while the connection was still being established.
+	*/
+	async connect() {
+		const state = this.#state;
+		let opening;
+		switch (state.phase) {
+			case "connected":
+			case "sending": return;
+			case "closing":
+			case "closed": throw new MllpClientClosedError(state.reason);
+			case "connecting":
+				opening = state.opening;
+				break;
+			case "idle": {
+				const abort = new AbortController();
+				opening = this.#dial(abort.signal);
+				this.#state = {
+					abort,
+					opening,
+					phase: "connecting"
+				};
+				break;
+			}
+		}
+		try {
+			await opening;
+		} catch (error) {
+			if (error instanceof MllpConnectionError) await this.destroy(error);
+			throw error;
+		}
+	}
+	/**
+	* Sends one message and returns its acknowledgment. Connects first when the
+	* client is not connected yet, and waits for the send in flight, if any,
+	* before writing.
+	*
+	* Sends go out in the order `send()` was called. The queue has no bound.
+	* `timeoutMs` runs from the moment the write starts, not from the call. A
+	* send still waiting when the client closes rejects with
+	* {@link MllpClientClosedError}; one waiting behind a dial that fails
+	* rejects with the dial's error, as `connect()` does.
+	*
+	* Nothing is written when an option, phase, or message error is thrown.
+	* Every wire failure also closes the client; a NAK does not.
+	*
+	* @throws {AckException} The remote system answered with a NAK. The
+	*   connection stays open.
+	* @throws {MllpInvalidOptionError} `timeoutMs` is out of range.
+	* @throws {MllpInvalidMessageError} The message cannot be sent as-is.
+	* @throws {MllpClientClosedError} The client is closed, or closed while
+	*   this send was waiting its turn.
+	* @throws {MllpConnectionFailedError} The connection could not be opened.
+	* @throws {MllpConnectionTimeoutError} The connection did not open in time.
+	* @throws {MllpSendTimeoutError} No acknowledgment arrived in time.
+	* @throws {MllpConnectionLostError} The connection was lost.
+	* @throws {MllpSendAbortedError} `destroy()` cut the send off.
+	* @throws {MllpInvalidResponseError} The reply is not a usable
+	*   acknowledgment of this message.
+	*/
+	async send(message, opts = {}) {
+		const timeoutMs = opts.timeoutMs ?? this.#sendTimeoutMs;
+		assertTimeoutMs("timeoutMs", timeoutMs);
+		const { bytes, controlId } = encode(message);
+		const at = this.#state;
+		if (at.phase === "closing" || at.phase === "closed") throw new MllpClientClosedError(at.reason);
+		const turn = this.#queue.enter();
+		try {
+			if (turn.wait !== null) await turn.wait;
+			if (!this.connected) await this.connect();
+			return await this.#send(controlId, bytes, timeoutMs);
+		} finally {
+			this.#queue.leave(turn);
+		}
+	}
+	/**
+	* Ends the connection once the message in flight is acknowledged, and
+	* resolves when it is down. New sends, and sends waiting their turn, are
+	* refused from the moment this is called. An attempt to connect stops at
+	* once.
+	*
+	* Resolves from any phase. Never rejects. Idempotent. The wait is bounded by
+	* the in-flight send's own deadline; {@link destroy} does not wait at all.
+	* If the message it waits for fails, the client closes with that failure;
+	* otherwise with `null`.
+	*/
+	async close() {
+		const from = this.#state;
+		switch (from.phase) {
+			case "closing":
+				await from.closed;
+				return;
+			case "sending": {
+				const closed = (async () => {
+					await this.#queue.drained();
+					await this.#destroy(from, null);
+				})();
+				this.#state = {
+					closed,
+					phase: "closing",
+					reason: null,
+					session: from.session
+				};
+				this.#queue.rejectWaiting(new MllpClientClosedError());
+				await closed;
+				return;
+			}
+			case "idle":
+			case "connecting":
+			case "connected":
+			case "closed": await this.destroy();
+		}
+	}
+	/**
+	* Ends the connection now, and resolves when it is down. A message in flight
+	* rejects with {@link MllpSendAbortedError}. An attempt to connect stops at
+	* once. The client closes with `reason`: the failure it reports on `close`
+	* and on every later call, or `null` for the owner's own decision.
+	*
+	* Resolves from any phase. Never rejects. Idempotent. Sends waiting their
+	* turn are rejected with `reason` when its delivery is `not-sent`, and with
+	* {@link 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.
+	*/
+	async destroy(reason = null) {
+		const from = this.#state;
+		switch (from.phase) {
+			case "closed": return;
+			case "closing":
+				if (from.reason === null && reason !== null) this.#state = {
+					...from,
+					reason
+				};
+				await from.session?.destroy();
+				await from.closed;
+				return;
+			case "idle":
+				this.#state = {
+					phase: "closed",
+					reason
+				};
+				this.emit("close", reason);
+				return;
+			case "connecting":
+			case "connected":
+			case "sending": {
+				const closed = this.#destroy(from, reason);
+				this.#state = {
+					closed,
+					phase: "closing",
+					reason,
+					session: "session" in from ? from.session : null
+				};
+				this.#queue.rejectWaiting(reason?.delivery === "not-sent" ? reason : new MllpClientClosedError(reason));
+				await closed;
+			}
+		}
+	}
+	/** Calls {@link close}. Enables `await using`. */
+	async [Symbol.asyncDispose]() {
+		await this.close();
+	}
+	/**
+	* Dials under the policy until a session opens, then moves to `connected`
+	* and reports `connect`. Each attempt after the first waits
+	* `delay(attempt)` first.
+	*
+	* @throws {MllpClientClosedError} `signal` aborted: the owner closed the
+	*   client. Nothing is left open.
+	* @throws {MllpConnectionFailedError} The policy gave up; the last attempt
+	*   could not open the socket.
+	* @throws {MllpConnectionTimeoutError} The policy gave up; the last attempt
+	*   did not open in time.
+	*/
+	async #dial(signal) {
+		for (let attempt = 0;; attempt += 1) {
+			if (attempt > 0) await sleep(this.#policy.delay(attempt), signal);
+			if (signal.aborted) throw new MllpClientClosedError(signal.reason);
+			const session = createSession(this.#socket, this.#connect, signal);
+			try {
+				await session.ready;
+			} catch (error) {
+				if (signal.aborted) throw new MllpClientClosedError(signal.reason);
+				if (attempt >= this.#policy.attempts) throw error;
+				continue;
+			}
+			if (signal.aborted) {
+				await session.destroy();
+				throw new MllpClientClosedError(signal.reason);
+			}
+			this.#state = {
+				phase: "connected",
+				session
+			};
+			this.emit("connect");
+			return;
+		}
+	}
+	/**
+	* Ends what `from` holds, the dial or the session, then moves to `closed`
+	* with the reason `closing` holds by then and reports `close`. A dial is
+	* aborted with `reason`.
+	*
+	* MUST NOT touch `#state` before its first `await`: the caller moves to
+	* `closing` after calling it.
+	*/
+	async #destroy(from, reason) {
+		switch (from.phase) {
+			case "connecting":
+				from.abort.abort(reason);
+				await Promise.allSettled([from.opening]);
+				break;
+			case "connected":
+			case "sending":
+				await from.session.destroy();
+				break;
+		}
+		const ending = this.#state;
+		assertPhase(ending, "closing", "The teardown");
+		this.#state = {
+			phase: "closed",
+			reason: ending.reason
+		};
+		this.emit("close", ending.reason);
+	}
+	/**
+	* The `sending` phase: the message on the wire and its acknowledgment,
+	* from `connected` and back to it.
+	*
+	* A failure of unknown delivery closes the client with it. A NAK, or a
+	* message refused before the write, leaves the connection in step.
+	*/
+	async #send(controlId, bytes, timeoutMs) {
+		const at = this.#state;
+		assertPhase(at, "connected", "send() at its turn");
+		const { session } = at;
+		this.#state = {
+			phase: "sending",
+			session
+		};
+		try {
+			return decode(await session.exchange(bytes, timeoutMs), controlId);
+		} catch (error) {
+			return await this.#sendFailed(error, controlId);
+		} finally {
+			if (this.#state.phase === "sending") this.#state = {
+				phase: "connected",
+				session
+			};
+		}
+	}
+	/**
+	* The send of `controlId` failed with `error`. Throws it as the client
+	* reports it: a reply the codec could not read is
+	* {@link MllpInvalidResponseError}. A failure of unknown delivery, other
+	* than a send cut off by `destroy()`, closes the client first.
+	*
+	* From `closing`, the ending under way is waiting for this send: started,
+	* not awaited.
+	*/
+	async #sendFailed(error, controlId) {
+		const reason = error instanceof MllpCodecError ? new MllpInvalidResponseError(error, controlId) : error;
+		if (!(reason instanceof MllpClientError) || reason.delivery !== "unknown") throw reason;
+		if (reason instanceof MllpSendAbortedError) throw reason;
+		if (this.#state.phase === "sending") await this.destroy(reason);
+		else this.destroy(reason);
+		throw reason;
+	}
+};
+//#endregion
+export { MllpClient, MllpClientClosedError, MllpClientEmitter, MllpClientError, MllpConnectionError, MllpConnectionFailedError, MllpConnectionLostError, MllpConnectionTimeoutError, MllpErrorCode, MllpInvalidMessageError, MllpInvalidOptionError, MllpInvalidResponseError, MllpSendAbortedError, MllpSendTimeoutError };
+
+//# sourceMappingURL=index.js.map