Interface: BuildMessageInit

Input shape for buildMessage (SER-06). Mirrors msg.meta 1-for-1 so read and write surfaces share field names (sendingApp, sendingFacility, receivingApp, receivingFacility, controlId, timestamp, version, processingId). type is the only required field.

Empty string vs. undefined semantics: omitting a field and passing an empty string produce IDENTICAL wire output (both emit as an absent positional field). To emit an HL7 explicit null ("") at a specific position in an outbound message, build the message first and then call .setField(path, '""'): the mutation method sets isNull=true on the underlying RawField, and the emitter preserves that as the literal two-char output per D-02.

Example

import { buildMessage } from "@cosyte/hl7";
const msg = buildMessage({
  type: "ADT^A01",
  sendingApp: "CLINIC",
  sendingFacility: "MAIN",
  receivingApp: "LAB",
  receivingFacility: "REF",
  timestamp: new Date("2026-04-19T10:15:00Z"),
})
  .addSegment("PID", ["", "", "MRN123", "", "Doe^John"]);
console.log(msg.toString());

// To emit HL7 explicit null ("") instead of absent:
//   msg.setField("PID.2", '""');   // distinct from empty/omitted

Properties

controlId?

readonly optional controlId?: string

Auto-generated via generateControlId() when omitted (D-12).

---

processingId?

readonly optional processingId?: string

Defaults to "P" (production).

---

receivingApp?

readonly optional receivingApp?: string

---

receivingFacility?

readonly optional receivingFacility?: string

---

sendingApp?

readonly optional sendingApp?: string

---

sendingFacility?

readonly optional sendingFacility?: string

---

timestamp?

readonly optional timestamp?: string | Date

Date formatted to HL7 YYYYMMDDHHmmss (UTC, seconds) when supplied; pre-formatted HL7 TS string passed through verbatim (D-13). Defaults to new Date().

---

type

readonly type: string

HL7 message type, e.g. "ADT^A01" (code + trigger) or "ORU^R01^ORU_R01" (code + trigger + structure). Required (D-16).

The string is split on ^ into MSH-9 components; each component is emitted verbatim. Literal ^ characters in a component are NOT representable via this field: splitting is unconditional. Callers needing that edge case should build the message and then use .setField("MSH.9.1", ...) etc. after construction.

Rejected at runtime (D-16 / WR-04):

• empty string "" or whitespace-only " ";
• strings whose every ^-split component is empty/whitespace (e.g. "^", "^^", " ^ ").

---

version?

readonly optional version?: string

Defaults to "2.5".