Class: OpfsSpoolStore

"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);

Constructors

Constructor

new OpfsSpoolStore(opts?: OpfsSpoolStoreOptions): OpfsSpoolStore;

Parameters

Parameter	Type
opts	OpfsSpoolStoreOptions

Returns

OpfsSpoolStore

Methods

delete()

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

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.

---

has()

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

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;

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>;

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.

---

write()

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

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>	The bytes to store, as a string or Uint8Array.
opts?	OpfsSpoolReaderOptions	Per-call override for streamThresholdBytes.

Returns

Promise<OpfsSpoolReader>

An OpfsSpoolReader over the stored bytes.

---

isOpfsSpoolStore()

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

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.