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

package/src/packlets/file-api-types/index.ts

@@ -226,7 +226,14 @@ export async function safeShowOpenFilePicker(
   options?: ShowOpenFilePickerOptions
 ): Promise<FileSystemFileHandle[] | null> {
   if (supportsFileSystemAccess(window)) {
-    return window.showOpenFilePicker(options);
+    try {
+      return await window.showOpenFilePicker(options);
+    } catch (error) {
+      if (error instanceof DOMException && error.name === 'AbortError') {
+        return null;
+      }
+      throw error;
+    }
   }
   return null;
 }
@@ -243,7 +250,14 @@ export async function safeShowSaveFilePicker(
   options?: ShowSaveFilePickerOptions
 ): Promise<FileSystemFileHandle | null> {
   if (supportsFileSystemAccess(window)) {
-    return window.showSaveFilePicker(options);
+    try {
+      return await window.showSaveFilePicker(options);
+    } catch (error) {
+      if (error instanceof DOMException && error.name === 'AbortError') {
+        return null;
+      }
+      throw error;
+    }
   }
   return null;
 }
@@ -260,7 +274,14 @@ export async function safeShowDirectoryPicker(
   options?: ShowDirectoryPickerOptions
 ): Promise<FileSystemDirectoryHandle | null> {
   if (supportsFileSystemAccess(window)) {
-    return window.showDirectoryPicker(options);
+    try {
+      return await window.showDirectoryPicker(options);
+    } catch (error) {
+      if (error instanceof DOMException && error.name === 'AbortError') {
+        return null;
+      }
+      throw error;
+    }
   }
   return null;
 }

package/src/packlets/file-tree/directoryHandleStore.ts

@@ -0,0 +1,136 @@
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+/**
+ * Persistent storage for FileSystemDirectoryHandle objects using IndexedDB.
+ * Allows directory handles to survive page reloads without re-prompting the user.
+ * @packageDocumentation
+ */
+
+import { fail, Result, succeed } from '@fgv/ts-utils';
+import { createStore, del, get, keys, set } from 'idb-keyval';
+import { FileSystemDirectoryHandle } from '../file-api-types';
+
+/**
+ * Default IndexedDB database name for directory handles.
+ * @public
+ */
+export const DEFAULT_DIRECTORY_HANDLE_DB = 'chocolate-lab-storage';
+
+/**
+ * Default IndexedDB store name for directory handles.
+ * @public
+ */
+export const DEFAULT_DIRECTORY_HANDLE_STORE = 'directory-handles';
+
+/**
+ * Manages persistence of {@link FileSystemDirectoryHandle} objects in IndexedDB.
+ * Keyed by a label (typically the directory name).
+ * @public
+ */
+export class DirectoryHandleStore {
+  private readonly _store: ReturnType<typeof createStore>;
+
+  public constructor(
+    dbName: string = DEFAULT_DIRECTORY_HANDLE_DB,
+    storeName: string = DEFAULT_DIRECTORY_HANDLE_STORE
+  ) {
+    this._store = createStore(dbName, storeName);
+  }
+
+  /**
+   * 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
+   */
+  public async save(label: string, handle: FileSystemDirectoryHandle): Promise<Result<void>> {
+    try {
+      await set(label, handle, this._store);
+      return succeed(undefined);
+    } catch (e) {
+      return fail(`DirectoryHandleStore.save "${label}": ${String(e)}`);
+    }
+  }
+
+  /**
+   * 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
+   */
+  public async load(label: string): Promise<Result<FileSystemDirectoryHandle | undefined>> {
+    try {
+      const handle = await get<FileSystemDirectoryHandle>(label, this._store);
+      return succeed(handle);
+    } catch (e) {
+      return fail(`DirectoryHandleStore.load "${label}": ${String(e)}`);
+    }
+  }
+
+  /**
+   * Removes a directory handle from IndexedDB.
+   * @param label - Key to remove
+   * @returns Success or Failure
+   */
+  public async remove(label: string): Promise<Result<void>> {
+    try {
+      await del(label, this._store);
+      return succeed(undefined);
+    } catch (e) {
+      return fail(`DirectoryHandleStore.remove "${label}": ${String(e)}`);
+    }
+  }
+
+  /**
+   * Returns all stored labels (keys).
+   * @returns Success with array of labels, or Failure
+   */
+  public async getAllLabels(): Promise<Result<string[]>> {
+    try {
+      const allKeys = await keys<string>(this._store);
+      return succeed(allKeys);
+    } catch (e) {
+      return fail(`DirectoryHandleStore.getAllLabels: ${String(e)}`);
+    }
+  }
+
+  /**
+   * Returns all stored handles as label/handle pairs.
+   * @returns Success with array of entries, or Failure
+   */
+  public async getAll(): Promise<Result<Array<{ label: string; handle: FileSystemDirectoryHandle }>>> {
+    const labelsResult = await this.getAllLabels();
+    if (labelsResult.isFailure()) {
+      return fail(labelsResult.message);
+    }
+
+    const entries: Array<{ label: string; handle: FileSystemDirectoryHandle }> = [];
+    for (const label of labelsResult.value) {
+      const handleResult = await this.load(label);
+      if (handleResult.isFailure()) {
+        return fail(handleResult.message);
+      }
+      if (handleResult.value !== undefined) {
+        entries.push({ label, handle: handleResult.value });
+      }
+    }
+    return succeed(entries);
+  }
+}

package/src/packlets/file-tree/fileApiTreeAccessors.ts

@@ -29,6 +29,9 @@ import {
   FileSystemFileHandle,
   FileSystemDirectoryHandle
 } from '../file-api-types';
+import { FileSystemAccessTreeAccessors, IFileSystemAccessTreeParams } from './fileSystemAccessTreeAccessors';
+import { HttpTreeAccessors, IHttpTreeParams } from './httpTreeAccessors';
+import { LocalStorageTreeAccessors, ILocalStorageTreeParams } from './localStorageTreeAccessors';
 
 /**
  * Interface for File objects that may have the webkitRelativePath property.
@@ -101,6 +104,111 @@ export interface IFileMetadata {
  * @public
  */
 export 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
+   */
+  public static async createPersistent<TCT extends string = string>(
+    dirHandle: FileSystemDirectoryHandle,
+    params?: IFileSystemAccessTreeParams<TCT>
+  ): Promise<Result<FileTree.FileTree<TCT>>> {
+    const accessorsResult = await FileSystemAccessTreeAccessors.fromDirectoryHandle<TCT>(dirHandle, params);
+    if (accessorsResult.isFailure()) {
+      return fail(accessorsResult.message);
+    }
+
+    return FileTree.FileTree.create<TCT>(accessorsResult.value);
+  }
+
+  /**
+   * Create a persistent FileTree from an HTTP storage service.
+   *
+   * @param params - Configuration including API base URL, namespace, and optional autoSync
+   * @returns Promise resolving to a FileTree with persistence capability
+   * @public
+   */
+  public static async createFromHttp<TCT extends string = string>(
+    params: IHttpTreeParams<TCT>
+  ): Promise<Result<FileTree.FileTree<TCT>>> {
+    const accessorsResult = await HttpTreeAccessors.fromHttp<TCT>(params);
+    if (accessorsResult.isFailure()) {
+      return fail(accessorsResult.message);
+    }
+    return FileTree.FileTree.create<TCT>(accessorsResult.value);
+  }
+
+  /**
+   * 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
+   */
+  public static async createPersistentFromFile<TCT extends string = string>(
+    fileHandle: FileSystemFileHandle,
+    params?: IFileSystemAccessTreeParams<TCT>
+  ): Promise<Result<FileTree.FileTree<TCT>>> {
+    const accessorsResult = await FileSystemAccessTreeAccessors.fromFileHandle<TCT>(fileHandle, params);
+    if (accessorsResult.isFailure()) {
+      return fail(accessorsResult.message);
+    }
+
+    return FileTree.FileTree.create<TCT>(accessorsResult.value);
+  }
+
+  /**
+   * 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
+   */
+  public static createFromLocalStorage<TCT extends string = string>(
+    params: ILocalStorageTreeParams<TCT>
+  ): Result<FileTree.FileTree<TCT>> {
+    const accessorsResult = LocalStorageTreeAccessors.fromStorage<TCT>(params);
+    /* c8 ignore next 3 - coverage intermittently missed in full suite */
+    if (accessorsResult.isFailure()) {
+      return fail(accessorsResult.message);
+    }
+
+    return FileTree.FileTree.create<TCT>(accessorsResult.value);
+  }
+
   /**
    * Create FileTree from various file sources using TreeInitializer array.
    * @param initializers - Array of TreeInitializer objects specifying file sources