@cosyte/astm 0.0.3 → 0.0.4

package/dist/index.mjs

@@ -175,6 +175,28 @@ var WARNING_CODES = {
    * this warning flags the anomaly. Positional context only; no field value.
    */
   ASTM_RECORD_AMBIGUOUS_MESSAGE_KIND: "ASTM_RECORD_AMBIGUOUS_MESSAGE_KIND",
+  /**
+   * A later `H` (header) record declared a **different** delimiter set from the one in force, and the
+   * parser **followed it**: that header and every record after it are read with the newly-declared
+   * delimiters, until the next `H`. Records already read keep the set that was in force when they were
+   * read — a redeclaration never reinterprets bytes that have already been consumed.
+   *
+   * A stream carrying several messages back to back is ordinary, and a header that simply **repeats**
+   * the delimiters already in force is a no-op that warns nothing. This code fires only when the set
+   * actually changes, because that is the point at which a reader still using the old set would begin
+   * merging fields together.
+   */
+  ASTM_RECORD_DELIMITERS_REDECLARED: "ASTM_RECORD_DELIMITERS_REDECLARED",
+  /**
+   * A later `H` (header) record could not declare a usable delimiter set — it was too short, or the
+   * field separator it named also appeared among the other three, leaving the four roles
+   * indistinguishable. The delimiters **already in force are kept** and every record is still surfaced;
+   * a set is never guessed and no record is dropped.
+   *
+   * The same condition on the *first* header is unrecoverable and remains the
+   * `ASTM_RECORD_UNDECLARED_DELIMITERS` fatal — there is no earlier set to fall back to.
+   */
+  ASTM_RECORD_UNREADABLE_REDECLARATION: "ASTM_RECORD_UNREADABLE_REDECLARATION",
   /**
    * The downgraded form an active vendor {@link AstmProfile} produces from a deviation it *expects*
    * (see `src/profiles/`). The original warning is **never dropped**: its code moves to
@@ -201,6 +223,20 @@ function nonStandardDelimiters(position) {
     position
   };
 }
+function delimitersRedeclared(position) {
+  return {
+    code: WARNING_CODES.ASTM_RECORD_DELIMITERS_REDECLARED,
+    message: "A later header declared different delimiters \u2014 honored from that header onward; earlier records keep the set they were read with.",
+    position
+  };
+}
+function unreadableRedeclaration(position) {
+  return {
+    code: WARNING_CODES.ASTM_RECORD_UNREADABLE_REDECLARATION,
+    message: "A later header could not declare a usable delimiter set \u2014 the delimiters already in force were kept.",
+    position
+  };
+}
 function unknownEscapeSequence(position) {
   return {
     code: WARNING_CODES.ASTM_UNKNOWN_ESCAPE_SEQUENCE,
@@ -897,6 +933,17 @@ function tokenizeRecord(record, d, onUnknownEscape) {
   const rawFields = splitEscapeAware(record, d.field, d.escape);
   return rawFields.map((raw, fieldIndex) => toField(raw, d, () => onUnknownEscape?.(fieldIndex)));
 }
+function tokenizeHeader(record, d, onUnknownEscape) {
+  const defEnd = record.indexOf(d.field, 2);
+  const definition = defEnd === -1 ? record.slice(2) : record.slice(2, defEnd);
+  const head = [opaqueField(record.slice(0, Math.min(1, record.length))), opaqueField(definition)];
+  if (defEnd === -1) return head;
+  const data = tokenizeRecord(record.slice(defEnd + 1), d, (i) => onUnknownEscape?.(i + 2));
+  return [...head, ...data];
+}
+function opaqueField(raw) {
+  return { raw, components: [raw], repeats: [[raw]] };
+}
 function toField(raw, d, onUnknownEscape) {
   const rawRepeats = splitEscapeAware(raw, d.repeat, d.escape);
   const repeats = rawRepeats.map(
@@ -950,9 +997,13 @@ function parseAstmRecords(raw, options = {}) {
   if (isNonStandard(delimiters)) {
     warnings.push(nonStandardDelimiters({ recordIndex: 0, recordType: "H" }));
   }
-  const built = lines.map(
-    (line2, recordIndex) => buildRecord(line2, recordIndex, delimiters, warnings)
-  );
+  let active = delimiters;
+  const built = lines.map((line2, recordIndex) => {
+    if (recordIndex > 0 && line2.charAt(0) === "H") {
+      active = adoptRedeclaredDelimiters(line2, active, recordIndex, warnings);
+    }
+    return buildRecord(line2, recordIndex, active, warnings);
+  });
   const records = attachComments(built, warnings);
   const classification = classifyMessage(records);
   if (classification.hasQuery && classification.hasResults) {
@@ -982,6 +1033,21 @@ function resolveProfile(options) {
   if (options.profile !== void 0) return options.profile;
   return getDefaultAstmProfile();
 }
+function adoptRedeclaredDelimiters(line2, active, recordIndex, warnings) {
+  const position = { recordIndex, recordType: "H" };
+  const declared = readDelimiters(line2);
+  if (declared === void 0) {
+    warnings.push(unreadableRedeclaration(position));
+    return active;
+  }
+  if (sameDelimiters(declared, active)) return active;
+  warnings.push(delimitersRedeclared(position));
+  if (isNonStandard(declared)) warnings.push(nonStandardDelimiters(position));
+  return declared;
+}
+function sameDelimiters(a, b) {
+  return a.field === b.field && a.repeat === b.repeat && a.component === b.component && a.escape === b.escape;
+}
 function decodeBytes(bytes) {
   let out = "";
   for (const b of bytes) out += String.fromCharCode(b);
@@ -992,11 +1058,12 @@ function astmField(fields, n) {
 }
 function buildRecord(line2, recordIndex, d, warnings) {
   const rawType = line2.charAt(0);
-  const fields = tokenizeRecord(line2, d, (fieldIndex) => {
+  const onUnknownEscape = (fieldIndex) => {
     warnings.push(
       unknownEscapeSequence({ recordIndex, recordType: rawType, fieldIndex: fieldIndex + 1 })
     );
-  });
+  };
+  const fields = rawType === "H" ? tokenizeHeader(line2, d, onUnknownEscape) : tokenizeRecord(line2, d, onUnknownEscape);
   switch (rawType) {
     case "H":
       return {
@@ -1218,19 +1285,57 @@ function definedString(key, value) {
 
 // src/records/serialize.ts
 var AstmSerializeError = class extends Error {
-  /** Stable discriminant; `ASTM_EMIT_UNENCODABLE_VALUE` for a `CR`/`LF` in a value. */
+  /**
+   * Stable discriminant. `ASTM_EMIT_UNENCODABLE_VALUE` for a `CR`/`LF` in a value;
+   * `ASTM_EMIT_INVALID_DELIMITERS` for a delimiter set that cannot be emitted
+   * reversibly.
+   */
   code;
   /** 0-based ordinal of the record within the message, when known. */
   recordIndex;
   /** @internal */
-  constructor(message, recordIndex) {
+  constructor(message, recordIndex, code = "ASTM_EMIT_UNENCODABLE_VALUE") {
     super(message);
     this.name = "AstmSerializeError";
-    this.code = "ASTM_EMIT_UNENCODABLE_VALUE";
+    this.code = code;
     if (recordIndex !== void 0) this.recordIndex = recordIndex;
   }
 };
+var DELIMITER_ROLES = ["field", "repeat", "component", "escape"];
+var CONTROL_CHARACTER = /[\u0000-\u001f\u007f]/;
+function assertEmittableDelimiters(d, recordIndex) {
+  const invalid = (reason) => {
+    throw new AstmSerializeError(
+      `Cannot emit against these delimiters: ${reason}.`,
+      recordIndex,
+      "ASTM_EMIT_INVALID_DELIMITERS"
+    );
+  };
+  if (typeof d !== "object" || d === null) {
+    invalid("a delimiter set is required");
+  }
+  for (const role of DELIMITER_ROLES) {
+    const char = d[role];
+    if (typeof char !== "string" || char.length !== 1) {
+      invalid(`the ${role} delimiter must be exactly one character`);
+    }
+    if (char === "\r" || char === "\n") {
+      invalid(`the ${role} delimiter must not be a record terminator (CR/LF)`);
+    }
+  }
+  DELIMITER_ROLES.forEach((a, i) => {
+    for (const b of DELIMITER_ROLES.slice(i + 1)) {
+      if (d[a] === d[b]) {
+        invalid(`the ${a} and ${b} delimiters must not be the same character`);
+      }
+    }
+  });
+}
 function encodeComponent(leaf, d, recordIndex) {
+  assertEmittableDelimiters(d, recordIndex);
+  return encodeLeaf(leaf, d, recordIndex);
+}
+function encodeLeaf(leaf, d, recordIndex) {
   if (leaf.includes("\r") || leaf.includes("\n")) {
     throw new AstmSerializeError(
       "A value contains a record terminator (CR/LF), which cannot be escaped without breaking framing.",
@@ -1240,28 +1345,58 @@ function encodeComponent(leaf, d, recordIndex) {
   return leaf.split(d.escape).join(d.escape + "E" + d.escape).split(d.field).join(d.escape + "F" + d.escape).split(d.component).join(d.escape + "S" + d.escape).split(d.repeat).join(d.escape + "R" + d.escape);
 }
 function encodeField(repeats, d, recordIndex) {
-  return repeats.map((rep) => rep.map((c) => encodeComponent(c, d, recordIndex)).join(d.component)).join(d.repeat);
+  return repeats.map((rep) => rep.map((c) => encodeLeaf(c, d, recordIndex)).join(d.component)).join(d.repeat);
 }
 function serializeAstmRecord(record, d = CANONICAL_DELIMITERS) {
-  if (record.type === "M" || record.type === "S") return record.rawLine;
+  assertEmittableDelimiters(d, record.recordIndex);
+  return serializeRecordChecked(record, d);
+}
+function serializeRecordChecked(record, d) {
+  if (record.type === "M" || record.type === "S") return serializeVerbatimRecord(record, d);
   if (record.type === "H") return serializeHeader(record, d);
   return record.fields.map((f) => encodeField(f.repeats, d, record.recordIndex)).join(d.field);
 }
+function serializeVerbatimRecord(record, d) {
+  if (recoversVerbatim(record, d)) return record.rawLine;
+  return record.fields.map((f) => encodeField(f.repeats, d, record.recordIndex)).join(d.field);
+}
+function recoversVerbatim(record, d) {
+  return sameFieldTree(tokenizeRecord(record.rawLine, d), record.fields);
+}
+function sameFieldTree(a, b) {
+  if (a.length !== b.length) return false;
+  return a.every((fieldA, i) => {
+    const fieldB = b[i];
+    if (fieldB === void 0) return false;
+    if (fieldA.repeats.length !== fieldB.repeats.length) return false;
+    return fieldA.repeats.every((repA, r) => {
+      const repB = fieldB.repeats[r];
+      if (repB === void 0 || repA.length !== repB.length) return false;
+      return repA.every((comp, c) => comp === repB[c]);
+    });
+  });
+}
 function serializeHeader(header, d) {
-  const head = "H" + d.field + d.repeat + d.component + d.escape;
-  const src = header.delimiters;
-  const defEnd = header.rawLine.indexOf(src.field, 2);
-  if (defEnd === -1) return head;
-  const dataPortion = header.rawLine.slice(defEnd + 1);
-  const dataFields = tokenizeRecord(dataPortion, src);
+  const head = "H" + d.field + d.repeat + d.component + d.escape + declarationResidual(header, d);
+  const dataFields = header.fields.slice(2);
   const rest = dataFields.map((f) => d.field + encodeField(f.repeats, d, header.recordIndex)).join("");
   return head + rest;
 }
+function declarationResidual(header, d) {
+  const declaration = header.fields[1]?.raw ?? "";
+  const roles = d.repeat + d.component + d.escape;
+  if (!declaration.startsWith(roles)) return "";
+  const residual = declaration.slice(roles.length);
+  if (residual.includes(d.field) || CONTROL_CHARACTER.test(residual)) return "";
+  return residual;
+}
 function serializeAstmRecords(input, d = CANONICAL_DELIMITERS) {
+  assertEmittableDelimiters(d);
   const records = Array.isArray(input) ? input : input.records;
-  return records.map((r) => serializeAstmRecord(r, d) + "\r").join("");
+  return records.map((r) => serializeRecordChecked(r, d) + "\r").join("");
 }
 function serializeField(field, d = CANONICAL_DELIMITERS) {
+  assertEmittableDelimiters(d);
   return encodeField(field.repeats, d);
 }
 
@@ -1396,17 +1531,108 @@ function buildAstmMessage(input) {
   return lines.map((l) => l + "\r").join("");
 }
 
+// src/records/messages.ts
+var AMBIGUOUS_CODES = {
+  /** The stream carries more than one `H` … `L` message, so a stream-wide answer spans patients. */
+  ASTM_AMBIGUOUS_MULTI_MESSAGE: "ASTM_AMBIGUOUS_MULTI_MESSAGE",
+  /** The one message in the stream carries more than one `P`, so "the patient" is not determined. */
+  ASTM_AMBIGUOUS_MULTI_PATIENT: "ASTM_AMBIGUOUS_MULTI_PATIENT"
+};
+var AstmAmbiguousStreamError = class extends Error {
+  /** The stable discriminant — see {@link AMBIGUOUS_CODES}. */
+  code;
+  /** Where the ambiguity became visible: the second header, or the second `P`. Value-free. */
+  position;
+  /** How many `H` … `L` messages the stream carries. */
+  messageCount;
+  /** How many `P` records the message in question carries. */
+  patientCount;
+  /** @internal */
+  constructor(code, message, position, counts) {
+    super(message);
+    this.name = "AstmAmbiguousStreamError";
+    this.code = code;
+    this.position = position;
+    this.messageCount = counts.messageCount;
+    this.patientCount = counts.patientCount;
+  }
+};
+function messages(msg) {
+  const groups = [];
+  let current;
+  for (const record of msg.records) {
+    if (record.type === "H" || current === void 0) {
+      current = [];
+      groups.push(current);
+    }
+    current.push(record);
+  }
+  return Object.freeze(
+    groups.map((records, index) => {
+      const header = records.find((r) => r.type === "H") ?? msg.header;
+      const patients = records.filter((r) => r.type === "P");
+      return Object.freeze({
+        index,
+        header,
+        delimiters: header.delimiters,
+        records: Object.freeze(records),
+        patient: patients.length === 1 ? patients[0] : void 0,
+        patients: Object.freeze(patients),
+        results: Object.freeze(records.filter((r) => r.type === "R")),
+        orders: Object.freeze(records.filter((r) => r.type === "O")),
+        comments: Object.freeze(records.filter((r) => r.type === "C")),
+        queries: Object.freeze(records.filter((r) => r.type === "Q"))
+      });
+    })
+  );
+}
+function surveyMessages(msg) {
+  let count = 0;
+  let secondHeader;
+  for (const record of msg.records) {
+    if (record.type !== "H") continue;
+    count += 1;
+    if (count === 2) secondHeader = record;
+  }
+  return { count, secondHeader };
+}
+function assertSingleMessage(msg, accessor) {
+  const { count, secondHeader } = surveyMessages(msg);
+  if (count <= 1) return;
+  throw new AstmAmbiguousStreamError(
+    AMBIGUOUS_CODES.ASTM_AMBIGUOUS_MULTI_MESSAGE,
+    `${accessor} is scoped to the whole stream, and this stream carries ${String(count)} messages, so its answer would span patients. Use messages() and read each message's own records.`,
+    { recordIndex: secondHeader?.recordIndex ?? 0, recordType: "H" },
+    { messageCount: count, patientCount: 0 }
+  );
+}
+function assertSinglePatient(msg, accessor) {
+  const patients = msg.records.filter((r) => r.type === "P");
+  if (patients.length <= 1) return;
+  throw new AstmAmbiguousStreamError(
+    AMBIGUOUS_CODES.ASTM_AMBIGUOUS_MULTI_PATIENT,
+    `${accessor} cannot name one patient: this message carries ${String(patients.length)} P records. Read them from messages()[n].patients and pair each with the records it owns.`,
+    { recordIndex: patients[1]?.recordIndex ?? 0, recordType: "P" },
+    { messageCount: 1, patientCount: patients.length }
+  );
+}
+
 // src/records/extractors.ts
 function results(msg) {
+  assertSingleMessage(msg, "results()");
   return msg.records.filter((r) => r.type === "R");
 }
 function patient(msg) {
+  assertSingleMessage(msg, "patient()");
+  assertSinglePatient(msg, "patient()");
   return msg.records.find((r) => r.type === "P");
 }
 function orders(msg) {
+  assertSingleMessage(msg, "orders()");
   return msg.records.filter((r) => r.type === "O");
 }
 function comments(msg) {
+  assertSingleMessage(msg, "comments()");
   return msg.records.filter((r) => r.type === "C");
 }
 function commentsFor(msg, parent) {
@@ -1415,6 +1641,7 @@ function commentsFor(msg, parent) {
   );
 }
 function query(msg) {
+  assertSingleMessage(msg, "query()");
   return msg.records.filter((r) => r.type === "Q");
 }
 
@@ -1970,8 +2197,8 @@ function concatBytes3(chunks) {
 }
 
 // src/index.ts
-var VERSION = "0.0.3";
+var VERSION = "0.0.4";
 
-export { ALL_ASTM_WARNING_CODES, ACK as ASTM_ACK, ENQ as ASTM_ENQ, EOT as ASTM_EOT, NAK as ASTM_NAK, AstmFrameEncodeError, AstmFrameStrictError, AstmParseError, AstmProfileDefinitionError, AstmSerializeError, AstmStrictError, CANONICAL_DELIMITERS, FATAL_CODES, FRAME_WARNING_CODES, LIVD_WARNING_CODES, LTP_WARNING_CODES, SAFETY_CRITICAL_CODES, TOLERABLE_CODES, VERSION, WARNING_CODES, ambiguousMessageKind, ambiguousValueSplit, applyAstmProfile, applyAstmProfileToWarnings, applyLivd, astmDateToLocalISO, astmProfiles, attachComments, buildAstmMessage, classifyMessage, comments, commentsFor, composeAstmFrames, computeChecksum, decodeAstmFrames, decodeEscapes, deepFreeze, defineAstmProfile, defineLivdCatalog, detectFraming, encodeComponent, fieldScalar, frameBadChecksum, frameOversize, frameSequenceGap, frameUnterminated, getAstmProfile, getDefaultAstmProfile, interpretAbnormalFlag, interpretResultStatus, isNonStandard, isSafetyCriticalCode, listAstmProfiles, livdAmbiguousMapping, livdUnmappedCode, lookupLivdForRecord, ltpAmbiguousTransport, ltpFrameRejected, ltpInitialState, ltpReduce, ltpUnexpectedEvent, nonStandardDelimiters, orders, orphanComment, parseAstmDate, parseAstmRecords, parseChecksumHex, parseFramedAstm, parseReferenceRange, partialTimestamp, patient, primaryCode, profileQuirkApplied, query, readDelimiters, recognizeUniversalTestId, resolveProfileTransport, results, serializeAstmRecord, serializeAstmRecords, serializeField, serializeFramedAstm, setDefaultAstmProfile, splitEscapeAware, toChecksumHex, tokenizeRecord, undefinedAbnormalFlag, undefinedResultStatus, uninterpretedQueryStatus, unitsAbsent, unknownEscapeSequence, unknownRecordType, unparseableReferenceRange };
+export { ALL_ASTM_WARNING_CODES, AMBIGUOUS_CODES, ACK as ASTM_ACK, ENQ as ASTM_ENQ, EOT as ASTM_EOT, NAK as ASTM_NAK, AstmAmbiguousStreamError, AstmFrameEncodeError, AstmFrameStrictError, AstmParseError, AstmProfileDefinitionError, AstmSerializeError, AstmStrictError, CANONICAL_DELIMITERS, FATAL_CODES, FRAME_WARNING_CODES, LIVD_WARNING_CODES, LTP_WARNING_CODES, SAFETY_CRITICAL_CODES, TOLERABLE_CODES, VERSION, WARNING_CODES, ambiguousMessageKind, ambiguousValueSplit, applyAstmProfile, applyAstmProfileToWarnings, applyLivd, astmDateToLocalISO, astmProfiles, attachComments, buildAstmMessage, classifyMessage, comments, commentsFor, composeAstmFrames, computeChecksum, decodeAstmFrames, decodeEscapes, deepFreeze, defineAstmProfile, defineLivdCatalog, delimitersRedeclared, detectFraming, encodeComponent, fieldScalar, frameBadChecksum, frameOversize, frameSequenceGap, frameUnterminated, getAstmProfile, getDefaultAstmProfile, interpretAbnormalFlag, interpretResultStatus, isNonStandard, isSafetyCriticalCode, listAstmProfiles, livdAmbiguousMapping, livdUnmappedCode, lookupLivdForRecord, ltpAmbiguousTransport, ltpFrameRejected, ltpInitialState, ltpReduce, ltpUnexpectedEvent, messages, nonStandardDelimiters, orders, orphanComment, parseAstmDate, parseAstmRecords, parseChecksumHex, parseFramedAstm, parseReferenceRange, partialTimestamp, patient, primaryCode, profileQuirkApplied, query, readDelimiters, recognizeUniversalTestId, resolveProfileTransport, results, serializeAstmRecord, serializeAstmRecords, serializeField, serializeFramedAstm, setDefaultAstmProfile, splitEscapeAware, toChecksumHex, tokenizeHeader, tokenizeRecord, undefinedAbnormalFlag, undefinedResultStatus, uninterpretedQueryStatus, unitsAbsent, unknownEscapeSequence, unknownRecordType, unparseableReferenceRange, unreadableRedeclaration };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map