@glion/mllp 0.14.1

package/dist/mllp.js

@@ -0,0 +1,791 @@
+import { value } from "@glion/util-query";
+import { VFile } from "vfile";
+//#region src/transport/constants.ts
+/**
+* MLLP Start Byte - Vertical Tab (VT)
+* Marks the beginning of an MLLP frame
+*/
+const MLLP_START_BYTE = 11;
+/**
+* MLLP End Byte 1 - File Separator (FS)
+* First byte of the end sequence
+*/
+const MLLP_END_BYTE_1 = 28;
+/**
+* MLLP End Byte 2 - Carriage Return (CR)
+* Second byte of the end sequence
+*/
+const MLLP_END_BYTE_2 = 13;
+/**
+* MLLP header as a Uint8Array containing the start byte
+*/
+const MLLP_HEADER = new Uint8Array([11]);
+/**
+* MLLP trailer as a Uint8Array containing the end sequence
+*/
+const MLLP_TRAILER = new Uint8Array([28, 13]);
+//#endregion
+//#region src/errors.ts
+/**
+* Base error class for all MLLP errors.
+*
+* All error types in the MLLP package extend this class.
+* Provides a common `code` field so that any MLLP error can be
+* programmatically identified and translated (e.g., into ACK/NAK responses).
+*/
+var MllpError = class extends Error {
+	/** Machine-readable error code identifying the error type */
+	code;
+	/** Error condition string (e.g., for ERR segment in ACK) */
+	errorCondition;
+	constructor(code, message, options) {
+		super(message, options);
+		this.name = "MllpError";
+		this.code = code;
+		this.errorCondition = options?.errorCondition;
+	}
+};
+//#endregion
+//#region src/transport/errors.ts
+/**
+* Transport-level error for MLLP framing issues (invalid framing, incomplete
+* messages, etc.)
+*/
+var TransportError = class extends MllpError {
+	/** Position in the data where the error occurred (if applicable) */
+	position;
+	constructor(code, message, position) {
+		super(code, message);
+		this.name = "TransportError";
+		this.position = position;
+	}
+};
+//#endregion
+//#region src/transport/types.ts
+/**
+* Error codes for MLLP frame-level errors
+*/
+const TransportErrorCode = {
+	INCOMPLETE_MESSAGE: "INCOMPLETE_MESSAGE",
+	INVALID_END_SEQUENCE: "INVALID_END_SEQUENCE",
+	INVALID_START_BYTE: "INVALID_START_BYTE",
+	MESSAGE_TOO_LARGE: "MESSAGE_TOO_LARGE"
+};
+//#endregion
+//#region src/transport/dynamic-buffer.ts
+/**
+* A growable byte buffer with geometric capacity doubling.
+*
+* Designed for protocol decoders that accumulate bytes from arbitrarily
+* chunked TCP streams. Amortizes copy cost to O(n) total — the same
+* strategy used by pg-protocol, NATS.js, and Java's ArrayList.
+*
+* The buffer maintains a read offset so consumed bytes can be skipped
+* without shifting data. When the wasted prefix exceeds half the
+* capacity, the buffer auto-compacts by shifting remaining bytes to
+* the front.
+*
+* @internal
+*/
+var DynamicBuffer = class {
+	_buffer;
+	_length = 0;
+	_offset = 0;
+	constructor(initialCapacity = 4096) {
+		this._buffer = new Uint8Array(initialCapacity);
+	}
+	get capacity() {
+		return this._buffer.length;
+	}
+	get available() {
+		return this._length - this._offset;
+	}
+	append(chunk) {
+		const needed = this._length + chunk.length;
+		if (needed > this._buffer.length) {
+			const newCapacity = Math.max(this._buffer.length * 2, needed);
+			const newBuffer = new Uint8Array(newCapacity);
+			newBuffer.set(this._buffer.subarray(0, this._length));
+			this._buffer = newBuffer;
+		}
+		this._buffer.set(chunk, this._length);
+		this._length += chunk.length;
+	}
+	view() {
+		return this._buffer.subarray(this._offset, this._length);
+	}
+	consume(n) {
+		this._offset += n;
+		if (this._offset >= this._length) {
+			this._offset = 0;
+			this._length = 0;
+			return;
+		}
+		if (this._offset > this._buffer.length / 2) this._compact();
+	}
+	reset() {
+		this._offset = 0;
+		this._length = 0;
+	}
+	_compact() {
+		const remaining = this._length - this._offset;
+		this._buffer.copyWithin(0, this._offset, this._length);
+		this._offset = 0;
+		this._length = remaining;
+	}
+};
+//#endregion
+//#region src/transport/decoder-stream.ts
+function defaultOnError(error) {
+	console.warn(`MLLP decode error: [${error.code}] ${error.message}`);
+}
+/**
+* Default decoder options, merged with user-provided values via spread.
+*
+* - `encoding` — `"utf8"`, the standard encoding for HL7v2.
+* - `onError` — logs to `console.warn`; the stream continues processing.
+*/
+const defaultDecoderOptions = {
+	encoding: "utf8",
+	onError: defaultOnError
+};
+/**
+* Build the {@link Transformer} that powers both {@link createDecoderStream}
+* and {@link MLLPDecoderStream}.
+*
+* ## How MLLP framing works
+*
+* Every HL7v2 message on the wire is wrapped in a minimal envelope:
+*
+*     <VT> message-payload <FS><CR>
+*     0x0B                 0x1C 0x0D
+*
+* Multiple frames can arrive back-to-back within the same TCP stream.
+* The decoder's job is to find each `<VT>…<FS><CR>` envelope, strip
+* the framing bytes, and emit the inner payload as a {@link DecodedMessage}.
+*
+* ## State machine
+*
+* The decoder alternates between two states:
+*
+*     ┌──────────────┐   VT found    ┌────────────┐
+*     │ WAITING_START │──────────────▶│ IN_MESSAGE │
+*     └──────┬───────┘               └─────┬──────┘
+*            ▲  garbage → onError          │
+*            │                             │ FS CR found → emit message
+*            └─────────────────────────────┘
+*
+* 1. **WAITING_START** — Scans byte-by-byte for a VT start byte. Any bytes
+*    encountered before the VT are garbage (e.g. noise on the line or a partial
+*    connection reset); they are reported via `onError` and discarded.
+* 2. **IN_MESSAGE** — Scans for the two-byte FS CR end sequence. Once found, the
+*    bytes between VT and FS CR are the message payload. The decoder emits the
+*    message and transitions back to WAITING_START.
+*
+* ## Chunk boundaries
+*
+* TCP delivers data in arbitrarily-sized chunks that rarely align with
+* MLLP frame boundaries. A single chunk may contain:
+*
+* - A fraction of one frame (the rest arrives in the next chunk)
+* - Exactly one frame
+* - Multiple complete frames
+* - A mix of complete frames and a trailing partial frame
+*
+* The transformer handles all of these by appending every incoming
+* chunk to an internal `buffer`, then running `processBuffer()` to
+* extract as many complete frames as possible. Any leftover bytes
+* (a partial frame) stay in the buffer until the next chunk arrives.
+*
+* ## Error recovery
+*
+* The stream is **resilient** — it never throws. All framing errors
+* are reported via the `onError` callback, and the decoder continues
+* scanning for the next valid frame. Error scenarios:
+*
+* - **Garbage before VT** — bytes are skipped, `INVALID_START_BYTE` reported.
+* - **Oversized message** — frame is abandoned, `MESSAGE_TOO_LARGE` reported,
+*   scanning resumes.
+* - **Incomplete frame at stream end** — `INCOMPLETE_MESSAGE` reported during
+*   `flush()`. This is the only error that can't be recovered from, since there
+*   is no more data coming.
+*
+* ## Size enforcement
+*
+* When `maxMessageSize` is set, the decoder checks the payload length
+* in two places to bound memory usage:
+*
+* 1. **Mid-accumulation** — while waiting for the end sequence, if the buffered
+*    payload already exceeds the limit, the frame is abandoned immediately.
+*    This prevents a missing end sequence from causing unbounded buffer
+*    growth.
+* 2. **On completion** — once the end sequence is found, the final payload length
+*    is checked before the message is enqueued.
+*/
+function createDecoderTransformer(options) {
+	const opts = {
+		...defaultDecoderOptions,
+		...options
+	};
+	const textDecoder = new TextDecoder(opts.encoding);
+	/**
+	* Accumulation buffer — grows as chunks arrive, shrinks as frames are
+	* consumed.
+	*/
+	const dynBuffer = new DynamicBuffer();
+	/** Current state machine position. */
+	let state = "WAITING_START";
+	/**
+	* Byte offset within the buffer view where the current frame's VT start byte
+	* lives. Only meaningful when `state === "IN_MESSAGE"`.
+	*/
+	let messageStartPos = 0;
+	/**
+	* Scan `view` for the next VT (0x0B) at or after `startPos`.
+	*
+	* @returns The index of the VT byte, or -1 if not found.
+	*/
+	function findStartByte(view, startPos) {
+		for (let i = startPos; i < view.length; i++) if (view[i] === 11) return i;
+		return -1;
+	}
+	/**
+	* Scan `view` for the two-byte FS CR (0x1C 0x0D) end sequence
+	* at or after `startPos`.
+	*
+	* @returns The index of the FS byte (first byte of the pair), or -1 if not
+	*   found.
+	*/
+	function findEndSequence(view, startPos) {
+		for (let i = startPos; i < view.length - 1; i++) if (view[i] === 28 && view[i + 1] === 13) return i;
+		return -1;
+	}
+	/**
+	* Drain as many complete frames from the buffer as possible, enqueuing
+	* each decoded message into `controller`.
+	*
+	* Returns when the buffer contains only an incomplete frame (or is
+	* empty). The incomplete bytes are kept for the next `transform()` call.
+	*
+	* The loop uses a local `position` cursor that always resets to 0
+	* after a `consume()` call, since consumption shifts the view.
+	*/
+	function processBuffer(controller) {
+		let position = 0;
+		while (true) {
+			const view = dynBuffer.view();
+			if (position >= view.length) break;
+			if (state === "WAITING_START") {
+				const startPos = findStartByte(view, position);
+				if (startPos === -1) {
+					if (view.length > 0) opts.onError(new TransportError(TransportErrorCode.INVALID_START_BYTE, `Skipped ${view.length - position} bytes before finding start byte`, position));
+					dynBuffer.reset();
+					return;
+				}
+				if (startPos > position) opts.onError(new TransportError(TransportErrorCode.INVALID_START_BYTE, `Skipped ${startPos - position} bytes before start byte`, position));
+				state = "IN_MESSAGE";
+				messageStartPos = startPos;
+				position = startPos + 1;
+			}
+			if (state === "IN_MESSAGE") {
+				const endPos = findEndSequence(view, position);
+				if (endPos === -1) {
+					const currentSize = view.length - messageStartPos - 1;
+					if (opts.maxMessageSize !== void 0 && currentSize > opts.maxMessageSize) {
+						opts.onError(new TransportError(TransportErrorCode.MESSAGE_TOO_LARGE, `Message size ${currentSize} exceeds maximum ${opts.maxMessageSize}`, messageStartPos));
+						state = "WAITING_START";
+						position = messageStartPos + 1;
+						dynBuffer.consume(position);
+						position = 0;
+						continue;
+					}
+					if (messageStartPos > 0) {
+						dynBuffer.consume(messageStartPos);
+						messageStartPos = 0;
+					}
+					return;
+				}
+				const messageData = view.slice(messageStartPos + 1, endPos);
+				const messageLength = messageData.length;
+				if (opts.maxMessageSize !== void 0 && messageLength > opts.maxMessageSize) opts.onError(new TransportError(TransportErrorCode.MESSAGE_TOO_LARGE, `Message size ${messageLength} exceeds maximum ${opts.maxMessageSize}`, messageStartPos));
+				else controller.enqueue({
+					byteLength: messageLength,
+					data: messageData,
+					text: textDecoder.decode(messageData)
+				});
+				position = endPos + 2;
+				state = "WAITING_START";
+				dynBuffer.consume(position);
+				position = 0;
+			}
+		}
+	}
+	return {
+		flush(_controller) {
+			if (state === "IN_MESSAGE" && dynBuffer.available > 0) opts.onError(new TransportError(TransportErrorCode.INCOMPLETE_MESSAGE, "Stream ended with incomplete MLLP message", messageStartPos));
+		},
+		transform(chunk, controller) {
+			dynBuffer.append(chunk);
+			processBuffer(controller);
+		}
+	};
+}
+/**
+* Create a `TransformStream` that extracts MLLP messages from a raw
+* byte stream.
+*
+* Pipe a TCP socket's `ReadableStream<Uint8Array>` through this stream
+* to receive one {@link DecodedMessage} per MLLP frame, regardless of
+* how the bytes are chunked on the wire.
+*
+* @example
+*   ```typescript
+*   import { createDecoderStream } from "@glion/mllp";
+*
+*   const decoder = createDecoderStream({
+*     maxMessageSize: 1024 * 1024, // 1 MB limit
+*     onError: (err) => log.warn(err), // custom error handler
+*   });
+*
+*   const messages = socket.readable.pipeThrough(decoder).getReader();
+*
+*   while (true) {
+*     const { done, value } = await messages.read();
+*     if (done) break;
+*     console.log(value.text); // HL7v2 message string
+*   }
+*   ```;
+*
+* @param options - Optional decoder settings (max size, encoding, error
+*   handler).
+* @returns A `TransformStream<Uint8Array, DecodedMessage>`.
+*/
+function createDecoderStream(options) {
+	return new TransformStream(createDecoderTransformer(options));
+}
+/**
+* Class-based variant of {@link createDecoderStream} for cases where
+* a reusable instance is preferred over the factory function.
+*
+* Functionally identical — both delegate to the same internal
+* transformer.
+*
+* @example
+*   ```typescript
+*   const decoder = new MLLPDecoderStream({ maxMessageSize: 512_000 });
+*   socket.readable.pipeThrough(decoder);
+*   ```;
+*/
+var MLLPDecoderStream = class extends TransformStream {
+	constructor(options) {
+		super(createDecoderTransformer(options));
+	}
+};
+//#endregion
+//#region src/transport/encoder.ts
+/** Module-level singleton — avoids allocation per encode() call. */
+const textEncoder = new TextEncoder();
+/**
+* Encode a single HL7v2 message into an MLLP frame.
+*
+* Wraps the message with MLLP framing:
+* - Start byte: 0x0B (VT)
+* - End sequence: 0x1C 0x0D (FS + CR)
+*/
+function encode(message, _options) {
+	const messageBytes = typeof message === "string" ? textEncoder.encode(message) : message;
+	const frame = new Uint8Array(messageBytes.length + 3);
+	frame[0] = 11;
+	frame.set(messageBytes, 1);
+	frame[frame.length - 2] = 28;
+	frame[frame.length - 1] = 13;
+	return frame;
+}
+/**
+* Encode multiple HL7v2 messages into concatenated MLLP frames.
+*/
+function encodeMultiple(messages, options) {
+	const frames = messages.map((msg) => encode(msg, options));
+	let totalLength = 0;
+	for (const frame of frames) totalLength += frame.length;
+	const result = new Uint8Array(totalLength);
+	let offset = 0;
+	for (const frame of frames) {
+		result.set(frame, offset);
+		offset += frame.length;
+	}
+	return result;
+}
+//#endregion
+//#region src/server/compose.ts
+/**
+* Compose an array of middleware into a single function that executes
+* them in onion-model order (like Hono/Koa).
+*
+* Each middleware receives (ctx, next). Calling next() proceeds to the
+* next middleware. If a middleware returns a Response without
+* calling next(), it short-circuits the chain.
+*
+* Response handling follows Hono's pattern: return values are written
+* to ctx.res, and middleware can also set ctx.res directly.
+* Last write wins.
+*/
+function compose(middlewares) {
+	return async (ctx) => {
+		let index = -1;
+		async function dispatch(i) {
+			if (i <= index) throw new Error("next() called multiple times");
+			index = i;
+			if (i >= middlewares.length) return;
+			const middleware = middlewares[i];
+			const result = await middleware(ctx, () => dispatch(i + 1));
+			if (result && typeof result === "object" && "raw" in result && typeof result.raw === "string") ctx.res = result;
+		}
+		await dispatch(0);
+	};
+}
+//#endregion
+//#region src/server/context.ts
+/**
+* Create a new Context for an incoming message.
+*
+* Only the **parse** step runs eagerly (sync, fast). Routing fields are
+* extracted as strings from the parsed tree immediately — these cached
+* strings always reflect the original wire values (see ADR-0013).
+*
+* The expensive pipeline stages are lazy:
+*
+* - `ctx.tree()` — triggers `run()` (transformers: annotations, escape decoding,
+*   lint). Cached after first call.
+* - `ctx.result()` — triggers `run()` + `stringify()` (compilation, e.g., JSON
+*   via hl7v2Jsonify). Cached after first call.
+*
+* If no handler matches or middleware short-circuits before accessing
+* the tree, the transform and compile steps never execute.
+*/
+function createContext(options) {
+	const { raw, bytes, connection, processor } = options;
+	const variables = /* @__PURE__ */ new Map();
+	let varSnapshot;
+	const file = new VFile(raw);
+	const parsed = processor.parse(file);
+	const controlId = value(parsed, "MSH-10")?.value ?? "";
+	const messageType = value(parsed, "MSH-9.1")?.value ?? "";
+	const triggerEvent = value(parsed, "MSH-9.2")?.value ?? "";
+	const messageStructure = value(parsed, "MSH-9.3")?.value ?? "";
+	const version = value(parsed, "MSH-12.1")?.value ?? "";
+	let transformedTree;
+	let transformPromise;
+	function getTree() {
+		if (transformedTree) return Promise.resolve(transformedTree);
+		if (!transformPromise) transformPromise = (async () => {
+			const result = await processor.run(parsed, file);
+			transformedTree = result;
+			return result;
+		})();
+		return transformPromise;
+	}
+	let resultPromise;
+	function getResult() {
+		if (!resultPromise) resultPromise = (async () => {
+			const tree = await getTree();
+			return processor.compiler ? processor.stringify(tree, file) : void 0;
+		})();
+		return resultPromise;
+	}
+	return {
+		ast: parsed,
+		connection: Object.freeze(connection),
+		controlId,
+		file,
+		get(key) {
+			return variables.get(key);
+		},
+		messageStructure,
+		messageType,
+		req: Object.freeze({
+			bytes,
+			raw
+		}),
+		res: void 0,
+		result: getResult,
+		set(key, value) {
+			variables.set(key, value);
+			varSnapshot = void 0;
+		},
+		tree: getTree,
+		triggerEvent,
+		get var() {
+			if (!varSnapshot) varSnapshot = Object.freeze(Object.fromEntries(variables));
+			return varSnapshot;
+		},
+		version
+	};
+}
+//#endregion
+//#region src/server/types.ts
+/**
+* Parse a pattern string like "ADT^A01", "ADT^*", "*^A01", or "*"
+* into a structured RoutePattern.
+*/
+function parsePattern(pattern) {
+	if (pattern === "*") return {
+		messageType: "*",
+		source: pattern,
+		triggerEvent: "*"
+	};
+	const caretIndex = pattern.indexOf("^");
+	if (caretIndex === -1) return {
+		messageType: pattern,
+		source: pattern,
+		triggerEvent: "*"
+	};
+	return {
+		messageType: pattern.slice(0, caretIndex) || "*",
+		source: pattern,
+		triggerEvent: pattern.slice(caretIndex + 1) || "*"
+	};
+}
+/**
+* Test whether a route pattern matches a given message type and trigger event.
+*/
+function matchPattern(pattern, messageType, triggerEvent) {
+	const typeMatch = pattern.messageType === "*" || pattern.messageType === messageType;
+	const eventMatch = pattern.triggerEvent === "*" || pattern.triggerEvent === triggerEvent;
+	return typeMatch && eventMatch;
+}
+//#endregion
+//#region src/server/router.ts
+/**
+* Create a matcher function from a string pattern.
+*/
+function patternMatcher(pattern) {
+	const parsed = parsePattern(pattern);
+	return (ctx) => matchPattern(parsed, ctx.messageType, ctx.triggerEvent);
+}
+/**
+* Pattern-matching router for HL7v2 message types.
+*
+* Routes are matched in registration order (first match wins).
+* Supports string patterns with wildcards or filter functions.
+*
+* String patterns:
+*
+* - `"ADT^A01"` — exact match
+* - `"ADT^*"` — any ADT message
+* - `"*"` — catch-all
+*
+* Filter functions:
+*
+* - `(ctx) => ctx.messageType === "ADT" && ctx.version === "2.5.1"`
+*/
+var Router = class {
+	#routes = [];
+	#globalMiddleware = [];
+	#scopedMiddleware = [];
+	/**
+	* Register a route handler with a string pattern or filter function.
+	*/
+	add(patternOrFilter, handler) {
+		const filter = typeof patternOrFilter === "string" ? patternMatcher(patternOrFilter) : patternOrFilter;
+		this.#routes.push({
+			filter,
+			handler
+		});
+	}
+	addMiddleware(patternOrFilterOrMiddleware, middlewareOrPrepend) {
+		if (typeof patternOrFilterOrMiddleware === "function" && (middlewareOrPrepend === void 0 || typeof middlewareOrPrepend === "boolean")) {
+			if (middlewareOrPrepend === true) this.#globalMiddleware.unshift(patternOrFilterOrMiddleware);
+			else this.#globalMiddleware.push(patternOrFilterOrMiddleware);
+			return;
+		}
+		if (typeof middlewareOrPrepend === "function") {
+			const middleware = middlewareOrPrepend;
+			const filter = typeof patternOrFilterOrMiddleware === "string" ? patternMatcher(patternOrFilterOrMiddleware) : patternOrFilterOrMiddleware;
+			this.#scopedMiddleware.push({
+				filter,
+				middleware
+			});
+		}
+	}
+	/**
+	* Match a context against registered routes and middleware.
+	* Returns the first matching handler and all applicable middleware.
+	*/
+	match(ctx) {
+		let handler;
+		for (const route of this.#routes) if (route.filter(ctx)) {
+			handler = route.handler;
+			break;
+		}
+		const middlewares = [...this.#globalMiddleware];
+		for (const scoped of this.#scopedMiddleware) if (scoped.filter(ctx)) middlewares.push(scoped.middleware);
+		return {
+			handler,
+			middlewares
+		};
+	}
+};
+//#endregion
+//#region src/server/mllp.ts
+/**
+* Internal store for associating message routing info with errors.
+* Uses a WeakMap so error objects can be garbage-collected normally.
+*/
+const errorMessageInfo = /* @__PURE__ */ new WeakMap();
+/**
+* Retrieve the {@link MessageInfo} associated with an error thrown
+* by `Mllp.handle()`. Returns `undefined` for errors that did not
+* originate from message processing (e.g., lifecycle callback errors).
+*/
+function getMessageInfo(error) {
+	return errorMessageInfo.get(error);
+}
+/**
+* MLLP application for HL7v2 messaging.
+*
+* A pure routing and middleware engine with no TCP/server concerns.
+* Use `serve()` to bind this to a TCP server.
+*
+* @example
+*   ```typescript
+*   import { Mllp } from "@glion/mllp";
+*   import { parseHL7v2 } from "@glion/hl7v2";
+*
+*   const app = new Mllp().parser(parseHL7v2).on("ADT^A01", async (ctx) => {
+*     const tree = await ctx.tree();
+*     return { raw: "..." };
+*   });
+*   ```;
+*/
+var Mllp = class {
+	#router = new Router();
+	#processor;
+	#errorHandler;
+	/**
+	* Register an HL7v2 processor for incoming messages.
+	*
+	* Accepts a unified `Processor` — either a pre-built one like
+	* `parseHL7v2` from `@glion/hl7v2`, or a custom composition
+	* via `unified().use(hl7v2Parser).use(...)`.
+	*
+	* Must be called before `handle()`. Calling multiple times replaces
+	* the previous processor (last-write-wins).
+	*/
+	parser(processor) {
+		this.#processor = processor;
+		return this;
+	}
+	use(first, second) {
+		if ((typeof first === "string" || typeof first === "function") && typeof second === "function") {
+			this.#router.addMiddleware(first, second);
+			return this;
+		}
+		if (typeof first === "function") {
+			const prepend = second && typeof second === "object" ? second.prepend : false;
+			this.#router.addMiddleware(first, prepend);
+			return this;
+		}
+		return this;
+	}
+	/**
+	* Register a route handler for a message type pattern or filter function.
+	*
+	* String patterns:
+	*
+	* - `"ADT^A01"` — exact match
+	* - `"ADT^*"` — any ADT message
+	* - `"*^A01"` — any type with A01 trigger
+	* - `"*"` — catch-all
+	*
+	* Filter functions:
+	*
+	* - `(ctx) => ctx.messageType === "ADT" && ctx.version === "2.5.1"`
+	*/
+	on(patternOrFilter, handler) {
+		this.#router.add(patternOrFilter, handler);
+		return this;
+	}
+	/**
+	* Register a global error handler.
+	*
+	* Called when middleware or a handler throws. Without an error handler,
+	* the error is re-thrown to the caller (e.g. `serve()`).
+	*
+	* If the error handler returns a response, it is used as the reply.
+	* If the error handler itself throws, the new error is re-thrown.
+	*/
+	onError(handler) {
+		this.#errorHandler = handler;
+		return this;
+	}
+	/**
+	* Process a raw HL7v2 message through the middleware chain and router.
+	* This is the integration point — analogous to Hono's `fetch()`.
+	*
+	* The pipeline is lazy (see ADR-0013):
+	* 1. Parse (sync, fast) — always runs, extracts routing fields
+	* 2. Route match — uses pre-transform routing fields
+	* 3. If no match → return undefined (no transform/compile cost)
+	* 4. Transform/compile — only when handlers access ctx.tree()/ctx.result()
+	*
+	* Throws `MllpError` if no processor has been registered via `app.parser()`.
+	*/
+	async handle(raw, bytes, connection) {
+		if (!this.#processor) throw new MllpError("ERR_NO_PARSER", "No parser registered. Call app.parser() before handling messages.");
+		const ctx = createContext({
+			bytes,
+			connection,
+			processor: this.#processor,
+			raw
+		});
+		try {
+			const match = this.#router.match(ctx);
+			const middlewares = [...match.middlewares];
+			if (match.handler) {
+				const handler = match.handler;
+				middlewares.push((handlerCtx) => handler(handlerCtx));
+			}
+			await compose(middlewares)(ctx);
+			return ctx.res;
+		} catch (error) {
+			return this.#handleError(error instanceof Error ? error : new Error(String(error)), ctx);
+		}
+	}
+	/**
+	* Handle an error during message processing.
+	*
+	* If a custom error handler is registered, delegates to it.
+	* If the error handler itself throws, re-throws the error handler's error.
+	* If no error handler is registered, re-throws the original error.
+	*
+	* In both re-throw cases, message routing fields are attached to the
+	* error via {@link getMessageInfo} so callers can include message
+	* context in error reporting.
+	*
+	* Callers (e.g. `serve()`) are responsible for catching these errors
+	* and deciding how to handle them at the transport level.
+	*/
+	async #handleError(err, ctx) {
+		const info = {
+			controlId: ctx.controlId,
+			messageStructure: ctx.messageStructure,
+			messageType: ctx.messageType,
+			triggerEvent: ctx.triggerEvent,
+			version: ctx.version
+		};
+		if (this.#errorHandler) try {
+			return await this.#errorHandler(err, ctx);
+		} catch (handlerError) {
+			const e = handlerError instanceof Error ? handlerError : new Error(String(handlerError));
+			errorMessageInfo.set(e, info);
+			throw e;
+		}
+		errorMessageInfo.set(err, info);
+		throw err;
+	}
+};
+//#endregion
+export { encode as a, createDecoderStream as c, MllpError as d, MLLP_END_BYTE_1 as f, MLLP_TRAILER as g, MLLP_START_BYTE as h, parsePattern as i, TransportErrorCode as l, MLLP_HEADER as m, getMessageInfo as n, encodeMultiple as o, MLLP_END_BYTE_2 as p, matchPattern as r, MLLPDecoderStream as s, Mllp as t, TransportError as u };
+
+//# sourceMappingURL=mllp.js.map