@statewalker/webrun-files-browser 0.5.0 → 0.7.0

package/dist/cjs/index.cjs

@@ -1,128 +1,18 @@
 let __statewalker_webrun_files = require("@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 (0, __statewalker_webrun_files.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 (0, __statewalker_webrun_files.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
 //#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 +23,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 = (0, __statewalker_webrun_files.resolveFileRef)(path);
+		const normalized = (0, __statewalker_webrun_files.normalizePath)(path);
 		const parentPath = (0, __statewalker_webrun_files.dirname)(normalized);
 		const fileName = (0, __statewalker_webrun_files.basename)(normalized);
 		const parent = await this.getDirectoryHandle(parentPath, options);
@@ -149,14 +35,51 @@ var BrowserFilesApi = class {
 			return null;
 		}
 	}
-	/**
-	* Lists entries in a directory.
-	*/
-	async *list(file, options = {}) {
-		const normalized = (0, __statewalker_webrun_files.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 = (0, __statewalker_webrun_files.normalizePath)(path);
+		const parentPath = (0, __statewalker_webrun_files.dirname)(normalized);
+		const fileName = (0, __statewalker_webrun_files.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 = (0, __statewalker_webrun_files.normalizePath)(path);
+		await this.getDirectoryHandle(normalized, { create: true });
+	}
+	async *list(path, options) {
+		const normalized = (0, __statewalker_webrun_files.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 = (0, __statewalker_webrun_files.joinPath)(normalized, name);
 			const isDirectory = handle.kind === "directory";
@@ -167,25 +90,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 = (0, __statewalker_webrun_files.resolveFileRef)(file);
-		const fileName = (0, __statewalker_webrun_files.basename)(normalized);
+	async stats(path) {
+		const normalized = (0, __statewalker_webrun_files.normalizePath)(path);
 		if (normalized === "/") return {
 			kind: "directory",
-			name: "",
-			path: "/",
 			lastModified: 0
 		};
 		const fileHandle = await this.getFileHandle(normalized);
@@ -193,27 +109,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 = (0, __statewalker_webrun_files.resolveFileRef)(file);
+	async exists(path) {
+		return await this.stats(path) !== void 0;
+	}
+	async remove(path) {
+		const normalized = (0, __statewalker_webrun_files.normalizePath)(path);
 		const parentPath = (0, __statewalker_webrun_files.dirname)(normalized);
 		const name = (0, __statewalker_webrun_files.basename)(normalized);
 		const parent = await this.getDirectoryHandle(parentPath);
@@ -225,47 +136,16 @@ 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 = (0, __statewalker_webrun_files.resolveFileRef)(file);
-		const parentPath = (0, __statewalker_webrun_files.dirname)(normalized);
-		const fileName = (0, __statewalker_webrun_files.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 = (0, __statewalker_webrun_files.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) {
 		if (!await this.copy(source, target)) return false;
 		return this.remove(source);
 	}
-	/**
-	* Copies a file or directory.
-	*/
-	async copy(source, target, options = {}) {
-		const sourcePath = (0, __statewalker_webrun_files.resolveFileRef)(source);
-		const targetPath = (0, __statewalker_webrun_files.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 = (0, __statewalker_webrun_files.normalizePath)(source);
+		const targetPath = (0, __statewalker_webrun_files.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 +166,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,22 +193,81 @@ 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
-exports.BrowserFileHandle = BrowserFileHandle;
+//#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
 exports.BrowserFilesApi = BrowserFilesApi;
 exports.getOPFSFilesApi = getOPFSFilesApi;
-exports.openBrowserFilesApi = openBrowserFilesApi;
+exports.isHandlerAccessible = isHandlerAccessible;
+exports.openBrowserFilesApi = openBrowserFilesApi;
+exports.verifyPermission = verifyPermission;