@fgv/ts-web-extras 5.0.2 → 5.1.0-0

package/dist/ts-web-extras.d.ts

@@ -9,15 +9,82 @@
  * @packageDocumentation
  */
 
+import { CryptoUtils as CryptoUtils_2 } from '@fgv/ts-extras';
+import { DetailedResult } from '@fgv/ts-utils';
 import { FileTree } from '@fgv/ts-json-base';
 import { Result } from '@fgv/ts-utils';
 
+/**
+ * Browser implementation of `ICryptoProvider` using the Web Crypto API.
+ * Uses AES-256-GCM for authenticated encryption.
+ *
+ * Note: This provider requires a browser environment with Web Crypto API support.
+ * In Node.js 15+, Web Crypto is available via globalThis.crypto or require('crypto').webcrypto.
+ *
+ * @public
+ */
+declare class BrowserCryptoProvider implements ICryptoProvider {
+    private readonly _crypto;
+    /**
+     * Creates a new {@link CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider}.
+     * @param cryptoApi - Optional Crypto instance (defaults to globalThis.crypto)
+     */
+    constructor(cryptoApi?: Crypto);
+    /**
+     * Encrypts plaintext using AES-256-GCM.
+     * @param plaintext - UTF-8 string to encrypt
+     * @param key - 32-byte encryption key
+     * @returns `Success` with encryption result, or `Failure` with an error.
+     */
+    encrypt(plaintext: string, key: Uint8Array): Promise<Result<IEncryptionResult>>;
+    /**
+     * Decrypts ciphertext using AES-256-GCM.
+     * @param encryptedData - Encrypted bytes
+     * @param key - 32-byte decryption key
+     * @param iv - Initialization vector (12 bytes)
+     * @param authTag - GCM authentication tag (16 bytes)
+     * @returns `Success` with decrypted UTF-8 string, or `Failure` with an error.
+     */
+    decrypt(encryptedData: Uint8Array, key: Uint8Array, iv: Uint8Array, authTag: Uint8Array): Promise<Result<string>>;
+    /**
+     * Generates a random 32-byte key suitable for AES-256.
+     * @returns Success with generated key, or Failure with error
+     */
+    generateKey(): Promise<Result<Uint8Array>>;
+    /**
+     * Derives a key from a password using PBKDF2.
+     * @param password - Password string
+     * @param salt - Salt bytes (should be at least 16 bytes)
+     * @param iterations - Number of iterations (recommend 100000+)
+     * @returns Success with derived 32-byte key, or Failure with error
+     */
+    deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array>>;
+    /**
+     * Generates cryptographically secure random bytes.
+     * @param length - Number of bytes to generate
+     * @returns Success with random bytes, or Failure with error
+     */
+    generateRandomBytes(length: number): Result<Uint8Array>;
+    /**
+     * Encodes binary data to base64 string.
+     * @param data - Binary data to encode
+     * @returns Base64-encoded string
+     */
+    toBase64(data: Uint8Array): string;
+    /**
+     * Decodes base64 string to binary data.
+     * @param base64 - Base64-encoded string
+     * @returns Success with decoded bytes, or Failure if invalid base64
+     */
+    fromBase64(base64: string): Result<Uint8Array>;
+}
+
 /**
  * Browser-compatible hash provider using the Web Crypto API.
  * Supports common hash algorithms available in browsers.
  * @public
  */
-export declare class BrowserHashProvider {
+declare class BrowserHashProvider {
     /**
      * Hash a string using the specified algorithm.
      * @param data - The string to hash
@@ -35,12 +102,83 @@ export declare class BrowserHashProvider {
     static hashParts(parts: string[], algorithm?: string, separator?: string): Promise<Result<string>>;
 }
 
+/**
+ * Creates a {@link CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider} if Web
+ * Crypto API is available.
+ * @returns `Success` with provider, or `Failure` if not available
+ * @public
+ */
+declare function createBrowserCryptoProvider(): Result<BrowserCryptoProvider>;
+
+declare namespace CryptoUtils {
+    export {
+        BrowserHashProvider,
+        createBrowserCryptoProvider,
+        BrowserCryptoProvider
+    }
+}
+export { CryptoUtils }
+
+/**
+ * Default IndexedDB database name for directory handles.
+ * @public
+ */
+export declare const DEFAULT_DIRECTORY_HANDLE_DB = "chocolate-lab-storage";
+
+/**
+ * Default IndexedDB store name for directory handles.
+ * @public
+ */
+export declare const DEFAULT_DIRECTORY_HANDLE_STORE = "directory-handles";
+
 /**
  * Default initialization parameters for a `FileTree` using {@link FileApiTreeAccessors}.
  * @public
  */
 declare const defaultFileApiTreeInitParams: FileTree.IFileTreeInitParams<string>;
 
+/**
+ * Manages persistence of {@link FileSystemDirectoryHandle} objects in IndexedDB.
+ * Keyed by a label (typically the directory name).
+ * @public
+ */
+export declare class DirectoryHandleStore {
+    private readonly _store;
+    constructor(dbName?: string, storeName?: string);
+    /**
+     * Saves a directory handle to IndexedDB under the given label.
+     * @param label - Key to store the handle under (typically dirHandle.name)
+     * @param handle - The FileSystemDirectoryHandle to persist
+     * @returns Success or Failure
+     */
+    save(label: string, handle: FileSystemDirectoryHandle_2): Promise<Result<void>>;
+    /**
+     * Retrieves a directory handle by label.
+     * @param label - Key to look up
+     * @returns Success with handle (or undefined if not found), or Failure on error
+     */
+    load(label: string): Promise<Result<FileSystemDirectoryHandle_2 | undefined>>;
+    /**
+     * Removes a directory handle from IndexedDB.
+     * @param label - Key to remove
+     * @returns Success or Failure
+     */
+    remove(label: string): Promise<Result<void>>;
+    /**
+     * Returns all stored labels (keys).
+     * @returns Success with array of labels, or Failure
+     */
+    getAllLabels(): Promise<Result<string[]>>;
+    /**
+     * Returns all stored handles as label/handle pairs.
+     * @returns Success with array of entries, or Failure
+     */
+    getAll(): Promise<Result<Array<{
+        label: string;
+        handle: FileSystemDirectoryHandle_2;
+    }>>>;
+}
+
 /**
  * Export data as JSON file using legacy blob download method.
  * Creates a temporary download link and triggers file download.
@@ -91,6 +229,61 @@ declare function extractFileListMetadata(fileList: FileList): Array<IFileMetadat
   * @public
   */
  export declare class FileApiTreeAccessors<TCT extends string = string> {
+     /**
+      * Create a persistent FileTree from a File System Access API directory handle.
+      * Changes to files can be synced back to disk.
+      *
+      * @param dirHandle - FileSystemDirectoryHandle to load files from
+      * @param params - Optional parameters including autoSync and permission settings
+      * @returns Promise resolving to a FileTree with persistence capability
+      *
+      * @remarks
+      * - Only works in browsers supporting File System Access API (Chrome, Edge, Opera)
+      * - Requires 'readwrite' permission on the directory handle
+      * - Falls back to read-only mode if permissions unavailable (unless requireWritePermission is true)
+      *
+      * @public
+      */
+     static createPersistent<TCT extends string = string>(dirHandle: FileSystemDirectoryHandle_2, params?: IFileSystemAccessTreeParams<TCT>): Promise<Result<FileTree.FileTree<TCT>>>;
+     /**
+      * Create a persistent FileTree from a single File System Access API file handle.
+      * The tree contains exactly one file at `/<filename>`.
+      * Changes can be synced back to the original file via `syncToDisk()`.
+      *
+      * @param fileHandle - FileSystemFileHandle to load
+      * @param params - Optional parameters including autoSync and permission settings
+      * @returns Promise resolving to a FileTree with persistence capability
+      * @public
+      */
+     static createPersistentFromFile<TCT extends string = string>(fileHandle: FileSystemFileHandle_2, params?: IFileSystemAccessTreeParams<TCT>): Promise<Result<FileTree.FileTree<TCT>>>;
+     /**
+      * Create a persistent FileTree from browser localStorage.
+      * Changes to files can be synced back to localStorage.
+      *
+      * @param params - Configuration including path-to-key mappings and optional autoSync
+      * @returns Result containing a FileTree with persistence capability
+      *
+      * @remarks
+      * - Works in all browsers with localStorage support
+      * - Maps directory paths to localStorage keys
+      * - Each key stores multiple collections as JSON
+      * - Files are automatically discovered from storage
+      *
+      * @example
+      * ```typescript
+      * const tree = FileApiTreeAccessors.createFromLocalStorage({
+      *   pathToKeyMap: {
+      *     '/data/ingredients': 'myapp:ingredients:v1',
+      *     '/data/fillings': 'myapp:fillings:v1'
+      *   },
+      *   mutable: true,
+      *   autoSync: false
+      * });
+      * ```
+      *
+      * @public
+      */
+     static createFromLocalStorage<TCT extends string = string>(params: ILocalStorageTreeParams<TCT>): Result<FileTree.FileTree<TCT>>;
      /**
       * Create FileTree from various file sources using TreeInitializer array.
       * @param initializers - Array of TreeInitializer objects specifying file sources
@@ -180,6 +373,114 @@ declare function extractFileListMetadata(fileList: FileList): Array<IFileMetadat
      accept: Record<string, string | string[]>;
  }
 
+ /**
+  * Implementation of `FileTree.IPersistentFileTreeAccessors` that uses the File System Access API
+  * to provide persistent file editing in browsers.
+  * @public
+  */
+ export declare class FileSystemAccessTreeAccessors<TCT extends string = string> extends FileTree.InMemoryTreeAccessors<TCT> implements FileTree.IPersistentFileTreeAccessors<TCT> {
+     private readonly _handles;
+     private readonly _rootDir;
+     private readonly _dirtyFiles;
+     private readonly _autoSync;
+     private readonly _hasWritePermission;
+     /**
+      * Protected constructor for FileSystemAccessTreeAccessors.
+      * @param files - An array of in-memory files to include in the tree.
+      * @param rootDir - The root directory handle.
+      * @param handles - Map of file paths to their handles.
+      * @param params - Optional params for the tree.
+      * @param hasWritePermission - Whether write permission was granted.
+      */
+     protected constructor(files: FileTree.IInMemoryFile<TCT>[], rootDir: FileSystemDirectoryHandle_2, handles: Map<string, FileSystemFileHandle_2>, params: IFileSystemAccessTreeParams<TCT> | undefined, hasWritePermission: boolean);
+     /**
+      * Creates a new FileSystemAccessTreeAccessors instance from a directory handle.
+      * @param dirHandle - The FileSystemDirectoryHandle to load files from.
+      * @param params - Optional parameters including autoSync and permission settings.
+      * @returns Promise resolving to a FileSystemAccessTreeAccessors instance.
+      * @public
+      */
+     static fromDirectoryHandle<TCT extends string = string>(dirHandle: FileSystemDirectoryHandle_2, params?: IFileSystemAccessTreeParams<TCT>): Promise<Result<FileSystemAccessTreeAccessors<TCT>>>;
+     /**
+      * Creates a new FileSystemAccessTreeAccessors instance from a single file handle.
+      *
+      * The resulting tree contains exactly one file at `/<filename>`.
+      * `syncToDisk()` writes changes back to the original file via the File System Access API.
+      * New file creation is not supported on this tree (no parent directory handle).
+      *
+      * @param fileHandle - The FileSystemFileHandle to load.
+      * @param params - Optional parameters including autoSync and permission settings.
+      * @returns Promise resolving to a FileSystemAccessTreeAccessors instance.
+      * @public
+      */
+     static fromFileHandle<TCT extends string = string>(fileHandle: FileSystemFileHandle_2, params?: IFileSystemAccessTreeParams<TCT>): Promise<Result<FileSystemAccessTreeAccessors<TCT>>>;
+     /**
+      * Check if the directory handle has write permission.
+      * @param handle - The directory handle to check.
+      * @returns Promise resolving to true if write permission is granted.
+      * @internal
+      */
+     private static _checkWritePermission;
+     /**
+      * Check if the file handle has write permission.
+      * @param handle - The file handle to check.
+      * @returns Promise resolving to true if write permission is granted.
+      * @internal
+      */
+     private static _checkFileWritePermission;
+     /**
+      * Load all files from a directory handle recursively.
+      * @param dirHandle - The directory handle to load from.
+      * @param basePath - The base path for files.
+      * @param params - Optional parameters.
+      * @returns Promise resolving to files and handles.
+      * @internal
+      */
+     private static _loadDirectory;
+     /**
+      * Join path segments.
+      * @param base - The base path.
+      * @param name - The name to append.
+      * @returns The joined path.
+      * @internal
+      */
+     private static _joinPath;
+     /**
+      * Implements `FileTree.IPersistentFileTreeAccessors.syncToDisk`
+      */
+     syncToDisk(): Promise<Result<void>>;
+     /**
+      * Implements `FileTree.IPersistentFileTreeAccessors.isDirty`
+      */
+     isDirty(): boolean;
+     /**
+      * Implements `FileTree.IPersistentFileTreeAccessors.getDirtyPaths`
+      */
+     getDirtyPaths(): string[];
+     /**
+      * Implements `FileTree.IMutableFileTreeAccessors.saveFileContents`
+      */
+     saveFileContents(path: string, contents: string): Result<string>;
+     /**
+      * Implements `FileTree.IMutableFileTreeAccessors.fileIsMutable`
+      */
+     fileIsMutable(path: string): DetailedResult<boolean, FileTree.SaveDetail>;
+     /**
+      * Sync a single file to disk.
+      * @param path - The path of the file to sync.
+      * @returns Promise resolving to success or failure.
+      * @internal
+      */
+     private _syncFile;
+     /**
+      * Create a new file and write its contents.
+      * @param path - The path of the file to create.
+      * @returns Promise resolving to success or failure.
+      * @internal
+      */
+     private _createAndWriteFile;
+ }
+
  /**
   * Options for creating writable file streams
   * @public
@@ -327,6 +628,8 @@ declare function extractFileListMetadata(fileList: FileList): Array<IFileMetadat
   */
  declare function getOriginalFile(fileList: FileList, path: string): Result<File>;
 
+ declare type ICryptoProvider = CryptoUtils_2.ICryptoProvider;
+
  /**
   * Tree initializer for File System Access API directory handles.
   * @public
@@ -337,6 +640,8 @@ declare function extractFileListMetadata(fileList: FileList): Array<IFileMetadat
      readonly nonRecursive?: boolean;
  }
 
+ declare type IEncryptionResult = CryptoUtils_2.IEncryptionResult;
+
  /**
   * Tree initializer for File System Access API file handles.
   * @public
@@ -366,6 +671,32 @@ declare function extractFileListMetadata(fileList: FileList): Array<IFileMetadat
      lastModified: number;
  }
 
+ /**
+  * Options for creating persistent file trees.
+  * @public
+  */
+ export declare interface IFileSystemAccessTreeParams<TCT extends string = string> extends FileTree.IFileTreeInitParams<TCT> {
+     /**
+      * Automatically sync changes to disk immediately after each save.
+      * If false, changes are batched and written on explicit syncToDisk() call.
+      * @defaultValue false
+      */
+     autoSync?: boolean;
+     /**
+      * Require write permission on the directory handle.
+      * If true, fails if write permission cannot be obtained.
+      * If false, falls back to read-only mode.
+      * @defaultValue true
+      */
+     requireWritePermission?: boolean;
+     /**
+      * Override the path at which the file is stored in the tree (for fromFileHandle).
+      * Must be an absolute path (e.g., '/data/confections/common.yaml').
+      * If omitted, defaults to `/<filename>`.
+      */
+     filePath?: string;
+ }
+
  /**
   * File System Access API methods available on Window
   * @public
@@ -376,6 +707,29 @@ declare function extractFileListMetadata(fileList: FileList): Array<IFileMetadat
      showSaveFilePicker(options?: ShowSaveFilePickerOptions): Promise<FileSystemFileHandle_2>;
  }
 
+ /**
+  * Configuration for LocalStorageTreeAccessors.
+  * @public
+  */
+ export declare interface ILocalStorageTreeParams<TCT extends string = string> extends FileTree.IFileTreeInitParams<TCT> {
+     /**
+      * Map of directory path prefixes to localStorage keys.
+      * Files under each prefix are stored in the corresponding localStorage key.
+      * Example: \{ '/data/ingredients': 'myapp:ingredients:v1' \}
+      */
+     pathToKeyMap: Record<string, string>;
+     /**
+      * Storage instance to use. Defaults to window.localStorage.
+      * Can be overridden for testing with mock storage.
+      */
+     storage?: Storage;
+     /**
+      * If true, automatically sync changes to localStorage on every modification.
+      * If false (default), changes are only synced when syncToDisk() is called.
+      */
+     autoSync?: boolean;
+ }
+
  /**
   * Type guard to check if a FileSystemHandle is a directory handle
   * @param handle - The handle to check
@@ -457,6 +811,111 @@ declare function extractFileListMetadata(fileList: FileList): Array<IFileMetadat
      zipFile?: string;
  }
 
+ /**
+  * Browser localStorage-backed file tree accessors with persistence support.
+  *
+  * Maps filesystem-like directory paths to localStorage keys, where each key stores
+  * multiple collections as a JSON object. This provides a general-purpose implementation
+  * for browser-based file tree persistence without requiring File System Access API.
+  *
+  * Storage format per key: `{ "collection-id": "<raw file content>" }`
+  * File paths map as: `/data/ingredients/collection-id.yaml` → stored in key for `/data/ingredients`
+  *
+  * Legacy format (v1): `{ "collection-id": { ...parsedJsonObject } }` is auto-migrated on load.
+  *
+  * @public
+  */
+ export declare class LocalStorageTreeAccessors<TCT extends string = string> extends FileTree.InMemoryTreeAccessors<TCT> implements FileTree.IPersistentFileTreeAccessors<TCT> {
+     private readonly _storage;
+     private readonly _pathToKeyMap;
+     private readonly _keyToPathMap;
+     private readonly _dirtyFiles;
+     private readonly _autoSync;
+     /**
+      * Private constructor. Use fromStorage() factory method instead.
+      * @internal
+      */
+     private constructor();
+     /**
+      * Create LocalStorageTreeAccessors from browser localStorage.
+      * Loads all collections from the configured storage keys.
+      *
+      * @param params - Configuration including path-to-key mappings
+      * @returns Result containing the accessors or an error
+      * @public
+      */
+     static fromStorage<TCT extends string = string>(params: ILocalStorageTreeParams<TCT>): Result<LocalStorageTreeAccessors<TCT>>;
+     /**
+      * Load all files from localStorage based on path-to-key mappings.
+      * @internal
+      */
+     private static _loadFromStorage;
+     /**
+      * Heuristic check: does the content look like JSON?
+      * @internal
+      */
+     private static _looksLikeJson;
+     /**
+      * Join path components, handling leading/trailing slashes.
+      * @internal
+      */
+     private static _joinPath;
+     /**
+      * Get the storage key for a given file path.
+      * @internal
+      */
+     private _getStorageKeyForPath;
+     /**
+      * Get the data path prefix for a given file path.
+      * @internal
+      */
+     private _getDataPathForPath;
+     /**
+      * Extract collection ID from a file path.
+      * Example: '/data/ingredients/my-collection.yaml' → 'my-collection'
+      * @internal
+      */
+     private _getCollectionIdFromPath;
+     /**
+      * Sync a single dirty file to localStorage.
+      * @internal
+      */
+     private _syncFile;
+     /**
+      * Sync all dirty files to localStorage.
+      * @returns Result indicating success or failure
+      * @public
+      */
+     syncToDisk(): Promise<Result<void>>;
+     /**
+      * Check if there are unsaved changes.
+      * @returns True if there are dirty files
+      * @public
+      */
+     isDirty(): boolean;
+     /**
+      * Get list of file paths with unsaved changes.
+      * @returns Array of dirty file paths
+      * @public
+      */
+     getDirtyPaths(): string[];
+     /**
+      * Save file contents. Marks file as dirty and optionally auto-syncs.
+      * @param path - File path
+      * @param contents - New file contents
+      * @returns Result with the saved contents or error
+      * @public
+      */
+     saveFileContents(path: string, contents: string): Result<string>;
+     /**
+      * Check if a file is mutable and return persistence detail.
+      * @param path - File path to check
+      * @returns DetailedResult with mutability status and 'persistent' detail if mutable
+      * @public
+      */
+     fileIsMutable(path: string): DetailedResult<boolean, FileTree.SaveDetail>;
+ }
+
  /**
   * Converts context filter token to context object
   * Example: "language=en-US|territory=US" -\> \{ language: "en-US", territory: "US" \}

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.54.0"
+      "packageVersion": "7.57.6"
     }
   ]
 }

package/docs/ts-web-extras.cryptoutils.browsercryptoprovider._constructor_.md

@@ -0,0 +1,50 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@fgv/ts-web-extras](./ts-web-extras.md) &gt; [CryptoUtils](./ts-web-extras.cryptoutils.md) &gt; [BrowserCryptoProvider](./ts-web-extras.cryptoutils.browsercryptoprovider.md) &gt; [(constructor)](./ts-web-extras.cryptoutils.browsercryptoprovider._constructor_.md)
+
+## CryptoUtils.BrowserCryptoProvider.(constructor)
+
+Creates a new [BrowserCryptoProvider](./ts-web-extras.cryptoutils.browsercryptoprovider.md)<!-- -->.
+
+**Signature:**
+
+```typescript
+constructor(cryptoApi?: Crypto);
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+cryptoApi
+
+
+</td><td>
+
+Crypto
+
+
+</td><td>
+
+_(Optional)_ Optional Crypto instance (defaults to globalThis.crypto)
+
+
+</td></tr>
+</tbody></table>
+

package/docs/ts-web-extras.cryptoutils.browsercryptoprovider.decrypt.md

@@ -0,0 +1,104 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@fgv/ts-web-extras](./ts-web-extras.md) &gt; [CryptoUtils](./ts-web-extras.cryptoutils.md) &gt; [BrowserCryptoProvider](./ts-web-extras.cryptoutils.browsercryptoprovider.md) &gt; [decrypt](./ts-web-extras.cryptoutils.browsercryptoprovider.decrypt.md)
+
+## CryptoUtils.BrowserCryptoProvider.decrypt() method
+
+Decrypts ciphertext using AES-256-GCM.
+
+**Signature:**
+
+```typescript
+decrypt(encryptedData: Uint8Array, key: Uint8Array, iv: Uint8Array, authTag: Uint8Array): Promise<Result<string>>;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+encryptedData
+
+
+</td><td>
+
+Uint8Array
+
+
+</td><td>
+
+Encrypted bytes
+
+
+</td></tr>
+<tr><td>
+
+key
+
+
+</td><td>
+
+Uint8Array
+
+
+</td><td>
+
+32-byte decryption key
+
+
+</td></tr>
+<tr><td>
+
+iv
+
+
+</td><td>
+
+Uint8Array
+
+
+</td><td>
+
+Initialization vector (12 bytes)
+
+
+</td></tr>
+<tr><td>
+
+authTag
+
+
+</td><td>
+
+Uint8Array
+
+
+</td><td>
+
+GCM authentication tag (16 bytes)
+
+
+</td></tr>
+</tbody></table>
+
+**Returns:**
+
+Promise&lt;Result&lt;string&gt;&gt;
+
+`Success` with decrypted UTF-8 string, or `Failure` with an error.
+