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

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

@@ -30,6 +30,7 @@ import {
   FileSystemDirectoryHandle
 } from '../file-api-types';
 import { FileSystemAccessTreeAccessors, IFileSystemAccessTreeParams } from './fileSystemAccessTreeAccessors';
+import { HttpTreeAccessors, IHttpTreeParams } from './httpTreeAccessors';
 import { LocalStorageTreeAccessors, ILocalStorageTreeParams } from './localStorageTreeAccessors';
 
 /**
@@ -130,6 +131,23 @@ export class FileApiTreeAccessors<TCT extends string = string> {
     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>`.

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

@@ -20,7 +20,15 @@
  * SOFTWARE.
  */
 
-import { Result, succeed, fail, captureResult, DetailedResult, succeedWithDetail } from '@fgv/ts-utils';
+import {
+  Result,
+  succeed,
+  fail,
+  captureResult,
+  DetailedResult,
+  succeedWithDetail,
+  Logging
+} from '@fgv/ts-utils';
 import { FileTree } from '@fgv/ts-json-base';
 import { FileSystemDirectoryHandle, FileSystemFileHandle } from '../file-api-types';
 
@@ -51,6 +59,9 @@ export interface IFileSystemAccessTreeParams<TCT extends string = string>
    * If omitted, defaults to `/<filename>`.
    */
   filePath?: string;
+
+  /** Optional logger for auto-sync and persistence failures. */
+  logger?: Logging.LogReporter<unknown>;
 }
 
 /**
@@ -65,8 +76,10 @@ export class FileSystemAccessTreeAccessors<TCT extends string = string>
   private readonly _handles: Map<string, FileSystemFileHandle>;
   private readonly _rootDir: FileSystemDirectoryHandle;
   private readonly _dirtyFiles: Set<string>;
+  private readonly _pendingDeletions: Set<string>;
   private readonly _autoSync: boolean;
   private readonly _hasWritePermission: boolean;
+  private readonly _logger: Logging.LogReporter<unknown>;
 
   /**
    * Protected constructor for FileSystemAccessTreeAccessors.
@@ -87,8 +100,26 @@ export class FileSystemAccessTreeAccessors<TCT extends string = string>
     this._rootDir = rootDir;
     this._handles = handles;
     this._dirtyFiles = new Set();
+    this._pendingDeletions = new Set();
+    /* c8 ignore next 3 - intermittent branch coverage: ?? fallback branches in constructor */
     this._autoSync = params?.autoSync ?? false;
     this._hasWritePermission = hasWritePermission;
+    this._logger = params?.logger ?? new Logging.LogReporter<unknown>();
+  }
+
+  private async _runAutoSyncTask(
+    path: string,
+    operation: 'save' | 'delete',
+    action: () => Promise<Result<void>>
+  ): Promise<void> {
+    try {
+      const result = await action();
+      if (result.isFailure()) {
+        this._logger.error(`Auto-${operation} failed for ${path}: ${result.message}`);
+      }
+    } catch (err) {
+      this._logger.error(`Auto-${operation} threw for ${path}: ${String(err)}`);
+    }
   }
 
   /**
@@ -149,6 +180,7 @@ export class FileSystemAccessTreeAccessors<TCT extends string = string>
     try {
       const hasWritePermission = await this._checkFileWritePermission(fileHandle);
 
+      /* c8 ignore next 1 - intermittent branch coverage: ?? true fallback */
       if (!hasWritePermission && (params?.requireWritePermission ?? true)) {
         return fail('Write permission required but not granted');
       }
@@ -156,6 +188,7 @@ export class FileSystemAccessTreeAccessors<TCT extends string = string>
       const file = await fileHandle.getFile();
       const contents = await file.text();
       const path = params?.filePath ?? `/${fileHandle.name}`;
+      /* c8 ignore next 3 - intermittent branch coverage: ternary for inferContentType */
       const contentType = params?.inferContentType
         ? params.inferContentType(path, file.type).orDefault()
         : undefined;
@@ -166,6 +199,7 @@ export class FileSystemAccessTreeAccessors<TCT extends string = string>
       const dummyRoot = {} as FileSystemDirectoryHandle;
       const effectiveParams: IFileSystemAccessTreeParams<TCT> = {
         ...params,
+        /* c8 ignore next 1 - intermittent branch coverage: ?? false fallback */
         mutable: hasWritePermission ? true : params?.mutable ?? false
       };
 
@@ -173,6 +207,7 @@ export class FileSystemAccessTreeAccessors<TCT extends string = string>
         new FileSystemAccessTreeAccessors<TCT>(files, dummyRoot, handles, effectiveParams, hasWritePermission)
       );
     } catch (error) {
+      /* c8 ignore next 1 - intermittent branch coverage: error instanceof Error false branch */
       const message = error instanceof Error ? error.message : String(error);
       return fail(`Failed to create FileSystemAccessTreeAccessors from file: ${message}`);
     }
@@ -294,6 +329,14 @@ export class FileSystemAccessTreeAccessors<TCT extends string = string>
 
     const errors: string[] = [];
 
+    // Process pending deletions from disk
+    for (const path of this._pendingDeletions) {
+      const deleteResult = await this._deleteFileFromDisk(path);
+      if (deleteResult.isFailure()) {
+        errors.push(`delete ${path}: ${deleteResult.message}`);
+      }
+    }
+
     for (const path of this._dirtyFiles) {
       const syncResult = await this._syncFile(path);
       if (syncResult.isFailure()) {
@@ -305,6 +348,7 @@ export class FileSystemAccessTreeAccessors<TCT extends string = string>
       return fail(`Failed to sync ${errors.length} file(s):\n${errors.join('\n')}`);
     }
 
+    this._pendingDeletions.clear();
     this._dirtyFiles.clear();
     return succeed(undefined);
   }
@@ -313,14 +357,34 @@ export class FileSystemAccessTreeAccessors<TCT extends string = string>
    * Implements `FileTree.IPersistentFileTreeAccessors.isDirty`
    */
   public isDirty(): boolean {
-    return this._dirtyFiles.size > 0;
+    return this._dirtyFiles.size > 0 || this._pendingDeletions.size > 0;
   }
 
   /**
    * Implements `FileTree.IPersistentFileTreeAccessors.getDirtyPaths`
    */
   public getDirtyPaths(): string[] {
-    return Array.from(this._dirtyFiles);
+    return [...Array.from(this._dirtyFiles), ...Array.from(this._pendingDeletions)];
+  }
+
+  /**
+   * Override deleteFile to track pending deletions for syncToDisk.
+   */
+  public deleteFile(path: string): Result<boolean> {
+    const result = super.deleteFile(path);
+    if (result.isSuccess()) {
+      this._dirtyFiles.delete(path);
+      this._handles.delete(path);
+
+      if (this._hasWritePermission) {
+        this._pendingDeletions.add(path);
+
+        if (this._autoSync) {
+          void this._runAutoSyncTask(path, 'delete', () => this._deleteFileFromDisk(path));
+        }
+      }
+    }
+    return result;
   }
 
   /**
@@ -335,11 +399,8 @@ export class FileSystemAccessTreeAccessors<TCT extends string = string>
 
       // 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);
-        });
+        // Fire and log-on-failure; don't block the save path.
+        void this._runAutoSyncTask(path, 'save', () => this._syncFile(path));
       }
     }
 
@@ -389,6 +450,37 @@ export class FileSystemAccessTreeAccessors<TCT extends string = string>
     }
   }
 
+  /**
+   * Delete a file from disk using the File System Access API.
+   * @param path - The path of the file to delete.
+   * @returns Promise resolving to success or failure.
+   * @internal
+   */
+  private async _deleteFileFromDisk(path: string): Promise<Result<void>> {
+    try {
+      const absolutePath = this.resolveAbsolutePath(path);
+      const parts = absolutePath.split('/').filter((p) => p.length > 0);
+      const filename = parts.pop();
+
+      /* c8 ignore next 3 - defensive: invalid path */
+      if (!filename) {
+        return fail(`Invalid file path: ${path}`);
+      }
+
+      // Navigate to the parent directory
+      let currentDir = this._rootDir;
+      for (const part of parts) {
+        currentDir = await currentDir.getDirectoryHandle(part);
+      }
+
+      await currentDir.removeEntry(filename);
+      return succeed(undefined);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return fail(`Failed to delete file ${path}: ${message}`);
+    }
+  }
+
   /**
    * Create a new file and write its contents.
    * @param path - The path of the file to create.

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

@@ -0,0 +1,381 @@
+/*
+ * 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 { DetailedResult, fail, type Result, succeed, succeedWithDetail, Logging } from '@fgv/ts-utils';
+import { FileTree } from '@fgv/ts-json-base';
+
+interface IHttpStorageTreeItem {
+  readonly path: string;
+  readonly name: string;
+  readonly type: 'file' | 'directory';
+}
+
+interface IHttpStorageTreeChildrenResponse {
+  readonly path: string;
+  readonly children: ReadonlyArray<IHttpStorageTreeItem>;
+}
+
+interface IHttpStorageFileResponse {
+  readonly path: string;
+  readonly contents: string;
+  readonly contentType?: string;
+}
+
+interface IHttpStorageSyncResponse {
+  readonly synced: number;
+}
+
+function normalizeFetch(fetchImpl?: typeof fetch): typeof fetch {
+  const resolved = fetchImpl ?? globalThis.fetch;
+  return resolved.bind(globalThis) as typeof fetch;
+}
+
+/**
+ * Configuration for creating HTTP-backed tree accessors.
+ * @public
+ */
+export interface IHttpTreeParams<TCT extends string = string> extends FileTree.IFileTreeInitParams<TCT> {
+  readonly baseUrl: string;
+  readonly namespace?: string;
+  readonly autoSync?: boolean;
+  readonly fetchImpl?: typeof fetch;
+  readonly userId?: string;
+  readonly logger?: Logging.LogReporter<unknown>;
+}
+
+/**
+ * HTTP-backed file tree accessors that cache data in memory and persist via REST API.
+ * @public
+ */
+export class HttpTreeAccessors<TCT extends string = string>
+  extends FileTree.InMemoryTreeAccessors<TCT>
+  implements FileTree.IPersistentFileTreeAccessors<TCT>
+{
+  private readonly _baseUrl: string;
+  private readonly _namespace: string | undefined;
+  private readonly _fetchImpl: typeof fetch;
+  private readonly _dirtyFiles: Set<string> = new Set();
+  private readonly _pendingDeletions: Set<string> = new Set();
+  private readonly _autoSync: boolean;
+  private readonly _userId: string | undefined;
+  private readonly _logger: Logging.LogReporter<unknown>;
+
+  private constructor(files: FileTree.IInMemoryFile<TCT>[], params: IHttpTreeParams<TCT>) {
+    super(files, params);
+    this._baseUrl = params.baseUrl.replace(/\/$/, '');
+    this._namespace = params.namespace;
+    this._fetchImpl = normalizeFetch(params.fetchImpl);
+    this._autoSync = params.autoSync ?? false;
+    this._userId = params.userId;
+    this._logger = params.logger ?? new Logging.LogReporter<unknown>();
+  }
+
+  private async _runAutoSyncTask(path: string): Promise<void> {
+    try {
+      const result = await this.syncToDisk();
+      if (result.isFailure()) {
+        this._logger.error(`Auto-sync failed for ${path}: ${result.message}`);
+      }
+    } catch (err) {
+      this._logger.error(`Auto-sync threw for ${path}: ${String(err)}`);
+    }
+  }
+
+  /**
+   * Creates a new HttpTreeAccessors instance from an HTTP backend.
+   * @param params - Configuration parameters for the HTTP tree accessors.
+   * @returns A promise that resolves to a result containing the new HttpTreeAccessors instance or an error message.
+   */
+  public static async fromHttp<TCT extends string = string>(
+    params: IHttpTreeParams<TCT>
+  ): Promise<Result<HttpTreeAccessors<TCT>>> {
+    const filesResult = await this._loadFiles<TCT>(params, '/');
+    if (filesResult.isFailure()) {
+      return fail(filesResult.message);
+    }
+    return succeed(new HttpTreeAccessors<TCT>(filesResult.value, params));
+  }
+
+  /**
+   * Synchronizes all dirty files to the HTTP backend.
+   * @returns A promise that resolves to a result indicating success or failure.
+   */
+  public async syncToDisk(): Promise<Result<void>> {
+    if (this._dirtyFiles.size === 0 && this._pendingDeletions.size === 0) {
+      return succeed(undefined);
+    }
+
+    for (const path of this._pendingDeletions) {
+      const query = new URLSearchParams();
+      query.set('path', path);
+      if (this._namespace) {
+        query.set('namespace', this._namespace);
+      }
+
+      const deleteResult = await this._request<{ deleted: boolean }>(`/file?${query.toString()}`, {
+        method: 'DELETE'
+      });
+      if (deleteResult.isFailure()) {
+        return fail(`delete ${path}: ${deleteResult.message}`);
+      }
+    }
+
+    for (const path of this._dirtyFiles) {
+      const contentsResult = this.getFileContents(path);
+      if (contentsResult.isFailure()) {
+        return fail(`${path}: ${contentsResult.message}`);
+      }
+
+      const body: Record<string, unknown> = {
+        path,
+        contents: contentsResult.value
+      };
+      if (this._namespace) {
+        body.namespace = this._namespace;
+      }
+
+      const saveResult = await this._request<IHttpStorageFileResponse>('/file', {
+        method: 'PUT',
+        body: JSON.stringify(body)
+      });
+      if (saveResult.isFailure()) {
+        return fail(`sync ${path}: ${saveResult.message}`);
+      }
+    }
+
+    this._pendingDeletions.clear();
+    this._dirtyFiles.clear();
+
+    const syncBody: Record<string, unknown> = {};
+    if (this._namespace) {
+      syncBody.namespace = this._namespace;
+    }
+
+    const syncResult = await this._request<IHttpStorageSyncResponse>('/sync', {
+      method: 'POST',
+      body: JSON.stringify(syncBody)
+    });
+
+    return syncResult.isFailure() ? fail(syncResult.message) : succeed(undefined);
+  }
+
+  /**
+   * Checks if there are any dirty files that need synchronization.
+   * @returns True if there are dirty files, false otherwise.
+   */
+  public isDirty(): boolean {
+    return this._dirtyFiles.size > 0 || this._pendingDeletions.size > 0;
+  }
+
+  /**
+   * Gets the list of paths for all dirty files.
+   * @returns An array of file paths that have been modified but not yet synchronized.
+   */
+  public getDirtyPaths(): string[] {
+    return [...Array.from(this._dirtyFiles), ...Array.from(this._pendingDeletions)];
+  }
+
+  public deleteFile(path: string): Result<boolean> {
+    const result = super.deleteFile(path);
+    if (result.isFailure()) {
+      return result;
+    }
+
+    this._dirtyFiles.delete(path);
+    this._pendingDeletions.add(path);
+
+    if (!this._autoSync) {
+      return result;
+    }
+
+    void this._runAutoSyncTask(path);
+    return result;
+  }
+
+  /**
+   * Saves file contents and marks the file as dirty for synchronization.
+   * @param path - The path to the file.
+   * @param contents - The new contents of the file.
+   * @returns A result indicating success or failure.
+   */
+  public saveFileContents(path: string, contents: string): Result<string> {
+    const result = super.saveFileContents(path, contents);
+    if (result.isFailure()) {
+      return result;
+    }
+
+    this._dirtyFiles.add(path);
+    if (!this._autoSync) {
+      return result;
+    }
+
+    // fire-and-log-on-failure automatic sync for immediate persistence workflow
+    void this._runAutoSyncTask(path);
+    return result;
+  }
+
+  /**
+   * Checks if a file is mutable (can be modified).
+   * @param path - The path to the file.
+   * @returns A detailed result indicating if the file is mutable and the reason.
+   */
+  public fileIsMutable(path: string): DetailedResult<boolean, FileTree.SaveDetail> {
+    const result = super.fileIsMutable(path);
+    if (result.isSuccess() && result.value === true) {
+      return succeedWithDetail(true, 'persistent');
+    }
+    return result;
+  }
+
+  /**
+   * Makes an HTTP request to the specified resource path.
+   * @param resourcePath - The path to the resource.
+   * @param init - Optional request initialization options.
+   * @returns A promise that resolves to a result containing the response data or an error message.
+   */
+  private async _request<T>(resourcePath: string, init?: RequestInit): Promise<Result<T>> {
+    const response = await this._fetchImpl(`${this._baseUrl}${resourcePath}`, {
+      headers: {
+        'Content-Type': 'application/json',
+        ...(this._userId ? { 'X-User-Id': this._userId } : {}),
+        /* c8 ignore next 1 - defensive coding: init.headers is never set by current callers */
+        ...(init?.headers ?? {})
+      },
+      ...init
+    }).catch((err: unknown) => ({ err } as const));
+
+    if ('err' in response) {
+      const message = response.err instanceof Error ? response.err.message : String(response.err);
+      return fail(message);
+    }
+
+    if (!response.ok) {
+      const message = await response.text().catch(() => `HTTP ${response.status}`);
+      return fail(message);
+    }
+
+    const json = await response.json().catch(() => undefined);
+    if (json === undefined) {
+      return fail('invalid JSON response');
+    }
+    return succeed(json as T);
+  }
+
+  /**
+   * Loads files from the HTTP backend for the specified directory path.
+   * @param params - Configuration parameters for the HTTP tree accessors.
+   * @param directoryPath - The path to the directory to load files from.
+   * @returns A promise that resolves to a result containing the loaded files or an error message.
+   */
+  private static async _loadFiles<TCT extends string = string>(
+    params: IHttpTreeParams<TCT>,
+    directoryPath: string
+  ): Promise<Result<FileTree.IInMemoryFile<TCT>[]>> {
+    const childrenResult = await this._requestWithParams<IHttpStorageTreeChildrenResponse>(
+      params,
+      '/tree/children',
+      {
+        path: directoryPath,
+        namespace: params.namespace
+      }
+    );
+    if (childrenResult.isFailure()) {
+      return fail(childrenResult.message);
+    }
+
+    const allFiles: FileTree.IInMemoryFile<TCT>[] = [];
+
+    for (const item of childrenResult.value.children) {
+      if (item.type === 'directory') {
+        const nestedResult = await this._loadFiles(params, item.path);
+        if (nestedResult.isFailure()) {
+          return fail(nestedResult.message);
+        }
+        allFiles.push(...nestedResult.value);
+      } else {
+        const fileResult = await this._requestWithParams<IHttpStorageFileResponse>(params, '/file', {
+          path: item.path,
+          namespace: params.namespace
+        });
+        if (fileResult.isFailure()) {
+          return fail(fileResult.message);
+        }
+
+        const contentType = params.inferContentType?.(item.path, fileResult.value.contentType).orDefault();
+        allFiles.push({
+          path: item.path,
+          contents: fileResult.value.contents,
+          contentType
+        });
+      }
+    }
+
+    return succeed(allFiles);
+  }
+
+  /**
+   * Makes an HTTP request with query parameters to the specified resource path.
+   * @param params - Configuration parameters for the HTTP tree accessors.
+   * @param resourcePath - The path to the resource.
+   * @param query - Query parameters to include in the request.
+   * @returns A promise that resolves to a result containing the response data or an error message.
+   */
+  private static async _requestWithParams<T>(
+    params: IHttpTreeParams,
+    resourcePath: string,
+    query: Record<string, string | undefined>
+  ): Promise<Result<T>> {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined) {
+        search.set(key, value);
+      }
+    }
+
+    const fetchImpl = normalizeFetch(params.fetchImpl);
+    /* c8 ignore next 3 - userId header in static _requestWithParams; covered by userId tests via fromHttp */
+    const userIdHeaders: RequestInit | undefined = params.userId
+      ? { headers: { 'X-User-Id': params.userId } }
+      : undefined;
+    const response = await fetchImpl(
+      `${params.baseUrl.replace(/\/$/, '')}${resourcePath}?${search.toString()}`,
+      userIdHeaders
+    ).catch((err: unknown) => ({ err } as const));
+
+    if ('err' in response) {
+      const message = response.err instanceof Error ? response.err.message : String(response.err);
+      return fail(message);
+    }
+
+    if (!response.ok) {
+      const message = await response.text().catch(() => `HTTP ${response.status}`);
+      return fail(message);
+    }
+
+    const json = await response.json().catch(() => undefined);
+    if (json === undefined) {
+      return fail('invalid JSON response');
+    }
+
+    return succeed(json as T);
+  }
+}

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

@@ -28,4 +28,5 @@
 export * from './directoryHandleStore';
 export * from './fileApiTreeAccessors';
 export * from './fileSystemAccessTreeAccessors';
+export * from './httpTreeAccessors';
 export * from './localStorageTreeAccessors';