@glion/mllp 0.14.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Rethink Health
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,486 @@
+# @glion/mllp
+
+MLLP (Minimal Lower Layer Protocol) transport for HL7v2 messaging — primitives, streaming, and a [Hono](https://hono.dev)-style middleware server.
+
+## Overview
+
+This package provides everything needed to send and receive HL7v2 messages over MLLP/TCP:
+
+1. **Primitives** — Frame encoding/decoding, streaming TransformStreams
+2. **Server** — Hono-style `Mllp` class with middleware, pattern-based routing, and unified processor integration
+
+**Key characteristics:**
+
+- **Hono-style API** — `.use()` middleware, `.on()` pattern routing, fluent chaining
+- **Unified integration** — pass a unified processor directly to `.use()`
+- **Web Streams** — built on `ReadableStream`/`WritableStream` throughout
+- **Dual API** — simple functions for one-shot operations + streaming for TCP
+
+## Installation
+
+```bash
+pnpm add @glion/mllp
+```
+
+### Package Exports
+
+| Subpath            | Description                        |
+| ------------------ | ---------------------------------- |
+| `@glion/mllp`      | Core `Mllp` class and primitives   |
+| `@glion/mllp/node` | `serve()` function for Node.js/Bun |
+
+## Glion CLI — dev and start
+
+The `glion` CLI provides a zero-config development server with live reload and a production-ready start command.
+
+### Quick Start (Zero-Config)
+
+Create a single entry file and run:
+
+```bash
+cat > glion.app.ts <<'EOF'
+import { Mllp } from "@glion/mllp";
+import { parseHL7v2 } from "@glion/hl7v2";
+export default new Mllp().parser(parseHL7v2);
+EOF
+
+pnpm add -D @glion/mllp @glion/hl7v2
+pnpm glion dev
+```
+
+The server starts on port `2575` listening on all interfaces. The TUI shows a `zero-config` badge to indicate no config file was loaded.
+
+### With an Explicit Config File
+
+For more control, create a `glion.config.ts`:
+
+```typescript
+// glion.config.ts
+import { defineConfig } from "@glion/mllp/config";
+
+export default defineConfig({
+  entry: "./src/app.ts",
+  port: 2575,
+  hostname: "0.0.0.0",
+  // tls: { cert: "./certs/server.pem", key: "./certs/server.key" },
+  // watch: ["./src"],
+  // gracefulCloseMs: 5000,
+});
+```
+
+```typescript
+// src/app.ts
+import { Mllp } from "@glion/mllp";
+import { parseHL7v2 } from "@glion/hl7v2";
+
+export default new Mllp()
+  .parser(parseHL7v2)
+  .on("ADT^A01", async (ctx) => ({ raw: buildAck(ctx) }))
+  .on("ORU^R01", async (ctx) => ({ raw: buildAck(ctx) }))
+  .on("*", async (ctx) => ({ raw: buildNak(ctx, "Unsupported") }));
+```
+
+```json
+// package.json
+{
+  "scripts": {
+    "dev": "glion dev",
+    "start": "glion start"
+  }
+}
+```
+
+### Two Verbs
+
+**`glion dev`** — Development mode with a live Ink TUI, file watcher, and cold restarts on save:
+
+- Shows request/response counts, uptime, and error summaries in the TUI
+- Watches the entry file (and configured paths) for changes
+- Cold-restarts the server on save (~100–300ms interruption in-flight TCP sessions)
+- Falls back to log-only mode when stdout is not a TTY (CI, piped output)
+
+**`glion start`** — Production mode with no TUI and graceful shutdown:
+
+- Runs without a watcher
+- Emits JSON-line events to stdout for log aggregators
+- Handles SIGTERM with graceful drain (configurable via `gracefulCloseMs`, default 5000ms)
+- No in-flight connection interruption — existing TCP sessions complete before exit
+
+### Cross-Runtime Usage
+
+The glion bin ships with `#!/usr/bin/env node` — the standard for Node.js. Bun and Deno require explicit opt-in because they default to honoring the Node shebang.
+
+| Runtime        | Invocation                                                               |
+| -------------- | ------------------------------------------------------------------------ |
+| Node (default) | `pnpm dev` or `npm run dev` or `npx glion dev`                           |
+| Bun            | `bun --bun run dev` (from package.json script) or `bunx --bun glion dev` |
+| Deno           | `deno task dev` with a `deno.json` task that runs the compiled bin       |
+
+### Zero-Config Fallback
+
+If no `glion.config.*` file is found, glion looks for a conventional entry file in this order:
+
+1. `glion.app.ts`
+2. `glion.app.mts`
+3. `glion.app.mjs`
+4. `glion.app.js`
+5. `src/glion.app.ts`
+6. `src/glion.app.js`
+
+When found, it starts with sensible defaults: port `2575`, hostname `0.0.0.0`, no TLS, and watches `dirname(entry)`. The TUI header shows a `zero-config` badge to make this discoverable.
+
+### Programmatic API
+
+To embed glion in another tool, use the `runGlion` function:
+
+```typescript
+import { runGlion } from "@glion/mllp/cli";
+import { defineConfig, type GlionConfig } from "@glion/mllp/config";
+
+const exitCode = await runGlion({
+  argv: ["dev"],
+  cwd: process.cwd(),
+});
+```
+
+## Server
+
+### Quick Start
+
+```typescript
+import { Mllp } from "@glion/mllp";
+import { parseHL7v2 } from "@glion/hl7v2";
+import { serve } from "@glion/mllp/node";
+
+const app = new Mllp().parser(parseHL7v2);
+
+// Route by message type
+app.on("ADT^A01", async (ctx) => {
+  // Handle patient admission
+  return { raw: buildAckFor(ctx) };
+});
+
+app.on("ORU^R01", async (ctx) => {
+  // Handle lab results
+  return { raw: buildAckFor(ctx) };
+});
+
+app.on("*", async (ctx) => {
+  return { raw: buildNakFor(ctx, "Unsupported message type") };
+});
+
+const server = serve(app, { port: 2575 });
+```
+
+### Unified Processor Integration
+
+Pass a unified processor directly to `.parser()` — the server runs `parse()` eagerly for routing, then `run()` and `stringify()` lazily when handlers access `ctx.tree()` or `ctx.result()`:
+
+```typescript
+import { Mllp } from "@glion/mllp";
+import { serve } from "@glion/mllp/node";
+import { parseHL7v2 } from "@glion/hl7v2";
+
+const app = new Mllp().parser(parseHL7v2);
+
+app.on("ADT^A01", async (ctx) => {
+  const tree = await ctx.tree(); // transformed AST (escape decoding, annotations, lint)
+  const result = await ctx.result(); // compiled output (e.g., JSON from hl7v2Jsonify)
+  console.log(ctx.file.messages); // lint warnings
+  return { raw: "..." };
+});
+
+const server = serve(app, { port: 2575 });
+```
+
+### Routing Patterns
+
+```typescript
+app.on("ADT^A01", handler); // Exact match
+app.on("ADT^*", handler); // Any ADT trigger event
+app.on("*^A01", handler); // Any message type with A01
+app.on("ADT", handler); // Any ADT (same as ADT^*)
+app.on("*", handler); // Catch-all
+```
+
+Routes are matched **first-match-wins** — register specific routes before catch-alls.
+
+### Middleware
+
+Middleware follows the Hono/Koa onion model:
+
+```typescript
+// Global middleware — runs for all messages
+app.use(async (ctx, next) => {
+  const start = Date.now();
+  await next();
+  console.log(`Processed in ${Date.now() - start}ms`);
+});
+
+// Scoped middleware — only for matching messages
+app.use("ADT^*", async (ctx, next) => {
+  ctx.set("isAdmission", true);
+  await next();
+});
+```
+
+Middleware can short-circuit by returning a response without calling `next()`:
+
+```typescript
+app.use(async (ctx) => {
+  if (!isAuthorized(ctx.connection.remoteAddress)) {
+    return { raw: buildNakFor(ctx, "Unauthorized") };
+  }
+});
+```
+
+### Context
+
+The `Context` object is available in all middleware and handlers. The pipeline is **lazy** — only the parse step runs eagerly. Transforms and compilation are deferred until accessed.
+
+#### Sync properties (always available, zero cost)
+
+| Property               | Description                                            |
+| ---------------------- | ------------------------------------------------------ |
+| `ctx.req.raw`          | Original HL7v2 message string                          |
+| `ctx.req.bytes`        | Raw bytes from the MLLP frame                          |
+| `ctx.connection`       | `{ remoteAddress, remotePort, localPort, secure }`     |
+| `ctx.messageType`      | MSH-9.1 (e.g., `"ADT"`)                                |
+| `ctx.triggerEvent`     | MSH-9.2 (e.g., `"A01"`)                                |
+| `ctx.messageStructure` | MSH-9.3 (e.g., `"ADT_A01"`)                            |
+| `ctx.version`          | MSH-12 (e.g., `"2.5.1"`)                               |
+| `ctx.controlId`        | MSH-10 message control ID                              |
+| `ctx.ast`              | Raw parsed AST — pre-transform, straight from the wire |
+| `ctx.file`             | VFile (diagnostics accumulate after `tree()`)          |
+| `ctx.set(key, value)`  | Store a variable                                       |
+| `ctx.get(key)`         | Retrieve a variable                                    |
+| `ctx.var`              | Read-only snapshot of all variables                    |
+
+#### Async methods (lazy, trigger pipeline stages on first call)
+
+| Method               | Triggers                | Description                                          |
+| -------------------- | ----------------------- | ---------------------------------------------------- |
+| `await ctx.tree()`   | `run()` (transform)     | Transformed AST — escape decoding, annotations, lint |
+| `await ctx.result()` | `run()` + `stringify()` | Compiled output (e.g., JSON from hl7v2Jsonify)       |
+
+Both are cached — subsequent calls return the same value instantly.
+
+### `ctx.ast` vs `await ctx.tree()` — Choosing the Right One
+
+**Use `ctx.ast`** when you only need the raw message structure:
+
+- Reading MSH fields (message type, version, control ID)
+- Building ACK/NAK responses
+- Route filter functions
+- Middleware that doesn't need escape-decoded values
+
+```typescript
+// Fast — no pipeline cost
+app.use((ctx, next) => {
+  console.log(`Received ${ctx.messageType}^${ctx.triggerEvent}`);
+  return next();
+});
+```
+
+**Use `await ctx.tree()`** when you need the fully processed tree:
+
+- Business logic that reads decoded field values
+- Handlers that inspect annotations or resolved message structures
+- Any operation that depends on transformer output
+
+```typescript
+// Triggers transform pipeline on first call
+app.on("ADT^A01", async (ctx) => {
+  const tree = await ctx.tree();
+  // tree has escape sequences decoded, message structure resolved, etc.
+  return { raw: "..." };
+});
+```
+
+**Use `await ctx.result()`** when you need the compiled output:
+
+```typescript
+app.on("ORU^R01", async (ctx) => {
+  const json = await ctx.result(); // triggers transform + compile
+  // json is the Hl7v2JsonResult from hl7v2Jsonify
+  await saveToDatabase(json);
+  return { raw: "..." };
+});
+```
+
+### Writing Middleware — Best Practices
+
+**Prefer `ctx.ast` over `await ctx.tree()` in middleware.** Most middleware only needs routing fields or raw MSH data — both available synchronously from `ctx.ast`. This keeps the middleware fast and avoids triggering the transform pipeline unnecessarily.
+
+```typescript
+// ✅ Good — sync, fast, no pipeline cost
+function authMiddleware(): Middleware {
+  return (ctx, next) => {
+    if (!isAuthorized(ctx.connection.remoteAddress)) {
+      return { raw: buildNak(ctx.ast, "Unauthorized") };
+    }
+    return next();
+  };
+}
+
+// ✅ Good — ACK middleware uses ctx.ast (pre-transform tree)
+// The acknowledge() function only reads MSH fields
+function ackMiddleware(): Middleware {
+  return async (ctx, next) => {
+    await next();
+    ctx.res = { raw: toHl7v2(acknowledge(ctx.ast)) };
+  };
+}
+
+// ⚠️ Only when needed — triggers transform pipeline
+function validationMiddleware(): Middleware {
+  return async (ctx, next) => {
+    const tree = await ctx.tree();
+    // tree has escape sequences decoded — needed for value validation
+    if (!isValid(tree)) {
+      return { raw: buildNak(ctx.ast, "Invalid") };
+    }
+    return next();
+  };
+}
+```
+
+### Error Handling
+
+```typescript
+app.onError(async (err, ctx) => {
+  console.error(`Error processing ${ctx.controlId}:`, err.message);
+  return { raw: buildNakFor(ctx, err.message) };
+});
+```
+
+Without an error handler, errors are absorbed and no response is sent. The sending system will time out and retry per standard MLLP behavior. See the [FAQ](#faq) for the rationale behind this design.
+
+### TLS
+
+TLS is supported via `serve()` options:
+
+```typescript
+import fs from "node:fs";
+import { Mllp } from "@glion/mllp";
+import { parseHL7v2 } from "@glion/hl7v2";
+import { serve } from "@glion/mllp/node";
+
+const app = new Mllp().parser(parseHL7v2);
+
+const server = serve(app, {
+  port: 2575,
+  tls: {
+    cert: fs.readFileSync("cert.pem"),
+    key: fs.readFileSync("key.pem"),
+  },
+});
+```
+
+## Primitives
+
+### Simple API
+
+```typescript
+import { encode, decode, encodeMultiple } from "@glion/mllp";
+
+const mllpFrame = encode(hl7Message);
+const decoded = decode(mllpFrame);
+console.log(decoded.text);
+
+const frames = encodeMultiple(["MSH|1", "MSH|2"]);
+```
+
+### Streaming API
+
+```typescript
+import { createDecoderStream } from "@glion/mllp";
+
+const decoder = createDecoderStream({
+  maxMessageSize: 1024 * 1024,
+  onError: (error) => console.warn(`[${error.code}] ${error.message}`),
+});
+
+tcpSocket.readable.pipeThrough(decoder).pipeTo(
+  new WritableStream({
+    write(message) {
+      console.log("Received:", message.text);
+    },
+  })
+);
+```
+
+## API Reference
+
+### Server
+
+| Export                               | Description                      |
+| ------------------------------------ | -------------------------------- |
+| `Mllp`                               | Hono-style MLLP server class     |
+| `serve()` (from `/node`)             | Start a Node.js/Bun TCP server   |
+| `parsePattern(pattern)`              | Parse a route pattern string     |
+| `matchPattern(pattern, type, event)` | Test a pattern against a message |
+
+### Types
+
+| Type               | Description                                                        |
+| ------------------ | ------------------------------------------------------------------ |
+| `Context`          | Request context with message data and routing fields               |
+| `Response`         | Response object `{ raw: string }`                                  |
+| `Hl7v2Processor`   | Unified `Processor` type for HL7v2 (`Processor<Root, Root, Root>`) |
+| `Middleware`       | Middleware function `(ctx, next) => ...`                           |
+| `Handler`          | Terminal route handler `(ctx) => Response`                         |
+| `ErrorHandler`     | Error handler `(err, ctx) => Response`                             |
+| `RouteFilter`      | Filter function `(ctx) => boolean` for routing                     |
+| `MiddlewareReturn` | Return type of middleware functions                                |
+| `ConnectionInfo`   | Connection metadata                                                |
+| `RoutePattern`     | Parsed route pattern                                               |
+
+### Primitives
+
+| Function                        | Description                       |
+| ------------------------------- | --------------------------------- |
+| `encode(message)`               | Encode a message to an MLLP frame |
+| `decode(frame)`                 | Decode a single MLLP frame        |
+| `encodeMultiple(messages)`      | Encode multiple messages          |
+| `createDecoderStream(options?)` | Streaming decoder TransformStream |
+
+## FAQ
+
+### Why doesn't the server return an error response by default?
+
+HTTP servers like [Hono](https://hono.dev) return a generic `500 Internal Server Error` when a handler throws. This works because HTTP has a universal error response format that every client understands.
+
+HL7v2 has no such universal format. An ACK/NAK message is version-dependent, varies by message type, and requires knowledge of the original MSH segment to construct correctly. Building ACK generation into the core would couple the routing engine to HL7v2 message construction — the wrong layer of abstraction.
+
+Instead, the `Mllp` class follows a **middleware-first** design:
+
+- **Default behavior**: No response is sent. The sending system times out and retries, which is valid and expected in MLLP.
+- **Logging**: Add a logger middleware to make errors observable.
+- **ACK/NAK**: Add an acknowledgment middleware to translate errors into proper NAK responses.
+- **Custom error handling**: Use `app.onError()` for application-specific error responses.
+
+```typescript
+const app = new Mllp().parser(parseHL7v2);
+
+// Compose the behavior you need
+app.use(logger()); // observability — provided by middleware
+app.use(ackMiddleware()); // error → NAK translation — @glion/mllp-ack
+
+app.on("ADT^A01", handler);
+```
+
+This keeps the core engine simple and protocol-agnostic, while middleware handles the HL7v2-specific concerns.
+
+### Why is there no built-in logging?
+
+Same philosophy as Hono — the core has zero `console.log` or `console.error` calls. Logging is an opt-in middleware concern. This gives you full control over log format, destination, and verbosity without the core making assumptions about your observability stack.
+
+## Requirements
+
+- Node.js 18+ or Bun
+- ESM only
+
+## License
+
+MIT

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Options for constructing an MllpError.
+ */
+export interface MllpErrorOptions extends ErrorOptions {
+    /** Error condition string (e.g., for ERR segment in ACK) */
+    errorCondition?: string;
+}
+/**
+ * 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).
+ */
+export declare class MllpError extends Error {
+    /** Machine-readable error code identifying the error type */
+    readonly code: string;
+    /** Error condition string (e.g., for ERR segment in ACK) */
+    readonly errorCondition?: string;
+    constructor(code: string, message: string, options?: MllpErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;gBAErB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB;CAMtE"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { createDecoderStream, decode, encode, encodeMultiple, TransportError, ErrorCode, MLLP_END_BYTE_1, MLLP_END_BYTE_2, MLLP_HEADER, MLLP_START_BYTE, MLLP_TRAILER, MLLPDecoderStream, } from "./transport";
+export type { DecodedMessage, DecoderOptions, EncoderInput, EncoderOptions, } from "./transport";
+export { MllpError } from "./errors";
+export type { MllpErrorOptions } from "./errors";
+export { getMessageInfo, Mllp } from "./server/mllp";
+export type { MessageInfo } from "./server/mllp";
+export type { ConnectionInfo, Context, ErrorHandler, Handler, Hl7v2Processor, Middleware, MiddlewareReturn, Response, RouteFilter, RoutePattern, } from "./server/types";
+export { matchPattern, parsePattern } from "./server/types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,mBAAmB,EACnB,MAAM,EACN,MAAM,EACN,cAAc,EACd,cAAc,EACd,SAAS,EACT,eAAe,EACf,eAAe,EACf,WAAW,EACX,eAAe,EACf,YAAY,EACZ,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,cAAc,EACd,cAAc,EACd,YAAY,EACZ,cAAc,GACf,MAAM,aAAa,CAAC;AAKrB,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAKjD,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACrD,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,YAAY,EACV,cAAc,EACd,OAAO,EACP,YAAY,EACZ,OAAO,EACP,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,38 @@
+import { a as encode, c as createDecoderStream, d as MllpError, f as MLLP_END_BYTE_1, g as MLLP_TRAILER, h as MLLP_START_BYTE, i as parsePattern, l as TransportErrorCode, m as MLLP_HEADER, n as getMessageInfo, o as encodeMultiple, p as MLLP_END_BYTE_2, r as matchPattern, s as MLLPDecoderStream, t as Mllp, u as TransportError } from "./mllp.js";
+//#region src/transport/decoder.ts
+/**
+* Decode a single MLLP frame (VT ... FS CR) into a message.
+*
+* Validates framing, strips the envelope, and returns the payload as
+* both raw bytes and decoded text. Throws {@link TransportError} on
+* any structural issue.
+*
+* For streaming / chunked TCP data, use {@link createDecoderStream} instead.
+*
+* @throws TransportError with `INVALID_START_BYTE` if byte 0 is not 0x0B
+* @throws TransportError with `INVALID_END_SEQUENCE` if frame doesn't end with
+*   0x1C 0x0D
+* @throws TransportError with `MESSAGE_TOO_LARGE` if payload exceeds
+*   `maxMessageSize`
+*/
+function decode(frame, options) {
+	if (frame.length < 3) throw new TransportError(TransportErrorCode.INVALID_END_SEQUENCE, "Frame too short to contain valid MLLP structure", 0);
+	const startByte = frame[0];
+	if (startByte !== 11) throw new TransportError(TransportErrorCode.INVALID_START_BYTE, `Invalid start byte: expected 0x0B, got 0x${(startByte ?? 0).toString(16).padStart(2, "0")}`, 0);
+	const len = frame.length;
+	const endByte1 = frame[len - 2];
+	const endByte2 = frame[len - 1];
+	if (endByte1 !== 28 || endByte2 !== 13) throw new TransportError(TransportErrorCode.INVALID_END_SEQUENCE, `Invalid end sequence: expected 0x1C 0x0D, got 0x${(endByte1 ?? 0).toString(16).padStart(2, "0")} 0x${(endByte2 ?? 0).toString(16).padStart(2, "0")}`, len - 2);
+	const messageLength = len - 3;
+	if (options?.maxMessageSize !== void 0 && messageLength > options.maxMessageSize) throw new TransportError(TransportErrorCode.MESSAGE_TOO_LARGE, `Message size ${messageLength} exceeds maximum ${options.maxMessageSize}`, 0);
+	const data = frame.subarray(1, len - 2);
+	return {
+		byteLength: messageLength,
+		data,
+		text: new TextDecoder(options?.encoding ?? "utf8").decode(data)
+	};
+}
+//#endregion
+export { TransportErrorCode as ErrorCode, MLLPDecoderStream, MLLP_END_BYTE_1, MLLP_END_BYTE_2, MLLP_HEADER, MLLP_START_BYTE, MLLP_TRAILER, Mllp, MllpError, TransportError, createDecoderStream, decode, encode, encodeMultiple, getMessageInfo, matchPattern, parsePattern };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/transport/decoder.ts"],"sourcesContent":["import { MLLP_END_BYTE_1, MLLP_END_BYTE_2, MLLP_START_BYTE } from \"./constants\";\nimport { TransportError } from \"./errors\";\nimport type { DecodedMessage, DecoderOptions } from \"./types\";\nimport { TransportErrorCode } from \"./types\";\n\n/**\n * Decode a single MLLP frame (VT ... FS CR) into a message.\n *\n * Validates framing, strips the envelope, and returns the payload as\n * both raw bytes and decoded text. Throws {@link TransportError} on\n * any structural issue.\n *\n * For streaming / chunked TCP data, use {@link createDecoderStream} instead.\n *\n * @throws TransportError with `INVALID_START_BYTE` if byte 0 is not 0x0B\n * @throws TransportError with `INVALID_END_SEQUENCE` if frame doesn't end with\n *   0x1C 0x0D\n * @throws TransportError with `MESSAGE_TOO_LARGE` if payload exceeds\n *   `maxMessageSize`\n */\nexport function decode(\n  frame: Uint8Array,\n  options?: DecoderOptions\n): DecodedMessage {\n  if (frame.length < 3) {\n    throw new TransportError(\n      TransportErrorCode.INVALID_END_SEQUENCE,\n      \"Frame too short to contain valid MLLP structure\",\n      0\n    );\n  }\n\n  const startByte = frame[0];\n  if (startByte !== MLLP_START_BYTE) {\n    throw new TransportError(\n      TransportErrorCode.INVALID_START_BYTE,\n      `Invalid start byte: expected 0x0B, got 0x${(startByte ?? 0).toString(16).padStart(2, \"0\")}`,\n      0\n    );\n  }\n\n  const len = frame.length;\n  const endByte1 = frame[len - 2];\n  const endByte2 = frame[len - 1];\n  if (endByte1 !== MLLP_END_BYTE_1 || endByte2 !== MLLP_END_BYTE_2) {\n    throw new TransportError(\n      TransportErrorCode.INVALID_END_SEQUENCE,\n      `Invalid end sequence: expected 0x1C 0x0D, got 0x${(endByte1 ?? 0).toString(16).padStart(2, \"0\")} 0x${(endByte2 ?? 0).toString(16).padStart(2, \"0\")}`,\n      len - 2\n    );\n  }\n\n  const messageLength = len - 3;\n  if (\n    options?.maxMessageSize !== undefined &&\n    messageLength > options.maxMessageSize\n  ) {\n    throw new TransportError(\n      TransportErrorCode.MESSAGE_TOO_LARGE,\n      `Message size ${messageLength} exceeds maximum ${options.maxMessageSize}`,\n      0\n    );\n  }\n\n  const data = frame.subarray(1, len - 2);\n  const text = new TextDecoder(options?.encoding ?? \"utf8\").decode(data);\n\n  return {\n    byteLength: messageLength,\n    data,\n    text,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAoBA,SAAgB,OACd,OACA,SACgB;AAChB,KAAI,MAAM,SAAS,EACjB,OAAM,IAAI,eACR,mBAAmB,sBACnB,mDACA,EACD;CAGH,MAAM,YAAY,MAAM;AACxB,KAAI,cAAA,GACF,OAAM,IAAI,eACR,mBAAmB,oBACnB,6CAA6C,aAAa,GAAG,SAAS,GAAG,CAAC,SAAS,GAAG,IAAI,IAC1F,EACD;CAGH,MAAM,MAAM,MAAM;CAClB,MAAM,WAAW,MAAM,MAAM;CAC7B,MAAM,WAAW,MAAM,MAAM;AAC7B,KAAI,aAAA,MAAgC,aAAA,GAClC,OAAM,IAAI,eACR,mBAAmB,sBACnB,oDAAoD,YAAY,GAAG,SAAS,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,MAAM,YAAY,GAAG,SAAS,GAAG,CAAC,SAAS,GAAG,IAAI,IACnJ,MAAM,EACP;CAGH,MAAM,gBAAgB,MAAM;AAC5B,KACE,SAAS,mBAAmB,KAAA,KAC5B,gBAAgB,QAAQ,eAExB,OAAM,IAAI,eACR,mBAAmB,mBACnB,gBAAgB,cAAc,mBAAmB,QAAQ,kBACzD,EACD;CAGH,MAAM,OAAO,MAAM,SAAS,GAAG,MAAM,EAAE;AAGvC,QAAO;EACL,YAAY;EACZ;EACA,MALW,IAAI,YAAY,SAAS,YAAY,OAAO,CAAC,OAAO,KAAK;EAMrE"}