@nhtio/adk/batteries/storage/flydrive

Flydrive-backed spooled artifact storage for Node and server runtimes.

Remarks

Requires Node 24+. flydrive uses the node:stream ReadableStream web API which is only available from Node 24. This battery does not work in the browser or earlier Node versions.

Opt-in storage battery backed by flydrive. Provides FlydriveSpoolReader (a @nhtio/adk!SpoolReader over a flydrive key) and FlydriveSpoolStore (a write(callId, bytes) → reader persistence layer that wraps an existing Disk).

The reader has two modes selected at construction time based on the size of the underlying object:

• Eager mode — when the object's contentLength is below streamThresholdBytes (default 10 MiB), the reader calls disk.get(key) once, splits the content on \n, and caches lines + byte count. All subsequent line() / byteLength() / lineCount() calls resolve from memory.
• Streaming mode — when contentLength meets or exceeds the threshold, the reader streams the file once via disk.getStream(key) to build a line-offset index (number[] of byte offsets per line), then serves each line(i) request by streaming the byte range [offsets[i], offsets[i+1]). Caps RAM at one index + one line buffer regardless of file size.

Set streamThresholdBytes: 0 to force streaming mode; set it to Infinity to force eager mode. The default of 10 MiB matches typical tool output sizes — tune it for your workload.

The store and reader are pure-flydrive: they don't know about S3, GCS, or filesystem specifically — they delegate to whatever Disk you construct.

Classes

Class	Description
FlydriveSpoolReader	Reads a flydrive-backed file as a @nhtio/adk!SpoolReader.
FlydriveSpoolStore	"Give bytes, get a reader" persistence layer over a flydrive Disk.

Interfaces

Interface	Description
FlydriveSpoolReaderOptions	Constructor options for FlydriveSpoolReader.
FlydriveSpoolStoreOptions	Constructor options for FlydriveSpoolStore.