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

package/docs/classes/LocalStorageTreeAccessors.md

@@ -0,0 +1,520 @@
+[**@fgv/ts-web-extras**](../README.md)
+
+***
+
+[@fgv/ts-web-extras](../README.md) / LocalStorageTreeAccessors
+
+# Class: LocalStorageTreeAccessors\<TCT\>
+
+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.
+
+## Extends
+
+- [`InMemoryTreeAccessors`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-json-base/docs)\<`TCT`\>
+
+## Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `TCT` *extends* `string` | `string` |
+
+## Implements
+
+- [`IPersistentFileTreeAccessors`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-json-base/docs)\<`TCT`\>
+
+## Methods
+
+### createDirectory()
+
+> **createDirectory**(`dirPath`): [`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<`string`\>
+
+FileTree.IMutableFileTreeAccessors.createDirectory
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `dirPath` | `string` |
+
+#### Returns
+
+[`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<`string`\>
+
+#### Implementation of
+
+`FileTree.IPersistentFileTreeAccessors.createDirectory`
+
+#### Inherited from
+
+`FileTree.InMemoryTreeAccessors.createDirectory`
+
+***
+
+### deleteDirectory()
+
+> **deleteDirectory**(`path`): [`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<`boolean`\>
+
+FileTree.IMutableFileTreeAccessors.deleteDirectory
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `path` | `string` |
+
+#### Returns
+
+[`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<`boolean`\>
+
+#### Implementation of
+
+`FileTree.IPersistentFileTreeAccessors.deleteDirectory`
+
+#### Inherited from
+
+`FileTree.InMemoryTreeAccessors.deleteDirectory`
+
+***
+
+### deleteFile()
+
+> **deleteFile**(`path`): [`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<`boolean`\>
+
+Delete a file and remove it from localStorage.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `path` | `string` | File path to delete |
+
+#### Returns
+
+[`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<`boolean`\>
+
+Result with true if deleted, or error
+
+#### Implementation of
+
+`FileTree.IPersistentFileTreeAccessors.deleteFile`
+
+#### Overrides
+
+`FileTree.InMemoryTreeAccessors.deleteFile`
+
+***
+
+### fileIsMutable()
+
+> **fileIsMutable**(`path`): [`DetailedResult`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<`boolean`, [`SaveDetail`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-json-base/docs)\>
+
+Check if a file is mutable and return persistence detail.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `path` | `string` | File path to check |
+
+#### Returns
+
+[`DetailedResult`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<`boolean`, [`SaveDetail`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-json-base/docs)\>
+
+DetailedResult with mutability status and 'persistent' detail if mutable
+
+#### Implementation of
+
+`FileTree.IPersistentFileTreeAccessors.fileIsMutable`
+
+#### Overrides
+
+`FileTree.InMemoryTreeAccessors.fileIsMutable`
+
+***
+
+### getBaseName()
+
+> **getBaseName**(`path`, `suffix?`): `string`
+
+FileTree.IFileTreeAccessors.getBaseName
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `path` | `string` |
+| `suffix?` | `string` |
+
+#### Returns
+
+`string`
+
+#### Implementation of
+
+`FileTree.IPersistentFileTreeAccessors.getBaseName`
+
+#### Inherited from
+
+`FileTree.InMemoryTreeAccessors.getBaseName`
+
+***
+
+### getChildren()
+
+> **getChildren**(`path`): [`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<readonly [`FileTreeItem`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-json-base/docs)\<`TCT`\>[]\>
+
+FileTree.IFileTreeAccessors.getChildren
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `path` | `string` |
+
+#### Returns
+
+[`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<readonly [`FileTreeItem`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-json-base/docs)\<`TCT`\>[]\>
+
+#### Implementation of
+
+`FileTree.IPersistentFileTreeAccessors.getChildren`
+
+#### Inherited from
+
+`FileTree.InMemoryTreeAccessors.getChildren`
+
+***
+
+### getDirtyPaths()
+
+> **getDirtyPaths**(): `string`[]
+
+Get list of file paths with unsaved changes.
+
+#### Returns
+
+`string`[]
+
+Array of dirty file paths
+
+#### Implementation of
+
+`FileTree.IPersistentFileTreeAccessors.getDirtyPaths`
+
+***
+
+### getExtension()
+
+> **getExtension**(`path`): `string`
+
+FileTree.IFileTreeAccessors.getExtension
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `path` | `string` |
+
+#### Returns
+
+`string`
+
+#### Implementation of
+
+`FileTree.IPersistentFileTreeAccessors.getExtension`
+
+#### Inherited from
+
+`FileTree.InMemoryTreeAccessors.getExtension`
+
+***
+
+### getFileContents()
+
+> **getFileContents**(`path`): [`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<`string`\>
+
+FileTree.IFileTreeAccessors.getFileContents
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `path` | `string` |
+
+#### Returns
+
+[`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<`string`\>
+
+#### Implementation of
+
+`FileTree.IPersistentFileTreeAccessors.getFileContents`
+
+#### Inherited from
+
+`FileTree.InMemoryTreeAccessors.getFileContents`
+
+***
+
+### getFileContentType()
+
+> **getFileContentType**(`path`, `provided?`): [`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<`TCT` \| `undefined`\>
+
+FileTree.IFileTreeAccessors.getFileContentType
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `path` | `string` |
+| `provided?` | `string` |
+
+#### Returns
+
+[`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<`TCT` \| `undefined`\>
+
+#### Implementation of
+
+`FileTree.IPersistentFileTreeAccessors.getFileContentType`
+
+#### Inherited from
+
+`FileTree.InMemoryTreeAccessors.getFileContentType`
+
+***
+
+### getItem()
+
+> **getItem**(`itemPath`): [`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<[`FileTreeItem`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-json-base/docs)\<`TCT`\>\>
+
+FileTree.IFileTreeAccessors.getItem
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `itemPath` | `string` |
+
+#### Returns
+
+[`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<[`FileTreeItem`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-json-base/docs)\<`TCT`\>\>
+
+#### Implementation of
+
+`FileTree.IPersistentFileTreeAccessors.getItem`
+
+#### Inherited from
+
+`FileTree.InMemoryTreeAccessors.getItem`
+
+***
+
+### isDirty()
+
+> **isDirty**(): `boolean`
+
+Check if there are unsaved changes.
+
+#### Returns
+
+`boolean`
+
+True if there are dirty files
+
+#### Implementation of
+
+`FileTree.IPersistentFileTreeAccessors.isDirty`
+
+***
+
+### joinPaths()
+
+> **joinPaths**(...`paths`): `string`
+
+FileTree.IFileTreeAccessors.joinPaths
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| ...`paths` | `string`[] |
+
+#### Returns
+
+`string`
+
+#### Implementation of
+
+`FileTree.IPersistentFileTreeAccessors.joinPaths`
+
+#### Inherited from
+
+`FileTree.InMemoryTreeAccessors.joinPaths`
+
+***
+
+### resolveAbsolutePath()
+
+> **resolveAbsolutePath**(...`paths`): `string`
+
+FileTree.IFileTreeAccessors.resolveAbsolutePath
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| ...`paths` | `string`[] |
+
+#### Returns
+
+`string`
+
+#### Implementation of
+
+`FileTree.IPersistentFileTreeAccessors.resolveAbsolutePath`
+
+#### Inherited from
+
+`FileTree.InMemoryTreeAccessors.resolveAbsolutePath`
+
+***
+
+### saveFileContents()
+
+> **saveFileContents**(`path`, `contents`): [`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<`string`\>
+
+Save file contents. Marks file as dirty and optionally auto-syncs.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `path` | `string` | File path |
+| `contents` | `string` | New file contents |
+
+#### Returns
+
+[`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<`string`\>
+
+Result with the saved contents or error
+
+#### Implementation of
+
+`FileTree.IPersistentFileTreeAccessors.saveFileContents`
+
+#### Overrides
+
+`FileTree.InMemoryTreeAccessors.saveFileContents`
+
+***
+
+### syncToDisk()
+
+> **syncToDisk**(): `Promise`\<[`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<`void`\>\>
+
+Sync all dirty files to localStorage.
+
+#### Returns
+
+`Promise`\<[`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<`void`\>\>
+
+Result indicating success or failure
+
+#### Implementation of
+
+`FileTree.IPersistentFileTreeAccessors.syncToDisk`
+
+***
+
+### create()
+
+#### Call Signature
+
+> `static` **create**\<`TCT`\>(`files`, `prefix?`): [`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<[`InMemoryTreeAccessors`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-json-base/docs)\<`TCT`\>\>
+
+Creates a new [InMemoryTreeAccessors](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-json-base/docs) instance with the supplied
+in-memory files.
+
+##### Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `TCT` *extends* `string` | `string` |
+
+##### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `files` | [`IInMemoryFile`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-json-base/docs)\<`TCT`\>[] | An array of [in-memory files](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-json-base/docs) to include in the tree. |
+| `prefix?` | `string` | Optional prefix for the tree. |
+
+##### Returns
+
+[`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<[`InMemoryTreeAccessors`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-json-base/docs)\<`TCT`\>\>
+
+##### Inherited from
+
+`FileTree.InMemoryTreeAccessors.create`
+
+#### Call Signature
+
+> `static` **create**\<`TCT`\>(`files`, `params?`): [`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<[`InMemoryTreeAccessors`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-json-base/docs)\<`TCT`\>\>
+
+Creates a new [InMemoryTreeAccessors](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-json-base/docs) instance with the supplied
+in-memory files.
+
+##### Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `TCT` *extends* `string` | `string` |
+
+##### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `files` | [`IInMemoryFile`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-json-base/docs)\<`TCT`\>[] | An array of [in-memory files](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-json-base/docs) to include in the tree. |
+| `params?` | [`IFileTreeInitParams`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-json-base/docs)\<`TCT`\> | Optional params for the tree. |
+
+##### Returns
+
+[`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<[`InMemoryTreeAccessors`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-json-base/docs)\<`TCT`\>\>
+
+##### Inherited from
+
+`FileTree.InMemoryTreeAccessors.create`
+
+***
+
+### fromStorage()
+
+> `static` **fromStorage**\<`TCT`\>(`params`): [`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<`LocalStorageTreeAccessors`\<`TCT`\>\>
+
+Create LocalStorageTreeAccessors from browser localStorage.
+Loads all collections from the configured storage keys.
+
+#### Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `TCT` *extends* `string` | `string` |
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `params` | [`ILocalStorageTreeParams`](../interfaces/ILocalStorageTreeParams.md)\<`TCT`\> | Configuration including path-to-key mappings |
+
+#### Returns
+
+[`Result`](https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils/docs)\<`LocalStorageTreeAccessors`\<`TCT`\>\>
+
+Result containing the accessors or an error

package/docs/functions/exportAsJson.md

@@ -0,0 +1,23 @@
+[**@fgv/ts-web-extras**](../README.md)
+
+***
+
+[@fgv/ts-web-extras](../README.md) / exportAsJson
+
+# Function: exportAsJson()
+
+> **exportAsJson**(`data`, `filename`): `void`
+
+Export data as JSON file using legacy blob download method.
+Creates a temporary download link and triggers file download.
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `data` | `unknown` | Data to export as JSON |
+| `filename` | `string` | Name for the downloaded file |
+
+## Returns
+
+`void`

package/docs/functions/exportUsingFileSystemAPI.md

@@ -0,0 +1,26 @@
+[**@fgv/ts-web-extras**](../README.md)
+
+***
+
+[@fgv/ts-web-extras](../README.md) / exportUsingFileSystemAPI
+
+# Function: exportUsingFileSystemAPI()
+
+> **exportUsingFileSystemAPI**(`data`, `suggestedName`, `description`, `window`): `Promise`\<`boolean`\>
+
+Export data using File System Access API with fallback to blob download.
+
+## Parameters
+
+| Parameter | Type | Default value | Description |
+| ------ | ------ | ------ | ------ |
+| `data` | `unknown` | `undefined` | Data to export as JSON |
+| `suggestedName` | `string` | `undefined` | Suggested filename for the save dialog |
+| `description` | `string` | `'JSON files'` | Description for file type filter (default: 'JSON files') |
+| `window` | `Window` | `globalThis.window` | Window object for API access (default: globalThis.window) |
+
+## Returns
+
+`Promise`\<`boolean`\>
+
+Promise resolving to true if saved via File System Access API, false if fallback used

package/docs/functions/extractDirectoryPath.md

@@ -0,0 +1,23 @@
+[**@fgv/ts-web-extras**](../README.md)
+
+***
+
+[@fgv/ts-web-extras](../README.md) / extractDirectoryPath
+
+# Function: extractDirectoryPath()
+
+> **extractDirectoryPath**(`path`): `string`
+
+Extracts the directory path from a file or directory path
+If the path appears to be a directory (no extension), returns it as-is
+If the path appears to be a file, returns the parent directory
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `path` | `string` |
+
+## Returns
+
+`string`

package/docs/functions/isDirectoryHandle.md

@@ -0,0 +1,23 @@
+[**@fgv/ts-web-extras**](../README.md)
+
+***
+
+[@fgv/ts-web-extras](../README.md) / isDirectoryHandle
+
+# Function: isDirectoryHandle()
+
+> **isDirectoryHandle**(`handle`): `handle is FileSystemDirectoryHandle`
+
+Type guard to check if a FileSystemHandle is a directory handle
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `handle` | [`FileSystemHandle`](../interfaces/FileSystemHandle.md) | The handle to check |
+
+## Returns
+
+`handle is FileSystemDirectoryHandle`
+
+True if the handle is a FileSystemDirectoryHandle

package/docs/functions/isFileHandle.md

@@ -0,0 +1,23 @@
+[**@fgv/ts-web-extras**](../README.md)
+
+***
+
+[@fgv/ts-web-extras](../README.md) / isFileHandle
+
+# Function: isFileHandle()
+
+> **isFileHandle**(`handle`): `handle is FileSystemFileHandle`
+
+Type guard to check if a FileSystemHandle is a file handle
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `handle` | [`FileSystemHandle`](../interfaces/FileSystemHandle.md) | The handle to check |
+
+## Returns
+
+`handle is FileSystemFileHandle`
+
+True if the handle is a FileSystemFileHandle

package/docs/functions/isFilePath.md

@@ -0,0 +1,21 @@
+[**@fgv/ts-web-extras**](../README.md)
+
+***
+
+[@fgv/ts-web-extras](../README.md) / isFilePath
+
+# Function: isFilePath()
+
+> **isFilePath**(`path`): `boolean`
+
+Determines if a path appears to be a file (has extension) or directory
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `path` | `string` |
+
+## Returns
+
+`boolean`

package/docs/functions/parseContextFilter.md

@@ -0,0 +1,22 @@
+[**@fgv/ts-web-extras**](../README.md)
+
+***
+
+[@fgv/ts-web-extras](../README.md) / parseContextFilter
+
+# Function: parseContextFilter()
+
+> **parseContextFilter**(`contextFilter`): `Record`\<`string`, `string`\>
+
+Converts context filter token to context object
+Example: "language=en-US|territory=US" -\> { language: "en-US", territory: "US" }
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `contextFilter` | `string` |
+
+## Returns
+
+`Record`\<`string`, `string`\>

package/docs/functions/parseQualifierDefaults.md

@@ -0,0 +1,22 @@
+[**@fgv/ts-web-extras**](../README.md)
+
+***
+
+[@fgv/ts-web-extras](../README.md) / parseQualifierDefaults
+
+# Function: parseQualifierDefaults()
+
+> **parseQualifierDefaults**(`qualifierDefaults`): `Record`\<`string`, `string`[]\>
+
+Converts qualifier defaults token to structured format
+Example: "language=en-US,en-CA|territory=US" -\> { language: ["en-US", "en-CA"], territory: ["US"] }
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `qualifierDefaults` | `string` |
+
+## Returns
+
+`Record`\<`string`, `string`[]\>