opfs-mock 2.6.0 → 2.7.0

package/README.md

@@ -1,7 +1,7 @@
 # opfs-mock
 
 In-memory implementation of the [origin private file system](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system). Its main utility is for testing OPFS-dependent code in Node.js. It's tested
-on Node.js versions 20-25.
+on all supported Node.js versions (`22.x`, `24.x`, `25.x`, `26.x`).
 
 ## Installation
 

package/dist/index.d.mts

@@ -3,20 +3,39 @@
 // https://developer.mozilla.org/en-US/docs/Web/API/FileSystemHandle/queryPermission
 // https://developer.mozilla.org/en-US/docs/Web/API/FileSystemHandle/requestPermission
 // https://developer.mozilla.org/en-US/docs/Web/API/FileSystemHandle/remove
+// https://developer.mozilla.org/en-US/docs/Web/API/FileSystemObserver
+// https://developer.mozilla.org/en-US/docs/Web/API/FileSystemChangeRecord
 type PermissionHandler = (descriptor?: FileSystemHandlePermissionDescriptor) => Promise<PermissionState>;
 declare global {
+  type FileSystemChangeType = 'appeared' | 'disappeared' | 'errored' | 'modified' | 'moved' | 'unknown';
+  interface FileSystemChangeRecord {
+    changedHandle: FileSystemHandle | FileSystemSyncAccessHandle | null;
+    relativePathComponents: string[];
+    relativePathMovedFrom: string[] | null;
+    root: FileSystemHandle | FileSystemSyncAccessHandle;
+    type: FileSystemChangeType;
+  }
+  type FileSystemObserverCallback = (records: FileSystemChangeRecord[], observer: FileSystemObserver) => void;
+  interface FileSystemObserver {
+    disconnect(): void;
+    observe(handle: FileSystemHandle | FileSystemSyncAccessHandle): Promise<void>;
+  }
+  const FileSystemObserver: {
+    prototype: FileSystemObserver;
+    new (callback: FileSystemObserverCallback): FileSystemObserver;
+  };
   interface FileSystemHandlePermissionDescriptor {
     mode?: 'read' | 'readwrite';
   }
   interface FileSystemFileHandle extends FileSystemHandle {
     queryPermission(descriptor?: FileSystemHandlePermissionDescriptor): Promise<PermissionState>;
     requestPermission(descriptor?: FileSystemHandlePermissionDescriptor): Promise<PermissionState>;
-    remove(): Promise<void>;
+    remove(options?: FileSystemRemoveOptions): Promise<void>;
   }
   interface FileSystemDirectoryHandle extends FileSystemHandle {
     queryPermission(descriptor?: FileSystemHandlePermissionDescriptor): Promise<PermissionState>;
     requestPermission(descriptor?: FileSystemHandlePermissionDescriptor): Promise<PermissionState>;
-    remove(): Promise<void>;
+    remove(options?: FileSystemRemoveOptions): Promise<void>;
   }
 }
 //#endregion

package/dist/index.mjs

@@ -14,22 +14,94 @@ const getSizeOfDirectory = async (directory) => {
 	return totalSize;
 };
 //#endregion
+//#region src/observer.ts
+const handleMetadata = /* @__PURE__ */ new WeakMap();
+const observers = /* @__PURE__ */ new Set();
+const isPathWithin = (path, rootPath) => {
+	if (path.length < rootPath.length) return false;
+	return rootPath.every((component, index) => path[index] === component);
+};
+const relativePath = (path, rootPath) => {
+	return path.slice(rootPath.length);
+};
+const setFileSystemHandleMetadata = (handle, path) => {
+	handleMetadata.set(handle, { path });
+};
+const notifyFileSystemObservers = (type, changedHandle, path, relativePathMovedFrom = null) => {
+	for (const observer of observers) observer.queueRecord(type, changedHandle, path, relativePathMovedFrom);
+};
+var FileSystemObserver = class {
+	#callback;
+	#observations = /* @__PURE__ */ new Map();
+	#records = [];
+	#scheduled = false;
+	constructor(callback) {
+		if (typeof callback !== "function") throw new TypeError("FileSystemObserver callback must be a function");
+		this.#callback = callback;
+	}
+	async observe(handle) {
+		const metadata = handleMetadata.get(handle);
+		if (!metadata) throw new DOMException("The supplied handle is not managed by opfs-mock.", "NotFoundError");
+		this.#observations.set(handle, {
+			root: handle,
+			path: metadata.path
+		});
+		observers.add(this);
+	}
+	disconnect() {
+		this.#observations.clear();
+		this.#records = [];
+		this.#scheduled = false;
+		observers.delete(this);
+	}
+	queueRecord(type, changedHandle, path, relativePathMovedFrom) {
+		for (const observation of this.#observations.values()) {
+			if (!isPathWithin(path, observation.path)) continue;
+			this.#records.push({
+				changedHandle: type === "disappeared" || type === "errored" || type === "unknown" ? null : changedHandle,
+				relativePathComponents: relativePath(path, observation.path),
+				relativePathMovedFrom,
+				root: observation.root,
+				type
+			});
+		}
+		if (this.#records.length > 0 && !this.#scheduled) {
+			this.#scheduled = true;
+			queueMicrotask(() => {
+				this.#scheduled = false;
+				const records = this.#records;
+				this.#records = [];
+				if (records.length > 0) this.#callback(records, this);
+			});
+		}
+	}
+};
+const installFileSystemObserver = () => {
+	Object.defineProperty(globalThis, "FileSystemObserver", {
+		configurable: true,
+		value: FileSystemObserver,
+		writable: true
+	});
+};
+//#endregion
 //#region src/opfs.ts
 const isObject = (v) => typeof v === "object" && v !== null;
 const isLegacyWriteParams = (v) => isObject(v) && !("type" in v) && "data" in v;
-const fileSystemFileHandleFactory = (name, fileData, exists, onRemove, permissions) => {
+const isArrayBuffer = (v) => Object.prototype.toString.call(v) === "[object ArrayBuffer]";
+const fileSystemFileHandleFactory = (name, fileData, path, exists, onRemove, permissions) => {
 	const checkPermission = async (mode = "read") => {
 		if (await (permissions?.queryPermission?.({ mode }) ?? Promise.resolve("granted")) !== "granted") throw new DOMException("Permission denied", "NotAllowedError");
 	};
-	return {
+	const handle = {
 		kind: "file",
 		name,
 		queryPermission: permissions?.queryPermission ?? (async () => "granted"),
 		requestPermission: permissions?.requestPermission ?? (async () => "granted"),
-		remove: async () => {
+		remove: async (_options) => {
 			await checkPermission("readwrite");
 			if (!exists()) throw new DOMException("A requested file or directory could not be found at the time an operation was processed.", "NotFoundError");
 			onRemove?.();
+			notifyFileSystemObservers("disappeared", null, path);
 		},
 		isSameEntry: async function(other) {
 			return other === this;
@@ -89,7 +161,7 @@ const fileSystemFileHandleFactory = (name, fileData, exists, onRemove, permissio
 					const ab = await chunk.arrayBuffer();
 					encoded = new Uint8Array(ab);
 				} else if (ArrayBuffer.isView(chunk)) encoded = new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength);
-				else if (chunk instanceof ArrayBuffer) encoded = new Uint8Array(chunk);
+				else if (isArrayBuffer(chunk)) encoded = new Uint8Array(chunk);
 				else if (isLegacyWriteParams(chunk)) {
 					const wp = chunk;
 					if (wp.position !== void 0 && wp.position !== null) {
@@ -103,7 +175,7 @@ const fileSystemFileHandleFactory = (name, fileData, exists, onRemove, permissio
 						const ab = await data.arrayBuffer();
 						encoded = new Uint8Array(ab);
 					} else if (ArrayBuffer.isView(data)) encoded = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
-					else if (data instanceof ArrayBuffer) encoded = new Uint8Array(data);
+					else if (isArrayBuffer(data)) encoded = new Uint8Array(data);
 					else throw new TypeError("Invalid data in WriteParams");
 				} else throw new TypeError("Invalid data type written to the file. Data must be of type FileSystemWriteChunkType.");
 				const requiredSize = cursorPosition + encoded.length;
@@ -121,6 +193,7 @@ const fileSystemFileHandleFactory = (name, fileData, exists, onRemove, permissio
 				isClosed = true;
 				fileData.content = content;
 				fileData.lastModified = Date.now();
+				notifyFileSystemObservers("modified", handle, path);
 			};
 			const doAbort = async (reason) => {
 				if (isAborted) return;
@@ -161,7 +234,7 @@ const fileSystemFileHandleFactory = (name, fileData, exists, onRemove, permissio
 			if (fileData.locked) throw new DOMException("A sync access handle is already open for this file", "InvalidStateError");
 			fileData.locked = true;
 			let closed = false;
-			return {
+			const syncHandle = {
 				getSize: () => {
 					if (closed) throw new DOMException("The access handle is closed", "InvalidStateError");
 					return fileData.content.byteLength;
@@ -190,6 +263,7 @@ const fileSystemFileHandleFactory = (name, fileData, exists, onRemove, permissio
 					if (data instanceof DataView) for (let i = 0; i < data.byteLength; i++) fileData.content[at + i] = data.getUint8(i);
 					else fileData.content.set(data, at);
 					fileData.lastModified = Date.now();
+					notifyFileSystemObservers("modified", syncHandle, path);
 					return writeLength;
 				},
 				truncate: (size) => {
@@ -201,6 +275,7 @@ const fileSystemFileHandleFactory = (name, fileData, exists, onRemove, permissio
 						fileData.content = newBuffer;
 					}
 					fileData.lastModified = Date.now();
+					notifyFileSystemObservers("modified", syncHandle, path);
 				},
 				flush: async () => {
 					if (closed) throw new DOMException("The access handle is closed", "InvalidStateError");
@@ -210,10 +285,14 @@ const fileSystemFileHandleFactory = (name, fileData, exists, onRemove, permissio
 					fileData.locked = false;
 				}
 			};
+			setFileSystemHandleMetadata(syncHandle, path);
+			return syncHandle;
 		}
 	};
+	setFileSystemHandleMetadata(handle, path);
+	return handle;
 };
-const fileSystemDirectoryHandleFactory = (name, permissions, onRemove) => {
+const fileSystemDirectoryHandleFactory = (name, permissions, onRemove, path = []) => {
 	const files = /* @__PURE__ */ new Map();
 	const directories = /* @__PURE__ */ new Map();
 	const getJoinedMaps = () => {
@@ -227,11 +306,20 @@ const fileSystemDirectoryHandleFactory = (name, permissions, onRemove) => {
 		name,
 		queryPermission: permissions?.queryPermission ?? (async () => "granted"),
 		requestPermission: permissions?.requestPermission ?? (async () => "granted"),
-		remove: async () => {
+		remove: async (options) => {
 			await checkPermission("readwrite");
-			if (!onRemove) throw new DOMException("The root directory cannot be removed.", "InvalidModificationError");
-			for await (const _ of handle.values()) throw new DOMException("The directory is not empty", "InvalidModificationError");
+			if (!onRemove) {
+				if (options?.recursive) {
+					files.clear();
+					directories.clear();
+					notifyFileSystemObservers("modified", handle, path);
+					return;
+				}
+				throw new DOMException("The root directory cannot be removed.", "InvalidModificationError");
+			}
+			if (!options?.recursive) for await (const _ of handle.values()) throw new DOMException("The directory is not empty", "InvalidModificationError");
 			onRemove();
+			notifyFileSystemObservers("disappeared", null, path);
 		},
 		isSameEntry: async function(other) {
 			return other === this;
@@ -244,7 +332,8 @@ const fileSystemDirectoryHandleFactory = (name, permissions, onRemove) => {
 					content: new Uint8Array(),
 					lastModified: Date.now(),
 					id: Symbol("file")
-				}, () => files.has(fileName), () => files.delete(fileName), permissions));
+				}, [...path, fileName], () => files.has(fileName), () => files.delete(fileName), permissions));
+				notifyFileSystemObservers("appeared", files.get(fileName) ?? null, [...path, fileName]);
 			} else await checkPermission("read");
 			const fileHandle = files.get(fileName);
 			if (!fileHandle) throw new DOMException(`File not found: ${fileName}`, "NotFoundError");
@@ -254,8 +343,9 @@ const fileSystemDirectoryHandleFactory = (name, permissions, onRemove) => {
 			if (files.has(dirName)) throw new DOMException(`A file with the same name exists: ${dirName}`, "TypeMismatchError");
 			if (!directories.has(dirName) && options?.create) {
 				await checkPermission("readwrite");
-				const dir = fileSystemDirectoryHandleFactory(dirName, permissions, () => directories.delete(dirName));
+				const dir = fileSystemDirectoryHandleFactory(dirName, permissions, () => directories.delete(dirName), [...path, dirName]);
 				directories.set(dirName, dir);
+				notifyFileSystemObservers("appeared", dir, [...path, dirName]);
 			} else await checkPermission("read");
 			const directoryHandle = directories.get(dirName);
 			if (!directoryHandle) throw new DOMException(`Directory not found: ${dirName}`, "NotFoundError");
@@ -265,12 +355,14 @@ const fileSystemDirectoryHandleFactory = (name, permissions, onRemove) => {
 			await checkPermission("readwrite");
 			if (files.has(entryName)) {
 				files.delete(entryName);
+				notifyFileSystemObservers("disappeared", null, [...path, entryName]);
 				return;
 			}
 			const dir = directories.get(entryName);
 			if (dir) {
 				if (!options?.recursive) for await (const _ of dir.values()) throw new DOMException("The directory is not empty", "InvalidModificationError");
 				directories.delete(entryName);
+				notifyFileSystemObservers("disappeared", null, [...path, entryName]);
 				return;
 			}
 			throw new DOMException(`No such file or directory: ${entryName}`, "NotFoundError");
@@ -283,7 +375,8 @@ const fileSystemDirectoryHandleFactory = (name, permissions, onRemove) => {
 		},
 		entries: async function* () {
 			await checkPermission("read");
-			yield* getJoinedMaps().entries();
+			const joinedMaps = getJoinedMaps();
+			for (const [n, h] of joinedMaps.entries()) yield [n, h];
 		},
 		keys: async function* () {
 			await checkPermission("read");
@@ -291,7 +384,8 @@ const fileSystemDirectoryHandleFactory = (name, permissions, onRemove) => {
 		},
 		values: async function* () {
 			await checkPermission("read");
-			yield* getJoinedMaps().values();
+			const joinedMaps = getJoinedMaps();
+			for (const h of joinedMaps.values()) yield h;
 		},
 		resolve: async function(possibleDescendant) {
 			await checkPermission("read");
@@ -308,6 +402,7 @@ const fileSystemDirectoryHandleFactory = (name, permissions, onRemove) => {
 			return traverseDirectory(this, possibleDescendant);
 		}
 	};
+	setFileSystemHandleMetadata(handle, path);
 	return handle;
 };
 //#endregion
@@ -337,13 +432,16 @@ const storageFactory = ({ usage = 0, quota = 1024 ** 3, queryPermission, request
 };
 const mockOPFS = () => {
 	if (!("navigator" in globalThis)) Object.defineProperty(globalThis, "navigator", {
+		configurable: true,
 		value: {},
 		writable: true
 	});
 	if (!globalThis.navigator.storage) Object.defineProperty(globalThis.navigator, "storage", {
+		configurable: true,
 		value: storageFactory(),
 		writable: true
 	});
+	installFileSystemObserver();
 };
 const resetMockOPFS = (options = {}) => {
 	const root = fileSystemDirectoryHandleFactory("root", {
@@ -351,6 +449,7 @@ const resetMockOPFS = (options = {}) => {
 		requestPermission: options.requestPermission
 	});
 	Object.defineProperty(globalThis.navigator.storage, "getDirectory", {
+		configurable: true,
 		value: () => root,
 		writable: true
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opfs-mock",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "type": "module",
   "description": "Mock all origin private file system APIs for your Jest or Vitest tests",
   "author": "Jure Rotar <hello@jurerotar.com>",
@@ -60,14 +60,14 @@
     "release": "npm publish --access public"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.4.6",
-    "@typescript/native-preview": "7.0.0-dev.20260309.1",
-    "@vitest/coverage-v8": "4.0.18",
+    "@biomejs/biome": "2.4.15",
+    "@typescript/native-preview": "7.0.0-dev.20260522.1",
+    "@vitest/coverage-v8": "4.1.7",
     "@web-std/file": "3.0.3",
-    "happy-dom": "20.8.3",
-    "jsdom": "28.1.0",
-    "tsdown": "0.21.1",
-    "typescript": "5.9.3",
-    "vitest": "4.0.18"
+    "happy-dom": "20.9.0",
+    "jsdom": "29.1.1",
+    "tsdown": "0.22.0",
+    "typescript": "6.0.3",
+    "vitest": "4.1.7"
   }
 }