ACK builder

Typed HL7v2 acknowledgment codes and exceptions.

What it does

@glion/ack gives you typed exceptions and constants for HL7v2 acknowledgments. Instead of comparing raw strings like "AE" or "207", you throw and catch real error classes and use named constants.

• One class per rejection code. Throw AckApplicationError for AE, AckApplicationReject for AR, AckCommitError for CE, AckCommitReject for CR.
• Named constants for the standard tables. AckCode, Hl7ErrorCode, and Severity replace magic strings, with full TypeScript types.
• Works on both sides of a connection. Throw the exceptions in a server to reject a message. Catch them in a client when a remote system rejects yours.

Install

npm install @glion/ack

Use

Reject a message from a server handler — the exception carries the acknowledgment code and error data the server renders into the matching NAK:

import { AckApplicationError, Hl7ErrorCode } from "@glion/ack";

throw new AckApplicationError("Patient 12345 not found", {
  errorCode: Hl7ErrorCode.UnknownKeyIdentifier,
});

Handle a rejection from the client — @glion/mllp-client throws the same classes when the remote system NAKs:

import { AckException } from "@glion/ack";

try {
  await client.send(message);
} catch (error) {
  if (error instanceof AckException) {
    // the remote system said no — error.code is AE, AR, CE, or CR
  }
}

API

Exception classes

new AckApplicationError(message, options); // AE
new AckApplicationReject(message, options); // AR
new AckCommitError(message, options); // CE
new AckCommitReject(message, options); // CR

All four extend AckException, which extends Error. The code property carries the MSA-1 value (AckNakCode); options is an AckExceptionOptions:

Three pre-configured subclasses cover common cases:

new ApplicationInternalError(message, cause?); // AE, code 207
new UnsupportedMessageTypeReject(message); // AR, code 200
new CommitInternalError(message, cause?); // CE, code 207

Type guards

isAckCode(value) narrows a string to AckCode (any of the six Table 0008 codes). isAckNakCode(value) narrows to AckNakCode (AE / AR / CE / CR); on an AckCode, the negative branch narrows to AckSuccessCode (AA / CA).

Constants

AckCode, Hl7ErrorCode, and Severity are const objects with the standard HL7v2 enumeration values. Each name is also the union type of its values — const code: AckCode = AckCode.ApplicationAccept.

Acknowledgment codes

HL7v2 distinguishes two levels of acknowledgment — application and commit — and each has accept, error, and reject variants. The exception class determines MSA-1 directly.

When a server renders the response, the exception's message becomes MSA-3 text. errorCode and severity stay data: the application renders them in whatever ERR shape its HL7v2 version requires.