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

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

@@ -0,0 +1,448 @@
+/*
+ * 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>;
+
+  /** Guards against concurrent syncToDisk calls (thundering herd from autoSync). */
+  private _syncPromise: Promise<Result<void>> | undefined;
+
+  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.
+   *
+   * Uses a concurrency guard: if a sync is already in progress, callers
+   * await the existing operation rather than starting a parallel one.
+   * This prevents the thundering herd that occurs when autoSync fires
+   * for every file written during a bulk operation (e.g. restore).
+   *
+   * @returns A promise that resolves to a result indicating success or failure.
+   */
+  public async syncToDisk(): Promise<Result<void>> {
+    if (this._syncPromise) {
+      return this._syncPromise;
+    }
+
+    this._syncPromise = this._doSync().finally(() => {
+      this._syncPromise = undefined;
+    });
+    return this._syncPromise;
+  }
+
+  private async _doSync(): Promise<Result<void>> {
+    if (this._dirtyFiles.size === 0 && this._pendingDeletions.size === 0) {
+      return succeed(undefined);
+    }
+
+    // Snapshot and clear dirty sets so that changes arriving during
+    // the async sync are not dropped when we finish.
+    const deletions = new Set(this._pendingDeletions);
+    const dirty = new Set(this._dirtyFiles);
+    this._pendingDeletions.clear();
+    this._dirtyFiles.clear();
+
+    for (const path of deletions) {
+      const query = new URLSearchParams();
+      query.set('path', path);
+      if (this._namespace) {
+        query.set('namespace', this._namespace);
+      }
+
+      const deleteResult = await this._requestWithRetry<{ deleted: boolean }>(`/file?${query.toString()}`, {
+        method: 'DELETE'
+      });
+      if (deleteResult.isFailure()) {
+        return fail(`delete ${path}: ${deleteResult.message}`);
+      }
+    }
+
+    for (const path of dirty) {
+      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._requestWithRetry<IHttpStorageFileResponse>('/file', {
+        method: 'PUT',
+        body: JSON.stringify(body)
+      });
+      if (saveResult.isFailure()) {
+        return fail(`sync ${path}: ${saveResult.message}`);
+      }
+    }
+
+    const syncBody: Record<string, unknown> = {};
+    if (this._namespace) {
+      syncBody.namespace = this._namespace;
+    }
+
+    const syncResult = await this._requestWithRetry<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 body = await response.text().catch(() => '');
+      const message = body
+        ? `HTTP ${response.status}: ${body}`
+        : `HTTP ${response.status} ${response.statusText}`;
+      return fail(message);
+    }
+
+    const json = await response.json().catch(() => undefined);
+    if (json === undefined) {
+      return fail('invalid JSON response');
+    }
+    return succeed(json as T);
+  }
+
+  /**
+   * Wraps `_request` with retry logic for transient failures
+   * (network errors, 503 service unavailable, etc.).
+   */
+  private async _requestWithRetry<T>(resourcePath: string, init?: RequestInit): Promise<Result<T>> {
+    const maxAttempts = 3;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const result = await this._request<T>(resourcePath, init);
+      if (result.isSuccess() || attempt === maxAttempts) {
+        return result;
+      }
+      // Retry on transient-looking errors
+      const msg = result.message;
+      const lowerMsg = msg.toLowerCase();
+      const isTransient =
+        msg.includes('503') ||
+        msg.includes('502') ||
+        msg.includes('429') ||
+        lowerMsg.includes('disconnect') ||
+        lowerMsg.includes('econnreset') ||
+        lowerMsg.includes('failed to fetch') ||
+        lowerMsg.includes('network');
+      if (!isTransient) {
+        return result;
+      }
+      // Exponential backoff: 500ms, 1000ms
+      const delayMs = 500 * Math.pow(2, attempt - 1);
+      this._logger.detail(
+        `Retrying ${
+          init?.method ?? 'GET'
+        } ${resourcePath} after ${delayMs}ms (attempt ${attempt}/${maxAttempts})`
+      );
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+    /* c8 ignore next 1 - defensive coding: loop always returns */
+    return fail('retry loop exited unexpectedly');
+  }
+
+  /**
+   * 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);
+    const userIdHeaders: RequestInit | undefined = /* c8 ignore next */ 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 body = await response.text().catch(() => '');
+      const message = body
+        ? `HTTP ${response.status}: ${body}`
+        : `HTTP ${response.status} ${response.statusText}`;
+      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';

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

@@ -89,6 +89,7 @@ export class LocalStorageTreeAccessors<TCT extends string = string>
     this._pathToKeyMap = pathToKeyMap;
     this._keyToPathMap = new Map(Array.from(pathToKeyMap.entries()).map(([k, v]) => [v, k]));
     this._dirtyFiles = new Set();
+    /* c8 ignore next 1 - intermittent branch coverage: ?? false branch when params is undefined */
     this._autoSync = params?.autoSync ?? false;
   }
 
@@ -104,6 +105,7 @@ export class LocalStorageTreeAccessors<TCT extends string = string>
     params: ILocalStorageTreeParams<TCT>
   ): Result<LocalStorageTreeAccessors<TCT>> {
     try {
+      /* c8 ignore next 1 - intermittent branch coverage: window.localStorage branch when params.storage is undefined */
       const storage = params.storage ?? (typeof window !== 'undefined' ? window.localStorage : undefined);
       if (!storage) {
         return fail('localStorage is not available');
@@ -160,6 +162,7 @@ export class LocalStorageTreeAccessors<TCT extends string = string>
           }
 
           const filePath = this._joinPath(dataPath, `${collectionId}${extension}`);
+          /* c8 ignore next 3 - intermittent branch coverage: ternary branches in tight loop */
           const contentType = params?.inferContentType
             ? params.inferContentType(filePath, undefined).orDefault()
             : undefined;
@@ -193,6 +196,7 @@ export class LocalStorageTreeAccessors<TCT extends string = string>
    * @internal
    */
   private static _joinPath(base: string, name: string): string {
+    /* c8 ignore next 2 - intermittent branch coverage: slash-trimming edge cases */
     const cleanBase = base.endsWith('/') ? base.slice(0, -1) : base;
     const cleanName = name.startsWith('/') ? name.slice(1) : name;
     return `${cleanBase}/${cleanName}`;
@@ -207,6 +211,7 @@ export class LocalStorageTreeAccessors<TCT extends string = string>
     let bestMatch: { prefix: string; key: string } | undefined;
     for (const [prefix, key] of this._pathToKeyMap.entries()) {
       if (path.startsWith(prefix)) {
+        /* c8 ignore next 1 - intermittent: overlapping-prefix branch requires two matching prefixes in iteration order */
         if (!bestMatch || prefix.length > bestMatch.prefix.length) {
           bestMatch = { prefix, key };
         }
@@ -242,6 +247,7 @@ export class LocalStorageTreeAccessors<TCT extends string = string>
     }
 
     const relativePath = path.slice(dataPath.length);
+    /* c8 ignore next 1 - defensive: relativePath always starts with / when paths are absolute */
     const cleanPath = relativePath.startsWith('/') ? relativePath.slice(1) : relativePath;
 
     // Remove any file extension
@@ -249,6 +255,38 @@ export class LocalStorageTreeAccessors<TCT extends string = string>
     return dotIndex > 0 ? cleanPath.slice(0, dotIndex) : cleanPath;
   }
 
+  /**
+   * Remove a file's entry from its localStorage key.
+   * @internal
+   */
+  private _deleteFileFromStorage(path: string): void {
+    const storageKey = this._getStorageKeyForPath(path);
+    if (!storageKey) {
+      return;
+    }
+
+    const collectionId = this._getCollectionIdFromPath(path);
+    const existingJson = this._storage.getItem(storageKey);
+    if (!existingJson) {
+      return;
+    }
+
+    try {
+      const parsed = JSON.parse(existingJson);
+      if (isJsonObject(parsed)) {
+        const existing = parsed as Record<string, unknown>;
+        delete existing[collectionId];
+        if (Object.keys(existing).length > 0) {
+          this._storage.setItem(storageKey, JSON.stringify(existing));
+        } else {
+          this._storage.removeItem(storageKey);
+        }
+      }
+    } catch {
+      // Storage is corrupted — nothing to clean up
+    }
+  }
+
   /**
    * Sync a single dirty file to localStorage.
    * @internal
@@ -338,6 +376,21 @@ export class LocalStorageTreeAccessors<TCT extends string = string>
     return Array.from(this._dirtyFiles);
   }
 
+  /**
+   * Delete a file and remove it from localStorage.
+   * @param path - File path to delete
+   * @returns Result with true if deleted, or error
+   * @public
+   */
+  public deleteFile(path: string): Result<boolean> {
+    const result = super.deleteFile(path);
+    if (result.isSuccess()) {
+      this._dirtyFiles.delete(path);
+      this._deleteFileFromStorage(path);
+    }
+    return result;
+  }
+
   /**
    * Save file contents. Marks file as dirty and optionally auto-syncs.
    * @param path - File path

package/src/test/unit/fileApiTreeAccessors.test.ts

@@ -22,6 +22,7 @@
 
 import '@fgv/ts-utils-jest';
 import { FileApiTreeAccessors } from '../../packlets/file-tree';
+import { FileTree } from '@fgv/ts-json-base';
 import { FileTreeHelpers } from '../../packlets/helpers';
 import {
   createMockFile,
@@ -30,6 +31,39 @@ import {
   verifyFileAPI
 } from '../utils/testHelpers';
 
+// ---- Minimal mock fetch helpers for createFromHttp tests ----
+
+interface IHttpMockResponse {
+  ok: boolean;
+  status?: number;
+  jsonValue?: unknown;
+  textValue?: string;
+  throwOnJson?: boolean;
+}
+
+function makeMockHttpResponse(options: IHttpMockResponse): Response {
+  const { ok, status = ok ? 200 : 400, jsonValue, textValue, throwOnJson } = options;
+  return {
+    ok,
+    status,
+    json: throwOnJson
+      ? () => Promise.reject(new Error('JSON parse error'))
+      : () => Promise.resolve(jsonValue),
+    text: () => Promise.resolve(textValue ?? `HTTP ${status}`)
+  } as unknown as Response;
+}
+
+function makeMockHttpFetch(responses: IHttpMockResponse[]): typeof fetch {
+  let callIndex = 0;
+  return (url: string | URL | Request, _init?: RequestInit): Promise<Response> => {
+    const response = responses[callIndex++];
+    if (response === undefined) {
+      return Promise.reject(new Error(`Unexpected fetch call to ${url.toString()}`));
+    }
+    return Promise.resolve(makeMockHttpResponse(response));
+  };
+}
+
 describe('FileApiTreeAccessors', () => {
   describe('Static factory methods', () => {
     describe('create', () => {
@@ -1315,4 +1349,39 @@ describe('FileApiTreeAccessors', () => {
       });
     });
   });
+
+  describe('createFromHttp', () => {
+    test('succeeds and returns a FileTree when HTTP backend loads successfully', async () => {
+      const fetchImpl = makeMockHttpFetch([
+        {
+          ok: true,
+          jsonValue: { path: '/', children: [{ path: '/data.json', name: 'data.json', type: 'file' }] }
+        },
+        { ok: true, jsonValue: { path: '/data.json', contents: '{"items":{}}' } }
+      ]);
+
+      const result = await FileApiTreeAccessors.createFromHttp({
+        baseUrl: 'http://localhost:3000',
+        fetchImpl,
+        mutable: true
+      });
+
+      expect(result).toSucceedAndSatisfy((tree) => {
+        expect(tree).toBeInstanceOf(FileTree.FileTree);
+        expect(tree.getFile('/data.json')).toSucceed();
+        expect(FileTree.isPersistentAccessors(tree.hal)).toBe(true);
+      });
+    });
+
+    test('fails when the HTTP backend returns an error during initial load', async () => {
+      const fetchImpl = makeMockHttpFetch([{ ok: false, status: 503, textValue: 'Service Unavailable' }]);
+
+      const result = await FileApiTreeAccessors.createFromHttp({
+        baseUrl: 'http://localhost:3000',
+        fetchImpl
+      });
+
+      expect(result).toFailWith(/service unavailable/i);
+    });
+  });
 });