@statewalker/webrun-files-browser 0.5.0 → 0.7.0

package/src/browser-files-api.ts

@@ -1,20 +1,18 @@
 /**
- * Browser implementation of IFilesApi using the File System Access API.
+ * Browser implementation of FilesApi using the File System Access API.
  *
  * Provides a filesystem-like interface over browser's FileSystemDirectoryHandle.
  * Works with directories obtained via showDirectoryPicker() or OPFS.
  */
 
 import type {
-  CopyOptions,
-  FileHandle,
   FileInfo,
-  FileRef,
-  IFilesApi,
+  FileStats,
+  FilesApi,
   ListOptions,
+  ReadOptions,
 } from "@statewalker/webrun-files";
-import { basename, dirname, joinPath, resolveFileRef } from "@statewalker/webrun-files";
-import { BrowserFileHandle } from "./browser-file-handle.js";
+import { basename, dirname, joinPath, normalizePath } from "@statewalker/webrun-files";
 
 export interface BrowserFilesApiOptions {
   /**
@@ -24,17 +22,20 @@ export interface BrowserFilesApiOptions {
   rootHandle: FileSystemDirectoryHandle;
 }
 
-export class BrowserFilesApi implements IFilesApi {
+/**
+ * Browser filesystem implementation using the File System Access API.
+ *
+ * Provides FilesApi interface over browser's FileSystemDirectoryHandle.
+ * This enables web applications to read/write files in user-selected directories
+ * or the Origin Private File System (OPFS).
+ */
+export class BrowserFilesApi implements FilesApi {
   private rootHandle: FileSystemDirectoryHandle;
 
   constructor(options: BrowserFilesApiOptions) {
     this.rootHandle = options.rootHandle;
   }
 
-  /**
-   * Navigates to a directory handle from a path.
-   * Returns null if the directory doesn't exist and create is false.
-   */
   private async getDirectoryHandle(
     path: string,
     options: { create?: boolean } = {},
@@ -53,15 +54,11 @@ export class BrowserFilesApi implements IFilesApi {
     return current;
   }
 
-  /**
-   * Gets a file handle from a path.
-   * Returns null if the file doesn't exist and create is false.
-   */
   private async getFileHandle(
     path: string,
     options: { create?: boolean } = {},
   ): Promise<FileSystemFileHandle | null> {
-    const normalized = resolveFileRef(path);
+    const normalized = normalizePath(path);
     const parentPath = dirname(normalized);
     const fileName = basename(normalized);
 
@@ -75,15 +72,71 @@ export class BrowserFilesApi implements IFilesApi {
     }
   }
 
-  /**
-   * Lists entries in a directory.
-   */
-  async *list(file: FileRef, options: ListOptions = {}): AsyncGenerator<FileInfo> {
-    const normalized = resolveFileRef(file);
+  async *read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array> {
+    const fileHandle = await this.getFileHandle(path);
+    if (!fileHandle) return;
+
+    try {
+      const file = await fileHandle.getFile();
+      const start = options?.start ?? 0;
+      const length = options?.length;
+      const end = length !== undefined ? start + length : file.size;
+
+      if (start >= file.size) return;
+
+      const bufferSize = 8192;
+      let position = start;
+      const actualEnd = Math.min(end, file.size);
+
+      while (position < actualEnd) {
+        const remaining = actualEnd - position;
+        const toRead = Math.min(bufferSize, remaining);
+        const slice = file.slice(position, position + toRead);
+        const buffer = await slice.arrayBuffer();
+        yield new Uint8Array(buffer);
+        position += buffer.byteLength;
+      }
+    } catch {
+      return;
+    }
+  }
+
+  async write(
+    path: string,
+    content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>,
+  ): Promise<void> {
+    const normalized = normalizePath(path);
+    const parentPath = dirname(normalized);
+    const fileName = basename(normalized);
+
+    const parent = await this.getDirectoryHandle(parentPath, { create: true });
+    if (!parent) {
+      throw new Error(`Cannot create directory: ${parentPath}`);
+    }
+
+    const fileHandle = await parent.getFileHandle(fileName, { create: true });
+    const writable = await fileHandle.createWritable();
+
+    try {
+      for await (const chunk of content) {
+        await writable.write(chunk as Uint8Array<ArrayBuffer>);
+      }
+    } finally {
+      await writable.close();
+    }
+  }
+
+  async mkdir(path: string): Promise<void> {
+    const normalized = normalizePath(path);
+    await this.getDirectoryHandle(normalized, { create: true });
+  }
+
+  async *list(path: string, options?: ListOptions): AsyncIterable<FileInfo> {
+    const normalized = normalizePath(path);
     const dirHandle = await this.getDirectoryHandle(normalized);
     if (!dirHandle) return;
 
-    const { recursive = false } = options;
+    const recursive = options?.recursive ?? false;
 
     for await (const [name, handle] of dirHandle.entries()) {
       const entryPath = joinPath(normalized, name);
@@ -102,7 +155,6 @@ export class BrowserFilesApi implements IFilesApi {
           const file = await fileHandle.getFile();
           info.size = file.size;
           info.lastModified = file.lastModified;
-          info.type = file.type;
         } catch {
           // Ignore errors getting file metadata
         }
@@ -116,19 +168,12 @@ export class BrowserFilesApi implements IFilesApi {
     }
   }
 
-  /**
-   * Gets file or directory stats.
-   */
-  async stats(file: FileRef): Promise<FileInfo | undefined> {
-    const normalized = resolveFileRef(file);
-    const fileName = basename(normalized);
+  async stats(path: string): Promise<FileStats | undefined> {
+    const normalized = normalizePath(path);
 
-    // Handle root directory
     if (normalized === "/") {
       return {
         kind: "directory",
-        name: "",
-        path: "/",
         lastModified: 0,
       };
     }
@@ -140,11 +185,8 @@ export class BrowserFilesApi implements IFilesApi {
         const f = await fileHandle.getFile();
         return {
           kind: "file",
-          name: fileName,
-          path: normalized,
           size: f.size,
           lastModified: f.lastModified,
-          type: f.type,
         };
       } catch {
         return undefined;
@@ -156,8 +198,6 @@ export class BrowserFilesApi implements IFilesApi {
     if (dirHandle) {
       return {
         kind: "directory",
-        name: fileName,
-        path: normalized,
         lastModified: 0,
       };
     }
@@ -165,11 +205,13 @@ export class BrowserFilesApi implements IFilesApi {
     return undefined;
   }
 
-  /**
-   * Removes a file or directory.
-   */
-  async remove(file: FileRef): Promise<boolean> {
-    const normalized = resolveFileRef(file);
+  async exists(path: string): Promise<boolean> {
+    const stats = await this.stats(path);
+    return stats !== undefined;
+  }
+
+  async remove(path: string): Promise<boolean> {
+    const normalized = normalizePath(path);
     const parentPath = dirname(normalized);
     const name = basename(normalized);
 
@@ -184,65 +226,26 @@ export class BrowserFilesApi implements IFilesApi {
     }
   }
 
-  /**
-   * Opens a file for reading and writing.
-   * Creates the file and parent directories if they don't exist.
-   */
-  async open(file: FileRef): Promise<FileHandle> {
-    const normalized = resolveFileRef(file);
-    const parentPath = dirname(normalized);
-    const fileName = basename(normalized);
-
-    // Ensure parent directory exists
-    const parent = await this.getDirectoryHandle(parentPath, { create: true });
-    if (!parent) {
-      throw new Error(`Cannot create directory: ${parentPath}`);
-    }
-
-    // Get or create file
-    const fileHandle = await parent.getFileHandle(fileName, { create: true });
-    const f = await fileHandle.getFile();
-
-    return new BrowserFileHandle({ fileHandle, initialFile: f });
-  }
-
-  /**
-   * Creates a directory (and parent directories if needed).
-   */
-  async mkdir(file: FileRef): Promise<void> {
-    const normalized = resolveFileRef(file);
-    await this.getDirectoryHandle(normalized, { create: true });
-  }
-
-  /**
-   * Moves a file or directory using copy + delete.
-   * The File System Access API doesn't have a native move operation.
-   */
-  async move(source: FileRef, target: FileRef): Promise<boolean> {
+  async move(source: string, target: string): Promise<boolean> {
     const copied = await this.copy(source, target);
     if (!copied) return false;
     return this.remove(source);
   }
 
-  /**
-   * Copies a file or directory.
-   */
-  async copy(source: FileRef, target: FileRef, options: CopyOptions = {}): Promise<boolean> {
-    const sourcePath = resolveFileRef(source);
-    const targetPath = resolveFileRef(target);
-    const { recursive = true } = options;
+  async copy(source: string, target: string): Promise<boolean> {
+    const sourcePath = normalizePath(source);
+    const targetPath = normalizePath(target);
 
-    const sourceInfo = await this.stats(source);
-    if (!sourceInfo) return false;
+    const sourceStats = await this.stats(source);
+    if (!sourceStats) return false;
 
-    if (sourceInfo.kind === "file") {
+    if (sourceStats.kind === "file") {
       // Copy single file
       const sourceHandle = await this.getFileHandle(sourcePath);
       if (!sourceHandle) return false;
 
       const sourceFile = await sourceHandle.getFile();
 
-      // Create target file
       const targetParentPath = dirname(targetPath);
       const targetFileName = basename(targetPath);
 
@@ -253,7 +256,6 @@ export class BrowserFilesApi implements IFilesApi {
       const writable = await targetHandle.createWritable();
 
       try {
-        // Stream the file content
         const reader = sourceFile.stream().getReader();
         while (true) {
           const { done, value } = await reader.read();
@@ -267,13 +269,9 @@ export class BrowserFilesApi implements IFilesApi {
       return true;
     }
 
-    // Copy directory
-    if (!recursive) return false;
-
-    // Create target directory
+    // Copy directory recursively
     await this.getDirectoryHandle(targetPath, { create: true });
 
-    // Copy all entries recursively
     for await (const entry of this.list(source, { recursive: true })) {
       if (entry.kind === "directory") continue;
 
@@ -291,7 +289,9 @@ export class BrowserFilesApi implements IFilesApi {
       const newTargetParent = await this.getDirectoryHandle(newTargetParentPath, { create: true });
       if (!newTargetParent) continue;
 
-      const newTargetHandle = await newTargetParent.getFileHandle(newTargetFileName, { create: true });
+      const newTargetHandle = await newTargetParent.getFileHandle(newTargetFileName, {
+        create: true,
+      });
       const writable = await newTargetHandle.createWritable();
 
       try {
@@ -310,19 +310,8 @@ export class BrowserFilesApi implements IFilesApi {
   }
 }
 
-/**
- * Opens a browser directory picker and returns a BrowserFilesApi instance.
- * Only works in secure contexts (HTTPS) and requires user gesture.
- */
-export async function openBrowserFilesApi(): Promise<BrowserFilesApi> {
-  // Cast to any since TypeScript's lib.dom.d.ts may not include showDirectoryPicker
-  const rootHandle = await (globalThis as unknown as { showDirectoryPicker: () => Promise<FileSystemDirectoryHandle> }).showDirectoryPicker();
-  return new BrowserFilesApi({ rootHandle });
-}
-
 /**
  * Gets a BrowserFilesApi instance backed by the Origin Private File System (OPFS).
- * OPFS provides a sandboxed filesystem that persists between sessions.
  */
 export async function getOPFSFilesApi(): Promise<BrowserFilesApi> {
   const rootHandle = await navigator.storage.getDirectory();

package/src/index.ts

@@ -4,9 +4,12 @@
 
 export {
   BrowserFilesApi,
-  getOPFSFilesApi,
-  openBrowserFilesApi,
   type BrowserFilesApiOptions,
+  getOPFSFilesApi,
 } from "./browser-files-api.js";
-
-export { BrowserFileHandle, type BrowserFileHandleOptions } from "./browser-file-handle.js";
+export {
+  isHandlerAccessible,
+  type OpenBrowserFilesApiOptions,
+  openBrowserFilesApi,
+  verifyPermission,
+} from "./open-browser-files-api.js";

package/src/open-browser-files-api.ts

@@ -0,0 +1,148 @@
+/**
+ * Utilities for opening and managing browser file system access.
+ *
+ * Provides functions for permission verification, handle accessibility checking,
+ * and opening directory pickers with optional persistent storage support.
+ */
+
+import { BrowserFilesApi } from "./browser-files-api.js";
+
+/**
+ * Extended FileSystemHandle interface with permission methods.
+ * These are part of the File System Access API but not fully typed in TypeScript's lib.dom.d.ts.
+ */
+interface FileSystemHandleWithPermissions {
+  queryPermission(descriptor?: { mode?: "read" | "readwrite" }): Promise<PermissionState>;
+  requestPermission(descriptor?: { mode?: "read" | "readwrite" }): Promise<PermissionState>;
+}
+
+/**
+ * Options for opening a browser files API with persistent storage support.
+ */
+export interface OpenBrowserFilesApiOptions {
+  /**
+   * Key used to store the directory handler in persistent storage.
+   * @default "root-dir"
+   */
+  handlerKey?: string;
+  /**
+   * Whether to request read-write access (true) or read-only (false).
+   * @default true
+   */
+  readwrite?: boolean;
+  /**
+   * Gets a stored directory handler by key.
+   * @default Returns undefined (no persistence)
+   */
+  get?: (key: string) => Promise<FileSystemDirectoryHandle | undefined>;
+  /**
+   * Stores a directory handler with a key.
+   * @default No-op (no persistence)
+   */
+  set?: (key: string, handler: FileSystemDirectoryHandle) => Promise<void>;
+  /**
+   * Deletes a stored directory handler by key.
+   * @default No-op (no persistence)
+   */
+  del?: (key: string) => Promise<void>;
+}
+
+/**
+ * Checks if a file system handle is still accessible by performing a real read operation.
+ * Handles may become inaccessible if the underlying file/directory was moved or deleted.
+ *
+ * @param fileHandle - The file or directory handle to check
+ * @returns True if the handle is accessible, false otherwise
+ */
+export async function isHandlerAccessible(
+  fileHandle: FileSystemFileHandle | FileSystemDirectoryHandle,
+): Promise<boolean> {
+  try {
+    if (fileHandle.kind === "file") {
+      await (fileHandle as FileSystemFileHandle).getFile();
+    } else {
+      // For directories, iterate to check accessibility
+      for await (const _item of (fileHandle as FileSystemDirectoryHandle).values()) {
+        break;
+      }
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Verifies and requests file system permissions for a handle.
+ * First checks if permission was already granted, then requests if needed.
+ *
+ * @param fileHandle - The file or directory handle to verify permissions for
+ * @param readWrite - Whether to request read-write access (true) or read-only (false)
+ * @returns True if permission is granted, false otherwise
+ */
+export async function verifyPermission(
+  fileHandle: FileSystemFileHandle | FileSystemDirectoryHandle,
+  readWrite: boolean = false,
+): Promise<boolean> {
+  const handle = fileHandle as unknown as FileSystemHandleWithPermissions;
+  const options: { mode?: "read" | "readwrite" } = {};
+  if (readWrite) {
+    options.mode = "readwrite";
+  }
+
+  // Check if permission was already granted
+  if ((await handle.queryPermission(options)) === "granted") {
+    return true;
+  }
+
+  // Request permission if not already granted
+  if ((await handle.requestPermission(options)) === "granted") {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Opens a browser directory picker and returns a BrowserFilesApi instance.
+ * Only works in secure contexts (HTTPS) and requires user gesture.
+ *
+ * Supports persistent storage of directory handles via optional get/set/del functions.
+ * When persistence is configured, will attempt to reuse a previously selected directory.
+ *
+ * @param options - Configuration options for opening the files API
+ * @returns A BrowserFilesApi instance for the selected directory
+ * @throws Error if access is not granted or the directory is not accessible
+ */
+export async function openBrowserFilesApi(
+  options: OpenBrowserFilesApiOptions = {},
+): Promise<BrowserFilesApi> {
+  const {
+    handlerKey = "root-dir",
+    readwrite = true,
+    get = async () => undefined,
+    set = async () => {},
+    del = async () => {},
+  } = options;
+
+  let rootHandle = await get(handlerKey);
+
+  if (!rootHandle) {
+    // Cast to any since TypeScript's lib.dom.d.ts may not include showDirectoryPicker
+    rootHandle = await (
+      globalThis as unknown as { showDirectoryPicker: () => Promise<FileSystemDirectoryHandle> }
+    ).showDirectoryPicker();
+    await set(handlerKey, rootHandle);
+  }
+
+  if (!(await verifyPermission(rootHandle, readwrite))) {
+    throw new Error("Access was not granted");
+  }
+
+  if (!(await isHandlerAccessible(rootHandle))) {
+    await del(handlerKey);
+    throw new Error("Cannot access the folder. Please try again.");
+  }
+
+  return new BrowserFilesApi({ rootHandle });
+}

package/dist/browser-file-handle.d.ts

@@ -1,42 +0,0 @@
-/**
- * Browser FileHandle implementation using File System Access API.
- *
- * Provides random access read/write operations for browser files.
- * Uses File.slice() for efficient partial reads and FileSystemWritableFileStream
- * for writes.
- */
-import type { AppendOptions, BinaryStream, FileHandle, ReadStreamOptions, WriteStreamOptions } from "@statewalker/webrun-files";
-export interface BrowserFileHandleOptions {
-    fileHandle: FileSystemFileHandle;
-    initialFile: File;
-}
-export declare class BrowserFileHandle implements FileHandle {
-    private fileHandle;
-    private file;
-    private _size;
-    private closed;
-    constructor(options: BrowserFileHandleOptions);
-    get size(): number;
-    close(): Promise<void>;
-    /**
-     * Appends data to the end of the file.
-     */
-    appendFile(data: BinaryStream, options?: AppendOptions): Promise<number>;
-    /**
-     * Creates a read stream for the file.
-     * Uses File.slice() for efficient partial reads.
-     */
-    createReadStream(options?: ReadStreamOptions): AsyncGenerator<Uint8Array>;
-    /**
-     * Writes data to the file starting at the specified position.
-     * If start > 0, preserves content before start position.
-     * Truncates file at start position before writing.
-     */
-    createWriteStream(data: BinaryStream, options?: WriteStreamOptions): Promise<number>;
-    /**
-     * Random access read from file at a specific position.
-     * Uses File.slice() for efficient partial reads.
-     */
-    read(buffer: Uint8Array, offset: number, length: number, position: number): Promise<number>;
-}
-//# sourceMappingURL=browser-file-handle.d.ts.map

package/dist/browser-file-handle.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"browser-file-handle.d.ts","sourceRoot":"","sources":["../src/browser-file-handle.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,2BAA2B,CAAC;AAGnC,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,oBAAoB,CAAC;IACjC,WAAW,EAAE,IAAI,CAAC;CACnB;AAED,qBAAa,iBAAkB,YAAW,UAAU;IAClD,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,IAAI,CAAc;IAC1B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,EAAE,wBAAwB;IAM7C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B;;OAEG;IACG,UAAU,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC;IAgClF;;;OAGG;IACI,gBAAgB,CAAC,OAAO,GAAE,iBAAsB,GAAG,cAAc,CAAC,UAAU,CAAC;IAmCpF;;;;OAIG;IACG,iBAAiB,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC;IAyC9F;;;OAGG;IACG,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CA0BlG"}