Class: OpfsSpoolStore

Defined in: batteries/storage/opfs/index.ts:431

"Give bytes, get a reader" persistence layer over an OPFS directory.

Remarks

write(callId, bytes) resolves the root directory (lazily, on first call), opens or creates the file named keyPrefix + callId, then writes via the API matching the current scope: a FileSystemSyncAccessHandle in worker scopes, OpfsFileHandle.createWritable() on the main thread. A fresh OpfsSpoolReader pointed at the same file is returned.

read(callId) returns a reader without re-writing; delete(callId) removes the entry.

The store is otherwise stateless — it owns no in-memory cache of writes. Multiple OpfsSpoolStore instances sharing the same root directory and key prefix see the same data.

Example

import { OpfsSpoolStore } from "@nhtio/adk/batteries/storage/opfs";

const store = new OpfsSpoolStore({ keyPrefix: "agent-runs/" });

const bytes = await tool.executor(ctx)(args);
const reader = await store.write(callId, bytes);
const Ctor = tool.artifactConstructor?.() ?? SpooledArtifact;
const artifact = new Ctor(reader);

Implements

• SpoolStore

Constructors

Constructor

new OpfsSpoolStore(opts?: OpfsSpoolStoreOptions): OpfsSpoolStore;

Defined in: batteries/storage/opfs/index.ts:437

Parameters

Parameter	Type
opts	OpfsSpoolStoreOptions

Returns

OpfsSpoolStore

Methods

delete()

delete(callId: string): Promise<boolean>;

Defined in: batteries/storage/opfs/index.ts:528

Removes the entry under callId.

Parameters

Parameter	Type	Description
callId	string	Identifier whose entry should be removed.

Returns

Promise<boolean>

true if the entry existed and was removed; false if it didn't exist.

Implementation of

SpoolStore.delete;

---

has()

has(callId: string): Promise<boolean>;

Defined in: batteries/storage/opfs/index.ts:546

Returns true if a file is present under callId.

Parameters

Parameter	Type	Description
callId	string	Identifier to test.

Returns

Promise<boolean>

true when the file exists, false otherwise.

---

keyFor()

keyFor(callId: string): string;

Defined in: batteries/storage/opfs/index.ts:565

Returns the full filename for a given callId (i.e. keyPrefix + callId).

Parameters

Parameter	Type
callId	string

Returns

string

Remarks

Useful for tests or for callers that want to interact with the underlying OPFS directory directly.

---

read()

read(callId: string, opts?: OpfsSpoolReaderOptions): Promise<OpfsSpoolReader | undefined>;

Defined in: batteries/storage/opfs/index.ts:507

Returns a reader over the bytes previously written under callId.

Parameters

Parameter	Type	Description
callId	string	Identifier supplied to a prior OpfsSpoolStore.write call.
opts?	OpfsSpoolReaderOptions	Per-call override for streamThresholdBytes.

Returns

Promise<OpfsSpoolReader | undefined>

An OpfsSpoolReader, or undefined if the key is missing.

Remarks

Returns undefined if the file does not exist.

Implementation of

SpoolStore.read;

---

write()

write(
   callId: string,
   bytes:
  | string
  | Uint8Array<ArrayBufferLike>
  | ReadableStream<Uint8Array<ArrayBufferLike>>,
opts?: OpfsSpoolReaderOptions): Promise<OpfsSpoolReader>;

Defined in: batteries/storage/opfs/index.ts:470

Persists bytes under callId and returns a reader bound to the stored key.

Parameters

Parameter	Type	Description
callId	string	Identifier used to retrieve the bytes via OpfsSpoolStore.read.
bytes	| string | Uint8Array<ArrayBufferLike> | ReadableStream<Uint8Array<ArrayBufferLike>>	The bytes to store, as a string, Uint8Array, or ReadableStream<Uint8Array>.
opts?	OpfsSpoolReaderOptions	Per-call override for streamThresholdBytes.

Returns

Promise<OpfsSpoolReader>

An OpfsSpoolReader over the stored bytes.

Remarks

string input is encoded as UTF-8; Uint8Array is stored byte-faithfully; ReadableStream<Uint8Array> is written incrementally — the stream is consumed chunk-by-chunk straight to OPFS without first materializing the whole payload in memory, which is the point of accepting a stream for a durable store.

Implementation of

SpoolStore.write;

---

isOpfsSpoolStore()

static isOpfsSpoolStore(value: unknown): value is OpfsSpoolStore;

Defined in: batteries/storage/opfs/index.ts:452

Returns true if value is an OpfsSpoolStore instance.

Parameters

Parameter	Type	Description
value	unknown	The value to test.

Returns

value is OpfsSpoolStore

true when value is an OpfsSpoolStore instance.

Remarks

Uses @nhtio/adk!isInstanceOf for cross-realm safety.