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

package/rush-logs/ts-web-extras.test.log

@@ -0,0 +1,75 @@
+Invoking: heft test --clean 
+ ---- build started ---- 
+[build:clean] Deleted 0 files and 3 folders
+[build:typescript] The TypeScript compiler version 5.9.3 is newer than the latest version that was tested with Heft (5.8); it may not work correctly.
+[build:typescript] Using TypeScript version 5.9.3
+[build:api-extractor] Using API Extractor version 7.57.6
+[build:api-extractor] Analysis will use the bundled TypeScript version 5.8.2
+[build:api-extractor] *** The target project appears to use TypeScript 5.9.3 which is newer than the bundled compiler engine; consider upgrading API Extractor.
+ ---- build finished (3.976s) ---- 
+ ---- test started ---- 
+[test:clean] Deleted 0 files and 1 folder
+[test:jest] Using Jest version 29.5.0
+[test:jest] 
+[test:jest] Run start. 9 test suites
+[test:jest] START lib/test/unit/fileApiTreeAccessors.test.js
+[test:jest] START lib/test/unit/httpTreeAccessors.test.js
+[test:jest] START lib/test/unit/localStorageTreeAccessors.test.js
+[test:jest] START lib/test/unit/fileSystemAccessTreeAccessors.test.js
+[test:jest] START lib/test/unit/fileTreeHelpers.test.js
+[test:jest] START lib/test/unit/fileApiTypes.test.js
+[test:jest] START lib/test/unit/urlParams.test.js
+[test:jest] START lib/test/unit/directoryHandleStore.test.js
+[test:jest] START lib/test/unit/browserHashProvider.test.js
+(node:99490) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:99493) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+[test:jest] PASS lib/test/unit/urlParams.test.js (duration: 0.793s, 60 passed, 0 failed)
+[test:jest] PASS lib/test/unit/fileSystemAccessTreeAccessors.test.js (duration: 0.886s, 44 passed, 0 failed)
+(node:99494) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+[test:jest] PASS lib/test/unit/directoryHandleStore.test.js (duration: 0.868s, 19 passed, 0 failed)
+(node:99488) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:99489) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+[test:jest] PASS lib/test/unit/localStorageTreeAccessors.test.js (duration: 0.949s, 44 passed, 0 failed)
+(node:99492) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+[test:jest] PASS lib/test/unit/fileApiTypes.test.js (duration: 0.931s, 36 passed, 0 failed)
+(node:99495) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:99487) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+[test:jest] PASS lib/test/unit/fileApiTreeAccessors.test.js (duration: 1.013s, 65 passed, 0 failed)
+(node:99491) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+[test:jest] PASS lib/test/unit/fileTreeHelpers.test.js (duration: 0.996s, 35 passed, 0 failed)
+[test:jest] PASS lib/test/unit/httpTreeAccessors.test.js (duration: 1.015s, 57 passed, 0 failed)
+[test:jest] PASS lib/test/unit/browserHashProvider.test.js (duration: 1.021s, 15 passed, 0 failed)
+[test:jest] 
+[test:jest] Tests finished:
+[test:jest]   Successes: 375
+[test:jest]   Failures: 0
+[test:jest]   Total: 376
+-----------------------------------|---------|----------|---------|---------|-------------------
+File                               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
+-----------------------------------|---------|----------|---------|---------|-------------------
+All files                          |     100 |    99.62 |     100 |     100 |                   
+ crypto-utils                      |     100 |      100 |     100 |     100 |                   
+  browserCryptoProvider.ts         |     100 |      100 |     100 |     100 |                   
+  browserHashProvider.ts           |     100 |      100 |     100 |     100 |                   
+ file-tree                         |     100 |    99.57 |     100 |     100 |                   
+  directoryHandleStore.ts          |     100 |      100 |     100 |     100 |                   
+  fileApiTreeAccessors.ts          |     100 |      100 |     100 |     100 |                   
+  fileSystemAccessTreeAccessors.ts |     100 |      100 |     100 |     100 |                   
+  httpTreeAccessors.ts             |     100 |    98.41 |     100 |     100 | 339               
+  localStorageTreeAccessors.ts     |     100 |      100 |     100 |     100 |                   
+ helpers                           |     100 |      100 |     100 |     100 |                   
+  fileTreeHelpers.ts               |     100 |      100 |     100 |     100 |                   
+ url-utils                         |     100 |      100 |     100 |     100 |                   
+  urlParams.ts                     |     100 |      100 |     100 |     100 |                   
+-----------------------------------|---------|----------|---------|---------|-------------------
+ ---- test finished (2.232s) ---- 
+-------------------- Finished (6.215s) --------------------

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.