Class: Segment

Wrapper over a RawSegment exposing typed per-position Field instances. seg.field(3) === seg.field(3): referential stability is guaranteed per segment instance.

Example

import { parseHL7 } from "@cosyte/hl7";
const msg = parseHL7(raw);
const pid = msg.segments("PID")[0];
if (pid !== undefined) console.log(pid.field(5).value);

Constructors

Constructor

new Segment(raw, enc, absoluteIndex, customFields?): Segment

Internal

Construct a new Segment. Called internally by Hl7Message; user code should obtain Segment instances via msg.segments(type) or msg.allSegments().

The optional customFields parameter is the per-segment portion of the applied profile's merged customSegments map (PROF-07 / D-16). When supplied, get(name) resolves names against it; otherwise get(name) always returns undefined.

Parameters

raw

RawSegment

enc

EncodingCharacters

absoluteIndex

number

customFields?

Readonly<Record<string, number>>

Returns

Segment

Properties

absoluteIndex

readonly absoluteIndex: number

Internal

Absolute index of this segment in Hl7Message.rawSegments[]. Used for position tracking.

---

customFields

readonly customFields: Readonly<Record<string, number>> | undefined

Internal

Lookup map from profile-declared field name → 1-indexed HL7 position. Absent when no profile was applied to the parent message, or when the applied profile does not declare customSegments for this segment's type. Consumed by get(name) to resolve named-field access (PROF-07).

---

enc

readonly enc: EncodingCharacters

Internal

The 5 encoding characters for this message. Exposed for composite parsers.

---

fields

readonly fields: readonly RawField[]

Reference to the underlying RawSegment.fields: 1-indexed per HL7 convention.

---

raw

readonly raw: RawSegment

Internal

The full RawSegment this wrapper wraps. Exposed for mutation methods.

---

type

readonly type: string

Segment identifier: three characters with a leading letter, e.g. "PID", "OBX", "ZPI".

Bounded, and it is "<withheld>" when the raw name is not that shape. A line with no field separator has its whole content read as a segment name, so an unescaped line break inside a narrative field forges a "segment" whose name is clinical text. This field presents itself as a structural identifier and consumers interpolate it into labels, loci and reports, so it never carries that text. "" still means absent, which is a different fact from withheld.

Use Segment.raw.name when you need the verbatim text: it is the unbounded value, and it is what serialization emits, so the byte-verbatim round-trip is unaffected. One consequence worth knowing: a segment whose raw name fails the shape (a 4-character vendor Z-segment, which HL7 v2 Ch. 2 §2.5 does not permit) is not matched by msg.segments(name).

Methods

field()

field(n): Field

Return the Field wrapper at HL7 position n. Indexing follows the HL7 1-indexed convention: seg.field(5) on a PID segment maps to PID-5. MSH segments use the same user-facing convention: msh.field(1) returns the field-separator (MSH-1), msh.field(2) returns encoding chars (MSH-2), msh.field(3) returns MSH-3, and so on: the internal fields[N-1] offset for MSH segments is applied here (mirrors the dot-path resolver in dot-path.ts, keeping msg.segments('MSH')[0].field(3) and msg.get('MSH.3') in agreement).

Returns a synthetic empty Field (.isNull === false, .value === "") when n is out of range: never throws (MODEL-05). Successive calls with the same n return the same Field instance (D-12).

Parameters

n

number

Returns

Field

Example

const pid5 = msg.segments("PID")[0]?.field(5);
console.log(pid5?.value); // "Smith"
const msh3 = msg.segments("MSH")[0]?.field(3);
console.log(msh3?.value); // sending application (HL7 MSH-3)

---

get()

get(name): Field | undefined

Return the Field at the profile-declared position for name, or undefined when no custom mapping exists (PROF-07). Unlike field(n), missing names return undefined, NOT a synthetic empty Field, so typos surface instead of silently resolving to an empty string (D-14).

For segments without a profile-declared customSegments slice (most non-Z segments, and any Z-segment whose host message had no profile applied), this method always returns undefined (D-15 defense-in-depth : D-05 already rejects standard-segment overlays at defineProfile() time).

When the declared position is out of range for the underlying RawSegment.fields, get(name) returns undefined (NOT a synthetic-empty Field) so callers can distinguish "name not declared" from "name declared but position missing in the raw message" only at the presence level (both collapse to undefined per D-14).

Parameters

name

string

Returns

Field | undefined

Example

const zpi = msg.allSegments().find((s) => s.type === "ZPI");
console.log(zpi?.get("encounterId")?.value);