@statewalker/webrun-files-browser 0.5.0 → 0.7.1

package/dist/esm/index.js

@@ -1,128 +1,17 @@
-import { basename, dirname, joinPath, resolveFileRef, toBinaryAsyncIterable } from "@statewalker/webrun-files";
-
-//#region src/browser-file-handle.ts
-var BrowserFileHandle = class {
-	fileHandle;
-	file;
-	_size;
-	closed = false;
-	constructor(options) {
-		this.fileHandle = options.fileHandle;
-		this.file = options.initialFile;
-		this._size = options.initialFile.size;
-	}
-	get size() {
-		return this._size;
-	}
-	async close() {
-		this.closed = true;
-		this.file = null;
-	}
-	/**
-	* Appends data to the end of the file.
-	*/
-	async appendFile(data, options = {}) {
-		if (this.closed) throw new Error("FileHandle is closed");
-		const { signal } = options;
-		const writable = await this.fileHandle.createWritable({ keepExistingData: true });
-		let bytesWritten = 0;
-		try {
-			await writable.seek(this._size);
-			for await (const chunk of toBinaryAsyncIterable(data)) {
-				if (signal?.aborted) throw new Error("Operation aborted");
-				await writable.write(chunk);
-				bytesWritten += chunk.length;
-			}
-		} finally {
-			await writable.close();
-		}
-		this.file = await this.fileHandle.getFile();
-		this._size = this.file.size;
-		return bytesWritten;
-	}
-	/**
-	* Creates a read stream for the file.
-	* Uses File.slice() for efficient partial reads.
-	*/
-	async *createReadStream(options = {}) {
-		if (this.closed) throw new Error("FileHandle is closed");
-		if (!this.file) {
-			this.file = await this.fileHandle.getFile();
-			this._size = this.file.size;
-		}
-		const { start = 0, end = Infinity, signal } = options;
-		const bufferSize = 8192;
-		const actualEnd = Math.min(end, this._size);
-		if (start >= actualEnd || this._size === 0) return;
-		let position = start;
-		while (position < actualEnd) {
-			if (signal?.aborted) throw new Error("Operation aborted");
-			const remaining = actualEnd - position;
-			const toRead = Math.min(bufferSize, remaining);
-			const buffer = await this.file.slice(position, position + toRead).arrayBuffer();
-			yield new Uint8Array(buffer);
-			position += buffer.byteLength;
-		}
-	}
-	/**
-	* 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.
-	*/
-	async createWriteStream(data, options = {}) {
-		if (this.closed) throw new Error("FileHandle is closed");
-		const { start = 0, signal } = options;
-		const writable = await this.fileHandle.createWritable({ keepExistingData: start > 0 });
-		let bytesWritten = 0;
-		try {
-			if (start > 0) {
-				await writable.seek(start);
-				await writable.truncate(start);
-			}
-			for await (const chunk of toBinaryAsyncIterable(data)) {
-				if (signal?.aborted) throw new Error("Operation aborted");
-				await writable.write(chunk);
-				bytesWritten += chunk.length;
-			}
-		} finally {
-			await writable.close();
-		}
-		this.file = await this.fileHandle.getFile();
-		this._size = this.file.size;
-		return bytesWritten;
-	}
-	/**
-	* Random access read from file at a specific position.
-	* Uses File.slice() for efficient partial reads.
-	*/
-	async read(buffer, offset, length, position) {
-		if (this.closed) throw new Error("FileHandle is closed");
-		if (!this.file) {
-			this.file = await this.fileHandle.getFile();
-			this._size = this.file.size;
-		}
-		let len = Math.min(length, buffer.length - offset);
-		len = Math.min(len, this._size - position);
-		len = Math.max(0, len);
-		if (len === 0) return 0;
-		const arrayBuffer = await this.file.slice(position, position + len).arrayBuffer();
-		const data = new Uint8Array(arrayBuffer);
-		buffer.set(data, offset);
-		return len;
-	}
-};
-
-//#endregion
+import { basename, dirname, joinPath, normalizePath } from "@statewalker/webrun-files";
 //#region src/browser-files-api.ts
+/**
+* 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).
+*/
 var BrowserFilesApi = class {
 	rootHandle;
 	constructor(options) {
 		this.rootHandle = options.rootHandle;
 	}
-	/**
-	* Navigates to a directory handle from a path.
-	* Returns null if the directory doesn't exist and create is false.
-	*/
 	async getDirectoryHandle(path, options = {}) {
 		const segments = path.split("/").filter((s) => s.length > 0);
 		let current = this.rootHandle;
@@ -133,12 +22,8 @@ var BrowserFilesApi = class {
 		}
 		return current;
 	}
-	/**
-	* Gets a file handle from a path.
-	* Returns null if the file doesn't exist and create is false.
-	*/
 	async getFileHandle(path, options = {}) {
-		const normalized = resolveFileRef(path);
+		const normalized = normalizePath(path);
 		const parentPath = dirname(normalized);
 		const fileName = basename(normalized);
 		const parent = await this.getDirectoryHandle(parentPath, options);
@@ -149,14 +34,51 @@ var BrowserFilesApi = class {
 			return null;
 		}
 	}
-	/**
-	* Lists entries in a directory.
-	*/
-	async *list(file, options = {}) {
-		const normalized = resolveFileRef(file);
+	async *read(path, options) {
+		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 !== void 0 ? 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 buffer = await file.slice(position, position + toRead).arrayBuffer();
+				yield new Uint8Array(buffer);
+				position += buffer.byteLength;
+			}
+		} catch {
+			return;
+		}
+	}
+	async write(path, content) {
+		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 writable = await (await parent.getFileHandle(fileName, { create: true })).createWritable();
+		try {
+			for await (const chunk of content) await writable.write(chunk);
+		} finally {
+			await writable.close();
+		}
+	}
+	async mkdir(path) {
+		const normalized = normalizePath(path);
+		await this.getDirectoryHandle(normalized, { create: true });
+	}
+	async *list(path, options) {
+		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);
 			const isDirectory = handle.kind === "directory";
@@ -167,25 +89,18 @@ var BrowserFilesApi = class {
 				lastModified: 0
 			};
 			if (!isDirectory) try {
-				const file$1 = await handle.getFile();
-				info.size = file$1.size;
-				info.lastModified = file$1.lastModified;
-				info.type = file$1.type;
+				const file = await handle.getFile();
+				info.size = file.size;
+				info.lastModified = file.lastModified;
 			} catch {}
 			yield info;
 			if (recursive && isDirectory) yield* this.list(entryPath, options);
 		}
 	}
-	/**
-	* Gets file or directory stats.
-	*/
-	async stats(file) {
-		const normalized = resolveFileRef(file);
-		const fileName = basename(normalized);
+	async stats(path) {
+		const normalized = normalizePath(path);
 		if (normalized === "/") return {
 			kind: "directory",
-			name: "",
-			path: "/",
 			lastModified: 0
 		};
 		const fileHandle = await this.getFileHandle(normalized);
@@ -193,27 +108,22 @@ var BrowserFilesApi = class {
 			const f = await fileHandle.getFile();
 			return {
 				kind: "file",
-				name: fileName,
-				path: normalized,
 				size: f.size,
-				lastModified: f.lastModified,
-				type: f.type
+				lastModified: f.lastModified
 			};
 		} catch {
 			return;
 		}
 		if (await this.getDirectoryHandle(normalized)) return {
 			kind: "directory",
-			name: fileName,
-			path: normalized,
 			lastModified: 0
 		};
 	}
-	/**
-	* Removes a file or directory.
-	*/
-	async remove(file) {
-		const normalized = resolveFileRef(file);
+	async exists(path) {
+		return await this.stats(path) !== void 0;
+	}
+	async remove(path) {
+		const normalized = normalizePath(path);
 		const parentPath = dirname(normalized);
 		const name = basename(normalized);
 		const parent = await this.getDirectoryHandle(parentPath);
@@ -225,47 +135,30 @@ var BrowserFilesApi = class {
 			return false;
 		}
 	}
-	/**
-	* Opens a file for reading and writing.
-	* Creates the file and parent directories if they don't exist.
-	*/
-	async open(file) {
-		const normalized = resolveFileRef(file);
-		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 });
-		return new BrowserFileHandle({
-			fileHandle,
-			initialFile: await fileHandle.getFile()
-		});
-	}
-	/**
-	* Creates a directory (and parent directories if needed).
-	*/
-	async mkdir(file) {
-		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, target) {
+		const sourcePath = normalizePath(source);
+		const targetPath = normalizePath(target);
+		const targetParentPath = dirname(targetPath);
+		const targetName = basename(targetPath);
+		const sourceStats = await this.stats(sourcePath);
+		if (!sourceStats) return false;
+		const sourceHandle = sourceStats.kind === "file" ? await this.getFileHandle(sourcePath) : await this.getDirectoryHandle(sourcePath);
+		if (!sourceHandle) return false;
+		if (typeof sourceHandle.move === "function") try {
+			const targetParent = await this.getDirectoryHandle(targetParentPath, { create: true });
+			if (!targetParent) return false;
+			await sourceHandle.move(targetParent, targetName);
+			return true;
+		} catch {}
 		if (!await this.copy(source, target)) return false;
 		return this.remove(source);
 	}
-	/**
-	* Copies a file or directory.
-	*/
-	async copy(source, target, options = {}) {
-		const sourcePath = resolveFileRef(source);
-		const targetPath = resolveFileRef(target);
-		const { recursive = true } = options;
-		const sourceInfo = await this.stats(source);
-		if (!sourceInfo) return false;
-		if (sourceInfo.kind === "file") {
+	async copy(source, target) {
+		const sourcePath = normalizePath(source);
+		const targetPath = normalizePath(target);
+		const sourceStats = await this.stats(source);
+		if (!sourceStats) return false;
+		if (sourceStats.kind === "file") {
 			const sourceHandle = await this.getFileHandle(sourcePath);
 			if (!sourceHandle) return false;
 			const sourceFile = await sourceHandle.getFile();
@@ -286,7 +179,6 @@ var BrowserFilesApi = class {
 			}
 			return true;
 		}
-		if (!recursive) return false;
 		await this.getDirectoryHandle(targetPath, { create: true });
 		for await (const entry of this.list(source, { recursive: true })) {
 			if (entry.kind === "directory") continue;
@@ -314,19 +206,75 @@ var BrowserFilesApi = class {
 	}
 };
 /**
-* Opens a browser directory picker and returns a BrowserFilesApi instance.
-* Only works in secure contexts (HTTPS) and requires user gesture.
-*/
-async function openBrowserFilesApi() {
-	return new BrowserFilesApi({ rootHandle: await globalThis.showDirectoryPicker() });
-}
-/**
 * Gets a BrowserFilesApi instance backed by the Origin Private File System (OPFS).
-* OPFS provides a sandboxed filesystem that persists between sessions.
 */
 async function getOPFSFilesApi() {
 	return new BrowserFilesApi({ rootHandle: await navigator.storage.getDirectory() });
 }
-
 //#endregion
-export { BrowserFileHandle, BrowserFilesApi, getOPFSFilesApi, openBrowserFilesApi };
+//#region src/open-browser-files-api.ts
+/**
+* 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.
+*/
+/**
+* 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
+*/
+async function isHandlerAccessible(fileHandle) {
+	try {
+		if (fileHandle.kind === "file") await fileHandle.getFile();
+		else for await (const _item of fileHandle.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
+*/
+async function verifyPermission(fileHandle, readWrite = false) {
+	const handle = fileHandle;
+	const options = {};
+	if (readWrite) options.mode = "readwrite";
+	if (await handle.queryPermission(options) === "granted") return true;
+	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
+*/
+async function openBrowserFilesApi(options = {}) {
+	const { handlerKey = "root-dir", readwrite = true, get = async () => void 0, set = async () => {}, del = async () => {} } = options;
+	let rootHandle = await get(handlerKey);
+	if (!rootHandle) {
+		rootHandle = await globalThis.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 });
+}
+//#endregion
+export { BrowserFilesApi, getOPFSFilesApi, isHandlerAccessible, openBrowserFilesApi, verifyPermission };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * webrun-files-browser - Browser File System Access API implementation
  */
-export { BrowserFilesApi, getOPFSFilesApi, openBrowserFilesApi, type BrowserFilesApiOptions, } from "./browser-files-api.js";
-export { BrowserFileHandle, type BrowserFileHandleOptions } from "./browser-file-handle.js";
+export { BrowserFilesApi, type BrowserFilesApiOptions, getOPFSFilesApi, } from "./browser-files-api.js";
+export { isHandlerAccessible, type OpenBrowserFilesApiOptions, openBrowserFilesApi, verifyPermission, } from "./open-browser-files-api.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,KAAK,sBAAsB,GAC5B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,eAAe,EACf,KAAK,sBAAsB,EAC3B,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,mBAAmB,EACnB,KAAK,0BAA0B,EAC/B,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,6BAA6B,CAAC"}

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

@@ -0,0 +1,67 @@
+/**
+ * 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";
+/**
+ * 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 declare function isHandlerAccessible(fileHandle: FileSystemFileHandle | FileSystemDirectoryHandle): Promise<boolean>;
+/**
+ * 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 declare function verifyPermission(fileHandle: FileSystemFileHandle | FileSystemDirectoryHandle, readWrite?: boolean): Promise<boolean>;
+/**
+ * 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 declare function openBrowserFilesApi(options?: OpenBrowserFilesApiOptions): Promise<BrowserFilesApi>;
+//# sourceMappingURL=open-browser-files-api.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"open-browser-files-api.d.ts","sourceRoot":"","sources":["../src/open-browser-files-api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAWzD;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,yBAAyB,GAAG,SAAS,CAAC,CAAC;IACtE;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,yBAAyB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzE;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,oBAAoB,GAAG,yBAAyB,GAC3D,OAAO,CAAC,OAAO,CAAC,CAclB;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,oBAAoB,GAAG,yBAAyB,EAC5D,SAAS,GAAE,OAAe,GACzB,OAAO,CAAC,OAAO,CAAC,CAkBlB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,eAAe,CAAC,CA6B1B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewalker/webrun-files-browser",
-  "version": "0.5.0",
+  "version": "0.7.1",
   "private": false,
   "type": "module",
   "description": "Browser File System Access API implementation for webrun-files",
@@ -28,25 +28,26 @@
     "dist",
     "src"
   ],
+  "scripts": {
+    "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
+    "test": "vitest run",
+    "lint": "biome lint src tests",
+    "prepublishOnly": "pnpm run build"
+  },
   "dependencies": {
-    "@statewalker/webrun-files": "0.5.0"
+    "@statewalker/webrun-files": "workspace:*"
   },
   "devDependencies": {
-    "@types/node": "^24.10.1",
+    "@statewalker/webrun-files-tests": "workspace:*",
+    "@types/node": "catalog:",
     "native-file-system-adapter": "^3.0.1",
-    "rimraf": "^6.1.2",
-    "rolldown": "^1.0.0-beta.53",
-    "typescript": "^5.6.0",
-    "vitest": "^4.0.12",
-    "@statewalker/webrun-files-tests": "1.0.0"
+    "rimraf": "catalog:",
+    "rolldown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
   },
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
-    "test": "vitest run",
-    "lint": "biome lint src tests"
   }
-}
+}