Class: AstmFrameEncodeError

Thrown by composeAstmFrames when the input cannot be framed into a 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 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.

The reserved-byte case, and why it has no escape hatch. STX, ETB and ETX are what decodeAstmFrames reads as frame structure: STX opens a frame, and the first ETB/ETX after it is the end of that frame's text. A record carrying one of those bytes therefore cannot be framed and read back, whichever form it arrives in, and this layer has no escape sequence to hide one behind. Passing bytes instead of a string does not route around it, because the byte is the problem rather than the encoding. Take the byte out of the value before framing: which byte belongs in a clinical value is the sender's call, not this library's, so it refuses rather than substituting or deleting one.

The start-frame-number case, and why an option gets an error of its own. A frame's number is a single ASCII digit, FN_ZERO + n for n in 0-7, and nothing used to check that options.startFrameNumber was one. What went out instead was whatever byte that sum truncated to: measured on this package's own round trip, -1 wrote / into the frame-number position and NaN, Infinity and -Infinity each wrote a NUL byte into every frame of the stream, after which the decoder read no frame number at all and emitted none of the records. Out-of-domain values that happened to land back on a digit were worse in a quieter way: 1.5 and 257 both produced the byte-for-byte stream a startFrameNumber of 1 produces, so the option silently accepted a value it documented as invalid. This one refusal is about the caller's own option rather than about record content, so its message names the value received. Nothing from the stream is quoted.

Example

import { composeAstmFrames, AstmFrameEncodeError } from "@cosyte/astm";
try {
  composeAstmFrames([]);
} catch (err) {
  if (err instanceof AstmFrameEncodeError) err.code; // "ASTM_FRAME_EMPTY_RECORD"
}

Extends

• Error

Constructors

Constructor

new AstmFrameEncodeError(message, recordIndex?, code?, characterIndex?): AstmFrameEncodeError

Internal

Parameters

message

string

recordIndex?

number

code?

AstmFrameEncodeErrorCode = "ASTM_FRAME_EMPTY_RECORD"

characterIndex?

number

Returns

AstmFrameEncodeError

Overrides

Error.constructor

Properties

characterIndex?

readonly optional characterIndex?: 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. For a record supplied as a Uint8Array this is the offending byte's index, which is the same position: a record string is a byte string, so the two indices coincide.

---

code

readonly code: AstmFrameEncodeErrorCode

Stable discriminant.

---

recordIndex?

readonly optional recordIndex?: number

Index of the offending record within the input, when applicable.