@statewalker/webrun-files-browser 0.5.0 → 0.7.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 statewalker
+Copyright (c) 2022-2026 statewalker
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,10 +1,10 @@
 # @statewalker/webrun-files-browser
 
-Browser File System Access API implementation for the `@statewalker/webrun-files` package.
+Browser File System Access API implementation of the `FilesApi` interface from `@statewalker/webrun-files`.
 
 ## Overview
 
-This package provides an `IFilesApi` implementation that works in modern browsers using the [File System Access API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API). It allows web applications to read and write files to:
+This package provides a `FilesApi` implementation that works in modern browsers using the [File System Access API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API). It allows web applications to read and write files to:
 
 - **User-selected directories** via `showDirectoryPicker()`
 - **Origin Private File System (OPFS)** - a sandboxed filesystem that persists between sessions
@@ -20,100 +20,95 @@ npm install @statewalker/webrun-files-browser @statewalker/webrun-files
 ### With User-Selected Directory
 
 ```typescript
-import { openBrowserFilesApi } from "@statewalker/webrun-files-browser";
-import { FilesApi } from "@statewalker/webrun-files";
+import { openBrowserFilesApi } from '@statewalker/webrun-files-browser';
+import { readText, writeText } from '@statewalker/webrun-files';
 
 // Opens a directory picker dialog (requires user gesture)
-const browserFs = await openBrowserFilesApi();
-const api = new FilesApi(browserFs);
+const files = await openBrowserFilesApi();
 
 // Write a file
-await api.write("/notes/hello.txt", [
-  new TextEncoder().encode("Hello, World!")
-]);
+await writeText(files, '/notes/hello.txt', 'Hello, World!');
 
 // Read a file
-const content = await api.readFile("/notes/hello.txt");
-console.log(new TextDecoder().decode(content)); // "Hello, World!"
+const content = await readText(files, '/notes/hello.txt');
+console.log(content); // "Hello, World!"
 
 // List directory contents
-for await (const entry of api.list("/notes")) {
+for await (const entry of files.list('/notes')) {
   console.log(entry.name, entry.kind);
 }
 ```
 
+### With Persistent Directory Handle
+
+Persist the directory handle using IndexedDB (via `idb-keyval` or similar) to avoid prompting the user every time:
+
+```typescript
+import { openBrowserFilesApi } from '@statewalker/webrun-files-browser';
+import { get, set, del } from 'idb-keyval';
+
+// Opens directory picker if no stored handle, otherwise reuses stored one
+const files = await openBrowserFilesApi({
+  handlerKey: 'my-project-dir',  // Key for storing the handle
+  readwrite: true,               // Request read-write access
+  get,                           // Retrieve stored handle
+  set,                           // Store the handle
+  del,                           // Delete stored handle if inaccessible
+});
+```
+
 ### With Origin Private File System (OPFS)
 
 OPFS provides a sandboxed filesystem that doesn't require user interaction:
 
 ```typescript
-import { getOPFSFilesApi } from "@statewalker/webrun-files-browser";
-import { FilesApi } from "@statewalker/webrun-files";
+import { getOPFSFilesApi } from '@statewalker/webrun-files-browser';
+import { writeText } from '@statewalker/webrun-files';
 
 // No user gesture required
-const opfsFs = await getOPFSFilesApi();
-const api = new FilesApi(opfsFs);
+const files = await getOPFSFilesApi();
 
-// Use the same API as above
-await api.write("/data/config.json", [
-  new TextEncoder().encode('{"theme": "dark"}')
-]);
+// Use the same API
+await writeText(files, '/data/config.json', '{"theme": "dark"}');
 ```
 
 ### With Custom Directory Handle
 
-You can also create a `BrowserFilesApi` instance with any `FileSystemDirectoryHandle`:
+Create a `BrowserFilesApi` instance with any `FileSystemDirectoryHandle`:
 
 ```typescript
-import { BrowserFilesApi } from "@statewalker/webrun-files-browser";
-import { FilesApi } from "@statewalker/webrun-files";
+import { BrowserFilesApi } from '@statewalker/webrun-files-browser';
 
 // Get a directory handle from drag & drop, IndexedDB, etc.
 const directoryHandle = await getDirectoryHandleSomehow();
 
-const browserFs = new BrowserFilesApi({ rootHandle: directoryHandle });
-const api = new FilesApi(browserFs);
+const files = new BrowserFilesApi({ rootHandle: directoryHandle });
 ```
 
 ## API Reference
 
 ### BrowserFilesApi
 
-Main class implementing `IFilesApi` for browser environments.
+Main class implementing `FilesApi` for browser environments.
 
 ```typescript
 interface BrowserFilesApiOptions {
   rootHandle: FileSystemDirectoryHandle;
 }
 
-class BrowserFilesApi implements IFilesApi {
+class BrowserFilesApi implements FilesApi {
   constructor(options: BrowserFilesApiOptions);
 
-  // Core IFilesApi methods
-  list(file: FileRef, options?: ListOptions): AsyncGenerator<FileInfo>;
-  stats(file: FileRef): Promise<FileInfo | undefined>;
-  remove(file: FileRef): Promise<boolean>;
-  open(file: FileRef): Promise<FileHandle>;
-
-  // Optional methods (implemented)
-  mkdir(file: FileRef): Promise<void>;
-  move(source: FileRef, target: FileRef): Promise<boolean>;
-  copy(source: FileRef, target: FileRef, options?: CopyOptions): Promise<boolean>;
-}
-```
-
-### BrowserFileHandle
-
-File handle class for random access read/write operations.
-
-```typescript
-class BrowserFileHandle implements FileHandle {
-  readonly size: number;
-
-  close(): Promise<void>;
-  appendFile(data: BinaryStream, options?: AppendOptions): Promise<number>;
-  createReadStream(options?: ReadStreamOptions): AsyncGenerator<Uint8Array>;
-  createWriteStream(data: BinaryStream, options?: WriteStreamOptions): Promise<number>;
+  // All FilesApi methods
+  read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array>;
+  write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;
+  mkdir(path: string): Promise<void>;
+  list(path: string, options?: ListOptions): AsyncIterable<FileInfo>;
+  stats(path: string): Promise<FileStats | undefined>;
+  exists(path: string): Promise<boolean>;
+  remove(path: string): Promise<boolean>;
+  move(source: string, target: string): Promise<boolean>;
+  copy(source: string, target: string): Promise<boolean>;
 }
 ```
 
@@ -121,49 +116,29 @@ class BrowserFileHandle implements FileHandle {
 
 ```typescript
 // Opens a directory picker and returns a BrowserFilesApi instance
-function openBrowserFilesApi(): Promise<BrowserFilesApi>;
+function openBrowserFilesApi(options?: OpenBrowserFilesApiOptions): Promise<BrowserFilesApi>;
+
+interface OpenBrowserFilesApiOptions {
+  handlerKey?: string;  // Key for storing the handle (default: "root-dir")
+  readwrite?: boolean;  // Request read-write access (default: true)
+  get?: (key: string) => Promise<FileSystemDirectoryHandle | undefined>;
+  set?: (key: string, handler: FileSystemDirectoryHandle) => Promise<void>;
+  del?: (key: string) => Promise<void>;
+}
 
 // Returns a BrowserFilesApi backed by the Origin Private File System
 function getOPFSFilesApi(): Promise<BrowserFilesApi>;
-```
-
-## How It Works
-
-### Directory Navigation
-
-The implementation navigates the filesystem by traversing `FileSystemDirectoryHandle` entries. Paths like `/docs/notes/file.txt` are resolved by getting directory handles step by step:
-
-```
-root → "docs" → "notes" → "file.txt"
-```
-
-### Reading Files
 
-Files are read using `File.slice()` for efficient partial reads. This enables random access without loading the entire file into memory:
+// Checks if a file system handle is still accessible
+function isHandlerAccessible(
+  fileHandle: FileSystemFileHandle | FileSystemDirectoryHandle
+): Promise<boolean>;
 
-```typescript
-const handle = await api.open("/large-file.bin");
-// Read only bytes 1000-2000
-for await (const chunk of handle.createReadStream({ start: 1000, end: 2000 })) {
-  console.log(chunk);
-}
-await handle.close();
-```
-
-### Writing Files
-
-Writes use `FileSystemWritableFileStream`:
-
-- **Full writes** create a new writable stream and write all data
-- **Partial writes** (with `start` option) preserve content before the start position
-- **Appends** seek to the end of the file before writing
-
-### Directory Creation
-
-Directories are created automatically when writing files. You can also create empty directories:
-
-```typescript
-await api.mkdir("/path/to/new/directory");
+// Verifies and requests file system permissions for a handle
+function verifyPermission(
+  fileHandle: FileSystemFileHandle | FileSystemDirectoryHandle,
+  readWrite?: boolean  // default: false
+): Promise<boolean>;
 ```
 
 ## Browser Support
@@ -174,7 +149,7 @@ The File System Access API is supported in:
 - Opera 72+
 - Chrome for Android 86+
 
-For other browsers, you may need a polyfill like [native-file-system-adapter](https://github.com/nicolo-ribaudo/native-file-system-adapter).
+For other browsers, you may need a polyfill like [native-file-system-adapter](https://github.com/jimmywarting/native-file-system-adapter).
 
 ## Security Considerations
 
@@ -183,19 +158,40 @@ For other browsers, you may need a polyfill like [native-file-system-adapter](ht
 - **Permission prompts**: Users must grant permission to access directories
 - **OPFS isolation**: Origin Private File System is isolated per-origin and not accessible to the user
 
-## Testing
+## Permission and Accessibility Utilities
 
-For testing in Node.js environments, we use [native-file-system-adapter](https://github.com/jimmywarting/native-file-system-adapter) which provides a memory backend:
+When working with persistent directory handles:
 
 ```typescript
-import { getOriginPrivateDirectory } from "native-file-system-adapter";
-import { BrowserFilesApi } from "@statewalker/webrun-files-browser";
+import { verifyPermission, isHandlerAccessible } from '@statewalker/webrun-files-browser';
 
-const rootHandle = await getOriginPrivateDirectory(
-  import("native-file-system-adapter/src/adapters/memory.js")
-);
+// Check if we have read-write permission
+const hasPermission = await verifyPermission(directoryHandle, true);
+
+// Check if the directory still exists and is accessible
+const isAccessible = await isHandlerAccessible(directoryHandle);
+
+if (!hasPermission) {
+  console.log('Permission denied - user may need to re-grant access');
+}
+
+if (!isAccessible) {
+  console.log('Directory no longer accessible - may have been deleted or moved');
+}
+```
+
+## Testing
+
+For testing in Node.js environments, use [native-file-system-adapter](https://github.com/jimmywarting/native-file-system-adapter) which provides a memory backend:
+
+```typescript
+import { getOriginPrivateDirectory } from 'native-file-system-adapter';
+// @ts-expect-error - no type declarations
+import * as driver from 'native-file-system-adapter/src/adapters/memory.js';
+import { BrowserFilesApi } from '@statewalker/webrun-files-browser';
 
-const api = new BrowserFilesApi({ rootHandle });
+const rootHandle = await getOriginPrivateDirectory(driver);
+const files = new BrowserFilesApi({ rootHandle });
 ```
 
 ## License

package/dist/browser-files-api.d.ts

@@ -1,10 +1,10 @@
 /**
- * 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, ListOptions } from "@statewalker/webrun-files";
+import type { FileInfo, FileStats, FilesApi, ListOptions, ReadOptions } from "@statewalker/webrun-files";
 export interface BrowserFilesApiOptions {
     /**
      * Root FileSystemDirectoryHandle to use as the filesystem root.
@@ -12,58 +12,30 @@ export interface BrowserFilesApiOptions {
      */
     rootHandle: FileSystemDirectoryHandle;
 }
-export declare 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 declare class BrowserFilesApi implements FilesApi {
     private rootHandle;
     constructor(options: BrowserFilesApiOptions);
-    /**
-     * Navigates to a directory handle from a path.
-     * Returns null if the directory doesn't exist and create is false.
-     */
     private getDirectoryHandle;
-    /**
-     * Gets a file handle from a path.
-     * Returns null if the file doesn't exist and create is false.
-     */
     private getFileHandle;
-    /**
-     * Lists entries in a directory.
-     */
-    list(file: FileRef, options?: ListOptions): AsyncGenerator<FileInfo>;
-    /**
-     * Gets file or directory stats.
-     */
-    stats(file: FileRef): Promise<FileInfo | undefined>;
-    /**
-     * Removes a file or directory.
-     */
-    remove(file: FileRef): Promise<boolean>;
-    /**
-     * Opens a file for reading and writing.
-     * Creates the file and parent directories if they don't exist.
-     */
-    open(file: FileRef): Promise<FileHandle>;
-    /**
-     * Creates a directory (and parent directories if needed).
-     */
-    mkdir(file: FileRef): Promise<void>;
-    /**
-     * Moves a file or directory using copy + delete.
-     * The File System Access API doesn't have a native move operation.
-     */
-    move(source: FileRef, target: FileRef): Promise<boolean>;
-    /**
-     * Copies a file or directory.
-     */
-    copy(source: FileRef, target: FileRef, options?: CopyOptions): Promise<boolean>;
+    read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array>;
+    write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;
+    mkdir(path: string): Promise<void>;
+    list(path: string, options?: ListOptions): AsyncIterable<FileInfo>;
+    stats(path: string): Promise<FileStats | undefined>;
+    exists(path: string): Promise<boolean>;
+    remove(path: string): Promise<boolean>;
+    move(source: string, target: string): Promise<boolean>;
+    copy(source: string, target: string): Promise<boolean>;
 }
-/**
- * Opens a browser directory picker and returns a BrowserFilesApi instance.
- * Only works in secure contexts (HTTPS) and requires user gesture.
- */
-export declare function openBrowserFilesApi(): Promise<BrowserFilesApi>;
 /**
  * Gets a BrowserFilesApi instance backed by the Origin Private File System (OPFS).
- * OPFS provides a sandboxed filesystem that persists between sessions.
  */
 export declare function getOPFSFilesApi(): Promise<BrowserFilesApi>;
 //# sourceMappingURL=browser-files-api.d.ts.map

package/dist/browser-files-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-files-api.d.ts","sourceRoot":"","sources":["../src/browser-files-api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,QAAQ,EACR,OAAO,EACP,SAAS,EACT,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAInC,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,UAAU,EAAE,yBAAyB,CAAC;CACvC;AAED,qBAAa,eAAgB,YAAW,SAAS;IAC/C,OAAO,CAAC,UAAU,CAA4B;gBAElC,OAAO,EAAE,sBAAsB;IAI3C;;;OAGG;YACW,kBAAkB;IAkBhC;;;OAGG;YACW,aAAa;IAkB3B;;OAEG;IACI,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,WAAgB,GAAG,cAAc,CAAC,QAAQ,CAAC;IAsC/E;;OAEG;IACG,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IA8CzD;;OAEG;IACG,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAgB7C;;;OAGG;IACG,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IAkB9C;;OAEG;IACG,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAKzC;;;OAGG;IACG,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAM9D;;OAEG;IACG,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;CAiF1F;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,eAAe,CAAC,CAIpE;AAED;;;GAGG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,eAAe,CAAC,CAGhE"}
+{"version":3,"file":"browser-files-api.d.ts","sourceRoot":"","sources":["../src/browser-files-api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAGnC,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,UAAU,EAAE,yBAAyB,CAAC;CACvC;AAED;;;;;;GAMG;AACH,qBAAa,eAAgB,YAAW,QAAQ;IAC9C,OAAO,CAAC,UAAU,CAA4B;gBAElC,OAAO,EAAE,sBAAsB;YAI7B,kBAAkB;YAkBlB,aAAa;IAkBpB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC;IA6BrE,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC;IAsBV,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC;IAqCnE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAqCnD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKtC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBtC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMtD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CA4E7D;AAED;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,eAAe,CAAC,CAGhE"}