@pritiranjan/hl7v2 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,309 @@
+import { H as HL7Message, a as HL7Segment, E as EncodingChars } from './schema-qr-scwmL.cjs';
+export { D as DEFAULT_ENCODING, b as HL7Field, M as MessageType } from './schema-qr-scwmL.cjs';
+
+interface ParseOptions {
+    /**
+     * When `true`, HL7 escape sequences within field values are decoded to their
+     * plain-text equivalents (e.g. `\F\` → `|`).
+     *
+     * Defaults to `false` so that `encode(parse(raw))` is byte-identical
+     * to the original input — essential for ACK generation and message forwarding.
+     */
+    decodeEscapes?: boolean;
+}
+/**
+ * Parse an HL7 v2.x message string into a structured {@link HL7Message}.
+ *
+ * ### Supported inputs
+ * - HL7 versions 2.1 – 2.8
+ * - Line endings: `\r` (canonical), `\n`, or `\r\n` — all normalised to `\r`
+ * - Custom encoding characters (non-default separators)
+ * - Messages with blank lines (skipped silently)
+ *
+ * ### Round-trip fidelity
+ * By default (`decodeEscapes: false`), field values retain their raw HL7
+ * escape sequences, making `encode(parse(raw)) === raw` hold true.
+ * Use `decodeEscapes: true` only when you need to display or process the
+ * human-readable values and do not intend to re-encode the message.
+ *
+ * @throws {InvalidHL7Error} When the input is empty or does not start with MSH
+ * @throws {HL7ParseError}   When a segment identifier or field structure is invalid
+ *
+ * @example
+ * import { parse } from 'hl7v2';
+ *
+ * const msg = parse(rawString);
+ * console.log(msg.messageType); // { type: 'ADT', event: 'A01', structure: 'ADT_A01' }
+ * console.log(msg.version);     // '2.5.1'
+ */
+declare function parse(raw: string, options?: ParseOptions): HL7Message;
+/**
+ * Return `true` if the input looks like an HL7 v2 message.
+ * This is a fast heuristic check — it does not fully parse the message.
+ */
+declare function isHL7(input: string): boolean;
+
+interface EncodeOptions {
+    /**
+     * Line ending to use between segments.
+     * HL7 v2 canonical is `'\r'`. Some systems expect `'\r\n'` or `'\n'`.
+     * @default '\r'
+     */
+    lineEnding?: '\r' | '\n' | '\r\n';
+    /**
+     * When `true`, a trailing line ending is appended after the last segment.
+     * @default false
+     */
+    trailingNewline?: boolean;
+}
+declare function encodeSegment(seg: HL7Segment, enc: EncodingChars): string;
+/**
+ * Encode an {@link HL7Message} back into a raw HL7 v2 string.
+ *
+ * ### Round-trip guarantee
+ * When called on a message produced by `parse(raw)` with default options
+ * (i.e., `decodeEscapes` was **not** set to `true`), this function produces
+ * output that is byte-identical to the original input, modulo line endings.
+ *
+ * ### Encoding characters
+ * The message's own `encoding` field is used. Override via `options.encoding`
+ * if you need to re-encode to a different separator set (rare).
+ *
+ * @param msg     - The message to encode
+ * @param options - Optional output configuration
+ *
+ * @example
+ * import { parse, encode } from 'hl7v2';
+ *
+ * const msg   = parse(rawString);
+ * const back  = encode(msg);   // byte-identical to rawString (modulo line endings)
+ *
+ * // Modify a field and re-encode
+ * const mutable = structuredClone(msg) as HL7Message;
+ * // ... set fields ...
+ * const updated = encode(mutable);
+ */
+declare function encode(msg: HL7Message, options?: EncodeOptions): string;
+
+/**
+ * Return the first segment with the given identifier.
+ *
+ * When a message contains multiple segments with the same identifier (e.g.
+ * repeating OBX groups), pass `{ segmentIndex: N }` (1-based) to select which
+ * occurrence to return. Defaults to the first occurrence (`segmentIndex: 1`).
+ *
+ * @throws {SegmentNotFoundError} When no segment with `id` exists at the given index.
+ *
+ * @example
+ * const pid  = segment(msg, 'PID');
+ * const obx1 = segment(msg, 'OBX', { segmentIndex: 1 });  // first OBX
+ * const obx2 = segment(msg, 'OBX', { segmentIndex: 2 });  // second OBX
+ */
+declare function segment(msg: HL7Message, id: string, options?: {
+    segmentIndex?: number;
+}): HL7Segment;
+/**
+ * Return all segments with the given identifier.
+ * Returns an empty array (never throws) when none are found.
+ *
+ * Useful for repeating segments such as OBX (lab results), NTE (notes),
+ * or DG1 (diagnoses).
+ *
+ * @example
+ * const allOBX = segments(msg, 'OBX');
+ * for (const obx of allOBX) {
+ *   console.log(get(msg, obx, 5)); // OBX.5 — observation value
+ * }
+ */
+declare function segments(msg: HL7Message, id: string): HL7Segment[];
+/**
+ * Return `true` if the message contains at least one segment with the given identifier.
+ *
+ * @example
+ * if (hasSegment(msg, 'PV1')) {
+ *   const pv1 = segment(msg, 'PV1');
+ * }
+ */
+declare function hasSegment(msg: HL7Message, id: string): boolean;
+interface GetOptions {
+    /**
+     * 1-based repetition number. Defaults to `1` (first repetition).
+     *
+     * @example
+     * // PID.3 can repeat — get the second identifier
+     * get(msg, 'PID', 3, undefined, undefined, { repetition: 2 });
+     */
+    repetition?: number;
+    /**
+     * When `true`, decode HL7 escape sequences in the returned value.
+     * Defaults to `false`.
+     */
+    decode?: boolean;
+    /**
+     * 1-based index when the message contains multiple segments with the same
+     * identifier. Defaults to `1` (first occurrence).
+     *
+     * @example
+     * // Get OBX.5 from the third OBX segment
+     * get(msg, 'OBX', 5, undefined, undefined, { segmentIndex: 3 });
+     */
+    segmentIndex?: number;
+}
+/**
+ * Extract a scalar string value from a message field using 1-based HL7 addressing.
+ *
+ * Returns an empty string `''` rather than throwing when the field, component,
+ * or sub-component does not exist — reflecting HL7's rule that absent elements
+ * are equivalent to empty strings.
+ *
+ * HL7 addressing reference (1-based throughout):
+ * - `get(msg, 'PID', 3)`          → PID.3       (first component, first repetition)
+ * - `get(msg, 'PID', 5, 1)`       → PID.5.1     (family name component)
+ * - `get(msg, 'PID', 5, 2)`       → PID.5.2     (given name component)
+ * - `get(msg, 'PID', 11, 1, 1)`   → PID.11.1.1  (sub-component)
+ * - `get(msg, 'OBX', 5, 1, 1, { repetition: 2 })` → OBX.5[2].1.1 (second repetition)
+ *
+ * @param msg        - Parsed HL7 message
+ * @param segmentId  - Three-letter segment identifier (case-insensitive)
+ * @param field      - 1-based field number
+ * @param component  - 1-based component number (defaults to 1)
+ * @param subComponent - 1-based sub-component number (defaults to 1)
+ * @param options    - See {@link GetOptions}
+ *
+ * @example
+ * import { parse, get } from 'hl7v2';
+ *
+ * const msg       = parse(raw);
+ * const mrn       = get(msg, 'PID', 3);       // PID.3 — medical record number
+ * const lastName  = get(msg, 'PID', 5, 1);    // PID.5.1 — family name
+ * const firstName = get(msg, 'PID', 5, 2);    // PID.5.2 — given name
+ */
+declare function get(msg: HL7Message, segmentId: string, field: number, component?: number, subComponent?: number, options?: GetOptions): string;
+/**
+ * Extract a field value from a known segment reference (returned by {@link segment}
+ * or {@link segments}).
+ *
+ * Equivalent to {@link get} but accepts an `HL7Segment` directly — useful when
+ * iterating over repeating segments.
+ *
+ * @example
+ * for (const obx of segments(msg, 'OBX')) {
+ *   const value = getFromSegment(obx, msg, 5);  // OBX.5 for each OBX segment
+ * }
+ */
+declare function getFromSegment(seg: HL7Segment, msg: HL7Message, field: number, component?: number, subComponent?: number, options?: Omit<GetOptions, 'segmentIndex'>): string;
+/**
+ * Return all repetitions of a field as a `string[][][]` structure (one entry
+ * per repetition, preserving the `[component][subComponent]` shape).
+ *
+ * Useful for fields like PID.3 (patient identifier list) that carry multiple
+ * typed identifiers — each with its own components — across repetitions.
+ *
+ * @example
+ * const ids = getRepetitions(msg, 'PID', 3);
+ * ids[0]?.[0]?.[0]  // → first identifier value  (PID.3[1].1)
+ * ids[0]?.[3]?.[0]  // → first identifier's assigning authority (PID.3[1].4)
+ * ids[1]?.[0]?.[0]  // → second identifier value (PID.3[2].1)
+ */
+declare function getRepetitions(msg: HL7Message, segmentId: string, field: number, options?: Omit<GetOptions, 'repetition'>): string[][][];
+
+/**
+ * Decode HL7 v2 escape sequences within a field value.
+ *
+ * Handles all standard sequences defined in the HL7 v2.x specification:
+ * - `\F\`   → field separator
+ * - `\S\`   → component separator
+ * - `\T\`   → sub-component separator
+ * - `\R\`   → repetition separator
+ * - `\E\`   → escape character
+ * - `\H\`   → start highlighting (stripped — presentation concern)
+ * - `\N\`   → normal text / end highlighting (stripped)
+ * - `\.br\` → carriage return / line break → `\n`
+ * - `\Xhh…\` → hex-encoded bytes → UTF-8 string
+ *
+ * Unknown or locally-defined sequences (`\Zxxx\`) are preserved as-is.
+ *
+ * @param value - Raw field value that may contain escape sequences
+ * @param enc   - Encoding characters from the message's MSH segment
+ */
+declare function decodeEscapes(value: string, enc: EncodingChars): string;
+/**
+ * Encode a plain string value for safe inclusion in an HL7 v2 field,
+ * escaping any characters that have special meaning in the given encoding.
+ *
+ * Characters are escaped in this order to avoid double-escaping:
+ * 1. Escape character itself (`\E\`)
+ * 2. Field separator     (`\F\`)
+ * 3. Component separator (`\S\`)
+ * 4. Repetition separator(`\R\`)
+ * 5. Sub-component sep   (`\T\`)
+ *
+ * @param value - Plain string to encode
+ * @param enc   - Encoding characters from the target message
+ */
+declare function encodeEscapes(value: string, enc: EncodingChars): string;
+
+/**
+ * Parse an HL7 v2 Date/Time string into a JavaScript `Date`.
+ *
+ * Supported formats (per HL7 v2 spec section 2.8.21):
+ * - `YYYY`
+ * - `YYYYMM`
+ * - `YYYYMMDD`
+ * - `YYYYMMDDHHMM`
+ * - `YYYYMMDDHHMMSS`
+ * - `YYYYMMDDHHMMSS.S[SSS]`
+ * - Any of the above with `+HHMM` or `-HHMM` timezone offset suffix
+ *
+ * @returns A `Date` object in UTC, or `undefined` if the value is empty.
+ * @throws {HL7ParseError} If the string is non-empty but unparseable.
+ */
+declare function parseHL7DateTime(raw: string): Date | undefined;
+/**
+ * Format a JavaScript `Date` as an HL7 v2 timestamp string in UTC.
+ * Output format: `YYYYMMDDHHMMSS`
+ */
+declare function formatHL7DateTime(date: Date): string;
+/**
+ * Format a JavaScript `Date` as an HL7 v2 date-only string in UTC.
+ * Output format: `YYYYMMDD`
+ */
+declare function formatHL7Date(date: Date): string;
+
+/**
+ * Thrown when an HL7 v2 message string cannot be parsed.
+ *
+ * The `line` and `segmentId` properties help pinpoint the exact failure location
+ * when debugging multi-segment messages from production systems.
+ */
+declare class HL7ParseError extends Error {
+    /** 1-based line number in the source string where the error occurred. */
+    readonly line: number | undefined;
+    /** Segment identifier that was being parsed when the error occurred. */
+    readonly segmentId: string | undefined;
+    constructor(message: string, options?: {
+        line?: number;
+        segmentId?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a required segment is not present in the message.
+ *
+ * @example
+ * // Thrown by segment() when the segment is not found
+ * const pid = segment(msg, 'PID'); // throws if no PID segment
+ */
+declare class SegmentNotFoundError extends Error {
+    readonly segmentId: string;
+    constructor(segmentId: string);
+}
+/**
+ * Thrown when an HL7 message cannot be identified as valid HL7 v2.
+ * Usually means the input is empty, truncated, or a completely different format.
+ */
+declare class InvalidHL7Error extends Error {
+    constructor(reason: string);
+}
+
+export { type EncodeOptions, EncodingChars, type GetOptions, HL7Message, HL7ParseError, HL7Segment, InvalidHL7Error, type ParseOptions, SegmentNotFoundError, decodeEscapes, encode, encodeEscapes, encodeSegment, formatHL7Date, formatHL7DateTime, get, getFromSegment, getRepetitions, hasSegment, isHL7, parse, parseHL7DateTime, segment, segments };

package/dist/index.d.ts

@@ -0,0 +1,309 @@
+import { H as HL7Message, a as HL7Segment, E as EncodingChars } from './schema-qr-scwmL.js';
+export { D as DEFAULT_ENCODING, b as HL7Field, M as MessageType } from './schema-qr-scwmL.js';
+
+interface ParseOptions {
+    /**
+     * When `true`, HL7 escape sequences within field values are decoded to their
+     * plain-text equivalents (e.g. `\F\` → `|`).
+     *
+     * Defaults to `false` so that `encode(parse(raw))` is byte-identical
+     * to the original input — essential for ACK generation and message forwarding.
+     */
+    decodeEscapes?: boolean;
+}
+/**
+ * Parse an HL7 v2.x message string into a structured {@link HL7Message}.
+ *
+ * ### Supported inputs
+ * - HL7 versions 2.1 – 2.8
+ * - Line endings: `\r` (canonical), `\n`, or `\r\n` — all normalised to `\r`
+ * - Custom encoding characters (non-default separators)
+ * - Messages with blank lines (skipped silently)
+ *
+ * ### Round-trip fidelity
+ * By default (`decodeEscapes: false`), field values retain their raw HL7
+ * escape sequences, making `encode(parse(raw)) === raw` hold true.
+ * Use `decodeEscapes: true` only when you need to display or process the
+ * human-readable values and do not intend to re-encode the message.
+ *
+ * @throws {InvalidHL7Error} When the input is empty or does not start with MSH
+ * @throws {HL7ParseError}   When a segment identifier or field structure is invalid
+ *
+ * @example
+ * import { parse } from 'hl7v2';
+ *
+ * const msg = parse(rawString);
+ * console.log(msg.messageType); // { type: 'ADT', event: 'A01', structure: 'ADT_A01' }
+ * console.log(msg.version);     // '2.5.1'
+ */
+declare function parse(raw: string, options?: ParseOptions): HL7Message;
+/**
+ * Return `true` if the input looks like an HL7 v2 message.
+ * This is a fast heuristic check — it does not fully parse the message.
+ */
+declare function isHL7(input: string): boolean;
+
+interface EncodeOptions {
+    /**
+     * Line ending to use between segments.
+     * HL7 v2 canonical is `'\r'`. Some systems expect `'\r\n'` or `'\n'`.
+     * @default '\r'
+     */
+    lineEnding?: '\r' | '\n' | '\r\n';
+    /**
+     * When `true`, a trailing line ending is appended after the last segment.
+     * @default false
+     */
+    trailingNewline?: boolean;
+}
+declare function encodeSegment(seg: HL7Segment, enc: EncodingChars): string;
+/**
+ * Encode an {@link HL7Message} back into a raw HL7 v2 string.
+ *
+ * ### Round-trip guarantee
+ * When called on a message produced by `parse(raw)` with default options
+ * (i.e., `decodeEscapes` was **not** set to `true`), this function produces
+ * output that is byte-identical to the original input, modulo line endings.
+ *
+ * ### Encoding characters
+ * The message's own `encoding` field is used. Override via `options.encoding`
+ * if you need to re-encode to a different separator set (rare).
+ *
+ * @param msg     - The message to encode
+ * @param options - Optional output configuration
+ *
+ * @example
+ * import { parse, encode } from 'hl7v2';
+ *
+ * const msg   = parse(rawString);
+ * const back  = encode(msg);   // byte-identical to rawString (modulo line endings)
+ *
+ * // Modify a field and re-encode
+ * const mutable = structuredClone(msg) as HL7Message;
+ * // ... set fields ...
+ * const updated = encode(mutable);
+ */
+declare function encode(msg: HL7Message, options?: EncodeOptions): string;
+
+/**
+ * Return the first segment with the given identifier.
+ *
+ * When a message contains multiple segments with the same identifier (e.g.
+ * repeating OBX groups), pass `{ segmentIndex: N }` (1-based) to select which
+ * occurrence to return. Defaults to the first occurrence (`segmentIndex: 1`).
+ *
+ * @throws {SegmentNotFoundError} When no segment with `id` exists at the given index.
+ *
+ * @example
+ * const pid  = segment(msg, 'PID');
+ * const obx1 = segment(msg, 'OBX', { segmentIndex: 1 });  // first OBX
+ * const obx2 = segment(msg, 'OBX', { segmentIndex: 2 });  // second OBX
+ */
+declare function segment(msg: HL7Message, id: string, options?: {
+    segmentIndex?: number;
+}): HL7Segment;
+/**
+ * Return all segments with the given identifier.
+ * Returns an empty array (never throws) when none are found.
+ *
+ * Useful for repeating segments such as OBX (lab results), NTE (notes),
+ * or DG1 (diagnoses).
+ *
+ * @example
+ * const allOBX = segments(msg, 'OBX');
+ * for (const obx of allOBX) {
+ *   console.log(get(msg, obx, 5)); // OBX.5 — observation value
+ * }
+ */
+declare function segments(msg: HL7Message, id: string): HL7Segment[];
+/**
+ * Return `true` if the message contains at least one segment with the given identifier.
+ *
+ * @example
+ * if (hasSegment(msg, 'PV1')) {
+ *   const pv1 = segment(msg, 'PV1');
+ * }
+ */
+declare function hasSegment(msg: HL7Message, id: string): boolean;
+interface GetOptions {
+    /**
+     * 1-based repetition number. Defaults to `1` (first repetition).
+     *
+     * @example
+     * // PID.3 can repeat — get the second identifier
+     * get(msg, 'PID', 3, undefined, undefined, { repetition: 2 });
+     */
+    repetition?: number;
+    /**
+     * When `true`, decode HL7 escape sequences in the returned value.
+     * Defaults to `false`.
+     */
+    decode?: boolean;
+    /**
+     * 1-based index when the message contains multiple segments with the same
+     * identifier. Defaults to `1` (first occurrence).
+     *
+     * @example
+     * // Get OBX.5 from the third OBX segment
+     * get(msg, 'OBX', 5, undefined, undefined, { segmentIndex: 3 });
+     */
+    segmentIndex?: number;
+}
+/**
+ * Extract a scalar string value from a message field using 1-based HL7 addressing.
+ *
+ * Returns an empty string `''` rather than throwing when the field, component,
+ * or sub-component does not exist — reflecting HL7's rule that absent elements
+ * are equivalent to empty strings.
+ *
+ * HL7 addressing reference (1-based throughout):
+ * - `get(msg, 'PID', 3)`          → PID.3       (first component, first repetition)
+ * - `get(msg, 'PID', 5, 1)`       → PID.5.1     (family name component)
+ * - `get(msg, 'PID', 5, 2)`       → PID.5.2     (given name component)
+ * - `get(msg, 'PID', 11, 1, 1)`   → PID.11.1.1  (sub-component)
+ * - `get(msg, 'OBX', 5, 1, 1, { repetition: 2 })` → OBX.5[2].1.1 (second repetition)
+ *
+ * @param msg        - Parsed HL7 message
+ * @param segmentId  - Three-letter segment identifier (case-insensitive)
+ * @param field      - 1-based field number
+ * @param component  - 1-based component number (defaults to 1)
+ * @param subComponent - 1-based sub-component number (defaults to 1)
+ * @param options    - See {@link GetOptions}
+ *
+ * @example
+ * import { parse, get } from 'hl7v2';
+ *
+ * const msg       = parse(raw);
+ * const mrn       = get(msg, 'PID', 3);       // PID.3 — medical record number
+ * const lastName  = get(msg, 'PID', 5, 1);    // PID.5.1 — family name
+ * const firstName = get(msg, 'PID', 5, 2);    // PID.5.2 — given name
+ */
+declare function get(msg: HL7Message, segmentId: string, field: number, component?: number, subComponent?: number, options?: GetOptions): string;
+/**
+ * Extract a field value from a known segment reference (returned by {@link segment}
+ * or {@link segments}).
+ *
+ * Equivalent to {@link get} but accepts an `HL7Segment` directly — useful when
+ * iterating over repeating segments.
+ *
+ * @example
+ * for (const obx of segments(msg, 'OBX')) {
+ *   const value = getFromSegment(obx, msg, 5);  // OBX.5 for each OBX segment
+ * }
+ */
+declare function getFromSegment(seg: HL7Segment, msg: HL7Message, field: number, component?: number, subComponent?: number, options?: Omit<GetOptions, 'segmentIndex'>): string;
+/**
+ * Return all repetitions of a field as a `string[][][]` structure (one entry
+ * per repetition, preserving the `[component][subComponent]` shape).
+ *
+ * Useful for fields like PID.3 (patient identifier list) that carry multiple
+ * typed identifiers — each with its own components — across repetitions.
+ *
+ * @example
+ * const ids = getRepetitions(msg, 'PID', 3);
+ * ids[0]?.[0]?.[0]  // → first identifier value  (PID.3[1].1)
+ * ids[0]?.[3]?.[0]  // → first identifier's assigning authority (PID.3[1].4)
+ * ids[1]?.[0]?.[0]  // → second identifier value (PID.3[2].1)
+ */
+declare function getRepetitions(msg: HL7Message, segmentId: string, field: number, options?: Omit<GetOptions, 'repetition'>): string[][][];
+
+/**
+ * Decode HL7 v2 escape sequences within a field value.
+ *
+ * Handles all standard sequences defined in the HL7 v2.x specification:
+ * - `\F\`   → field separator
+ * - `\S\`   → component separator
+ * - `\T\`   → sub-component separator
+ * - `\R\`   → repetition separator
+ * - `\E\`   → escape character
+ * - `\H\`   → start highlighting (stripped — presentation concern)
+ * - `\N\`   → normal text / end highlighting (stripped)
+ * - `\.br\` → carriage return / line break → `\n`
+ * - `\Xhh…\` → hex-encoded bytes → UTF-8 string
+ *
+ * Unknown or locally-defined sequences (`\Zxxx\`) are preserved as-is.
+ *
+ * @param value - Raw field value that may contain escape sequences
+ * @param enc   - Encoding characters from the message's MSH segment
+ */
+declare function decodeEscapes(value: string, enc: EncodingChars): string;
+/**
+ * Encode a plain string value for safe inclusion in an HL7 v2 field,
+ * escaping any characters that have special meaning in the given encoding.
+ *
+ * Characters are escaped in this order to avoid double-escaping:
+ * 1. Escape character itself (`\E\`)
+ * 2. Field separator     (`\F\`)
+ * 3. Component separator (`\S\`)
+ * 4. Repetition separator(`\R\`)
+ * 5. Sub-component sep   (`\T\`)
+ *
+ * @param value - Plain string to encode
+ * @param enc   - Encoding characters from the target message
+ */
+declare function encodeEscapes(value: string, enc: EncodingChars): string;
+
+/**
+ * Parse an HL7 v2 Date/Time string into a JavaScript `Date`.
+ *
+ * Supported formats (per HL7 v2 spec section 2.8.21):
+ * - `YYYY`
+ * - `YYYYMM`
+ * - `YYYYMMDD`
+ * - `YYYYMMDDHHMM`
+ * - `YYYYMMDDHHMMSS`
+ * - `YYYYMMDDHHMMSS.S[SSS]`
+ * - Any of the above with `+HHMM` or `-HHMM` timezone offset suffix
+ *
+ * @returns A `Date` object in UTC, or `undefined` if the value is empty.
+ * @throws {HL7ParseError} If the string is non-empty but unparseable.
+ */
+declare function parseHL7DateTime(raw: string): Date | undefined;
+/**
+ * Format a JavaScript `Date` as an HL7 v2 timestamp string in UTC.
+ * Output format: `YYYYMMDDHHMMSS`
+ */
+declare function formatHL7DateTime(date: Date): string;
+/**
+ * Format a JavaScript `Date` as an HL7 v2 date-only string in UTC.
+ * Output format: `YYYYMMDD`
+ */
+declare function formatHL7Date(date: Date): string;
+
+/**
+ * Thrown when an HL7 v2 message string cannot be parsed.
+ *
+ * The `line` and `segmentId` properties help pinpoint the exact failure location
+ * when debugging multi-segment messages from production systems.
+ */
+declare class HL7ParseError extends Error {
+    /** 1-based line number in the source string where the error occurred. */
+    readonly line: number | undefined;
+    /** Segment identifier that was being parsed when the error occurred. */
+    readonly segmentId: string | undefined;
+    constructor(message: string, options?: {
+        line?: number;
+        segmentId?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a required segment is not present in the message.
+ *
+ * @example
+ * // Thrown by segment() when the segment is not found
+ * const pid = segment(msg, 'PID'); // throws if no PID segment
+ */
+declare class SegmentNotFoundError extends Error {
+    readonly segmentId: string;
+    constructor(segmentId: string);
+}
+/**
+ * Thrown when an HL7 message cannot be identified as valid HL7 v2.
+ * Usually means the input is empty, truncated, or a completely different format.
+ */
+declare class InvalidHL7Error extends Error {
+    constructor(reason: string);
+}
+
+export { type EncodeOptions, EncodingChars, type GetOptions, HL7Message, HL7ParseError, HL7Segment, InvalidHL7Error, type ParseOptions, SegmentNotFoundError, decodeEscapes, encode, encodeEscapes, encodeSegment, formatHL7Date, formatHL7DateTime, get, getFromSegment, getRepetitions, hasSegment, isHL7, parse, parseHL7DateTime, segment, segments };