@microsoft/agents-hosting 1.9.0-beta.18.g6b8111bba5 → 1.9.0-beta.20.g0c48a31a21

package/dist/src/storage/fileStorage.d.ts

@@ -2,112 +2,124 @@
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * Licensed under the MIT License.
  */
-import { Storage, StoreItem, StorageWriteOptions } from './storage';
+import { StorageDeleteOptions, StorageDeleteResults, StorageReadResults, StorageWriteOptions, StorageWriteResults, Storage, StorageV2, StoreItem } from './storage';
+declare class FileStorageInternals {
+    private readonly statePath;
+    private readonly versionsPath;
+    private readonly expirationsPath;
+    readonly state: Record<string, unknown>;
+    readonly versions: Record<string, string>;
+    readonly expirations: Record<string, number>;
+    constructor(folder: string);
+    flush(): void;
+    getOrCreateVersion(key: string): string;
+    isExpired(key: string): boolean;
+    remove(key: string): void;
+}
 /**
  * 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.
+ * 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.
+ * 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 {@link 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
- * - 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.
+ * For production scenarios requiring these features, use a database-backed storage implementation.
  *
  * @example
  * ```typescript
- * const storage = new FileStorage('./data');
+ * const legacyStorage = new FileStorage('./data')
+ * const storageV2 = new FileStorageV2('./data-v2')
  *
- * // Write some data
- * await storage.write({
- *   'user123': { name: 'John', lastSeen: new Date().toISOString() },
- *   'conversation456': { turn: 5, context: 'discussing weather' }
- * });
+ * await storageV2.write({
+ *   user123: { name: 'John', lastSeen: new Date().toISOString() }
+ * })
  *
- * // Read specific keys
- * const data = await storage.read(['user123']);
- * console.log(data.user123); // { name: 'John', lastSeen: '...' }
+ * const result = await storageV2.read(['user123'])
+ * console.log(result.user123.value)
  *
- * // Delete data
- * await storage.delete(['conversation456']);
+ * await storageV2.delete(['user123'])
  * ```
- *
  */
-export declare class FileStorage implements Storage {
-    private _folder;
-    private _stateFile;
-    private _metadataFile;
+export declare class FileStorage extends FileStorageInternals implements Storage {
     /**
-     * Creates a new FileStorage instance that stores data in the specified folder.
-     *
-     * @param folder The absolute or relative path to the folder where the state.json file will be stored
-     * @throws May throw filesystem errors if the folder cannot be created or accessed
-     *
-     * @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
+     * Reads legacy items from `state.json`.
      *
+     * @param keys The keys to read; must not be empty.
+     * @returns Existing items keyed by storage key. Missing keys are omitted.
      */
-    constructor(folder: string);
+    read(keys: string[]): Promise<StoreItem>;
     /**
-     * Reads store items from the filesystem storage.
-     *
-     * @param keys Array of keys to read from storage
-     * @returns Promise resolving to an object containing the requested items (keys that don't exist are omitted)
-     * @throws ReferenceError if keys array is empty or undefined
-     *
-     * @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.
+     * Writes legacy items to `state.json`.
      *
+     * @param changes The items to write, keyed by storage key.
+     * @throws If `changes` is invalid or the file cannot be written.
      */
-    read(keys: string[]): Promise<StoreItem>;
+    write(changes: StoreItem): Promise<void>;
     /**
-     * Writes store items to the filesystem storage.
-     *
-     * @param changes Object containing key-value pairs to write to storage
-     * @returns 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.
+     * Deletes legacy items from `state.json`.
      *
+     * @param keys The keys to delete; must not be empty. Missing keys are ignored.
      */
-    write(changes: StoreItem, options?: StorageWriteOptions): Promise<void>;
+    delete(keys: string[]): Promise<void>;
+}
+/**
+ * A file-backed provider for the structured {@link StorageV2} contract.
+ *
+ * This is the V2 counterpart to {@link FileStorage}. Values are stored in `state.json`, while
+ * generated storage versions are stored separately in `state.versions.json`; an `eTag` property
+ * in an application value is therefore preserved. Reads and mutations return a result for every
+ * requested key and support create-only, replace, and expected-version conditions.
+ *
+ * Like {@link FileStorage}, this provider is for development, local testing, and single-instance
+ * deployments. It does not provide cross-process concurrency or multi-key atomicity.
+ */
+export declare class FileStorageV2 extends StorageV2 {
+    private readonly internals;
     /**
-     * Deletes store items from the filesystem storage.
+     * Creates a V2 file storage provider.
      *
-     * @param keys Array of keys to delete from storage
-     * @returns Promise that resolves when the delete operation completes
+     * @param folder The absolute or relative folder where `state.json` is stored.
+     * @throws May throw filesystem errors if the folder or state file cannot be created or read.
+     */
+    constructor(folder: string);
+    /**
+     * Reads items and their stored versions from the local state files.
      *
-     * @throws ReferenceError if keys array is empty or undefined
+     * @param keys The keys to read. Empty batches are valid.
+     * @returns A result for every key, with `notFound` for missing items. Returned values are cloned.
+     */
+    read<T extends object = Record<string, unknown>>(keys: string[]): Promise<StorageReadResults<T>>;
+    /**
+     * Writes cloned items and generated versions to the local state files.
      *
-     * @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.
+     * @param changes The values to write, keyed by storage key.
+     * @param options Create-only, replace, or expected-version conditions.
+     * @returns A result for every supplied key, including concurrency-condition outcomes.
+     */
+    write<T extends object = Record<string, unknown>>(changes: Record<string, T>, options?: StorageWriteOptions): Promise<StorageWriteResults>;
+    /**
+     * Deletes items and their versions from the local state files.
      *
+     * @param keys The keys to delete. Empty batches are valid.
+     * @param options An optional expected storage version.
+     * @returns A result for every supplied key.
      */
-    delete(keys: string[]): Promise<void>;
-    private isExpired;
-    private writeFiles;
+    delete(keys: string[], options?: StorageDeleteOptions): Promise<StorageDeleteResults>;
 }
+export {};