@cosyte/astm 0.0.9 → 0.0.10

package/dist/index.d.cts

@@ -4360,12 +4360,49 @@ declare function decodeAstmFrames(bytes: Uint8Array, options?: FrameOptions): De
  *
  * A record must carry bytes: an empty record (or an empty record list) is a typed
  * {@link AstmFrameEncodeError}, never an empty frame.
+ *
+ * **A record given as a `string` is a byte string.** Each character stands for one
+ * byte, so a character above `U+00FF` has no byte to stand for and the record is
+ * refused rather than written. See {@link AstmFrameEncodeError} for what that
+ * turns away and how to frame such content instead.
+ */
+/**
+ * The reasons {@link composeAstmFrames} refuses rather than emitting bytes that
+ * are not the record it was handed.
+ *
+ * - `ASTM_FRAME_EMPTY_RECORD`: an empty record list, or a record with no bytes.
+ *   A frame must carry a record; an empty one is a structural error, never an
+ *   empty frame.
+ * - `ASTM_FRAME_UNENCODABLE_CHARACTER`: a record given as a `string` holds a
+ *   character above `U+00FF`, which has no single byte to stand for.
+ *
+ * @example
+ * ```ts
+ * import type { AstmFrameEncodeErrorCode } from "@cosyte/astm";
+ * const code: AstmFrameEncodeErrorCode = "ASTM_FRAME_UNENCODABLE_CHARACTER";
+ * ```
  */
+type AstmFrameEncodeErrorCode = "ASTM_FRAME_EMPTY_RECORD" | "ASTM_FRAME_UNENCODABLE_CHARACTER";
 /**
  * Thrown by {@link composeAstmFrames} when the input cannot be framed into a
- * spec-clean stream: an empty record list, or a record with no bytes (a frame
- * must carry a record; an empty one is a structural error, never an empty frame).
- * Carries a stable code + the offending record index, never record bytes.
+ * spec-clean stream. Carries a stable code + positional context, never the
+ * record bytes and never the offending character (PHI discipline).
+ *
+ * **The unencodable-character case, and why it is a refusal.** A record passed as
+ * a `string` is a **byte string**: character `i` becomes byte `i`, which is the
+ * exact inverse of how this package turns record bytes back into a string (one
+ * `String.fromCharCode` per byte, so every byte survives 1:1). A character above
+ * `U+00FF` has no byte to become. Turning one into bytes takes a character
+ * encoding, and nothing this package reads from an ASTM stream says which one:
+ * it reads no character-set declaration from any record, so picking one would be
+ * a guess at bytes the caller never supplied. Emit also has no warning channel,
+ * so a warning here could only be ignored while the wrong bytes still shipped.
+ *
+ * **Framing content outside Latin-1.** Encode it yourself, with the code page
+ * your instrument actually uses, and hand {@link composeAstmFrames} the
+ * `Uint8Array`: it accepts bytes directly and writes them through untouched.
+ * The refusal removes no capability, it routes you to the parameter that already
+ * carried it.
  *
  * @example
  * ```ts
@@ -4379,11 +4416,17 @@ declare function decodeAstmFrames(bytes: Uint8Array, options?: FrameOptions): De
  */
 declare class AstmFrameEncodeError extends Error {
     /** Stable discriminant. */
-    readonly code: "ASTM_FRAME_EMPTY_RECORD";
+    readonly code: AstmFrameEncodeErrorCode;
     /** Index of the offending record within the input, when applicable. */
     readonly recordIndex?: number;
+    /**
+     * Position of the offending character within that record, when applicable:
+     * its index in the string, never the character itself and never its code
+     * point. Enough to find it in the caller's own data.
+     */
+    readonly characterIndex?: number;
     /** @internal */
-    constructor(message: string, recordIndex?: number);
+    constructor(message: string, recordIndex?: number, code?: AstmFrameEncodeErrorCode, characterIndex?: number);
 }
 /** Options for {@link composeAstmFrames}. */
 interface ComposeFramesOptions {
@@ -4402,11 +4445,31 @@ interface ComposeFramesOptions {
  * across the whole stream; every frame's modulo-256 checksum is computed and
  * emitted uppercase.
  *
+ * **A record in either accepted form is written through unchanged, or refused.** A
+ * record given as a `Uint8Array` is already bytes. A record given as a `string` is
+ * a **byte string**, character `i` becoming byte `i`, the exact inverse of how a
+ * decoded record becomes a string again. A character above `U+00FF` is not a byte,
+ * so it is refused with `ASTM_FRAME_UNENCODABLE_CHARACTER` rather than replaced by
+ * a different character (it used to be truncated to its low byte, which is another
+ * ordinary character, and reached the wire silently). To frame content outside
+ * Latin-1, encode it with the character encoding your instrument uses and pass the
+ * resulting `Uint8Array`. Those two forms are the whole of what `records` accepts.
+ * A caller reaching this from JavaScript with some **other** typed array is outside
+ * the signature and gets no such refusal: each element is still written as its low
+ * byte, the same substitution described above. Pass a `Uint8Array` or a string.
+ *
+ * That covers the string-to-bytes step only. It is **not** a guarantee that any
+ * accepted record reads back: a record already carrying an `STX`, `ETX` or `ETB`
+ * byte is framed as given and re-decodes wrong, which this refusal does not touch
+ * and does not claim to.
+ *
  * @param records - The reassembled record byte-strings (`Uint8Array` or latin1
  *   `string`), one entry per complete record.
  * @param options - Encode options.
  * @returns The framed byte stream.
- * @throws {@link AstmFrameEncodeError} when the list is empty or a record has no bytes.
+ * @throws {@link AstmFrameEncodeError} when the list is empty, a record has no
+ *   bytes (`ASTM_FRAME_EMPTY_RECORD`), or a record string holds a character above
+ *   `U+00FF` (`ASTM_FRAME_UNENCODABLE_CHARACTER`).
  * @example
  * ```ts
  * import { composeAstmFrames, decodeAstmFrames } from "@cosyte/astm";
@@ -4483,11 +4546,18 @@ declare function parseFramedAstm(bytes: Uint8Array, options?: FrameOptions & Ast
  * {@link decodeAstmFrames} reassembles: `parseFramedAstm(serializeFramedAstm(msg))`
  * yields an equal message.
  *
+ * A value carrying a character above `U+00FF` is **refused** here rather than
+ * framed: the record layer is happy to hold one, but a frame carries bytes and
+ * nothing in the message says which character encoding to turn it into. A message
+ * whose every value is Latin-1 is unaffected.
+ *
  * @param input - A parsed {@link AstmMessage} or a list of {@link AstmRecord}s.
  * @param options - Frame-encode options.
  * @returns The framed byte stream.
  * @throws {@link AstmSerializeError} when a value contains an unencodable `CR`/`LF`.
- * @throws {@link AstmFrameEncodeError} when there are no records to frame.
+ * @throws {@link AstmFrameEncodeError} when there are no records to frame
+ *   (`ASTM_FRAME_EMPTY_RECORD`), or a value holds a character above `U+00FF`
+ *   (`ASTM_FRAME_UNENCODABLE_CHARACTER`).
  * @example
  * ```ts
  * import { parseAstmRecords, serializeFramedAstm, parseFramedAstm } from "@cosyte/astm";
@@ -4659,4 +4729,4 @@ declare class AstmFrameStrictError extends Error {
  */
 declare const VERSION: string;
 
-export { ALL_ASTM_WARNING_CODES, AMBIGUOUS_CODES, ACK as ASTM_ACK, ENQ as ASTM_ENQ, EOT as ASTM_EOT, NAK as ASTM_NAK, type AbnormalFlag, type AbnormalFlagCode, type AbnormalFlagMeaning, type AmbiguousCode, type AnyAstmWarningCode, AstmAmbiguousStreamError, type AstmDate, type AstmDatePrecision, type AstmField, type AstmFrame, AstmFrameEncodeError, type AstmFramePosition, AstmFrameStrictError, type AstmFrameWarning, type AstmFraming, type AstmLivdWarning, type AstmLtpWarning, type AstmMessage, type AstmMessageClassification, type AstmMessageKind, AstmParseError, type AstmParseOptions, type AstmPosition, type AstmProfile, AstmProfileDefinitionError, type AstmProfileProvenance, type AstmQuirkMatch, type AstmQuirkTolerance, type AstmRecord, type AstmRecordInput, type AstmRecordWarning, AstmSerializeError, type AstmSerializeErrorCode, type AstmStreamMessage, AstmStrictError, CANONICAL_DELIMITERS, type CommentInput, type CommentRecord, type ComposeFramesOptions, type DecodeAstmFramesResult, type DefineAstmProfileOptions, type Delimiters, type DetectFramingOptions, type DetectFramingResult, FATAL_CODES, FRAME_WARNING_CODES, type FatalCode, type FrameChecksum, type FrameOptions, type FrameTerminator, type FrameWarningCode, type FramedAstmResult, type HeaderInput, type HeaderRecord, LIVD_WARNING_CODES, LTP_WARNING_CODES, type LivdAnnotation, type LivdCatalog, type LivdEntry, type LivdLookup, type LivdMapping, type LivdResult, type LivdWarningCode, type LtpAction, type LtpEvent, type LtpPhase, type LtpState, type LtpTransition, type LtpWarningCode, type ManufacturerRecord, type MessageInput, type OrderInput, type OrderRecord, type PatientInput, type PatientName, type PatientNameInput, type PatientRecord, type QueryInput, type QueryRecord, type ReferenceRange, type ReferenceRangeKind, type ResultInput, type ResultRecord, type ResultStatus, type ResultStatusCode, type ResultStatusMeaning, SAFETY_CRITICAL_CODES, type ScientificRecord, TOLERABLE_CODES, type TerminatorRecord, type UniversalTestId, type UniversalTestIdProvenance, type UnknownEscapeSink, type UnpairedEscapeSink, type UnsupportedRecord, VERSION, type VerbatimInput, WARNING_CODES, type WarningCode, ambiguousMessageKind, ambiguousValueSplit, applyAstmProfile, applyAstmProfileToWarnings, applyLivd, astmDateToLocalISO, astmProfiles, attachComments, buildAstmMessage, classifyMessage, comments, commentsFor, composeAstmFrames, computeChecksum, decodeAstmFrames, decodeEscapes, deepFreeze, defineAstmProfile, defineLivdCatalog, delimitersRedeclared, detectFraming, encodeComponent, fieldScalar, fieldsUnseparated, 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, unpairedEscapeCharacter, unparseableReferenceRange, unreadableRedeclaration };
+export { ALL_ASTM_WARNING_CODES, AMBIGUOUS_CODES, ACK as ASTM_ACK, ENQ as ASTM_ENQ, EOT as ASTM_EOT, NAK as ASTM_NAK, type AbnormalFlag, type AbnormalFlagCode, type AbnormalFlagMeaning, type AmbiguousCode, type AnyAstmWarningCode, AstmAmbiguousStreamError, type AstmDate, type AstmDatePrecision, type AstmField, type AstmFrame, AstmFrameEncodeError, type AstmFrameEncodeErrorCode, type AstmFramePosition, AstmFrameStrictError, type AstmFrameWarning, type AstmFraming, type AstmLivdWarning, type AstmLtpWarning, type AstmMessage, type AstmMessageClassification, type AstmMessageKind, AstmParseError, type AstmParseOptions, type AstmPosition, type AstmProfile, AstmProfileDefinitionError, type AstmProfileProvenance, type AstmQuirkMatch, type AstmQuirkTolerance, type AstmRecord, type AstmRecordInput, type AstmRecordWarning, AstmSerializeError, type AstmSerializeErrorCode, type AstmStreamMessage, AstmStrictError, CANONICAL_DELIMITERS, type CommentInput, type CommentRecord, type ComposeFramesOptions, type DecodeAstmFramesResult, type DefineAstmProfileOptions, type Delimiters, type DetectFramingOptions, type DetectFramingResult, FATAL_CODES, FRAME_WARNING_CODES, type FatalCode, type FrameChecksum, type FrameOptions, type FrameTerminator, type FrameWarningCode, type FramedAstmResult, type HeaderInput, type HeaderRecord, LIVD_WARNING_CODES, LTP_WARNING_CODES, type LivdAnnotation, type LivdCatalog, type LivdEntry, type LivdLookup, type LivdMapping, type LivdResult, type LivdWarningCode, type LtpAction, type LtpEvent, type LtpPhase, type LtpState, type LtpTransition, type LtpWarningCode, type ManufacturerRecord, type MessageInput, type OrderInput, type OrderRecord, type PatientInput, type PatientName, type PatientNameInput, type PatientRecord, type QueryInput, type QueryRecord, type ReferenceRange, type ReferenceRangeKind, type ResultInput, type ResultRecord, type ResultStatus, type ResultStatusCode, type ResultStatusMeaning, SAFETY_CRITICAL_CODES, type ScientificRecord, TOLERABLE_CODES, type TerminatorRecord, type UniversalTestId, type UniversalTestIdProvenance, type UnknownEscapeSink, type UnpairedEscapeSink, type UnsupportedRecord, VERSION, type VerbatimInput, WARNING_CODES, type WarningCode, ambiguousMessageKind, ambiguousValueSplit, applyAstmProfile, applyAstmProfileToWarnings, applyLivd, astmDateToLocalISO, astmProfiles, attachComments, buildAstmMessage, classifyMessage, comments, commentsFor, composeAstmFrames, computeChecksum, decodeAstmFrames, decodeEscapes, deepFreeze, defineAstmProfile, defineLivdCatalog, delimitersRedeclared, detectFraming, encodeComponent, fieldScalar, fieldsUnseparated, 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, unpairedEscapeCharacter, unparseableReferenceRange, unreadableRedeclaration };

package/dist/index.d.ts

@@ -4360,12 +4360,49 @@ declare function decodeAstmFrames(bytes: Uint8Array, options?: FrameOptions): De
  *
  * A record must carry bytes: an empty record (or an empty record list) is a typed
  * {@link AstmFrameEncodeError}, never an empty frame.
+ *
+ * **A record given as a `string` is a byte string.** Each character stands for one
+ * byte, so a character above `U+00FF` has no byte to stand for and the record is
+ * refused rather than written. See {@link AstmFrameEncodeError} for what that
+ * turns away and how to frame such content instead.
+ */
+/**
+ * The reasons {@link composeAstmFrames} refuses rather than emitting bytes that
+ * are not the record it was handed.
+ *
+ * - `ASTM_FRAME_EMPTY_RECORD`: an empty record list, or a record with no bytes.
+ *   A frame must carry a record; an empty one is a structural error, never an
+ *   empty frame.
+ * - `ASTM_FRAME_UNENCODABLE_CHARACTER`: a record given as a `string` holds a
+ *   character above `U+00FF`, which has no single byte to stand for.
+ *
+ * @example
+ * ```ts
+ * import type { AstmFrameEncodeErrorCode } from "@cosyte/astm";
+ * const code: AstmFrameEncodeErrorCode = "ASTM_FRAME_UNENCODABLE_CHARACTER";
+ * ```
  */
+type AstmFrameEncodeErrorCode = "ASTM_FRAME_EMPTY_RECORD" | "ASTM_FRAME_UNENCODABLE_CHARACTER";
 /**
  * Thrown by {@link composeAstmFrames} when the input cannot be framed into a
- * spec-clean stream: an empty record list, or a record with no bytes (a frame
- * must carry a record; an empty one is a structural error, never an empty frame).
- * Carries a stable code + the offending record index, never record bytes.
+ * spec-clean stream. Carries a stable code + positional context, never the
+ * record bytes and never the offending character (PHI discipline).
+ *
+ * **The unencodable-character case, and why it is a refusal.** A record passed as
+ * a `string` is a **byte string**: character `i` becomes byte `i`, which is the
+ * exact inverse of how this package turns record bytes back into a string (one
+ * `String.fromCharCode` per byte, so every byte survives 1:1). A character above
+ * `U+00FF` has no byte to become. Turning one into bytes takes a character
+ * encoding, and nothing this package reads from an ASTM stream says which one:
+ * it reads no character-set declaration from any record, so picking one would be
+ * a guess at bytes the caller never supplied. Emit also has no warning channel,
+ * so a warning here could only be ignored while the wrong bytes still shipped.
+ *
+ * **Framing content outside Latin-1.** Encode it yourself, with the code page
+ * your instrument actually uses, and hand {@link composeAstmFrames} the
+ * `Uint8Array`: it accepts bytes directly and writes them through untouched.
+ * The refusal removes no capability, it routes you to the parameter that already
+ * carried it.
  *
  * @example
  * ```ts
@@ -4379,11 +4416,17 @@ declare function decodeAstmFrames(bytes: Uint8Array, options?: FrameOptions): De
  */
 declare class AstmFrameEncodeError extends Error {
     /** Stable discriminant. */
-    readonly code: "ASTM_FRAME_EMPTY_RECORD";
+    readonly code: AstmFrameEncodeErrorCode;
     /** Index of the offending record within the input, when applicable. */
     readonly recordIndex?: number;
+    /**
+     * Position of the offending character within that record, when applicable:
+     * its index in the string, never the character itself and never its code
+     * point. Enough to find it in the caller's own data.
+     */
+    readonly characterIndex?: number;
     /** @internal */
-    constructor(message: string, recordIndex?: number);
+    constructor(message: string, recordIndex?: number, code?: AstmFrameEncodeErrorCode, characterIndex?: number);
 }
 /** Options for {@link composeAstmFrames}. */
 interface ComposeFramesOptions {
@@ -4402,11 +4445,31 @@ interface ComposeFramesOptions {
  * across the whole stream; every frame's modulo-256 checksum is computed and
  * emitted uppercase.
  *
+ * **A record in either accepted form is written through unchanged, or refused.** A
+ * record given as a `Uint8Array` is already bytes. A record given as a `string` is
+ * a **byte string**, character `i` becoming byte `i`, the exact inverse of how a
+ * decoded record becomes a string again. A character above `U+00FF` is not a byte,
+ * so it is refused with `ASTM_FRAME_UNENCODABLE_CHARACTER` rather than replaced by
+ * a different character (it used to be truncated to its low byte, which is another
+ * ordinary character, and reached the wire silently). To frame content outside
+ * Latin-1, encode it with the character encoding your instrument uses and pass the
+ * resulting `Uint8Array`. Those two forms are the whole of what `records` accepts.
+ * A caller reaching this from JavaScript with some **other** typed array is outside
+ * the signature and gets no such refusal: each element is still written as its low
+ * byte, the same substitution described above. Pass a `Uint8Array` or a string.
+ *
+ * That covers the string-to-bytes step only. It is **not** a guarantee that any
+ * accepted record reads back: a record already carrying an `STX`, `ETX` or `ETB`
+ * byte is framed as given and re-decodes wrong, which this refusal does not touch
+ * and does not claim to.
+ *
  * @param records - The reassembled record byte-strings (`Uint8Array` or latin1
  *   `string`), one entry per complete record.
  * @param options - Encode options.
  * @returns The framed byte stream.
- * @throws {@link AstmFrameEncodeError} when the list is empty or a record has no bytes.
+ * @throws {@link AstmFrameEncodeError} when the list is empty, a record has no
+ *   bytes (`ASTM_FRAME_EMPTY_RECORD`), or a record string holds a character above
+ *   `U+00FF` (`ASTM_FRAME_UNENCODABLE_CHARACTER`).
  * @example
  * ```ts
  * import { composeAstmFrames, decodeAstmFrames } from "@cosyte/astm";
@@ -4483,11 +4546,18 @@ declare function parseFramedAstm(bytes: Uint8Array, options?: FrameOptions & Ast
  * {@link decodeAstmFrames} reassembles: `parseFramedAstm(serializeFramedAstm(msg))`
  * yields an equal message.
  *
+ * A value carrying a character above `U+00FF` is **refused** here rather than
+ * framed: the record layer is happy to hold one, but a frame carries bytes and
+ * nothing in the message says which character encoding to turn it into. A message
+ * whose every value is Latin-1 is unaffected.
+ *
  * @param input - A parsed {@link AstmMessage} or a list of {@link AstmRecord}s.
  * @param options - Frame-encode options.
  * @returns The framed byte stream.
  * @throws {@link AstmSerializeError} when a value contains an unencodable `CR`/`LF`.
- * @throws {@link AstmFrameEncodeError} when there are no records to frame.
+ * @throws {@link AstmFrameEncodeError} when there are no records to frame
+ *   (`ASTM_FRAME_EMPTY_RECORD`), or a value holds a character above `U+00FF`
+ *   (`ASTM_FRAME_UNENCODABLE_CHARACTER`).
  * @example
  * ```ts
  * import { parseAstmRecords, serializeFramedAstm, parseFramedAstm } from "@cosyte/astm";
@@ -4659,4 +4729,4 @@ declare class AstmFrameStrictError extends Error {
  */
 declare const VERSION: string;
 
-export { ALL_ASTM_WARNING_CODES, AMBIGUOUS_CODES, ACK as ASTM_ACK, ENQ as ASTM_ENQ, EOT as ASTM_EOT, NAK as ASTM_NAK, type AbnormalFlag, type AbnormalFlagCode, type AbnormalFlagMeaning, type AmbiguousCode, type AnyAstmWarningCode, AstmAmbiguousStreamError, type AstmDate, type AstmDatePrecision, type AstmField, type AstmFrame, AstmFrameEncodeError, type AstmFramePosition, AstmFrameStrictError, type AstmFrameWarning, type AstmFraming, type AstmLivdWarning, type AstmLtpWarning, type AstmMessage, type AstmMessageClassification, type AstmMessageKind, AstmParseError, type AstmParseOptions, type AstmPosition, type AstmProfile, AstmProfileDefinitionError, type AstmProfileProvenance, type AstmQuirkMatch, type AstmQuirkTolerance, type AstmRecord, type AstmRecordInput, type AstmRecordWarning, AstmSerializeError, type AstmSerializeErrorCode, type AstmStreamMessage, AstmStrictError, CANONICAL_DELIMITERS, type CommentInput, type CommentRecord, type ComposeFramesOptions, type DecodeAstmFramesResult, type DefineAstmProfileOptions, type Delimiters, type DetectFramingOptions, type DetectFramingResult, FATAL_CODES, FRAME_WARNING_CODES, type FatalCode, type FrameChecksum, type FrameOptions, type FrameTerminator, type FrameWarningCode, type FramedAstmResult, type HeaderInput, type HeaderRecord, LIVD_WARNING_CODES, LTP_WARNING_CODES, type LivdAnnotation, type LivdCatalog, type LivdEntry, type LivdLookup, type LivdMapping, type LivdResult, type LivdWarningCode, type LtpAction, type LtpEvent, type LtpPhase, type LtpState, type LtpTransition, type LtpWarningCode, type ManufacturerRecord, type MessageInput, type OrderInput, type OrderRecord, type PatientInput, type PatientName, type PatientNameInput, type PatientRecord, type QueryInput, type QueryRecord, type ReferenceRange, type ReferenceRangeKind, type ResultInput, type ResultRecord, type ResultStatus, type ResultStatusCode, type ResultStatusMeaning, SAFETY_CRITICAL_CODES, type ScientificRecord, TOLERABLE_CODES, type TerminatorRecord, type UniversalTestId, type UniversalTestIdProvenance, type UnknownEscapeSink, type UnpairedEscapeSink, type UnsupportedRecord, VERSION, type VerbatimInput, WARNING_CODES, type WarningCode, ambiguousMessageKind, ambiguousValueSplit, applyAstmProfile, applyAstmProfileToWarnings, applyLivd, astmDateToLocalISO, astmProfiles, attachComments, buildAstmMessage, classifyMessage, comments, commentsFor, composeAstmFrames, computeChecksum, decodeAstmFrames, decodeEscapes, deepFreeze, defineAstmProfile, defineLivdCatalog, delimitersRedeclared, detectFraming, encodeComponent, fieldScalar, fieldsUnseparated, 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, unpairedEscapeCharacter, unparseableReferenceRange, unreadableRedeclaration };
+export { ALL_ASTM_WARNING_CODES, AMBIGUOUS_CODES, ACK as ASTM_ACK, ENQ as ASTM_ENQ, EOT as ASTM_EOT, NAK as ASTM_NAK, type AbnormalFlag, type AbnormalFlagCode, type AbnormalFlagMeaning, type AmbiguousCode, type AnyAstmWarningCode, AstmAmbiguousStreamError, type AstmDate, type AstmDatePrecision, type AstmField, type AstmFrame, AstmFrameEncodeError, type AstmFrameEncodeErrorCode, type AstmFramePosition, AstmFrameStrictError, type AstmFrameWarning, type AstmFraming, type AstmLivdWarning, type AstmLtpWarning, type AstmMessage, type AstmMessageClassification, type AstmMessageKind, AstmParseError, type AstmParseOptions, type AstmPosition, type AstmProfile, AstmProfileDefinitionError, type AstmProfileProvenance, type AstmQuirkMatch, type AstmQuirkTolerance, type AstmRecord, type AstmRecordInput, type AstmRecordWarning, AstmSerializeError, type AstmSerializeErrorCode, type AstmStreamMessage, AstmStrictError, CANONICAL_DELIMITERS, type CommentInput, type CommentRecord, type ComposeFramesOptions, type DecodeAstmFramesResult, type DefineAstmProfileOptions, type Delimiters, type DetectFramingOptions, type DetectFramingResult, FATAL_CODES, FRAME_WARNING_CODES, type FatalCode, type FrameChecksum, type FrameOptions, type FrameTerminator, type FrameWarningCode, type FramedAstmResult, type HeaderInput, type HeaderRecord, LIVD_WARNING_CODES, LTP_WARNING_CODES, type LivdAnnotation, type LivdCatalog, type LivdEntry, type LivdLookup, type LivdMapping, type LivdResult, type LivdWarningCode, type LtpAction, type LtpEvent, type LtpPhase, type LtpState, type LtpTransition, type LtpWarningCode, type ManufacturerRecord, type MessageInput, type OrderInput, type OrderRecord, type PatientInput, type PatientName, type PatientNameInput, type PatientRecord, type QueryInput, type QueryRecord, type ReferenceRange, type ReferenceRangeKind, type ResultInput, type ResultRecord, type ResultStatus, type ResultStatusCode, type ResultStatusMeaning, SAFETY_CRITICAL_CODES, type ScientificRecord, TOLERABLE_CODES, type TerminatorRecord, type UniversalTestId, type UniversalTestIdProvenance, type UnknownEscapeSink, type UnpairedEscapeSink, type UnsupportedRecord, VERSION, type VerbatimInput, WARNING_CODES, type WarningCode, ambiguousMessageKind, ambiguousValueSplit, applyAstmProfile, applyAstmProfileToWarnings, applyLivd, astmDateToLocalISO, astmProfiles, attachComments, buildAstmMessage, classifyMessage, comments, commentsFor, composeAstmFrames, computeChecksum, decodeAstmFrames, decodeEscapes, deepFreeze, defineAstmProfile, defineLivdCatalog, delimitersRedeclared, detectFraming, encodeComponent, fieldScalar, fieldsUnseparated, 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, unpairedEscapeCharacter, unparseableReferenceRange, unreadableRedeclaration };

package/dist/index.mjs

@@ -2224,18 +2224,37 @@ var AstmFrameEncodeError = class extends Error {
   code;
   /** Index of the offending record within the input, when applicable. */
   recordIndex;
+  /**
+   * Position of the offending character within that record, when applicable:
+   * its index in the string, never the character itself and never its code
+   * point. Enough to find it in the caller's own data.
+   */
+  characterIndex;
   /** @internal */
-  constructor(message, recordIndex) {
+  constructor(message, recordIndex, code = "ASTM_FRAME_EMPTY_RECORD", characterIndex) {
     super(message);
     this.name = "AstmFrameEncodeError";
-    this.code = "ASTM_FRAME_EMPTY_RECORD";
+    this.code = code;
     if (recordIndex !== void 0) this.recordIndex = recordIndex;
+    if (characterIndex !== void 0) this.characterIndex = characterIndex;
   }
 };
-function toBytes(input) {
+var MAX_SINGLE_BYTE_CODE_POINT = 255;
+function toBytes(input, recordIndex) {
   if (typeof input !== "string") return input;
   const out = new Uint8Array(input.length);
-  for (let i = 0; i < input.length; i += 1) out[i] = input.charCodeAt(i) & 255;
+  for (let i = 0; i < input.length; i += 1) {
+    const code = input.charCodeAt(i);
+    if (code > MAX_SINGLE_BYTE_CODE_POINT) {
+      throw new AstmFrameEncodeError(
+        "A record contains a character above U+00FF, which is not a single byte. Encode the record with the character encoding your instrument uses and pass the bytes.",
+        recordIndex,
+        "ASTM_FRAME_UNENCODABLE_CHARACTER",
+        i
+      );
+    }
+    out[i] = code;
+  }
   return out;
 }
 function encodeFrame(text, frameNumber, isFinal) {
@@ -2252,7 +2271,7 @@ function composeAstmFrames(records, options = {}) {
   const out = [];
   let frameNumber = options.startFrameNumber ?? FIRST_FRAME_NUMBER;
   records.forEach((record, recordIndex) => {
-    const bytes = toBytes(record);
+    const bytes = toBytes(record, recordIndex);
     if (bytes.length === 0) {
       throw new AstmFrameEncodeError(
         "Cannot frame an empty record: a frame must carry record bytes.",
@@ -2294,7 +2313,7 @@ function concatBytes3(chunks) {
 }
 
 // src/index.ts
-var VERSION = "0.0.9";
+var VERSION = "0.0.10";
 
 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, fieldsUnseparated, 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, unpairedEscapeCharacter, unparseableReferenceRange, unreadableRedeclaration };
 //# sourceMappingURL=index.mjs.map