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

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

@@ -29,6 +29,8 @@ import {
   FileSystemFileHandle,
   FileSystemDirectoryHandle
 } from '../file-api-types';
+import { FileSystemAccessTreeAccessors, IFileSystemAccessTreeParams } from './fileSystemAccessTreeAccessors';
+import { LocalStorageTreeAccessors, ILocalStorageTreeParams } from './localStorageTreeAccessors';
 
 /**
  * Interface for File objects that may have the webkitRelativePath property.
@@ -101,6 +103,94 @@ 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 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

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

@@ -0,0 +1,427 @@
+/*
+ * 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.
+ */
+
+import { Result, succeed, fail, captureResult, DetailedResult, succeedWithDetail } from '@fgv/ts-utils';
+import { FileTree } from '@fgv/ts-json-base';
+import { FileSystemDirectoryHandle, FileSystemFileHandle } from '../file-api-types';
+
+/**
+ * Options for creating persistent file trees.
+ * @public
+ */
+export interface IFileSystemAccessTreeParams<TCT extends string = string>
+  extends FileTree.IFileTreeInitParams<TCT> {
+  /**
+   * Automatically sync changes to disk immediately after each save.
+   * If false, changes are batched and written on explicit syncToDisk() call.
+   * @defaultValue false
+   */
+  autoSync?: boolean;
+
+  /**
+   * Require write permission on the directory handle.
+   * If true, fails if write permission cannot be obtained.
+   * If false, falls back to read-only mode.
+   * @defaultValue true
+   */
+  requireWritePermission?: boolean;
+
+  /**
+   * Override the path at which the file is stored in the tree (for fromFileHandle).
+   * Must be an absolute path (e.g., '/data/confections/common.yaml').
+   * If omitted, defaults to `/<filename>`.
+   */
+  filePath?: string;
+}
+
+/**
+ * Implementation of `FileTree.IPersistentFileTreeAccessors` that uses the File System Access API
+ * to provide persistent file editing in browsers.
+ * @public
+ */
+export class FileSystemAccessTreeAccessors<TCT extends string = string>
+  extends FileTree.InMemoryTreeAccessors<TCT>
+  implements FileTree.IPersistentFileTreeAccessors<TCT>
+{
+  private readonly _handles: Map<string, FileSystemFileHandle>;
+  private readonly _rootDir: FileSystemDirectoryHandle;
+  private readonly _dirtyFiles: Set<string>;
+  private readonly _autoSync: boolean;
+  private readonly _hasWritePermission: boolean;
+
+  /**
+   * Protected constructor for FileSystemAccessTreeAccessors.
+   * @param files - An array of in-memory files to include in the tree.
+   * @param rootDir - The root directory handle.
+   * @param handles - Map of file paths to their handles.
+   * @param params - Optional params for the tree.
+   * @param hasWritePermission - Whether write permission was granted.
+   */
+  protected constructor(
+    files: FileTree.IInMemoryFile<TCT>[],
+    rootDir: FileSystemDirectoryHandle,
+    handles: Map<string, FileSystemFileHandle>,
+    params: IFileSystemAccessTreeParams<TCT> | undefined,
+    hasWritePermission: boolean
+  ) {
+    super(files, params);
+    this._rootDir = rootDir;
+    this._handles = handles;
+    this._dirtyFiles = new Set();
+    this._autoSync = params?.autoSync ?? false;
+    this._hasWritePermission = hasWritePermission;
+  }
+
+  /**
+   * Creates a new FileSystemAccessTreeAccessors instance from a directory handle.
+   * @param dirHandle - The FileSystemDirectoryHandle to load files from.
+   * @param params - Optional parameters including autoSync and permission settings.
+   * @returns Promise resolving to a FileSystemAccessTreeAccessors instance.
+   * @public
+   */
+  public static async fromDirectoryHandle<TCT extends string = string>(
+    dirHandle: FileSystemDirectoryHandle,
+    params?: IFileSystemAccessTreeParams<TCT>
+  ): Promise<Result<FileSystemAccessTreeAccessors<TCT>>> {
+    try {
+      // Check write permission
+      const hasWritePermission = await this._checkWritePermission(dirHandle);
+
+      /* c8 ignore next 3 - coverage intermittently missed in full suite */
+      if (!hasWritePermission && (params?.requireWritePermission ?? true)) {
+        return fail('Write permission required but not granted');
+      }
+
+      // Load all files from the directory (always use '/' as base, prefix is handled by parent)
+      const { files, handles } = await this._loadDirectory<TCT>(dirHandle, '/', params);
+
+      // Enable tree mutability when write permission is granted and caller didn't explicitly set mutable
+      const effectiveParams: IFileSystemAccessTreeParams<TCT> = {
+        ...params,
+        mutable: params?.mutable ?? (hasWritePermission ? true : false)
+      };
+
+      return succeed(
+        new FileSystemAccessTreeAccessors<TCT>(files, dirHandle, handles, effectiveParams, hasWritePermission)
+      );
+      /* c8 ignore next 4 - defensive: outer catch for unexpected errors */
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return fail(`Failed to create FileSystemAccessTreeAccessors: ${message}`);
+    }
+  }
+
+  /**
+   * Creates a new FileSystemAccessTreeAccessors instance from a single file handle.
+   *
+   * The resulting tree contains exactly one file at `/<filename>`.
+   * `syncToDisk()` writes changes back to the original file via the File System Access API.
+   * New file creation is not supported on this tree (no parent directory handle).
+   *
+   * @param fileHandle - The FileSystemFileHandle to load.
+   * @param params - Optional parameters including autoSync and permission settings.
+   * @returns Promise resolving to a FileSystemAccessTreeAccessors instance.
+   * @public
+   */
+  public static async fromFileHandle<TCT extends string = string>(
+    fileHandle: FileSystemFileHandle,
+    params?: IFileSystemAccessTreeParams<TCT>
+  ): Promise<Result<FileSystemAccessTreeAccessors<TCT>>> {
+    try {
+      const hasWritePermission = await this._checkFileWritePermission(fileHandle);
+
+      if (!hasWritePermission && (params?.requireWritePermission ?? true)) {
+        return fail('Write permission required but not granted');
+      }
+
+      const file = await fileHandle.getFile();
+      const contents = await file.text();
+      const path = params?.filePath ?? `/${fileHandle.name}`;
+      const contentType = params?.inferContentType
+        ? params.inferContentType(path, file.type).orDefault()
+        : undefined;
+
+      const files: FileTree.IInMemoryFile<TCT>[] = [{ path, contents, contentType }];
+      const handles = new Map<string, FileSystemFileHandle>([[path, fileHandle]]);
+
+      const dummyRoot = {} as FileSystemDirectoryHandle;
+      const effectiveParams: IFileSystemAccessTreeParams<TCT> = {
+        ...params,
+        mutable: hasWritePermission ? true : params?.mutable ?? false
+      };
+
+      return succeed(
+        new FileSystemAccessTreeAccessors<TCT>(files, dummyRoot, handles, effectiveParams, hasWritePermission)
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return fail(`Failed to create FileSystemAccessTreeAccessors from file: ${message}`);
+    }
+  }
+
+  /**
+   * Check if the directory handle has write permission.
+   * @param handle - The directory handle to check.
+   * @returns Promise resolving to true if write permission is granted.
+   * @internal
+   */
+  private static async _checkWritePermission(handle: FileSystemDirectoryHandle): Promise<boolean> {
+    try {
+      const permission = await handle.queryPermission({ mode: 'readwrite' });
+
+      if (permission === 'granted') {
+        return true;
+      }
+
+      if (permission === 'prompt') {
+        const requested = await handle.requestPermission({ mode: 'readwrite' });
+        return requested === 'granted';
+      }
+
+      return false;
+    } catch (error) {
+      // Permission API might not be available or might throw
+      return false;
+    }
+  }
+
+  /**
+   * Check if the file handle has write permission.
+   * @param handle - The file handle to check.
+   * @returns Promise resolving to true if write permission is granted.
+   * @internal
+   */
+  private static async _checkFileWritePermission(handle: FileSystemFileHandle): Promise<boolean> {
+    try {
+      const permission = await handle.queryPermission({ mode: 'readwrite' });
+
+      if (permission === 'granted') {
+        return true;
+      }
+
+      if (permission === 'prompt') {
+        const requested = await handle.requestPermission({ mode: 'readwrite' });
+        return requested === 'granted';
+      }
+
+      return false;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Load all files from a directory handle recursively.
+   * @param dirHandle - The directory handle to load from.
+   * @param basePath - The base path for files.
+   * @param params - Optional parameters.
+   * @returns Promise resolving to files and handles.
+   * @internal
+   */
+  private static async _loadDirectory<TCT extends string = string>(
+    dirHandle: FileSystemDirectoryHandle,
+    basePath: string,
+    params?: IFileSystemAccessTreeParams<TCT>
+  ): Promise<{ files: FileTree.IInMemoryFile<TCT>[]; handles: Map<string, FileSystemFileHandle> }> {
+    const files: FileTree.IInMemoryFile<TCT>[] = [];
+    const handles = new Map<string, FileSystemFileHandle>();
+
+    for await (const [name, handle] of dirHandle.entries()) {
+      if (handle.kind === 'file') {
+        const fileHandle = handle as FileSystemFileHandle;
+        const file = await fileHandle.getFile();
+        const contents = await file.text();
+        const path = this._joinPath(basePath, name);
+        /* c8 ignore next 2 - coverage intermittently missed in full suite */
+        const contentType = params?.inferContentType
+          ? params.inferContentType(path, file.type).orDefault()
+          : undefined;
+
+        files.push({ path, contents, contentType });
+        handles.set(path, fileHandle);
+      } else if (handle.kind === 'directory') {
+        const subDirHandle = handle as FileSystemDirectoryHandle;
+        const subPath = this._joinPath(basePath, name);
+        const subResult = await this._loadDirectory<TCT>(subDirHandle, subPath, params);
+        files.push(...subResult.files);
+        for (const [path, fileHandle] of subResult.handles) {
+          handles.set(path, fileHandle);
+        }
+      }
+    }
+
+    return { files, handles };
+  }
+
+  /**
+   * Join path segments.
+   * @param base - The base path.
+   * @param name - The name to append.
+   * @returns The joined path.
+   * @internal
+   */
+  private static _joinPath(base: string, name: string): string {
+    const normalized = base.endsWith('/') ? base.slice(0, -1) : base;
+    return `${normalized}/${name}`;
+  }
+
+  /**
+   * Implements `FileTree.IPersistentFileTreeAccessors.syncToDisk`
+   */
+  public async syncToDisk(): Promise<Result<void>> {
+    if (!this._hasWritePermission) {
+      return fail('Write permission not granted - cannot sync to disk');
+    }
+
+    const errors: string[] = [];
+
+    for (const path of this._dirtyFiles) {
+      const syncResult = await this._syncFile(path);
+      if (syncResult.isFailure()) {
+        errors.push(`${path}: ${syncResult.message}`);
+      }
+    }
+
+    if (errors.length > 0) {
+      return fail(`Failed to sync ${errors.length} file(s):\n${errors.join('\n')}`);
+    }
+
+    this._dirtyFiles.clear();
+    return succeed(undefined);
+  }
+
+  /**
+   * Implements `FileTree.IPersistentFileTreeAccessors.isDirty`
+   */
+  public isDirty(): boolean {
+    return this._dirtyFiles.size > 0;
+  }
+
+  /**
+   * Implements `FileTree.IPersistentFileTreeAccessors.getDirtyPaths`
+   */
+  public getDirtyPaths(): string[] {
+    return Array.from(this._dirtyFiles);
+  }
+
+  /**
+   * Implements `FileTree.IMutableFileTreeAccessors.saveFileContents`
+   */
+  public saveFileContents(path: string, contents: string): Result<string> {
+    // Call parent to update in-memory state
+    const result = super.saveFileContents(path, contents);
+
+    if (result.isSuccess() && this._hasWritePermission) {
+      this._dirtyFiles.add(path);
+
+      // Auto-sync if enabled
+      if (this._autoSync) {
+        // Fire and forget - errors logged but don't block
+        this._syncFile(path).catch((err) => {
+          /* c8 ignore next 1 - defensive: async auto-sync error logging */
+          console.error(`Auto-sync failed for ${path}:`, err);
+        });
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Implements `FileTree.IMutableFileTreeAccessors.fileIsMutable`
+   */
+  public fileIsMutable(path: string): DetailedResult<boolean, FileTree.SaveDetail> {
+    const baseResult = super.fileIsMutable(path);
+
+    if (baseResult.isSuccess() && baseResult.detail === 'transient' && this._hasWritePermission) {
+      // Upgrade to 'persistent' if we have write permission
+      return succeedWithDetail(true, 'persistent');
+    }
+
+    return baseResult;
+  }
+
+  /**
+   * Sync a single file to disk.
+   * @param path - The path of the file to sync.
+   * @returns Promise resolving to success or failure.
+   * @internal
+   */
+  private async _syncFile(path: string): Promise<Result<void>> {
+    const handle = this._handles.get(path);
+    if (!handle) {
+      return this._createAndWriteFile(path);
+    }
+
+    const contents = this.getFileContents(path);
+    if (contents.isFailure()) {
+      return fail(contents.message);
+    }
+
+    try {
+      const writable = await handle.createWritable();
+      await writable.write(contents.value);
+      await writable.close();
+      return succeed(undefined);
+      /* c8 ignore next 4 - coverage intermittently missed in full suite */
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return fail(`Failed to write file: ${message}`);
+    }
+  }
+
+  /**
+   * Create a new file and write its contents.
+   * @param path - The path of the file to create.
+   * @returns Promise resolving to success or failure.
+   * @internal
+   */
+  private async _createAndWriteFile(path: string): Promise<Result<void>> {
+    try {
+      // Parse path to get directory and filename
+      const absolutePath = this.resolveAbsolutePath(path);
+      const parts = absolutePath.split('/').filter((p) => p.length > 0);
+      const filename = parts.pop();
+
+      /* c8 ignore next 3 - coverage intermittently missed in full suite */
+      if (!filename) {
+        return fail(`Invalid file path: ${path}`);
+      }
+
+      // Navigate/create directory structure
+      let currentDir = this._rootDir;
+      for (const part of parts) {
+        currentDir = await currentDir.getDirectoryHandle(part, { create: true });
+      }
+
+      // Create file and write contents
+      const fileHandle = await currentDir.getFileHandle(filename, { create: true });
+      this._handles.set(path, fileHandle);
+
+      return this._syncFile(path);
+      /* c8 ignore next 4 - coverage intermittently missed in full suite */
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return fail(`Failed to create file ${path}: ${message}`);
+    }
+  }
+}

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

@@ -25,4 +25,7 @@
  * @packageDocumentation
  */
 
+export * from './directoryHandleStore';
 export * from './fileApiTreeAccessors';
+export * from './fileSystemAccessTreeAccessors';
+export * from './localStorageTreeAccessors';