Chat Storage

chat/storage

Classes

FileStorage

Defined in: chat/storage.ts:263

File-based storage adapter that persists each item as a JSON file. Suitable for local applications, CLI tools, and development. Creates the storage directory if it doesn’t exist.

Example

const store = new FileStorage<ChatSession>({
  directory: "./data/sessions",
});
await store.create("session-1", mySession);

Type Parameters

T

T

The type of stored items (must be JSON-serializable)

Implements

IStorageAdapter<T>

Constructors

Constructor

new FileStorage<T>(options): FileStorage<T>

Defined in: chat/storage.ts:267

Parameters

options

FileStorageOptions

Returns

FileStorage<T>

Methods

clear()

clear(): Promise<void>

Defined in: chat/storage.ts:361

Remove all items from storage.

Returns

Promise<void>

Implementation of

IStorageAdapter.clear

count()

count(): Promise<number>

Defined in: chat/storage.ts:353

Return the number of stored items.

Returns

Promise<number>

Count of items

Implementation of

IStorageAdapter.count

create()

create(key, item): Promise<void>

Defined in: chat/storage.ts:312

Create a new item. Throws StorageError with code DUPLICATE_KEY if key exists.

Parameters

key

string

Unique identifier

item

T

Data to store

Returns

Promise<void>

Implementation of

IStorageAdapter.create

delete()

delete(key): Promise<void>

Defined in: chat/storage.ts:336

Delete an item by key. Throws StorageError with code NOT_FOUND if key missing.

Parameters

key

string

Unique identifier

Returns

Promise<void>

Implementation of

IStorageAdapter.delete

get()

get(key): Promise<T | null>

Defined in: chat/storage.ts:274

Retrieve an item by key.

Parameters

key

string

Unique identifier

Returns

Promise<T | null>

The item, or null if not found

Implementation of

IStorageAdapter.get

has()

has(key): Promise<boolean>

Defined in: chat/storage.ts:348

Check whether a key exists.

Parameters

key

string

Unique identifier

Returns

Promise<boolean>

true if key exists

Implementation of

IStorageAdapter.has

list()

list(options?): Promise<T[]>

Defined in: chat/storage.ts:283

List items with optional filtering, sorting, and pagination.

Parameters

options?

ListOptions<T>

Filter, sort, limit, offset options

Returns

Promise<T[]>

Array of matching items

Implementation of

IStorageAdapter.list

update()

update(key, item): Promise<void>

Defined in: chat/storage.ts:324

Update an existing item. Throws StorageError with code NOT_FOUND if key missing.

Parameters

key

string

Unique identifier

item

T

Updated data

Returns

Promise<void>

Implementation of

IStorageAdapter.update

InMemoryStorage

Defined in: chat/storage.ts:158

In-memory storage adapter backed by a Map. Suitable for development, testing, and short-lived processes. Data is lost when the process exits.

Example

const store = new InMemoryStorage<{ name: string }>();
await store.create("k1", { name: "Alice" });
await store.create("k2", { name: "Bob" });
const items = await store.list({ filter: i => i.name.startsWith("A") });
// [{ name: "Alice" }]

Type Parameters

T

T

The type of stored items

Implements

IStorageAdapter<T>

Constructors

Constructor

new InMemoryStorage<T>(): InMemoryStorage<T>

Returns

InMemoryStorage<T>

Methods

clear()

clear(): Promise<void>

Defined in: chat/storage.ts:231

Remove all items from storage.

Returns

Promise<void>

Implementation of

IStorageAdapter.clear

count()

count(): Promise<number>

Defined in: chat/storage.ts:226

Return the number of stored items.

Returns

Promise<number>

Count of items

Implementation of

IStorageAdapter.count

create()

create(key, item): Promise<void>

Defined in: chat/storage.ts:188

Create a new item. Throws StorageError with code DUPLICATE_KEY if key exists.

Parameters

key

string

Unique identifier

item

T

Data to store

Returns

Promise<void>

Implementation of

IStorageAdapter.create

delete()

delete(key): Promise<void>

Defined in: chat/storage.ts:210

Delete an item by key. Throws StorageError with code NOT_FOUND if key missing.

Parameters

key

string

Unique identifier

Returns

Promise<void>

Implementation of

IStorageAdapter.delete

get()

get(key): Promise<T | null>

Defined in: chat/storage.ts:162

Retrieve an item by key.

Parameters

key

string

Unique identifier

Returns

Promise<T | null>

The item, or null if not found

Implementation of

IStorageAdapter.get

has()

has(key): Promise<boolean>

Defined in: chat/storage.ts:221

Check whether a key exists.

Parameters

key

string

Unique identifier

Returns

Promise<boolean>

true if key exists

Implementation of

IStorageAdapter.has

list()

list(options?): Promise<T[]>

Defined in: chat/storage.ts:168

List items with optional filtering, sorting, and pagination.

Parameters

options?

ListOptions<T>

Filter, sort, limit, offset options

Returns

Promise<T[]>

Array of matching items

Implementation of

IStorageAdapter.list

update()

update(key, item): Promise<void>

Defined in: chat/storage.ts:199

Update an existing item. Throws StorageError with code NOT_FOUND if key missing.

Parameters

key

string

Unique identifier

item

T

Updated data

Returns

Promise<void>

Implementation of

IStorageAdapter.update

StorageError

Defined in: chat/storage.ts:31

Error thrown by storage operations.

Example

try {
  await store.get("missing-id");
} catch (e) {
  if (e instanceof StorageError && e.code === ErrorCode.STORAGE_NOT_FOUND) {
    // handle missing item
  }
}

Extends

AgentSDKError

Constructors

Constructor

new StorageError(message, code): StorageError

Defined in: chat/storage.ts:35

Parameters

message

string

Properties

code

readonly code: StorageErrorCode

Defined in: chat/storage.ts:33

Machine-readable error code from the unified ErrorCode enum

Overrides

AgentSDKError.code

httpStatus?

readonly optional httpStatus: number

Defined in: errors.ts:25

HTTP status code hint for error classification

Inherited from

AgentSDKError.httpStatus

retryable

readonly retryable: boolean

Defined in: errors.ts:23

Whether this error is safe to retry

Inherited from

AgentSDKError.retryable

Methods

is()

static is(error): error is AgentSDKError

Defined in: errors.ts:36

Check if an error is an AgentSDKError (works across bundled copies)

Parameters

error

unknown

Returns

error is AgentSDKError

Inherited from

AgentSDKError.is

Interfaces

FileStorageOptions

Defined in: chat/storage.ts:241

Options for configuring FileStorage.

Properties

extension?

optional extension: string

Defined in: chat/storage.ts:245

File extension (default: .json)

IStorageAdapter

Defined in: chat/storage.ts:80

Generic storage adapter for CRUD operations on any data type. Items are identified by a string key.

Example

const store: IStorageAdapter<{ name: string }> = new InMemoryStorage();
await store.create("key1", { name: "Alice" });
const item = await store.get("key1"); // { name: "Alice" }

Type Parameters

T

T

The type of stored items

Methods

clear()

clear(): Promise<void>

Defined in: chat/storage.ts:131

Remove all items from storage.

Returns

Promise<void>

count()

count(): Promise<number>

Defined in: chat/storage.ts:126

Return the number of stored items.

Returns

Promise<number>

Count of items

create()

create(key, item): Promise<void>

Defined in: chat/storage.ts:100

Create a new item. Throws StorageError with code DUPLICATE_KEY if key exists.

Parameters

key

string

Unique identifier

item

T

Data to store

Returns

Promise<void>

delete()

delete(key): Promise<void>

Defined in: chat/storage.ts:113

Delete an item by key. Throws StorageError with code NOT_FOUND if key missing.

Parameters

key

string

Unique identifier

Returns

Promise<void>

dispose()?

optional dispose(): Promise<void>

Defined in: chat/storage.ts:137

Release any resources held by this adapter (DB connections, file handles). Optional — adapters that don’t hold resources need not implement this.

Returns

Promise<void>

get()

get(key): Promise<T | null>

Defined in: chat/storage.ts:86

Retrieve an item by key.

Parameters

key

string

Unique identifier

Returns

Promise<T | null>

The item, or null if not found

has()

has(key): Promise<boolean>

Defined in: chat/storage.ts:120

Check whether a key exists.

Parameters

key

string

Unique identifier

Returns

Promise<boolean>

true if key exists

list()

list(options?): Promise<T[]>

Defined in: chat/storage.ts:93

List items with optional filtering, sorting, and pagination.

Parameters

options?

ListOptions<T>

Filter, sort, limit, offset options

Returns

Promise<T[]>

Array of matching items

update()

update(key, item): Promise<void>

Defined in: chat/storage.ts:107

Update an existing item. Throws StorageError with code NOT_FOUND if key missing.

Parameters

key

string

Unique identifier

item

T

Updated data

Returns

Promise<void>

ListOptions

Defined in: chat/storage.ts:56

Options for listing stored items.

Type Parameters

T

T

The type of stored items

Properties

filter()?

optional filter: (item) => boolean

Defined in: chat/storage.ts:58

Filter predicate — return true to include the item

Parameters

item

T

Returns

boolean

limit?

optional limit: number

Defined in: chat/storage.ts:62

Maximum number of items to return

offset?

optional offset: number

Defined in: chat/storage.ts:64

Number of items to skip (for pagination)

sort()?

optional sort: (a, b) => number

Defined in: chat/storage.ts:60

Sort comparator — standard Array.sort semantics

Parameters

a

T

b

T

Returns

number

Type Aliases

StorageErrorCode

StorageErrorCode = STORAGE_NOT_FOUND | STORAGE_DUPLICATE_KEY | STORAGE_IO_ERROR | STORAGE_SERIALIZATION_ERROR

Defined in: chat/storage.ts:43

Storage-specific subset of ErrorCode