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

package/docs/ts-web-extras.ifilesystemaccesstreeparams.autosync.md

@@ -0,0 +1,13 @@
+<!-- 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; [IFileSystemAccessTreeParams](./ts-web-extras.ifilesystemaccesstreeparams.md) &gt; [autoSync](./ts-web-extras.ifilesystemaccesstreeparams.autosync.md)
+
+## IFileSystemAccessTreeParams.autoSync property
+
+Automatically sync changes to disk immediately after each save. If false, changes are batched and written on explicit syncToDisk() call.
+
+**Signature:**
+
+```typescript
+autoSync?: boolean;
+```

package/docs/ts-web-extras.ifilesystemaccesstreeparams.md

@@ -0,0 +1,78 @@
+<!-- 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; [IFileSystemAccessTreeParams](./ts-web-extras.ifilesystemaccesstreeparams.md)
+
+## IFileSystemAccessTreeParams interface
+
+Options for creating persistent file trees.
+
+**Signature:**
+
+```typescript
+export interface IFileSystemAccessTreeParams<TCT extends string = string> extends FileTree.IFileTreeInitParams<TCT> 
+```
+**Extends:** FileTree.IFileTreeInitParams&lt;TCT&gt;
+
+## Properties
+
+<table><thead><tr><th>
+
+Property
+
+
+</th><th>
+
+Modifiers
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[autoSync?](./ts-web-extras.ifilesystemaccesstreeparams.autosync.md)
+
+
+</td><td>
+
+
+</td><td>
+
+boolean
+
+
+</td><td>
+
+_(Optional)_ Automatically sync changes to disk immediately after each save. If false, changes are batched and written on explicit syncToDisk() call.
+
+
+</td></tr>
+<tr><td>
+
+[requireWritePermission?](./ts-web-extras.ifilesystemaccesstreeparams.requirewritepermission.md)
+
+
+</td><td>
+
+
+</td><td>
+
+boolean
+
+
+</td><td>
+
+_(Optional)_ Require write permission on the directory handle. If true, fails if write permission cannot be obtained. If false, falls back to read-only mode.
+
+
+</td></tr>
+</tbody></table>
+

package/docs/ts-web-extras.ifilesystemaccesstreeparams.requirewritepermission.md

@@ -0,0 +1,13 @@
+<!-- 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; [IFileSystemAccessTreeParams](./ts-web-extras.ifilesystemaccesstreeparams.md) &gt; [requireWritePermission](./ts-web-extras.ifilesystemaccesstreeparams.requirewritepermission.md)
+
+## IFileSystemAccessTreeParams.requireWritePermission property
+
+Require write permission on the directory handle. If true, fails if write permission cannot be obtained. If false, falls back to read-only mode.
+
+**Signature:**
+
+```typescript
+requireWritePermission?: boolean;
+```

package/docs/ts-web-extras.ilocalstoragetreeparams.autosync.md

@@ -0,0 +1,13 @@
+<!-- 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; [ILocalStorageTreeParams](./ts-web-extras.ilocalstoragetreeparams.md) &gt; [autoSync](./ts-web-extras.ilocalstoragetreeparams.autosync.md)
+
+## ILocalStorageTreeParams.autoSync property
+
+If true, automatically sync changes to localStorage on every modification. If false (default), changes are only synced when syncToDisk() is called.
+
+**Signature:**
+
+```typescript
+autoSync?: boolean;
+```

package/docs/ts-web-extras.ilocalstoragetreeparams.md

@@ -0,0 +1,97 @@
+<!-- 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; [ILocalStorageTreeParams](./ts-web-extras.ilocalstoragetreeparams.md)
+
+## ILocalStorageTreeParams interface
+
+Configuration for LocalStorageTreeAccessors.
+
+**Signature:**
+
+```typescript
+export interface ILocalStorageTreeParams<TCT extends string = string> extends FileTree.IFileTreeInitParams<TCT> 
+```
+**Extends:** FileTree.IFileTreeInitParams&lt;TCT&gt;
+
+## Properties
+
+<table><thead><tr><th>
+
+Property
+
+
+</th><th>
+
+Modifiers
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[autoSync?](./ts-web-extras.ilocalstoragetreeparams.autosync.md)
+
+
+</td><td>
+
+
+</td><td>
+
+boolean
+
+
+</td><td>
+
+_(Optional)_ If true, automatically sync changes to localStorage on every modification. If false (default), changes are only synced when syncToDisk() is called.
+
+
+</td></tr>
+<tr><td>
+
+[pathToKeyMap](./ts-web-extras.ilocalstoragetreeparams.pathtokeymap.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Record&lt;string, string&gt;
+
+
+</td><td>
+
+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' }
+
+
+</td></tr>
+<tr><td>
+
+[storage?](./ts-web-extras.ilocalstoragetreeparams.storage.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Storage
+
+
+</td><td>
+
+_(Optional)_ Storage instance to use. Defaults to window.localStorage. Can be overridden for testing with mock storage.
+
+
+</td></tr>
+</tbody></table>
+

package/docs/ts-web-extras.ilocalstoragetreeparams.pathtokeymap.md

@@ -0,0 +1,13 @@
+<!-- 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; [ILocalStorageTreeParams](./ts-web-extras.ilocalstoragetreeparams.md) &gt; [pathToKeyMap](./ts-web-extras.ilocalstoragetreeparams.pathtokeymap.md)
+
+## ILocalStorageTreeParams.pathToKeyMap property
+
+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' }
+
+**Signature:**
+
+```typescript
+pathToKeyMap: Record<string, string>;
+```

package/docs/ts-web-extras.ilocalstoragetreeparams.storage.md

@@ -0,0 +1,13 @@
+<!-- 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; [ILocalStorageTreeParams](./ts-web-extras.ilocalstoragetreeparams.md) &gt; [storage](./ts-web-extras.ilocalstoragetreeparams.storage.md)
+
+## ILocalStorageTreeParams.storage property
+
+Storage instance to use. Defaults to window.localStorage. Can be overridden for testing with mock storage.
+
+**Signature:**
+
+```typescript
+storage?: Storage;
+```

package/docs/ts-web-extras.localstoragetreeaccessors.fileismutable.md

@@ -0,0 +1,56 @@
+<!-- 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; [LocalStorageTreeAccessors](./ts-web-extras.localstoragetreeaccessors.md) &gt; [fileIsMutable](./ts-web-extras.localstoragetreeaccessors.fileismutable.md)
+
+## LocalStorageTreeAccessors.fileIsMutable() method
+
+Check if a file is mutable and return persistence detail.
+
+**Signature:**
+
+```typescript
+fileIsMutable(path: string): DetailedResult<boolean, FileTree.SaveDetail>;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+path
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+File path to check
+
+
+</td></tr>
+</tbody></table>
+
+**Returns:**
+
+DetailedResult&lt;boolean, FileTree.SaveDetail&gt;
+
+DetailedResult with mutability status and 'persistent' detail if mutable
+

package/docs/ts-web-extras.localstoragetreeaccessors.fromstorage.md

@@ -0,0 +1,56 @@
+<!-- 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; [LocalStorageTreeAccessors](./ts-web-extras.localstoragetreeaccessors.md) &gt; [fromStorage](./ts-web-extras.localstoragetreeaccessors.fromstorage.md)
+
+## LocalStorageTreeAccessors.fromStorage() method
+
+Create LocalStorageTreeAccessors from browser localStorage. Loads all collections from the configured storage keys.
+
+**Signature:**
+
+```typescript
+static fromStorage<TCT extends string = string>(params: ILocalStorageTreeParams<TCT>): Result<LocalStorageTreeAccessors<TCT>>;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+params
+
+
+</td><td>
+
+[ILocalStorageTreeParams](./ts-web-extras.ilocalstoragetreeparams.md)<!-- -->&lt;TCT&gt;
+
+
+</td><td>
+
+Configuration including path-to-key mappings
+
+
+</td></tr>
+</tbody></table>
+
+**Returns:**
+
+Result&lt;[LocalStorageTreeAccessors](./ts-web-extras.localstoragetreeaccessors.md)<!-- -->&lt;TCT&gt;&gt;
+
+Result containing the accessors or an error
+

package/docs/ts-web-extras.localstoragetreeaccessors.getdirtypaths.md

@@ -0,0 +1,19 @@
+<!-- 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; [LocalStorageTreeAccessors](./ts-web-extras.localstoragetreeaccessors.md) &gt; [getDirtyPaths](./ts-web-extras.localstoragetreeaccessors.getdirtypaths.md)
+
+## LocalStorageTreeAccessors.getDirtyPaths() method
+
+Get list of file paths with unsaved changes.
+
+**Signature:**
+
+```typescript
+getDirtyPaths(): string[];
+```
+**Returns:**
+
+string\[\]
+
+Array of dirty file paths
+

package/docs/ts-web-extras.localstoragetreeaccessors.isdirty.md

@@ -0,0 +1,19 @@
+<!-- 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; [LocalStorageTreeAccessors](./ts-web-extras.localstoragetreeaccessors.md) &gt; [isDirty](./ts-web-extras.localstoragetreeaccessors.isdirty.md)
+
+## LocalStorageTreeAccessors.isDirty() method
+
+Check if there are unsaved changes.
+
+**Signature:**
+
+```typescript
+isDirty(): boolean;
+```
+**Returns:**
+
+boolean
+
+True if there are dirty files
+

package/docs/ts-web-extras.localstoragetreeaccessors.md

@@ -0,0 +1,131 @@
+<!-- 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; [LocalStorageTreeAccessors](./ts-web-extras.localstoragetreeaccessors.md)
+
+## LocalStorageTreeAccessors class
+
+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": { ...collectionData }, ... }` File paths map as: `/data/ingredients/collection-id.json` → stored in key for `/data/ingredients`
+
+**Signature:**
+
+```typescript
+export declare class LocalStorageTreeAccessors<TCT extends string = string> extends FileTree.InMemoryTreeAccessors<TCT> implements FileTree.IPersistentFileTreeAccessors<TCT> 
+```
+**Extends:** FileTree.InMemoryTreeAccessors&lt;TCT&gt;
+
+**Implements:** FileTree.IPersistentFileTreeAccessors&lt;TCT&gt;
+
+## Remarks
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `LocalStorageTreeAccessors` class.
+
+## Methods
+
+<table><thead><tr><th>
+
+Method
+
+
+</th><th>
+
+Modifiers
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[fileIsMutable(path)](./ts-web-extras.localstoragetreeaccessors.fileismutable.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Check if a file is mutable and return persistence detail.
+
+
+</td></tr>
+<tr><td>
+
+[fromStorage(params)](./ts-web-extras.localstoragetreeaccessors.fromstorage.md)
+
+
+</td><td>
+
+`static`
+
+
+</td><td>
+
+Create LocalStorageTreeAccessors from browser localStorage. Loads all collections from the configured storage keys.
+
+
+</td></tr>
+<tr><td>
+
+[getDirtyPaths()](./ts-web-extras.localstoragetreeaccessors.getdirtypaths.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Get list of file paths with unsaved changes.
+
+
+</td></tr>
+<tr><td>
+
+[isDirty()](./ts-web-extras.localstoragetreeaccessors.isdirty.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Check if there are unsaved changes.
+
+
+</td></tr>
+<tr><td>
+
+[saveFileContents(path, contents)](./ts-web-extras.localstoragetreeaccessors.savefilecontents.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Save file contents. Marks file as dirty and optionally auto-syncs.
+
+
+</td></tr>
+<tr><td>
+
+[syncToDisk()](./ts-web-extras.localstoragetreeaccessors.synctodisk.md)
+
+
+</td><td>
+
+
+</td><td>
+
+Sync all dirty files to localStorage.
+
+
+</td></tr>
+</tbody></table>
+

package/docs/ts-web-extras.localstoragetreeaccessors.savefilecontents.md

@@ -0,0 +1,72 @@
+<!-- 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; [LocalStorageTreeAccessors](./ts-web-extras.localstoragetreeaccessors.md) &gt; [saveFileContents](./ts-web-extras.localstoragetreeaccessors.savefilecontents.md)
+
+## LocalStorageTreeAccessors.saveFileContents() method
+
+Save file contents. Marks file as dirty and optionally auto-syncs.
+
+**Signature:**
+
+```typescript
+saveFileContents(path: string, contents: string): Result<string>;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+path
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+File path
+
+
+</td></tr>
+<tr><td>
+
+contents
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+New file contents
+
+
+</td></tr>
+</tbody></table>
+
+**Returns:**
+
+Result&lt;string&gt;
+
+Result with the saved contents or error
+

package/docs/ts-web-extras.localstoragetreeaccessors.synctodisk.md

@@ -0,0 +1,19 @@
+<!-- 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; [LocalStorageTreeAccessors](./ts-web-extras.localstoragetreeaccessors.md) &gt; [syncToDisk](./ts-web-extras.localstoragetreeaccessors.synctodisk.md)
+
+## LocalStorageTreeAccessors.syncToDisk() method
+
+Sync all dirty files to localStorage.
+
+**Signature:**
+
+```typescript
+syncToDisk(): Promise<Result<void>>;
+```
+**Returns:**
+
+Promise&lt;Result&lt;void&gt;&gt;
+
+Result indicating success or failure
+