Interface: SpoolReader
Backing store contract for a @nhtio/adk!SpooledArtifact.
Remarks
Implementations may read from memory, a file handle, a network stream, or any other byte source. The interface is intentionally minimal — the artifact layer handles all higher-level operations (head, tail, grep, etc.) by composing calls to these three primitives.
Line indexing is 0-based. Implementations must return undefined from SpoolReader.line when the index is out of range rather than throwing.
All three methods may be synchronous or asynchronous to accommodate both in-memory and I/O- backed implementations without forcing unnecessary promise overhead on simple cases.
Methods
byteLength()
byteLength(): number | Promise<number>;Returns the total number of bytes in the underlying data.
Returns
number | Promise<number>
The byte length of the underlying data.
Remarks
Used for reporting and token-estimation purposes. Byte length is distinct from character length for multi-byte encodings.
line()
line(index: number): string | Promise<string | undefined> | undefined;Returns the line at the given 0-based index, or undefined when out of range.
Parameters
| Parameter | Type | Description |
|---|---|---|
index | number | 0-based line index. |
Returns
string | Promise<string | undefined> | undefined
The raw line string (without trailing newline), or undefined.
lineCount()
lineCount(): number | Promise<number>;Returns the total number of lines in the underlying data.
Returns
number | Promise<number>
The total line count.
Remarks
Required so consumers know when to stop iterating; the line count must remain stable for the lifetime of the reader.
readAll()
readAll(): string | Promise<string>;Returns the full underlying content as a single decoded string, byte-faithful to the source.
Returns
string | Promise<string>
The full underlying content as a single string.
Remarks
Unlike SpoolReader.line, this method preserves trailing newlines and any non-\n line terminators (e.g. \r\n) present in the original bytes. It is the primitive that powers SpooledArtifact.asString() — the round-trip-faithful alternative to assembling the artifact body from per-line reads.
Implementations should make this O(n) in the size of the underlying data and may cache the result if the read source is durable. Streaming implementations may choose not to cache.