FileStorage class
A file-based storage implementation that persists data to the local filesystem.
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. Example
// 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']); ```
Constructors
| File |
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(Store |
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:
- Creates the target folder if it doesn't exist (including parent directories)
- Creates an empty state.json file if it doesn't exist
- 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
Remarks
This method removes the specified keys from both the in-memory cache and writes the updated state to the state.json file. Keys that don't exist in storage are silently ignored.
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)
Remarks
This method reads from the in-memory cache that was loaded during construction, making it very fast but potentially returning stale data if the file was modified by external processes.
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
Remarks
This method updates both the in-memory cache and writes the entire state to the state.json file. The file is written with pretty-printing (2-space indentation) for better readability during development and debugging.
Note: This implementation does not support eTag-based optimistic concurrency control. Any eTag values in the changes object are ignored.