---
url: >-
  https://adk.nht.io/api/@nhtio/adk/batteries/storage/opfs/classes/OpfsSpoolStore.md
description: '"Give bytes, get a reader" persistence layer over an OPFS directory.'
---

# Class: OpfsSpoolStore

Defined in: [batteries/storage/opfs/index.ts:431](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/batteries/storage/opfs/index.ts#L431)

"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](OpfsSpoolReader.md) 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

```ts
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`](../../../../common/type-aliases/SpoolStore.md)

## Constructors

### Constructor

```ts
new OpfsSpoolStore(opts?: OpfsSpoolStoreOptions): OpfsSpoolStore;
```

Defined in: [batteries/storage/opfs/index.ts:437](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/batteries/storage/opfs/index.ts#L437)

#### Parameters

| Parameter | Type                                                              |
| --------- | ----------------------------------------------------------------- |
| `opts`    | [`OpfsSpoolStoreOptions`](../interfaces/OpfsSpoolStoreOptions.md) |

#### Returns

`OpfsSpoolStore`

## Methods

### delete()

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

Defined in: [batteries/storage/opfs/index.ts:528](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/batteries/storage/opfs/index.ts#L528)

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

```ts
SpoolStore.delete;
```

***

### has()

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

Defined in: [batteries/storage/opfs/index.ts:546](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/batteries/storage/opfs/index.ts#L546)

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

```ts
keyFor(callId: string): string;
```

Defined in: [batteries/storage/opfs/index.ts:565](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/batteries/storage/opfs/index.ts#L565)

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

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

Defined in: [batteries/storage/opfs/index.ts:507](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/batteries/storage/opfs/index.ts#L507)

Returns a reader over the bytes previously written under `callId`.

#### Parameters

| Parameter | Type                                                                | Description                                                         |
| --------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `callId`  | `string`                                                            | Identifier supplied to a prior [OpfsSpoolStore.write](#write) call. |
| `opts?`   | [`OpfsSpoolReaderOptions`](../interfaces/OpfsSpoolReaderOptions.md) | Per-call override for `streamThresholdBytes`.                       |

#### Returns

`Promise`<[`OpfsSpoolReader`](OpfsSpoolReader.md) | `undefined`>

An [OpfsSpoolReader](OpfsSpoolReader.md), or `undefined` if the key is missing.

#### Remarks

Returns `undefined` if the file does not exist.

#### Implementation of

```ts
SpoolStore.read;
```

***

### write()

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

Defined in: [batteries/storage/opfs/index.ts:470](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/batteries/storage/opfs/index.ts#L470)

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](#read).           |
| `bytes`   | | `string` | `Uint8Array`<`ArrayBufferLike`> | `ReadableStream`<`Uint8Array`<`ArrayBufferLike`>> | The bytes to store, as a `string`, `Uint8Array`, or `ReadableStream<Uint8Array>`. |
| `opts?`   | [`OpfsSpoolReaderOptions`](../interfaces/OpfsSpoolReaderOptions.md)                                       | Per-call override for `streamThresholdBytes`.                                     |

#### Returns

`Promise`<[`OpfsSpoolReader`](OpfsSpoolReader.md)>

An [OpfsSpoolReader](OpfsSpoolReader.md) 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

```ts
SpoolStore.write;
```

***

### isOpfsSpoolStore()

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

Defined in: [batteries/storage/opfs/index.ts:452](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/batteries/storage/opfs/index.ts#L452)

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](../../../../guards/functions/isInstanceOf.md) for cross-realm safety.