FileStorage class

Package:
@microsoft/agents-hosting

A file-based storage implementation that persists data to the local filesystem.

Example

const storage = new FileStorage('./data');

// Write some data
await storage.write({
  'user123': { name: 'John', lastSeen: new Date().toISOString() },
  'conversation456': { turn: 5, context: 'discussing weather' }
});

// Read specific keys
const data = await storage.read(['user123']);
console.log(data.user123); // { name: 'John', lastSeen: '...' }

// Delete data
await storage.delete(['conversation456']);

Remarks

FileStorage stores all data in a single JSON file named 'state.json' within a specified folder. This implementation is suitable for development scenarios, local testing, and single-instance deployments where shared state across multiple instances is not required.

The storage format is a simple key-value JSON object where keys are strings and values can be any JSON-serializable data. All operations are synchronous file I/O operations wrapped in Promise interfaces to match the Storage contract.

Warning

This implementation does not provide:

  • Thread safety for concurrent access
  • Optimistic concurrency control (eTag support)
  • Atomic operations across multiple keys
  • Scale for large datasets

For production scenarios requiring these features, consider using database-backed storage implementations instead.

Constructors

FileStorage(string)

Creates a new FileStorage instance that stores data in the specified folder.

Methods

delete(string[])

Deletes store items from the filesystem storage.
read(string[])

Reads store items from the filesystem storage.
write(StoreItem)

Writes store items to the filesystem storage.

Constructor Details

FileStorage(string)

Creates a new FileStorage instance that stores data in the specified folder.

new FileStorage(folder: string)

Parameters

folder

string

The absolute or relative path to the folder where the state.json file will be stored

Remarks

The constructor performs the following initialization steps:

  1. Creates the target folder if it doesn't exist (including parent directories)
  2. Creates an empty state.json file if it doesn't exist
  3. Loads existing data from state.json into memory for fast access

Method Details

delete(string[])

Deletes store items from the filesystem storage.

function delete(keys: string[]): Promise<void>

Parameters

keys

string[]

Array of keys to delete from storage

Returns

Promise<void>

Promise that resolves when the delete operation completes

read(string[])

Reads store items from the filesystem storage.

function read(keys: string[]): Promise<StoreItem>

Parameters

keys

string[]

Array of keys to read from storage

Returns

Promise<StoreItem>

Promise resolving to an object containing the requested items (keys that don't exist are omitted)

write(StoreItem)

Writes store items to the filesystem storage.

function write(changes: StoreItem): Promise<void>

Parameters

changes
StoreItem

Object containing key-value pairs to write to storage

Returns

Promise<void>

Promise that resolves when the write operation completes