@statewalker/webrun-files-browser 0.5.0

package/dist/esm/index.js

@@ -0,0 +1,332 @@
+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
+//#region src/browser-files-api.ts
+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;
+		for (const segment of segments) try {
+			current = await current.getDirectoryHandle(segment, options);
+		} catch {
+			return null;
+		}
+		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 parentPath = dirname(normalized);
+		const fileName = basename(normalized);
+		const parent = await this.getDirectoryHandle(parentPath, options);
+		if (!parent) return null;
+		try {
+			return await parent.getFileHandle(fileName, options);
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Lists entries in a directory.
+	*/
+	async *list(file, options = {}) {
+		const normalized = resolveFileRef(file);
+		const dirHandle = await this.getDirectoryHandle(normalized);
+		if (!dirHandle) return;
+		const { recursive = false } = options;
+		for await (const [name, handle] of dirHandle.entries()) {
+			const entryPath = joinPath(normalized, name);
+			const isDirectory = handle.kind === "directory";
+			const info = {
+				kind: isDirectory ? "directory" : "file",
+				name,
+				path: entryPath,
+				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;
+			} 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);
+		if (normalized === "/") return {
+			kind: "directory",
+			name: "",
+			path: "/",
+			lastModified: 0
+		};
+		const fileHandle = await this.getFileHandle(normalized);
+		if (fileHandle) try {
+			const f = await fileHandle.getFile();
+			return {
+				kind: "file",
+				name: fileName,
+				path: normalized,
+				size: f.size,
+				lastModified: f.lastModified,
+				type: f.type
+			};
+		} 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);
+		const parentPath = dirname(normalized);
+		const name = basename(normalized);
+		const parent = await this.getDirectoryHandle(parentPath);
+		if (!parent) return false;
+		try {
+			await parent.removeEntry(name, { recursive: true });
+			return true;
+		} catch {
+			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) {
+		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") {
+			const sourceHandle = await this.getFileHandle(sourcePath);
+			if (!sourceHandle) return false;
+			const sourceFile = await sourceHandle.getFile();
+			const targetParentPath = dirname(targetPath);
+			const targetFileName = basename(targetPath);
+			const targetParent = await this.getDirectoryHandle(targetParentPath, { create: true });
+			if (!targetParent) return false;
+			const writable = await (await targetParent.getFileHandle(targetFileName, { create: true })).createWritable();
+			try {
+				const reader = sourceFile.stream().getReader();
+				while (true) {
+					const { done, value } = await reader.read();
+					if (done) break;
+					await writable.write(value);
+				}
+			} finally {
+				await writable.close();
+			}
+			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;
+			const newTargetPath = targetPath + entry.path.substring(sourcePath.length);
+			const entryHandle = await this.getFileHandle(entry.path);
+			if (!entryHandle) continue;
+			const entryFile = await entryHandle.getFile();
+			const newTargetParentPath = dirname(newTargetPath);
+			const newTargetFileName = basename(newTargetPath);
+			const newTargetParent = await this.getDirectoryHandle(newTargetParentPath, { create: true });
+			if (!newTargetParent) continue;
+			const writable = await (await newTargetParent.getFileHandle(newTargetFileName, { create: true })).createWritable();
+			try {
+				const reader = entryFile.stream().getReader();
+				while (true) {
+					const { done, value } = await reader.read();
+					if (done) break;
+					await writable.write(value);
+				}
+			} finally {
+				await writable.close();
+			}
+		}
+		return true;
+	}
+};
+/**
+* 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 };

package/dist/index.d.ts

@@ -0,0 +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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@statewalker/webrun-files-browser",
+  "version": "0.5.0",
+  "private": false,
+  "type": "module",
+  "description": "Browser File System Access API implementation for webrun-files",
+  "homepage": "https://github.com/statewalker/webrun-files",
+  "author": {
+    "name": "Mikhail Kotelnikov",
+    "email": "mikhail.kotelnikov@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:statewalker/webrun-files.git"
+  },
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@statewalker/webrun-files": "0.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "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"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
+    "test": "vitest run",
+    "lint": "biome lint src tests"
+  }
+}

package/src/browser-file-handle.ts

@@ -0,0 +1,194 @@
+/**
+ * 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";
+import { toBinaryAsyncIterable } from "@statewalker/webrun-files";
+
+export interface BrowserFileHandleOptions {
+  fileHandle: FileSystemFileHandle;
+  initialFile: File;
+}
+
+export class BrowserFileHandle implements FileHandle {
+  private fileHandle: FileSystemFileHandle;
+  private file: File | null;
+  private _size: number;
+  private closed = false;
+
+  constructor(options: BrowserFileHandleOptions) {
+    this.fileHandle = options.fileHandle;
+    this.file = options.initialFile;
+    this._size = options.initialFile.size;
+  }
+
+  get size(): number {
+    return this._size;
+  }
+
+  async close(): Promise<void> {
+    this.closed = true;
+    this.file = null;
+  }
+
+  /**
+   * Appends data to the end of the file.
+   */
+  async appendFile(data: BinaryStream, options: AppendOptions = {}): Promise<number> {
+    if (this.closed) {
+      throw new Error("FileHandle is closed");
+    }
+
+    const { signal } = options;
+    const writable = await this.fileHandle.createWritable({ keepExistingData: true });
+    let bytesWritten = 0;
+
+    try {
+      // Seek to end of file
+      await writable.seek(this._size);
+
+      for await (const chunk of toBinaryAsyncIterable(data)) {
+        if (signal?.aborted) {
+          throw new Error("Operation aborted");
+        }
+        // Cast to Uint8Array<ArrayBuffer> to satisfy FileSystemWritableFileStream.write()
+        await writable.write(chunk as Uint8Array<ArrayBuffer>);
+        bytesWritten += chunk.length;
+      }
+    } finally {
+      await writable.close();
+    }
+
+    // Refresh file reference and size
+    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: ReadStreamOptions = {}): AsyncGenerator<Uint8Array> {
+    if (this.closed) {
+      throw new Error("FileHandle is closed");
+    }
+
+    // Ensure we have a fresh file reference
+    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 slice = this.file.slice(position, position + toRead);
+      const buffer = await slice.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: BinaryStream, options: WriteStreamOptions = {}): Promise<number> {
+    if (this.closed) {
+      throw new Error("FileHandle is closed");
+    }
+
+    const { start = 0, signal } = options;
+
+    // Create writable stream, keeping existing data if we need to preserve content before start
+    const writable = await this.fileHandle.createWritable({
+      keepExistingData: start > 0,
+    });
+
+    let bytesWritten = 0;
+
+    try {
+      if (start > 0) {
+        // Seek to start position
+        await writable.seek(start);
+        // Truncate at start position (removes content after start)
+        await writable.truncate(start);
+      }
+
+      for await (const chunk of toBinaryAsyncIterable(data)) {
+        if (signal?.aborted) {
+          throw new Error("Operation aborted");
+        }
+        // Cast to Uint8Array<ArrayBuffer> to satisfy FileSystemWritableFileStream.write()
+        await writable.write(chunk as Uint8Array<ArrayBuffer>);
+        bytesWritten += chunk.length;
+      }
+    } finally {
+      await writable.close();
+    }
+
+    // Refresh file reference and size
+    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: Uint8Array, offset: number, length: number, position: number): Promise<number> {
+    if (this.closed) {
+      throw new Error("FileHandle is closed");
+    }
+
+    // Ensure we have a fresh file reference
+    if (!this.file) {
+      this.file = await this.fileHandle.getFile();
+      this._size = this.file.size;
+    }
+
+    // Calculate actual bytes to read
+    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 slice = this.file.slice(position, position + len);
+    const arrayBuffer = await slice.arrayBuffer();
+    const data = new Uint8Array(arrayBuffer);
+    buffer.set(data, offset);
+    return len;
+  }
+}