@fgv/ts-web-extras 5.1.0-1 → 5.1.0-10

package/docs/FileTreeHelpers/variables/defaultFileApiTreeInitParams.md

@@ -0,0 +1,9 @@
+[Home](../../README.md) > [FileTreeHelpers](../README.md) > defaultFileApiTreeInitParams
+
+# Variable: defaultFileApiTreeInitParams
+
+Default initialization parameters for a `FileTree` using FileApiTreeAccessors.
+
+## Type
+
+`FileTree.IFileTreeInitParams<string>`

package/docs/README.md

@@ -1,7 +1,3 @@
-**@fgv/ts-web-extras**
-
-***
-
 # @fgv/ts-web-extras
 
 Browser-compatible utilities and FileTree implementations.
@@ -13,66 +9,516 @@ All exports are designed to be tree-shakeable for optimal bundle size.
 
 ## Namespaces
 
-- [CryptoUtils](@fgv/namespaces/CryptoUtils/README.md)
-- [FileTreeHelpers](@fgv/namespaces/FileTreeHelpers/README.md)
+<table><thead><tr><th>
+
+Name
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody>
+<tr><td>
+
+[CryptoUtils](./CryptoUtils/README.md)
+
+</td><td>
+
+Browser-compatible cryptographic utilities using the Web Crypto API.
+
+</td></tr>
+<tr><td>
+
+[FileTreeHelpers](./FileTreeHelpers/README.md)
+
+</td><td>
+
+
+
+</td></tr>
+</tbody></table>
 
 ## Classes
 
-- [DirectoryHandleStore](classes/DirectoryHandleStore.md)
-- [FileApiTreeAccessors](classes/FileApiTreeAccessors.md)
-- [FileSystemAccessTreeAccessors](classes/FileSystemAccessTreeAccessors.md)
-- [HttpTreeAccessors](classes/HttpTreeAccessors.md)
-- [LocalStorageTreeAccessors](classes/LocalStorageTreeAccessors.md)
+<table><thead><tr><th>
+
+Name
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody>
+<tr><td>
+
+[DirectoryHandleStore](./classes/DirectoryHandleStore.md)
+
+</td><td>
+
+Manages persistence of FileSystemDirectoryHandle objects in IndexedDB.
+
+</td></tr>
+<tr><td>
+
+[FileApiTreeAccessors](./classes/FileApiTreeAccessors.md)
+
+</td><td>
+
+Helper class to create FileTree instances from various file sources.
+
+</td></tr>
+<tr><td>
+
+[FileSystemAccessTreeAccessors](./classes/FileSystemAccessTreeAccessors.md)
+
+</td><td>
+
+Implementation of `FileTree.IPersistentFileTreeAccessors` that uses the File System Access API
+
+</td></tr>
+<tr><td>
+
+[HttpTreeAccessors](./classes/HttpTreeAccessors.md)
+
+</td><td>
+
+HTTP-backed file tree accessors that cache data in memory and persist via REST API.
+
+</td></tr>
+<tr><td>
+
+[LocalStorageTreeAccessors](./classes/LocalStorageTreeAccessors.md)
+
+</td><td>
+
+Browser localStorage-backed file tree accessors with persistence support.
+
+</td></tr>
+</tbody></table>
 
 ## Interfaces
 
-- [FilePickerAcceptType](interfaces/FilePickerAcceptType.md)
-- [FileSystemCreateWritableOptions](interfaces/FileSystemCreateWritableOptions.md)
-- [FileSystemDirectoryHandle](interfaces/FileSystemDirectoryHandle.md)
-- [FileSystemFileHandle](interfaces/FileSystemFileHandle.md)
-- [FileSystemGetDirectoryOptions](interfaces/FileSystemGetDirectoryOptions.md)
-- [FileSystemGetFileOptions](interfaces/FileSystemGetFileOptions.md)
-- [FileSystemHandle](interfaces/FileSystemHandle.md)
-- [FileSystemHandlePermissionDescriptor](interfaces/FileSystemHandlePermissionDescriptor.md)
-- [FileSystemRemoveOptions](interfaces/FileSystemRemoveOptions.md)
-- [FileSystemWritableFileStream](interfaces/FileSystemWritableFileStream.md)
-- [IDirectoryHandleTreeInitializer](interfaces/IDirectoryHandleTreeInitializer.md)
-- [IFileHandleTreeInitializer](interfaces/IFileHandleTreeInitializer.md)
-- [IFileListTreeInitializer](interfaces/IFileListTreeInitializer.md)
-- [IFileMetadata](interfaces/IFileMetadata.md)
-- [IFileSystemAccessTreeParams](interfaces/IFileSystemAccessTreeParams.md)
-- [IFsAccessApis](interfaces/IFsAccessApis.md)
-- [IHttpTreeParams](interfaces/IHttpTreeParams.md)
-- [ILocalStorageTreeParams](interfaces/ILocalStorageTreeParams.md)
-- [IUrlConfigOptions](interfaces/IUrlConfigOptions.md)
-- [ShowDirectoryPickerOptions](interfaces/ShowDirectoryPickerOptions.md)
-- [ShowOpenFilePickerOptions](interfaces/ShowOpenFilePickerOptions.md)
-- [ShowSaveFilePickerOptions](interfaces/ShowSaveFilePickerOptions.md)
+<table><thead><tr><th>
+
+Name
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody>
+<tr><td>
+
+[IFileListTreeInitializer](./interfaces/IFileListTreeInitializer.md)
+
+</td><td>
+
+Tree initializer for FileList objects (from File API).
+
+</td></tr>
+<tr><td>
+
+[IFileHandleTreeInitializer](./interfaces/IFileHandleTreeInitializer.md)
+
+</td><td>
+
+Tree initializer for File System Access API file handles.
+
+</td></tr>
+<tr><td>
+
+[IDirectoryHandleTreeInitializer](./interfaces/IDirectoryHandleTreeInitializer.md)
+
+</td><td>
+
+Tree initializer for File System Access API directory handles.
+
+</td></tr>
+<tr><td>
+
+[IFileMetadata](./interfaces/IFileMetadata.md)
+
+</td><td>
+
+Interface for file metadata.
+
+</td></tr>
+<tr><td>
+
+[IFileSystemAccessTreeParams](./interfaces/IFileSystemAccessTreeParams.md)
+
+</td><td>
+
+Options for creating persistent file trees.
+
+</td></tr>
+<tr><td>
+
+[IHttpTreeParams](./interfaces/IHttpTreeParams.md)
+
+</td><td>
+
+Configuration for creating HTTP-backed tree accessors.
+
+</td></tr>
+<tr><td>
+
+[ILocalStorageTreeParams](./interfaces/ILocalStorageTreeParams.md)
+
+</td><td>
+
+Configuration for LocalStorageTreeAccessors.
+
+</td></tr>
+<tr><td>
+
+[IFsAccessApis](./interfaces/IFsAccessApis.md)
+
+</td><td>
+
+File System Access API methods available on Window
+
+</td></tr>
+<tr><td>
+
+[FileSystemHandle](./interfaces/FileSystemHandle.md)
+
+</td><td>
+
+Base interface for file system handles
+
+</td></tr>
+<tr><td>
+
+[FileSystemFileHandle](./interfaces/FileSystemFileHandle.md)
+
+</td><td>
+
+File handle interface
+
+</td></tr>
+<tr><td>
+
+[FileSystemDirectoryHandle](./interfaces/FileSystemDirectoryHandle.md)
+
+</td><td>
+
+Directory handle interface
+
+</td></tr>
+<tr><td>
+
+[FileSystemHandlePermissionDescriptor](./interfaces/FileSystemHandlePermissionDescriptor.md)
+
+</td><td>
+
+Permission descriptor for file system handles
+
+</td></tr>
+<tr><td>
+
+[FileSystemCreateWritableOptions](./interfaces/FileSystemCreateWritableOptions.md)
+
+</td><td>
+
+Options for creating writable file streams
+
+</td></tr>
+<tr><td>
+
+[FileSystemGetDirectoryOptions](./interfaces/FileSystemGetDirectoryOptions.md)
+
+</td><td>
+
+Options for getting directory handles
+
+</td></tr>
+<tr><td>
+
+[FileSystemGetFileOptions](./interfaces/FileSystemGetFileOptions.md)
+
+</td><td>
+
+Options for getting file handles
+
+</td></tr>
+<tr><td>
+
+[FileSystemRemoveOptions](./interfaces/FileSystemRemoveOptions.md)
+
+</td><td>
+
+Options for removing entries
+
+</td></tr>
+<tr><td>
+
+[FileSystemWritableFileStream](./interfaces/FileSystemWritableFileStream.md)
+
+</td><td>
+
+Writable file stream interface
+
+</td></tr>
+<tr><td>
+
+[ShowDirectoryPickerOptions](./interfaces/ShowDirectoryPickerOptions.md)
+
+</td><td>
+
+Directory picker options
+
+</td></tr>
+<tr><td>
+
+[ShowOpenFilePickerOptions](./interfaces/ShowOpenFilePickerOptions.md)
+
+</td><td>
+
+File picker options
+
+</td></tr>
+<tr><td>
+
+[ShowSaveFilePickerOptions](./interfaces/ShowSaveFilePickerOptions.md)
+
+</td><td>
+
+Save file picker options
+
+</td></tr>
+<tr><td>
+
+[FilePickerAcceptType](./interfaces/FilePickerAcceptType.md)
+
+</td><td>
+
+File picker accept type
+
+</td></tr>
+<tr><td>
+
+[IUrlConfigOptions](./interfaces/IUrlConfigOptions.md)
+
+</td><td>
+
+Configuration options that can be passed via URL parameters
+
+</td></tr>
+</tbody></table>
 
 ## Type Aliases
 
-- [TreeInitializer](type-aliases/TreeInitializer.md)
-- [WellKnownDirectory](type-aliases/WellKnownDirectory.md)
-- [WindowWithFsAccess](type-aliases/WindowWithFsAccess.md)
+<table><thead><tr><th>
 
-## Variables
+Name
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody>
+<tr><td>
+
+[TreeInitializer](./type-aliases/TreeInitializer.md)
+
+</td><td>
+
+Union type for all supported tree initializers.
+
+</td></tr>
+<tr><td>
 
-- [DEFAULT\_DIRECTORY\_HANDLE\_DB](variables/DEFAULT_DIRECTORY_HANDLE_DB.md)
-- [DEFAULT\_DIRECTORY\_HANDLE\_STORE](variables/DEFAULT_DIRECTORY_HANDLE_STORE.md)
+[WindowWithFsAccess](./type-aliases/WindowWithFsAccess.md)
+
+</td><td>
+
+Window interface extended with File System Access API
+
+</td></tr>
+<tr><td>
+
+[WellKnownDirectory](./type-aliases/WellKnownDirectory.md)
+
+</td><td>
+
+Well-known directory type
+
+</td></tr>
+</tbody></table>
 
 ## Functions
 
-- [exportAsJson](functions/exportAsJson.md)
-- [exportUsingFileSystemAPI](functions/exportUsingFileSystemAPI.md)
-- [extractDirectoryPath](functions/extractDirectoryPath.md)
-- [isDirectoryHandle](functions/isDirectoryHandle.md)
-- [isFileHandle](functions/isFileHandle.md)
-- [isFilePath](functions/isFilePath.md)
-- [parseContextFilter](functions/parseContextFilter.md)
-- [parseQualifierDefaults](functions/parseQualifierDefaults.md)
-- [parseResourceTypes](functions/parseResourceTypes.md)
-- [parseUrlParameters](functions/parseUrlParameters.md)
-- [safeShowDirectoryPicker](functions/safeShowDirectoryPicker.md)
-- [safeShowOpenFilePicker](functions/safeShowOpenFilePicker.md)
-- [safeShowSaveFilePicker](functions/safeShowSaveFilePicker.md)
-- [supportsFileSystemAccess](functions/supportsFileSystemAccess.md)
+<table><thead><tr><th>
+
+Name
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody>
+<tr><td>
+
+[supportsFileSystemAccess](./functions/supportsFileSystemAccess.md)
+
+</td><td>
+
+Type guard to check if the browser supports the File System Access API
+
+</td></tr>
+<tr><td>
+
+[isFileHandle](./functions/isFileHandle.md)
+
+</td><td>
+
+Type guard to check if a FileSystemHandle is a file handle
+
+</td></tr>
+<tr><td>
+
+[isDirectoryHandle](./functions/isDirectoryHandle.md)
+
+</td><td>
+
+Type guard to check if a FileSystemHandle is a directory handle
+
+</td></tr>
+<tr><td>
+
+[safeShowOpenFilePicker](./functions/safeShowOpenFilePicker.md)
+
+</td><td>
+
+Safely access showOpenFilePicker with proper type checking
+
+</td></tr>
+<tr><td>
+
+[safeShowSaveFilePicker](./functions/safeShowSaveFilePicker.md)
+
+</td><td>
+
+Safely access showSaveFilePicker with proper type checking
+
+</td></tr>
+<tr><td>
+
+[safeShowDirectoryPicker](./functions/safeShowDirectoryPicker.md)
+
+</td><td>
+
+Safely access showDirectoryPicker with proper type checking
+
+</td></tr>
+<tr><td>
+
+[exportAsJson](./functions/exportAsJson.md)
+
+</td><td>
+
+Export data as JSON file using legacy blob download method.
+
+</td></tr>
+<tr><td>
+
+[exportUsingFileSystemAPI](./functions/exportUsingFileSystemAPI.md)
+
+</td><td>
+
+Export data using File System Access API with fallback to blob download.
+
+</td></tr>
+<tr><td>
+
+[parseUrlParameters](./functions/parseUrlParameters.md)
+
+</td><td>
+
+Parses URL parameters and extracts configuration options
+
+</td></tr>
+<tr><td>
+
+[parseContextFilter](./functions/parseContextFilter.md)
+
+</td><td>
+
+Converts context filter token to context object
+
+</td></tr>
+<tr><td>
+
+[parseQualifierDefaults](./functions/parseQualifierDefaults.md)
+
+</td><td>
+
+Converts qualifier defaults token to structured format
+
+</td></tr>
+<tr><td>
+
+[parseResourceTypes](./functions/parseResourceTypes.md)
+
+</td><td>
+
+Converts resource types string to array
+
+</td></tr>
+<tr><td>
+
+[extractDirectoryPath](./functions/extractDirectoryPath.md)
+
+</td><td>
+
+Extracts the directory path from a file or directory path
+
+</td></tr>
+<tr><td>
+
+[isFilePath](./functions/isFilePath.md)
+
+</td><td>
+
+Determines if a path appears to be a file (has extension) or directory
+
+</td></tr>
+</tbody></table>
+
+## Variables
+
+<table><thead><tr><th>
+
+Name
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody>
+<tr><td>
+
+[DEFAULT_DIRECTORY_HANDLE_DB](./variables/DEFAULT_DIRECTORY_HANDLE_DB.md)
+
+</td><td>
+
+Default IndexedDB database name for directory handles.
+
+</td></tr>
+<tr><td>
+
+[DEFAULT_DIRECTORY_HANDLE_STORE](./variables/DEFAULT_DIRECTORY_HANDLE_STORE.md)
+
+</td><td>
+
+Default IndexedDB store name for directory handles.
+
+</td></tr>
+</tbody></table>

package/docs/classes/BrowserCryptoProvider.decrypt.md

@@ -0,0 +1,27 @@
+[Home](../README.md) > [BrowserCryptoProvider](./BrowserCryptoProvider.md) > decrypt
+
+## 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.

package/docs/classes/BrowserCryptoProvider.deriveKey.md

@@ -0,0 +1,26 @@
+[Home](../README.md) > [BrowserCryptoProvider](./BrowserCryptoProvider.md) > deriveKey
+
+## BrowserCryptoProvider.deriveKey() method
+
+Derives a key from a password using PBKDF2.
+
+**Signature:**
+
+```typescript
+deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array<ArrayBufferLike>>>;
+```
+
+**Parameters:**
+
+<table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>password</td><td>string</td><td>Password string</td></tr>
+<tr><td>salt</td><td>Uint8Array</td><td>Salt bytes (should be at least 16 bytes)</td></tr>
+<tr><td>iterations</td><td>number</td><td>Number of iterations (recommend 100000+)</td></tr>
+</tbody></table>
+
+**Returns:**
+
+Promise&lt;Result&lt;Uint8Array&lt;ArrayBufferLike&gt;&gt;&gt;
+
+Success with derived 32-byte key, or Failure with error

package/docs/classes/BrowserCryptoProvider.encrypt.md

@@ -0,0 +1,25 @@
+[Home](../README.md) > [BrowserCryptoProvider](./BrowserCryptoProvider.md) > encrypt
+
+## BrowserCryptoProvider.encrypt() method
+
+Encrypts plaintext using AES-256-GCM.
+
+**Signature:**
+
+```typescript
+encrypt(plaintext: string, key: Uint8Array): Promise<Result<IEncryptionResult>>;
+```
+
+**Parameters:**
+
+<table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>plaintext</td><td>string</td><td>UTF-8 string to encrypt</td></tr>
+<tr><td>key</td><td>Uint8Array</td><td>32-byte encryption key</td></tr>
+</tbody></table>
+
+**Returns:**
+
+Promise&lt;Result&lt;IEncryptionResult&gt;&gt;
+
+`Success` with encryption result, or `Failure` with an error.

package/docs/classes/BrowserCryptoProvider.fromBase64.md

@@ -0,0 +1,24 @@
+[Home](../README.md) > [BrowserCryptoProvider](./BrowserCryptoProvider.md) > fromBase64
+
+## BrowserCryptoProvider.fromBase64() method
+
+Decodes base64 string to binary data.
+
+**Signature:**
+
+```typescript
+fromBase64(base64: string): Result<Uint8Array<ArrayBufferLike>>;
+```
+
+**Parameters:**
+
+<table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>base64</td><td>string</td><td>Base64-encoded string</td></tr>
+</tbody></table>
+
+**Returns:**
+
+Result&lt;Uint8Array&lt;ArrayBufferLike&gt;&gt;
+
+Success with decoded bytes, or Failure if invalid base64

package/docs/classes/BrowserCryptoProvider.generateKey.md

@@ -0,0 +1,17 @@
+[Home](../README.md) > [BrowserCryptoProvider](./BrowserCryptoProvider.md) > generateKey
+
+## BrowserCryptoProvider.generateKey() method
+
+Generates a random 32-byte key suitable for AES-256.
+
+**Signature:**
+
+```typescript
+generateKey(): Promise<Result<Uint8Array<ArrayBufferLike>>>;
+```
+
+**Returns:**
+
+Promise&lt;Result&lt;Uint8Array&lt;ArrayBufferLike&gt;&gt;&gt;
+
+Success with generated key, or Failure with error