@fgv/ts-web-extras 5.1.0-19 → 5.1.0-20

package/src/packlets/file-api-types/index.ts

@@ -1,366 +0,0 @@
-/*
- * Copyright (c) 2025 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.
- */
-
-/**
- * File System Access API type definitions and utilities for browser compatibility.
- * @packageDocumentation
- */
-
-// Local type definitions for File System Access API
-// Based on https://wicg.github.io/file-system-access/
-
-/**
- * File System Access API methods available on Window
- * @public
- */
-export interface IFsAccessApis {
-  showDirectoryPicker(options?: ShowDirectoryPickerOptions): Promise<FileSystemDirectoryHandle>;
-  showOpenFilePicker(options?: ShowOpenFilePickerOptions): Promise<FileSystemFileHandle[]>;
-  showSaveFilePicker(options?: ShowSaveFilePickerOptions): Promise<FileSystemFileHandle>;
-}
-
-/**
- * Window interface extended with File System Access API
- * @public
- */
-export type WindowWithFsAccess = Window & IFsAccessApis;
-
-/**
- * Base interface for file system handles
- * @public
- */
-export interface FileSystemHandle {
-  readonly kind: 'file' | 'directory';
-  readonly name: string;
-  isSameEntry(other: FileSystemHandle): Promise<boolean>;
-  queryPermission(descriptor?: FileSystemHandlePermissionDescriptor): Promise<PermissionState>;
-  requestPermission(descriptor?: FileSystemHandlePermissionDescriptor): Promise<PermissionState>;
-}
-
-/**
- * File handle interface
- * @public
- */
-export interface FileSystemFileHandle extends FileSystemHandle {
-  readonly kind: 'file';
-  getFile(): Promise<File>;
-  createWritable(options?: FileSystemCreateWritableOptions): Promise<FileSystemWritableFileStream>;
-}
-
-/**
- * Directory handle interface
- * @public
- */
-export interface FileSystemDirectoryHandle extends FileSystemHandle {
-  readonly kind: 'directory';
-  getDirectoryHandle(
-    name: string,
-    options?: FileSystemGetDirectoryOptions
-  ): Promise<FileSystemDirectoryHandle>;
-  getFileHandle(name: string, options?: FileSystemGetFileOptions): Promise<FileSystemFileHandle>;
-  removeEntry(name: string, options?: FileSystemRemoveOptions): Promise<void>;
-  resolve(possibleDescendant: FileSystemHandle): Promise<string[] | null>;
-  keys(): AsyncIterableIterator<string>;
-  values(): AsyncIterableIterator<FileSystemHandle>;
-  entries(): AsyncIterableIterator<[string, FileSystemHandle]>;
-  [Symbol.asyncIterator](): AsyncIterableIterator<[string, FileSystemHandle]>;
-}
-
-/**
- * Permission descriptor for file system handles
- * @public
- */
-export interface FileSystemHandlePermissionDescriptor {
-  mode?: 'read' | 'readwrite';
-}
-
-/**
- * Options for creating writable file streams
- * @public
- */
-export interface FileSystemCreateWritableOptions {
-  keepExistingData?: boolean;
-}
-
-/**
- * Options for getting directory handles
- * @public
- */
-export interface FileSystemGetDirectoryOptions {
-  create?: boolean;
-}
-
-/**
- * Options for getting file handles
- * @public
- */
-export interface FileSystemGetFileOptions {
-  create?: boolean;
-}
-
-/**
- * Options for removing entries
- * @public
- */
-export interface FileSystemRemoveOptions {
-  recursive?: boolean;
-}
-
-/**
- * Writable file stream interface
- * @public
- */
-export interface FileSystemWritableFileStream extends WritableStream {
-  write(data: BufferSource | Blob | string): Promise<void>;
-  seek(position: number): Promise<void>;
-  truncate(size: number): Promise<void>;
-}
-
-/**
- * Directory picker options
- * @public
- */
-export interface ShowDirectoryPickerOptions {
-  id?: string;
-  mode?: 'read' | 'readwrite';
-  startIn?: FileSystemHandle | WellKnownDirectory;
-}
-
-/**
- * File picker options
- * @public
- */
-export interface ShowOpenFilePickerOptions {
-  multiple?: boolean;
-  excludeAcceptAllOption?: boolean;
-  id?: string;
-  startIn?: FileSystemHandle | WellKnownDirectory;
-  types?: FilePickerAcceptType[];
-}
-
-/**
- * Save file picker options
- * @public
- */
-export interface ShowSaveFilePickerOptions {
-  excludeAcceptAllOption?: boolean;
-  id?: string;
-  startIn?: FileSystemHandle | WellKnownDirectory;
-  suggestedName?: string;
-  types?: FilePickerAcceptType[];
-}
-
-/**
- * File picker accept type
- * @public
- */
-export interface FilePickerAcceptType {
-  description?: string;
-  accept: Record<string, string | string[]>;
-}
-
-/**
- * Well-known directory type
- * @public
- */
-export type WellKnownDirectory = 'desktop' | 'documents' | 'downloads' | 'music' | 'pictures' | 'videos';
-
-/**
- * Type guard to check if the browser supports the File System Access API
- * @param window - The window object to check
- * @returns True if the window supports File System Access API
- * @public
- */
-export function supportsFileSystemAccess(window: Window): window is WindowWithFsAccess {
-  return 'showOpenFilePicker' in window && 'showSaveFilePicker' in window && 'showDirectoryPicker' in window;
-}
-
-/**
- * Type guard to check if a FileSystemHandle is a file handle
- * @param handle - The handle to check
- * @returns True if the handle is a FileSystemFileHandle
- * @public
- */
-export function isFileHandle(handle: FileSystemHandle): handle is FileSystemFileHandle {
-  return handle.kind === 'file';
-}
-
-/**
- * Type guard to check if a FileSystemHandle is a directory handle
- * @param handle - The handle to check
- * @returns True if the handle is a FileSystemDirectoryHandle
- * @public
- */
-export function isDirectoryHandle(handle: FileSystemHandle): handle is FileSystemDirectoryHandle {
-  return handle.kind === 'directory';
-}
-
-/**
- * Safely access showOpenFilePicker with proper type checking
- * @param window - The window object
- * @param options - Options for the file picker
- * @returns Promise with file handles or null if not supported
- * @public
- */
-export async function safeShowOpenFilePicker(
-  window: Window,
-  options?: ShowOpenFilePickerOptions
-): Promise<FileSystemFileHandle[] | null> {
-  if (supportsFileSystemAccess(window)) {
-    try {
-      return await window.showOpenFilePicker(options);
-    } catch (error) {
-      if (error instanceof DOMException && error.name === 'AbortError') {
-        return null;
-      }
-      throw error;
-    }
-  }
-  return null;
-}
-
-/**
- * Safely access showSaveFilePicker with proper type checking
- * @param window - The window object
- * @param options - Options for the file picker
- * @returns Promise with file handle or null if not supported
- * @public
- */
-export async function safeShowSaveFilePicker(
-  window: Window,
-  options?: ShowSaveFilePickerOptions
-): Promise<FileSystemFileHandle | null> {
-  if (supportsFileSystemAccess(window)) {
-    try {
-      return await window.showSaveFilePicker(options);
-    } catch (error) {
-      if (error instanceof DOMException && error.name === 'AbortError') {
-        return null;
-      }
-      throw error;
-    }
-  }
-  return null;
-}
-
-/**
- * Safely access showDirectoryPicker with proper type checking
- * @param window - The window object
- * @param options - Options for the directory picker
- * @returns Promise with directory handle or null if not supported
- * @public
- */
-export async function safeShowDirectoryPicker(
-  window: Window,
-  options?: ShowDirectoryPickerOptions
-): Promise<FileSystemDirectoryHandle | null> {
-  if (supportsFileSystemAccess(window)) {
-    try {
-      return await window.showDirectoryPicker(options);
-    } catch (error) {
-      if (error instanceof DOMException && error.name === 'AbortError') {
-        return null;
-      }
-      throw error;
-    }
-  }
-  return null;
-}
-
-/**
- * Export data as JSON file using legacy blob download method.
- * Creates a temporary download link and triggers file download.
- * @param data - Data to export as JSON
- * @param filename - Name for the downloaded file
- * @public
- */
-export function exportAsJson(data: unknown, filename: string): void {
-  const json = JSON.stringify(data, null, 2);
-  const blob = new Blob([json], { type: 'application/json' });
-  const url = URL.createObjectURL(blob);
-
-  const a = document.createElement('a');
-  a.href = url;
-  a.download = filename;
-  document.body.appendChild(a);
-  a.click();
-  document.body.removeChild(a);
-  URL.revokeObjectURL(url);
-}
-
-/**
- * Export data using File System Access API with fallback to blob download.
- * @param data - Data to export as JSON
- * @param suggestedName - Suggested filename for the save dialog
- * @param description - Description for file type filter (default: 'JSON files')
- * @param window - Window object for API access (default: globalThis.window)
- * @returns Promise resolving to true if saved via File System Access API, false if fallback used
- * @public
- */
-export async function exportUsingFileSystemAPI(
-  data: unknown,
-  suggestedName: string,
-  description: string = 'JSON files',
-  window: Window = globalThis.window
-): Promise<boolean> {
-  if (!supportsFileSystemAccess(window)) {
-    // Fallback to blob download
-    exportAsJson(data, suggestedName);
-    return false;
-  }
-
-  try {
-    const fileHandle = await safeShowSaveFilePicker(window, {
-      suggestedName,
-      types: [
-        {
-          description,
-          accept: {
-            'application/json': ['.json']
-          }
-        }
-      ]
-    });
-
-    if (!fileHandle) {
-      // User cancelled - fallback to blob download
-      exportAsJson(data, suggestedName);
-      return false;
-    }
-
-    const json = JSON.stringify(data, null, 2);
-    const writable = await fileHandle.createWritable();
-    await writable.write(json);
-    await writable.close();
-
-    return true;
-  } catch (error) {
-    // Handle errors by falling back to blob download
-    if ((error as Error).name === 'AbortError') {
-      // User cancelled - fallback
-      exportAsJson(data, suggestedName);
-      return false;
-    }
-    // Other errors - re-throw as they indicate a real problem
-    throw error;
-  }
-}

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

@@ -1,136 +0,0 @@
-// 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.
-
-/**
- * Persistent storage for FileSystemDirectoryHandle objects using IndexedDB.
- * Allows directory handles to survive page reloads without re-prompting the user.
- * @packageDocumentation
- */
-
-import { fail, Result, succeed } from '@fgv/ts-utils';
-import { createStore, del, get, keys, set } from 'idb-keyval';
-import { FileSystemDirectoryHandle } from '../file-api-types';
-
-/**
- * Default IndexedDB database name for directory handles.
- * @public
- */
-export const DEFAULT_DIRECTORY_HANDLE_DB = 'chocolate-lab-storage';
-
-/**
- * Default IndexedDB store name for directory handles.
- * @public
- */
-export const DEFAULT_DIRECTORY_HANDLE_STORE = 'directory-handles';
-
-/**
- * Manages persistence of {@link FileSystemDirectoryHandle} objects in IndexedDB.
- * Keyed by a label (typically the directory name).
- * @public
- */
-export class DirectoryHandleStore {
-  private readonly _store: ReturnType<typeof createStore>;
-
-  public constructor(
-    dbName: string = DEFAULT_DIRECTORY_HANDLE_DB,
-    storeName: string = DEFAULT_DIRECTORY_HANDLE_STORE
-  ) {
-    this._store = createStore(dbName, storeName);
-  }
-
-  /**
-   * Saves a directory handle to IndexedDB under the given label.
-   * @param label - Key to store the handle under (typically dirHandle.name)
-   * @param handle - The FileSystemDirectoryHandle to persist
-   * @returns Success or Failure
-   */
-  public async save(label: string, handle: FileSystemDirectoryHandle): Promise<Result<void>> {
-    try {
-      await set(label, handle, this._store);
-      return succeed(undefined);
-    } catch (e) {
-      return fail(`DirectoryHandleStore.save "${label}": ${String(e)}`);
-    }
-  }
-
-  /**
-   * Retrieves a directory handle by label.
-   * @param label - Key to look up
-   * @returns Success with handle (or undefined if not found), or Failure on error
-   */
-  public async load(label: string): Promise<Result<FileSystemDirectoryHandle | undefined>> {
-    try {
-      const handle = await get<FileSystemDirectoryHandle>(label, this._store);
-      return succeed(handle);
-    } catch (e) {
-      return fail(`DirectoryHandleStore.load "${label}": ${String(e)}`);
-    }
-  }
-
-  /**
-   * Removes a directory handle from IndexedDB.
-   * @param label - Key to remove
-   * @returns Success or Failure
-   */
-  public async remove(label: string): Promise<Result<void>> {
-    try {
-      await del(label, this._store);
-      return succeed(undefined);
-    } catch (e) {
-      return fail(`DirectoryHandleStore.remove "${label}": ${String(e)}`);
-    }
-  }
-
-  /**
-   * Returns all stored labels (keys).
-   * @returns Success with array of labels, or Failure
-   */
-  public async getAllLabels(): Promise<Result<string[]>> {
-    try {
-      const allKeys = await keys<string>(this._store);
-      return succeed(allKeys);
-    } catch (e) {
-      return fail(`DirectoryHandleStore.getAllLabels: ${String(e)}`);
-    }
-  }
-
-  /**
-   * Returns all stored handles as label/handle pairs.
-   * @returns Success with array of entries, or Failure
-   */
-  public async getAll(): Promise<Result<Array<{ label: string; handle: FileSystemDirectoryHandle }>>> {
-    const labelsResult = await this.getAllLabels();
-    if (labelsResult.isFailure()) {
-      return fail(labelsResult.message);
-    }
-
-    const entries: Array<{ label: string; handle: FileSystemDirectoryHandle }> = [];
-    for (const label of labelsResult.value) {
-      const handleResult = await this.load(label);
-      if (handleResult.isFailure()) {
-        return fail(handleResult.message);
-      }
-      if (handleResult.value !== undefined) {
-        entries.push({ label, handle: handleResult.value });
-      }
-    }
-    return succeed(entries);
-  }
-}