Interface: SpoolReader
Defined in: src/lib/contracts/spool_reader.ts:19
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>;Defined in: src/lib/contracts/spool_reader.ts:37
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.
describe()?
optional describe():
| ReaderDescriptor
| undefined;Defined in: src/lib/contracts/spool_reader.ts:80
Optionally emit a serialisable ReaderDescriptor so a @nhtio/adk!SpooledArtifact backed by this reader can round-trip through encode()/decode() as a handle.
Returns
| ReaderDescriptor | undefined
A tagged, serialisable handle, or undefined/absent when the reader cannot describe itself.
Remarks
Synchronous by contract — the encoder's [ENCODE_METHOD]() is synchronous and cannot await. The descriptor describes where the bytes live (a spool key, or an inlined string for in-memory readers) — never the live binding (Disk, OPFS root), which the matching resolver re-injects on decode. A reader that omits this method is treated as non-describable: line/text reads still work at runtime, the SpooledArtifact simply cannot be serialised, and encoding it throws @nhtio/adk!E_READER_NOT_DESCRIBABLE.
line()
line(index: number): string | Promise<string | undefined> | undefined;Defined in: src/lib/contracts/spool_reader.ts:26
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>;Defined in: src/lib/contracts/spool_reader.ts:48
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>;Defined in: src/lib/contracts/spool_reader.ts:64
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.