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

package/lib/packlets/file-tree/httpTreeAccessors.js

@@ -0,0 +1,283 @@
+"use strict";
+/*
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpTreeAccessors = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const ts_json_base_1 = require("@fgv/ts-json-base");
+function normalizeFetch(fetchImpl) {
+    const resolved = fetchImpl !== null && fetchImpl !== void 0 ? fetchImpl : globalThis.fetch;
+    return resolved.bind(globalThis);
+}
+/**
+ * HTTP-backed file tree accessors that cache data in memory and persist via REST API.
+ * @public
+ */
+class HttpTreeAccessors extends ts_json_base_1.FileTree.InMemoryTreeAccessors {
+    constructor(files, params) {
+        var _a, _b;
+        super(files, params);
+        this._dirtyFiles = new Set();
+        this._pendingDeletions = new Set();
+        this._baseUrl = params.baseUrl.replace(/\/$/, '');
+        this._namespace = params.namespace;
+        this._fetchImpl = normalizeFetch(params.fetchImpl);
+        this._autoSync = (_a = params.autoSync) !== null && _a !== void 0 ? _a : false;
+        this._userId = params.userId;
+        this._logger = (_b = params.logger) !== null && _b !== void 0 ? _b : new ts_utils_1.Logging.LogReporter();
+    }
+    async _runAutoSyncTask(path) {
+        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.
+     */
+    static async fromHttp(params) {
+        const filesResult = await this._loadFiles(params, '/');
+        if (filesResult.isFailure()) {
+            return (0, ts_utils_1.fail)(filesResult.message);
+        }
+        return (0, ts_utils_1.succeed)(new HttpTreeAccessors(filesResult.value, params));
+    }
+    /**
+     * Synchronizes all dirty files to the HTTP backend.
+     * @returns A promise that resolves to a result indicating success or failure.
+     */
+    async syncToDisk() {
+        if (this._dirtyFiles.size === 0 && this._pendingDeletions.size === 0) {
+            return (0, ts_utils_1.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(`/file?${query.toString()}`, {
+                method: 'DELETE'
+            });
+            if (deleteResult.isFailure()) {
+                return (0, ts_utils_1.fail)(`delete ${path}: ${deleteResult.message}`);
+            }
+        }
+        for (const path of this._dirtyFiles) {
+            const contentsResult = this.getFileContents(path);
+            if (contentsResult.isFailure()) {
+                return (0, ts_utils_1.fail)(`${path}: ${contentsResult.message}`);
+            }
+            const body = {
+                path,
+                contents: contentsResult.value
+            };
+            if (this._namespace) {
+                body.namespace = this._namespace;
+            }
+            const saveResult = await this._request('/file', {
+                method: 'PUT',
+                body: JSON.stringify(body)
+            });
+            if (saveResult.isFailure()) {
+                return (0, ts_utils_1.fail)(`sync ${path}: ${saveResult.message}`);
+            }
+        }
+        this._pendingDeletions.clear();
+        this._dirtyFiles.clear();
+        const syncBody = {};
+        if (this._namespace) {
+            syncBody.namespace = this._namespace;
+        }
+        const syncResult = await this._request('/sync', {
+            method: 'POST',
+            body: JSON.stringify(syncBody)
+        });
+        return syncResult.isFailure() ? (0, ts_utils_1.fail)(syncResult.message) : (0, ts_utils_1.succeed)(undefined);
+    }
+    /**
+     * Checks if there are any dirty files that need synchronization.
+     * @returns True if there are dirty files, false otherwise.
+     */
+    isDirty() {
+        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.
+     */
+    getDirtyPaths() {
+        return [...Array.from(this._dirtyFiles), ...Array.from(this._pendingDeletions)];
+    }
+    deleteFile(path) {
+        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.
+     */
+    saveFileContents(path, contents) {
+        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.
+     */
+    fileIsMutable(path) {
+        const result = super.fileIsMutable(path);
+        if (result.isSuccess() && result.value === true) {
+            return (0, ts_utils_1.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.
+     */
+    async _request(resourcePath, init) {
+        var _a;
+        const response = await this._fetchImpl(`${this._baseUrl}${resourcePath}`, Object.assign({ headers: Object.assign(Object.assign({ 'Content-Type': 'application/json' }, (this._userId ? { 'X-User-Id': this._userId } : {})), ((_a = init === null || init === void 0 ? void 0 : init.headers) !== null && _a !== void 0 ? _a : {})) }, init)).catch((err) => ({ err }));
+        if ('err' in response) {
+            const message = response.err instanceof Error ? response.err.message : String(response.err);
+            return (0, ts_utils_1.fail)(message);
+        }
+        if (!response.ok) {
+            const message = await response.text().catch(() => `HTTP ${response.status}`);
+            return (0, ts_utils_1.fail)(message);
+        }
+        const json = await response.json().catch(() => undefined);
+        if (json === undefined) {
+            return (0, ts_utils_1.fail)('invalid JSON response');
+        }
+        return (0, ts_utils_1.succeed)(json);
+    }
+    /**
+     * 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.
+     */
+    static async _loadFiles(params, directoryPath) {
+        var _a;
+        const childrenResult = await this._requestWithParams(params, '/tree/children', {
+            path: directoryPath,
+            namespace: params.namespace
+        });
+        if (childrenResult.isFailure()) {
+            return (0, ts_utils_1.fail)(childrenResult.message);
+        }
+        const allFiles = [];
+        for (const item of childrenResult.value.children) {
+            if (item.type === 'directory') {
+                const nestedResult = await this._loadFiles(params, item.path);
+                if (nestedResult.isFailure()) {
+                    return (0, ts_utils_1.fail)(nestedResult.message);
+                }
+                allFiles.push(...nestedResult.value);
+            }
+            else {
+                const fileResult = await this._requestWithParams(params, '/file', {
+                    path: item.path,
+                    namespace: params.namespace
+                });
+                if (fileResult.isFailure()) {
+                    return (0, ts_utils_1.fail)(fileResult.message);
+                }
+                const contentType = (_a = params.inferContentType) === null || _a === void 0 ? void 0 : _a.call(params, item.path, fileResult.value.contentType).orDefault();
+                allFiles.push({
+                    path: item.path,
+                    contents: fileResult.value.contents,
+                    contentType
+                });
+            }
+        }
+        return (0, ts_utils_1.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.
+     */
+    static async _requestWithParams(params, resourcePath, query) {
+        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 = params.userId
+            ? { headers: { 'X-User-Id': params.userId } }
+            : undefined;
+        const response = await fetchImpl(`${params.baseUrl.replace(/\/$/, '')}${resourcePath}?${search.toString()}`, userIdHeaders).catch((err) => ({ err }));
+        if ('err' in response) {
+            const message = response.err instanceof Error ? response.err.message : String(response.err);
+            return (0, ts_utils_1.fail)(message);
+        }
+        if (!response.ok) {
+            const message = await response.text().catch(() => `HTTP ${response.status}`);
+            return (0, ts_utils_1.fail)(message);
+        }
+        const json = await response.json().catch(() => undefined);
+        if (json === undefined) {
+            return (0, ts_utils_1.fail)('invalid JSON response');
+        }
+        return (0, ts_utils_1.succeed)(json);
+    }
+}
+exports.HttpTreeAccessors = HttpTreeAccessors;
+//# sourceMappingURL=httpTreeAccessors.js.map

package/lib/packlets/file-tree/httpTreeAccessors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpTreeAccessors.js","sourceRoot":"","sources":["../../../src/packlets/file-tree/httpTreeAccessors.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { DetailedResult, fail, type Result, succeed, succeedWithDetail, Logging } from '@fgv/ts-utils';\nimport { FileTree } from '@fgv/ts-json-base';\n\ninterface IHttpStorageTreeItem {\n  readonly path: string;\n  readonly name: string;\n  readonly type: 'file' | 'directory';\n}\n\ninterface IHttpStorageTreeChildrenResponse {\n  readonly path: string;\n  readonly children: ReadonlyArray<IHttpStorageTreeItem>;\n}\n\ninterface IHttpStorageFileResponse {\n  readonly path: string;\n  readonly contents: string;\n  readonly contentType?: string;\n}\n\ninterface IHttpStorageSyncResponse {\n  readonly synced: number;\n}\n\nfunction normalizeFetch(fetchImpl?: typeof fetch): typeof fetch {\n  const resolved = fetchImpl ?? globalThis.fetch;\n  return resolved.bind(globalThis) as typeof fetch;\n}\n\n/**\n * Configuration for creating HTTP-backed tree accessors.\n * @public\n */\nexport interface IHttpTreeParams<TCT extends string = string> extends FileTree.IFileTreeInitParams<TCT> {\n  readonly baseUrl: string;\n  readonly namespace?: string;\n  readonly autoSync?: boolean;\n  readonly fetchImpl?: typeof fetch;\n  readonly userId?: string;\n  readonly logger?: Logging.LogReporter<unknown>;\n}\n\n/**\n * HTTP-backed file tree accessors that cache data in memory and persist via REST API.\n * @public\n */\nexport class HttpTreeAccessors<TCT extends string = string>\n  extends FileTree.InMemoryTreeAccessors<TCT>\n  implements FileTree.IPersistentFileTreeAccessors<TCT>\n{\n  private readonly _baseUrl: string;\n  private readonly _namespace: string | undefined;\n  private readonly _fetchImpl: typeof fetch;\n  private readonly _dirtyFiles: Set<string> = new Set();\n  private readonly _pendingDeletions: Set<string> = new Set();\n  private readonly _autoSync: boolean;\n  private readonly _userId: string | undefined;\n  private readonly _logger: Logging.LogReporter<unknown>;\n\n  private constructor(files: FileTree.IInMemoryFile<TCT>[], params: IHttpTreeParams<TCT>) {\n    super(files, params);\n    this._baseUrl = params.baseUrl.replace(/\\/$/, '');\n    this._namespace = params.namespace;\n    this._fetchImpl = normalizeFetch(params.fetchImpl);\n    this._autoSync = params.autoSync ?? false;\n    this._userId = params.userId;\n    this._logger = params.logger ?? new Logging.LogReporter<unknown>();\n  }\n\n  private async _runAutoSyncTask(path: string): Promise<void> {\n    try {\n      const result = await this.syncToDisk();\n      if (result.isFailure()) {\n        this._logger.error(`Auto-sync failed for ${path}: ${result.message}`);\n      }\n    } catch (err) {\n      this._logger.error(`Auto-sync threw for ${path}: ${String(err)}`);\n    }\n  }\n\n  /**\n   * Creates a new HttpTreeAccessors instance from an HTTP backend.\n   * @param params - Configuration parameters for the HTTP tree accessors.\n   * @returns A promise that resolves to a result containing the new HttpTreeAccessors instance or an error message.\n   */\n  public static async fromHttp<TCT extends string = string>(\n    params: IHttpTreeParams<TCT>\n  ): Promise<Result<HttpTreeAccessors<TCT>>> {\n    const filesResult = await this._loadFiles<TCT>(params, '/');\n    if (filesResult.isFailure()) {\n      return fail(filesResult.message);\n    }\n    return succeed(new HttpTreeAccessors<TCT>(filesResult.value, params));\n  }\n\n  /**\n   * Synchronizes all dirty files to the HTTP backend.\n   * @returns A promise that resolves to a result indicating success or failure.\n   */\n  public async syncToDisk(): Promise<Result<void>> {\n    if (this._dirtyFiles.size === 0 && this._pendingDeletions.size === 0) {\n      return succeed(undefined);\n    }\n\n    for (const path of this._pendingDeletions) {\n      const query = new URLSearchParams();\n      query.set('path', path);\n      if (this._namespace) {\n        query.set('namespace', this._namespace);\n      }\n\n      const deleteResult = await this._request<{ deleted: boolean }>(`/file?${query.toString()}`, {\n        method: 'DELETE'\n      });\n      if (deleteResult.isFailure()) {\n        return fail(`delete ${path}: ${deleteResult.message}`);\n      }\n    }\n\n    for (const path of this._dirtyFiles) {\n      const contentsResult = this.getFileContents(path);\n      if (contentsResult.isFailure()) {\n        return fail(`${path}: ${contentsResult.message}`);\n      }\n\n      const body: Record<string, unknown> = {\n        path,\n        contents: contentsResult.value\n      };\n      if (this._namespace) {\n        body.namespace = this._namespace;\n      }\n\n      const saveResult = await this._request<IHttpStorageFileResponse>('/file', {\n        method: 'PUT',\n        body: JSON.stringify(body)\n      });\n      if (saveResult.isFailure()) {\n        return fail(`sync ${path}: ${saveResult.message}`);\n      }\n    }\n\n    this._pendingDeletions.clear();\n    this._dirtyFiles.clear();\n\n    const syncBody: Record<string, unknown> = {};\n    if (this._namespace) {\n      syncBody.namespace = this._namespace;\n    }\n\n    const syncResult = await this._request<IHttpStorageSyncResponse>('/sync', {\n      method: 'POST',\n      body: JSON.stringify(syncBody)\n    });\n\n    return syncResult.isFailure() ? fail(syncResult.message) : succeed(undefined);\n  }\n\n  /**\n   * Checks if there are any dirty files that need synchronization.\n   * @returns True if there are dirty files, false otherwise.\n   */\n  public isDirty(): boolean {\n    return this._dirtyFiles.size > 0 || this._pendingDeletions.size > 0;\n  }\n\n  /**\n   * Gets the list of paths for all dirty files.\n   * @returns An array of file paths that have been modified but not yet synchronized.\n   */\n  public getDirtyPaths(): string[] {\n    return [...Array.from(this._dirtyFiles), ...Array.from(this._pendingDeletions)];\n  }\n\n  public deleteFile(path: string): Result<boolean> {\n    const result = super.deleteFile(path);\n    if (result.isFailure()) {\n      return result;\n    }\n\n    this._dirtyFiles.delete(path);\n    this._pendingDeletions.add(path);\n\n    if (!this._autoSync) {\n      return result;\n    }\n\n    void this._runAutoSyncTask(path);\n    return result;\n  }\n\n  /**\n   * Saves file contents and marks the file as dirty for synchronization.\n   * @param path - The path to the file.\n   * @param contents - The new contents of the file.\n   * @returns A result indicating success or failure.\n   */\n  public saveFileContents(path: string, contents: string): Result<string> {\n    const result = super.saveFileContents(path, contents);\n    if (result.isFailure()) {\n      return result;\n    }\n\n    this._dirtyFiles.add(path);\n    if (!this._autoSync) {\n      return result;\n    }\n\n    // fire-and-log-on-failure automatic sync for immediate persistence workflow\n    void this._runAutoSyncTask(path);\n    return result;\n  }\n\n  /**\n   * Checks if a file is mutable (can be modified).\n   * @param path - The path to the file.\n   * @returns A detailed result indicating if the file is mutable and the reason.\n   */\n  public fileIsMutable(path: string): DetailedResult<boolean, FileTree.SaveDetail> {\n    const result = super.fileIsMutable(path);\n    if (result.isSuccess() && result.value === true) {\n      return succeedWithDetail(true, 'persistent');\n    }\n    return result;\n  }\n\n  /**\n   * Makes an HTTP request to the specified resource path.\n   * @param resourcePath - The path to the resource.\n   * @param init - Optional request initialization options.\n   * @returns A promise that resolves to a result containing the response data or an error message.\n   */\n  private async _request<T>(resourcePath: string, init?: RequestInit): Promise<Result<T>> {\n    const response = await this._fetchImpl(`${this._baseUrl}${resourcePath}`, {\n      headers: {\n        'Content-Type': 'application/json',\n        ...(this._userId ? { 'X-User-Id': this._userId } : {}),\n        /* c8 ignore next 1 - defensive coding: init.headers is never set by current callers */\n        ...(init?.headers ?? {})\n      },\n      ...init\n    }).catch((err: unknown) => ({ err } as const));\n\n    if ('err' in response) {\n      const message = response.err instanceof Error ? response.err.message : String(response.err);\n      return fail(message);\n    }\n\n    if (!response.ok) {\n      const message = await response.text().catch(() => `HTTP ${response.status}`);\n      return fail(message);\n    }\n\n    const json = await response.json().catch(() => undefined);\n    if (json === undefined) {\n      return fail('invalid JSON response');\n    }\n    return succeed(json as T);\n  }\n\n  /**\n   * Loads files from the HTTP backend for the specified directory path.\n   * @param params - Configuration parameters for the HTTP tree accessors.\n   * @param directoryPath - The path to the directory to load files from.\n   * @returns A promise that resolves to a result containing the loaded files or an error message.\n   */\n  private static async _loadFiles<TCT extends string = string>(\n    params: IHttpTreeParams<TCT>,\n    directoryPath: string\n  ): Promise<Result<FileTree.IInMemoryFile<TCT>[]>> {\n    const childrenResult = await this._requestWithParams<IHttpStorageTreeChildrenResponse>(\n      params,\n      '/tree/children',\n      {\n        path: directoryPath,\n        namespace: params.namespace\n      }\n    );\n    if (childrenResult.isFailure()) {\n      return fail(childrenResult.message);\n    }\n\n    const allFiles: FileTree.IInMemoryFile<TCT>[] = [];\n\n    for (const item of childrenResult.value.children) {\n      if (item.type === 'directory') {\n        const nestedResult = await this._loadFiles(params, item.path);\n        if (nestedResult.isFailure()) {\n          return fail(nestedResult.message);\n        }\n        allFiles.push(...nestedResult.value);\n      } else {\n        const fileResult = await this._requestWithParams<IHttpStorageFileResponse>(params, '/file', {\n          path: item.path,\n          namespace: params.namespace\n        });\n        if (fileResult.isFailure()) {\n          return fail(fileResult.message);\n        }\n\n        const contentType = params.inferContentType?.(item.path, fileResult.value.contentType).orDefault();\n        allFiles.push({\n          path: item.path,\n          contents: fileResult.value.contents,\n          contentType\n        });\n      }\n    }\n\n    return succeed(allFiles);\n  }\n\n  /**\n   * Makes an HTTP request with query parameters to the specified resource path.\n   * @param params - Configuration parameters for the HTTP tree accessors.\n   * @param resourcePath - The path to the resource.\n   * @param query - Query parameters to include in the request.\n   * @returns A promise that resolves to a result containing the response data or an error message.\n   */\n  private static async _requestWithParams<T>(\n    params: IHttpTreeParams,\n    resourcePath: string,\n    query: Record<string, string | undefined>\n  ): Promise<Result<T>> {\n    const search = new URLSearchParams();\n    for (const [key, value] of Object.entries(query)) {\n      if (value !== undefined) {\n        search.set(key, value);\n      }\n    }\n\n    const fetchImpl = normalizeFetch(params.fetchImpl);\n    /* c8 ignore next 3 - userId header in static _requestWithParams; covered by userId tests via fromHttp */\n    const userIdHeaders: RequestInit | undefined = params.userId\n      ? { headers: { 'X-User-Id': params.userId } }\n      : undefined;\n    const response = await fetchImpl(\n      `${params.baseUrl.replace(/\\/$/, '')}${resourcePath}?${search.toString()}`,\n      userIdHeaders\n    ).catch((err: unknown) => ({ err } as const));\n\n    if ('err' in response) {\n      const message = response.err instanceof Error ? response.err.message : String(response.err);\n      return fail(message);\n    }\n\n    if (!response.ok) {\n      const message = await response.text().catch(() => `HTTP ${response.status}`);\n      return fail(message);\n    }\n\n    const json = await response.json().catch(() => undefined);\n    if (json === undefined) {\n      return fail('invalid JSON response');\n    }\n\n    return succeed(json as T);\n  }\n}\n"]}

package/lib/packlets/file-tree/index.d.ts

@@ -2,5 +2,9 @@
  * Browser-compatible FileTree implementations using the File API.
  * @packageDocumentation
  */
+export * from './directoryHandleStore';
 export * from './fileApiTreeAccessors';
+export * from './fileSystemAccessTreeAccessors';
+export * from './httpTreeAccessors';
+export * from './localStorageTreeAccessors';
 //# sourceMappingURL=index.d.ts.map

package/lib/packlets/file-tree/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/file-tree/index.ts"],"names":[],"mappings":"AAsBA;;;GAGG;AAEH,cAAc,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/file-tree/index.ts"],"names":[],"mappings":"AAsBA;;;GAGG;AAEH,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,iCAAiC,CAAC;AAChD,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC"}

package/lib/packlets/file-tree/index.js

@@ -39,5 +39,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Browser-compatible FileTree implementations using the File API.
  * @packageDocumentation
  */
+__exportStar(require("./directoryHandleStore"), exports);
 __exportStar(require("./fileApiTreeAccessors"), exports);
+__exportStar(require("./fileSystemAccessTreeAccessors"), exports);
+__exportStar(require("./httpTreeAccessors"), exports);
+__exportStar(require("./localStorageTreeAccessors"), exports);
 //# sourceMappingURL=index.js.map

package/lib/packlets/file-tree/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/file-tree/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;AAEH;;;GAGG;AAEH,yDAAuC","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Browser-compatible FileTree implementations using the File API.\n * @packageDocumentation\n */\n\nexport * from './fileApiTreeAccessors';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/file-tree/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;AAEH;;;GAGG;AAEH,yDAAuC;AACvC,yDAAuC;AACvC,kEAAgD;AAChD,sDAAoC;AACpC,8DAA4C","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Browser-compatible FileTree implementations using the File API.\n * @packageDocumentation\n */\n\nexport * from './directoryHandleStore';\nexport * from './fileApiTreeAccessors';\nexport * from './fileSystemAccessTreeAccessors';\nexport * from './httpTreeAccessors';\nexport * from './localStorageTreeAccessors';\n"]}

package/lib/packlets/file-tree/localStorageTreeAccessors.d.ts

@@ -0,0 +1,141 @@
+import { DetailedResult, Result } from '@fgv/ts-utils';
+import { FileTree } from '@fgv/ts-json-base';
+/**
+ * Configuration for LocalStorageTreeAccessors.
+ * @public
+ */
+export interface ILocalStorageTreeParams<TCT extends string = string> extends FileTree.IFileTreeInitParams<TCT> {
+    /**
+     * Map of directory path prefixes to localStorage keys.
+     * Files under each prefix are stored in the corresponding localStorage key.
+     * Example: \{ '/data/ingredients': 'myapp:ingredients:v1' \}
+     */
+    pathToKeyMap: Record<string, string>;
+    /**
+     * Storage instance to use. Defaults to window.localStorage.
+     * Can be overridden for testing with mock storage.
+     */
+    storage?: Storage;
+    /**
+     * If true, automatically sync changes to localStorage on every modification.
+     * If false (default), changes are only synced when syncToDisk() is called.
+     */
+    autoSync?: boolean;
+}
+/**
+ * Browser localStorage-backed file tree accessors with persistence support.
+ *
+ * Maps filesystem-like directory paths to localStorage keys, where each key stores
+ * multiple collections as a JSON object. This provides a general-purpose implementation
+ * for browser-based file tree persistence without requiring File System Access API.
+ *
+ * Storage format per key: `{ "collection-id": "<raw file content>" }`
+ * File paths map as: `/data/ingredients/collection-id.yaml` → stored in key for `/data/ingredients`
+ *
+ * Legacy format (v1): `{ "collection-id": { ...parsedJsonObject } }` is auto-migrated on load.
+ *
+ * @public
+ */
+export declare class LocalStorageTreeAccessors<TCT extends string = string> extends FileTree.InMemoryTreeAccessors<TCT> implements FileTree.IPersistentFileTreeAccessors<TCT> {
+    private readonly _storage;
+    private readonly _pathToKeyMap;
+    private readonly _keyToPathMap;
+    private readonly _dirtyFiles;
+    private readonly _autoSync;
+    /**
+     * Private constructor. Use fromStorage() factory method instead.
+     * @internal
+     */
+    private constructor();
+    /**
+     * Create LocalStorageTreeAccessors from browser localStorage.
+     * Loads all collections from the configured storage keys.
+     *
+     * @param params - Configuration including path-to-key mappings
+     * @returns Result containing the accessors or an error
+     * @public
+     */
+    static fromStorage<TCT extends string = string>(params: ILocalStorageTreeParams<TCT>): Result<LocalStorageTreeAccessors<TCT>>;
+    /**
+     * Load all files from localStorage based on path-to-key mappings.
+     * @internal
+     */
+    private static _loadFromStorage;
+    /**
+     * Heuristic check: does the content look like JSON?
+     * @internal
+     */
+    private static _looksLikeJson;
+    /**
+     * Join path components, handling leading/trailing slashes.
+     * @internal
+     */
+    private static _joinPath;
+    /**
+     * Get the storage key for a given file path.
+     * @internal
+     */
+    private _getStorageKeyForPath;
+    /**
+     * Get the data path prefix for a given file path.
+     * @internal
+     */
+    private _getDataPathForPath;
+    /**
+     * Extract collection ID from a file path.
+     * Example: '/data/ingredients/my-collection.yaml' → 'my-collection'
+     * @internal
+     */
+    private _getCollectionIdFromPath;
+    /**
+     * Remove a file's entry from its localStorage key.
+     * @internal
+     */
+    private _deleteFileFromStorage;
+    /**
+     * Sync a single dirty file to localStorage.
+     * @internal
+     */
+    private _syncFile;
+    /**
+     * Sync all dirty files to localStorage.
+     * @returns Result indicating success or failure
+     * @public
+     */
+    syncToDisk(): Promise<Result<void>>;
+    /**
+     * Check if there are unsaved changes.
+     * @returns True if there are dirty files
+     * @public
+     */
+    isDirty(): boolean;
+    /**
+     * Get list of file paths with unsaved changes.
+     * @returns Array of dirty file paths
+     * @public
+     */
+    getDirtyPaths(): string[];
+    /**
+     * Delete a file and remove it from localStorage.
+     * @param path - File path to delete
+     * @returns Result with true if deleted, or error
+     * @public
+     */
+    deleteFile(path: string): Result<boolean>;
+    /**
+     * Save file contents. Marks file as dirty and optionally auto-syncs.
+     * @param path - File path
+     * @param contents - New file contents
+     * @returns Result with the saved contents or error
+     * @public
+     */
+    saveFileContents(path: string, contents: string): Result<string>;
+    /**
+     * Check if a file is mutable and return persistence detail.
+     * @param path - File path to check
+     * @returns DetailedResult with mutability status and 'persistent' detail if mutable
+     * @public
+     */
+    fileIsMutable(path: string): DetailedResult<boolean, FileTree.SaveDetail>;
+}
+//# sourceMappingURL=localStorageTreeAccessors.d.ts.map

package/lib/packlets/file-tree/localStorageTreeAccessors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localStorageTreeAccessors.d.ts","sourceRoot":"","sources":["../../../src/packlets/file-tree/localStorageTreeAccessors.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,cAAc,EAAQ,MAAM,EAA8B,MAAM,eAAe,CAAC;AACzF,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAG7C;;;GAGG;AACH,MAAM,WAAW,uBAAuB,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM,CAClE,SAAQ,QAAQ,CAAC,mBAAmB,CAAC,GAAG,CAAC;IACzC;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAErC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,yBAAyB,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM,CAChE,SAAQ,QAAQ,CAAC,qBAAqB,CAAC,GAAG,CAC1C,YAAW,QAAQ,CAAC,4BAA4B,CAAC,GAAG,CAAC;IAErD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsB;IACpD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsB;IACpD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;IAEpC;;;OAGG;IACH,OAAO;IAeP;;;;;;;OAOG;WACW,WAAW,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM,EACnD,MAAM,EAAE,uBAAuB,CAAC,GAAG,CAAC,GACnC,MAAM,CAAC,yBAAyB,CAAC,GAAG,CAAC,CAAC;IAmBzC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAwD/B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAK7B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,SAAS;IAOxB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAc7B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAU3B;;;;OAIG;IACH,OAAO,CAAC,wBAAwB;IAgBhC;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IA4B9B;;;OAGG;IACH,OAAO,CAAC,SAAS;IAyCjB;;;;OAIG;IACU,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAqBhD;;;;OAIG;IACI,OAAO,IAAI,OAAO;IAIzB;;;;OAIG;IACI,aAAa,IAAI,MAAM,EAAE;IAIhC;;;;;OAKG;IACI,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC;IAShD;;;;;;OAMG;IACI,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAgBvE;;;;;OAKG;IACI,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC;CAOjF"}