---
url: 'https://adk.nht.io/api/@nhtio/adk/spooled_artifact/interfaces/SpoolReader.md'
description: 'Backing store contract for a {@link @nhtio/adk!SpooledArtifact}.'
---

# Interface: SpoolReader

Defined in: [lib/contracts/spool\_reader.ts:18](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/spool_reader.ts#L18)

Backing store contract for a [@nhtio/adk!SpooledArtifact](../classes/SpooledArtifact.md).

## 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](#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()

```ts
byteLength(): number | Promise<number>;
```

Defined in: [lib/contracts/spool\_reader.ts:36](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/spool_reader.ts#L36)

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()

```ts
line(index: number): string | Promise<string | undefined> | undefined;
```

Defined in: [lib/contracts/spool\_reader.ts:25](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/spool_reader.ts#L25)

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()

```ts
lineCount(): number | Promise<number>;
```

Defined in: [lib/contracts/spool\_reader.ts:47](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/spool_reader.ts#L47)

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()

```ts
readAll(): string | Promise<string>;
```

Defined in: [lib/contracts/spool\_reader.ts:63](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/spool_reader.ts#L63)

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](#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.