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

package/docs/CryptoUtils/README.md

@@ -0,0 +1,60 @@
+[Home](../README.md) > CryptoUtils
+
+# Namespace: CryptoUtils
+
+Browser-compatible cryptographic utilities using the Web Crypto API.
+
+## Classes
+
+<table><thead><tr><th>
+
+Name
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody>
+<tr><td>
+
+[BrowserHashProvider](./classes/BrowserHashProvider.md)
+
+</td><td>
+
+Browser-compatible hash provider using the Web Crypto API.
+
+</td></tr>
+<tr><td>
+
+[BrowserCryptoProvider](./classes/BrowserCryptoProvider.md)
+
+</td><td>
+
+Browser implementation of `ICryptoProvider` using the Web Crypto API.
+
+</td></tr>
+</tbody></table>
+
+## Functions
+
+<table><thead><tr><th>
+
+Name
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody>
+<tr><td>
+
+[createBrowserCryptoProvider](./functions/createBrowserCryptoProvider.md)
+
+</td><td>
+
+Creates a CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider if Web
+
+</td></tr>
+</tbody></table>

package/docs/CryptoUtils/classes/BrowserCryptoProvider.decrypt.md

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

@@ -0,0 +1,26 @@
+[Home](../../README.md) > [CryptoUtils](../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/CryptoUtils/classes/BrowserCryptoProvider.encrypt.md

@@ -0,0 +1,25 @@
+[Home](../../README.md) > [CryptoUtils](../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/CryptoUtils/classes/BrowserCryptoProvider.fromBase64.md

@@ -0,0 +1,24 @@
+[Home](../../README.md) > [CryptoUtils](../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/CryptoUtils/classes/BrowserCryptoProvider.generateKey.md

@@ -0,0 +1,17 @@
+[Home](../../README.md) > [CryptoUtils](../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

package/docs/CryptoUtils/classes/BrowserCryptoProvider.generateRandomBytes.md

@@ -0,0 +1,24 @@
+[Home](../../README.md) > [CryptoUtils](../README.md) > [BrowserCryptoProvider](./BrowserCryptoProvider.md) > generateRandomBytes
+
+## BrowserCryptoProvider.generateRandomBytes() method
+
+Generates cryptographically secure random bytes.
+
+**Signature:**
+
+```typescript
+generateRandomBytes(length: number): Result<Uint8Array<ArrayBufferLike>>;
+```
+
+**Parameters:**
+
+<table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>length</td><td>number</td><td>Number of bytes to generate</td></tr>
+</tbody></table>
+
+**Returns:**
+
+Result&lt;Uint8Array&lt;ArrayBufferLike&gt;&gt;
+
+Success with random bytes, or Failure with error

package/docs/CryptoUtils/classes/BrowserCryptoProvider.md

@@ -0,0 +1,151 @@
+[Home](../../README.md) > [CryptoUtils](../README.md) > BrowserCryptoProvider
+
+# Class: BrowserCryptoProvider
+
+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.
+
+**Implements:** `ICryptoProvider`
+
+## Constructors
+
+<table><thead><tr><th>
+
+Constructor
+
+</th><th>
+
+Modifiers
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody>
+<tr><td>
+
+`constructor(cryptoApi)`
+
+</td><td>
+
+
+
+</td><td>
+
+Creates a new CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider.
+
+</td></tr>
+</tbody></table>
+
+## Methods
+
+<table><thead><tr><th>
+
+Method
+
+</th><th>
+
+Modifiers
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody>
+<tr><td>
+
+[encrypt(plaintext, key)](./BrowserCryptoProvider.encrypt.md)
+
+</td><td>
+
+
+
+</td><td>
+
+Encrypts plaintext using AES-256-GCM.
+
+</td></tr>
+<tr><td>
+
+[decrypt(encryptedData, key, iv, authTag)](./BrowserCryptoProvider.decrypt.md)
+
+</td><td>
+
+
+
+</td><td>
+
+Decrypts ciphertext using AES-256-GCM.
+
+</td></tr>
+<tr><td>
+
+[generateKey()](./BrowserCryptoProvider.generateKey.md)
+
+</td><td>
+
+
+
+</td><td>
+
+Generates a random 32-byte key suitable for AES-256.
+
+</td></tr>
+<tr><td>
+
+[deriveKey(password, salt, iterations)](./BrowserCryptoProvider.deriveKey.md)
+
+</td><td>
+
+
+
+</td><td>
+
+Derives a key from a password using PBKDF2.
+
+</td></tr>
+<tr><td>
+
+[generateRandomBytes(length)](./BrowserCryptoProvider.generateRandomBytes.md)
+
+</td><td>
+
+
+
+</td><td>
+
+Generates cryptographically secure random bytes.
+
+</td></tr>
+<tr><td>
+
+[toBase64(data)](./BrowserCryptoProvider.toBase64.md)
+
+</td><td>
+
+
+
+</td><td>
+
+Encodes binary data to base64 string.
+
+</td></tr>
+<tr><td>
+
+[fromBase64(base64)](./BrowserCryptoProvider.fromBase64.md)
+
+</td><td>
+
+
+
+</td><td>
+
+Decodes base64 string to binary data.
+
+</td></tr>
+</tbody></table>

package/docs/CryptoUtils/classes/BrowserCryptoProvider.toBase64.md

@@ -0,0 +1,24 @@
+[Home](../../README.md) > [CryptoUtils](../README.md) > [BrowserCryptoProvider](./BrowserCryptoProvider.md) > toBase64
+
+## BrowserCryptoProvider.toBase64() method
+
+Encodes binary data to base64 string.
+
+**Signature:**
+
+```typescript
+toBase64(data: Uint8Array): string;
+```
+
+**Parameters:**
+
+<table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>data</td><td>Uint8Array</td><td>Binary data to encode</td></tr>
+</tbody></table>
+
+**Returns:**
+
+string
+
+Base64-encoded string

package/docs/CryptoUtils/classes/BrowserHashProvider.hashParts.md

@@ -0,0 +1,26 @@
+[Home](../../README.md) > [CryptoUtils](../README.md) > [BrowserHashProvider](./BrowserHashProvider.md) > hashParts
+
+## BrowserHashProvider.hashParts() method
+
+Hash multiple strings concatenated with a separator.
+
+**Signature:**
+
+```typescript
+static hashParts(parts: string[], algorithm: string, separator: string): Promise<Result<string>>;
+```
+
+**Parameters:**
+
+<table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>parts</td><td>string[]</td><td>Array of strings to concatenate and hash</td></tr>
+<tr><td>algorithm</td><td>string</td><td>The hash algorithm to use</td></tr>
+<tr><td>separator</td><td>string</td><td>Separator to use between parts (default: '|')</td></tr>
+</tbody></table>
+
+**Returns:**
+
+Promise&lt;Result&lt;string&gt;&gt;
+
+Promise resolving to the hex-encoded hash

package/docs/CryptoUtils/classes/BrowserHashProvider.hashString.md

@@ -0,0 +1,25 @@
+[Home](../../README.md) > [CryptoUtils](../README.md) > [BrowserHashProvider](./BrowserHashProvider.md) > hashString
+
+## BrowserHashProvider.hashString() method
+
+Hash a string using the specified algorithm.
+
+**Signature:**
+
+```typescript
+static hashString(data: string, algorithm: string): Promise<Result<string>>;
+```
+
+**Parameters:**
+
+<table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>data</td><td>string</td><td>The string to hash</td></tr>
+<tr><td>algorithm</td><td>string</td><td>The hash algorithm to use</td></tr>
+</tbody></table>
+
+**Returns:**
+
+Promise&lt;Result&lt;string&gt;&gt;
+
+Promise resolving to the hex-encoded hash

package/docs/CryptoUtils/classes/BrowserHashProvider.md

@@ -0,0 +1,81 @@
+[Home](../../README.md) > [CryptoUtils](../README.md) > BrowserHashProvider
+
+# Class: BrowserHashProvider
+
+Browser-compatible hash provider using the Web Crypto API.
+Supports common hash algorithms available in browsers.
+
+## Constructors
+
+<table><thead><tr><th>
+
+Constructor
+
+</th><th>
+
+Modifiers
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody>
+<tr><td>
+
+`constructor()`
+
+</td><td>
+
+
+
+</td><td>
+
+
+
+</td></tr>
+</tbody></table>
+
+## Methods
+
+<table><thead><tr><th>
+
+Method
+
+</th><th>
+
+Modifiers
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody>
+<tr><td>
+
+[hashString(data, algorithm)](./BrowserHashProvider.hashString.md)
+
+</td><td>
+
+`static`
+
+</td><td>
+
+Hash a string using the specified algorithm.
+
+</td></tr>
+<tr><td>
+
+[hashParts(parts, algorithm, separator)](./BrowserHashProvider.hashParts.md)
+
+</td><td>
+
+`static`
+
+</td><td>
+
+Hash multiple strings concatenated with a separator.
+
+</td></tr>
+</tbody></table>

package/docs/CryptoUtils/functions/createBrowserCryptoProvider.md

@@ -0,0 +1,12 @@
+[Home](../../README.md) > [CryptoUtils](../README.md) > createBrowserCryptoProvider
+
+# Function: createBrowserCryptoProvider
+
+Creates a CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider if Web
+Crypto API is available.
+
+## Signature
+
+```typescript
+function createBrowserCryptoProvider(): Result<BrowserCryptoProvider>
+```

package/docs/FileTreeHelpers/README.md

@@ -0,0 +1,85 @@
+[Home](../README.md) > FileTreeHelpers
+
+# Namespace: FileTreeHelpers
+
+## Functions
+
+<table><thead><tr><th>
+
+Name
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody>
+<tr><td>
+
+[fromFileList](./functions/fromFileList.md)
+
+</td><td>
+
+Helper function to create a new FileTree instance
+
+</td></tr>
+<tr><td>
+
+[fromDirectoryUpload](./functions/fromDirectoryUpload.md)
+
+</td><td>
+
+Helper function to create a new FileTree instance
+
+</td></tr>
+<tr><td>
+
+[getOriginalFile](./functions/getOriginalFile.md)
+
+</td><td>
+
+Helper function to get the original File object from a FileList by path.
+
+</td></tr>
+<tr><td>
+
+[extractFileListMetadata](./functions/extractFileListMetadata.md)
+
+</td><td>
+
+Helper function to extract metadata from a `FileList`.
+
+</td></tr>
+<tr><td>
+
+[extractFileMetadata](./functions/extractFileMetadata.md)
+
+</td><td>
+
+Helper function to extract metadata from a `File`.
+
+</td></tr>
+</tbody></table>
+
+## Variables
+
+<table><thead><tr><th>
+
+Name
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody>
+<tr><td>
+
+[defaultFileApiTreeInitParams](./variables/defaultFileApiTreeInitParams.md)
+
+</td><td>
+
+Default initialization parameters for a `FileTree` using FileApiTreeAccessors.
+
+</td></tr>
+</tbody></table>

package/docs/FileTreeHelpers/functions/extractFileListMetadata.md

@@ -0,0 +1,11 @@
+[Home](../../README.md) > [FileTreeHelpers](../README.md) > extractFileListMetadata
+
+# Function: extractFileListMetadata
+
+Helper function to extract metadata from a `FileList`.
+
+## Signature
+
+```typescript
+function extractFileListMetadata(fileList: FileList): IFileMetadata[]
+```

package/docs/FileTreeHelpers/functions/extractFileMetadata.md

@@ -0,0 +1,11 @@
+[Home](../../README.md) > [FileTreeHelpers](../README.md) > extractFileMetadata
+
+# Function: extractFileMetadata
+
+Helper function to extract metadata from a `File`.
+
+## Signature
+
+```typescript
+function extractFileMetadata(file: File): IFileMetadata
+```

package/docs/FileTreeHelpers/functions/fromDirectoryUpload.md

@@ -0,0 +1,12 @@
+[Home](../../README.md) > [FileTreeHelpers](../README.md) > fromDirectoryUpload
+
+# Function: fromDirectoryUpload
+
+Helper function to create a new FileTree instance
+from a directory upload with webkitRelativePath support.
+
+## Signature
+
+```typescript
+function fromDirectoryUpload(fileList: FileList, params: IFileTreeInitParams<string>): Promise<Result<FileTree_2<string>>>
+```

package/docs/FileTreeHelpers/functions/fromFileList.md

@@ -0,0 +1,12 @@
+[Home](../../README.md) > [FileTreeHelpers](../README.md) > fromFileList
+
+# Function: fromFileList
+
+Helper function to create a new FileTree instance
+from a browser FileList (e.g., from input[type="file"]).
+
+## Signature
+
+```typescript
+function fromFileList(fileList: FileList, params: IFileTreeInitParams<string>): Promise<Result<FileTree_2<string>>>
+```

package/docs/FileTreeHelpers/functions/getOriginalFile.md

@@ -0,0 +1,11 @@
+[Home](../../README.md) > [FileTreeHelpers](../README.md) > getOriginalFile
+
+# Function: getOriginalFile
+
+Helper function to get the original File object from a FileList by path.
+
+## Signature
+
+```typescript
+function getOriginalFile(fileList: FileList, path: string): Result<File>
+```