FileStorage class

Package:
@microsoft/agents-hosting

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

Example

const legacyStorage = new FileStorage('./data')
const storageV2 = new FileStorageV2('./data-v2')

await storageV2.write({
  user123: { name: 'John', lastSeen: new Date().toISOString() }
})

const result = await storageV2.read(['user123'])
console.log(result.user123.value)

await storageV2.delete(['user123'])
Extends

FileStorageInternals

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.

Values remain a key-value JSON object in state.json. V2 keeps generated storage versions in state.versions.json so a value's own eTag property is not changed. All operations use synchronous file I/O wrapped in Promise interfaces. Use FileStorageV2 for the structured StorageV2 contract. V2 supports create-only, replace, and expected-version conditions.

The inherited constructor creates the folder and state.json when needed, then loads values and V2 version metadata into memory. It creates state.versions.json on the first V2 write.

Warning

This implementation does not provide:

  • Thread safety for concurrent access
  • Atomic operations across multiple keys
  • Scale for large datasets

For production scenarios requiring these features, use a database-backed storage implementation.

Constructors

FileStorage(string)

Inherited Properties

expirations
state
versions

Methods

delete(string[])

Deletes legacy items from state.json.
read(string[])

Reads legacy items from state.json.
write(StoreItem)

Writes legacy items to state.json.

Inherited Methods

flush()
getOrCreateVersion(string)
isExpired(string)
remove(string)

Constructor Details

FileStorage(string) 

new FileStorage(folder: string)

Parameters

folder

string

Inherited Property Details

expirations 

expirations: Record<string, number>

Property Value

Record<string, number>

Inherited From FileStorageInternals.expirations

state 

state: Record<string, unknown>

Property Value

Record<string, unknown>

Inherited From FileStorageInternals.state

versions 

versions: Record<string, string>

Property Value

Record<string, string>

Inherited From FileStorageInternals.versions

Method Details

delete(string[])

Deletes legacy items from state.json.

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

Parameters

keys

string[]

The keys to delete; must not be empty. Missing keys are ignored.

Returns

Promise<void>

read(string[])

Reads legacy items from state.json.

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

Parameters

keys

string[]

The keys to read; must not be empty.

Returns

Promise<StoreItem>

Existing items keyed by storage key. Missing keys are omitted.

write(StoreItem)

Writes legacy items to state.json.

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

Parameters

changes
StoreItem

The items to write, keyed by storage key.

Returns

Promise<void>

Inherited Method Details

flush() 

function flush()

Inherited From FileStorageInternals.flush

getOrCreateVersion(string) 

function getOrCreateVersion(key: string): string

Parameters

key

string

Returns

string

Inherited From FileStorageInternals.getOrCreateVersion

isExpired(string) 

function isExpired(key: string): boolean

Parameters

key

string

Returns

boolean

Inherited From FileStorageInternals.isExpired

remove(string) 

function remove(key: string)

Parameters

key

string

Inherited From FileStorageInternals.remove