opfs-mock 2.2.0 → 2.3.0

package/LICENSE.md

@@ -1,21 +1,21 @@
-The MIT License (MIT)
-
-Copyright © 2024 Jure Rotar
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE
+The MIT License (MIT)
+
+Copyright © 2024 Jure Rotar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE

package/README.md

@@ -1,168 +1,168 @@
-# 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-24.
-
-## Installation
-
-```shell
-npm install -save-dev opfs-mock
-```
-
-## Limitations
-
-- `opfs-mock` requires **Node.js v20.0.0** or higher. It can work on Node v18.0.0 with either `--experimental-fetch` flag enabled or a global
-`File` polyfill.
-
-- `jsdom` testing environment is missing `File.prototype.text()` method, which is required for reading opfs files. Ensure your opfs-dependant tests are ran
-in `node` or `happy-dom` environment.
-
-## Usage
-
-It replicates the behavior of origin private file system, except data is not persisted to disk.
-
-The easiest way to use it is to import `opfs-mock`, which will polyfill OPFS API to global scope.
-
-```ts
-import "opfs-mock";
-```
-
-Alternatively, you can explicitly import `storageFactory`:
-
-```ts
-import { storageFactory } from "opfs-mock";
-
-test('Your test', async () => {
-  const storage = await storageFactory();
-  const root = await storage.getDirectory();
-  const directoryHandle = await root.getFileHandle('test-file.txt', { create: true });
-  // rest of your test
-});
-```
-
-`storageFactory` has `quota` and `usage` values set to `1024 ** 3 (1 GB)` and `0` respectively. When calling `storage.estimate()`, `usage` is dynamically calculated by summing the predefined usage value and any additional computed storage consumption.
-In case you need specific values, you can pass both as arguments to `storageFactory`.
-
-```ts
-import { storageFactory } from "opfs-mock";
-
-test('Your test', async () => {
-  const storage = await storageFactory({ quota: 1_000_000, usage: 1_000 });
-  const root = await storage.getDirectory();
-  const directoryHandle = await root.getFileHandle('test-file.txt', { create: true });
-  // rest of your test
-});
-```
-
-### Vitest
-
-To use `opfs-mock` in a single Vitest test suite, require `opfs-mock` at the beginning of the test file, as described above.
-
-To use it on all Vitest tests without having to include it in each file, add the auto setup script to the `test.setupFiles` in your Vite config:
-
-```ts
-// vite.config.ts
-
-import { defineConfig as defineViteConfig, mergeConfig } from 'vite';
-import { defineConfig as defineVitestConfig } from 'vitest/config';
-
-const viteConfig = defineViteConfig({
-  ...
-});
-
-const vitestConfig = defineVitestConfig({
-  test: {
-    setupFiles: ['opfs-mock'],
-  },
-});
-
-export default mergeConfig(viteConfig, vitestConfig);
-```
-
-Alternatively you can create a new setup file which then imports this module.
-
-```ts
-// vitest-setup.ts
-
-import "opfs-mock";
-```
-
-Add that file to your `test.setupFiles` array:
-
-```ts
-// vite.config.ts
-
-import { defineConfig as defineViteConfig, mergeConfig } from 'vite';
-import { defineConfig as defineVitestConfig } from 'vitest/config';
-
-const viteConfig = defineViteConfig({
-  ...
-});
-
-const vitestConfig = defineVitestConfig({
-  test: {
-    setupFiles: ['vitest-setup.ts'],
-  },
-});
-
-export default mergeConfig(viteConfig, vitestConfig);
-```
-
-
-### Jest
-
-To use `opfs-mock` in a single Jest test suite, require `opfs-mock` at the beginning of the test file, as described above.
-
-To use it on all Jest tests without having to include it in each file, add the auto setup script to the `setupFiles` in your Jest config:
-
-```ts
-// jest.config.js
-
-{
-  ...
-  "setupFiles": [
-    "opfs-mock"
-  ]
-}
-```
-
-Alternatively you can create a new setup file which then imports this module.
-
-```ts
-// jest-setup.ts
-
-import "opfs-mock";
-```
-
-Add that file to your `setupFiles` array:
-
-```ts
-// jest.config.js
-
-{
-  ...
-  "setupFiles": [
-    "jest-setup"
-  ]
-}
-```
-
-## Wiping/resetting the OPFS mock for a fresh state
-
-If you are keeping your tests completely isolated you might want to "reset" the state of the mocked OPFS. You can do this by using `resetMockOPFS` function, which creates a completely new instance of the mock.
-
-```ts
-import { resetMockOPFS } from 'opfs-mock';
-
-beforeEach(() => {
-  resetMockOPFS();
-});
-
-test('First isolated test', async () => {
-  // rest of your test
-});
-
-test('Second isolated test', async () => {
-  // rest of your test
-});
-```
+# 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-24.
+
+## Installation
+
+```shell
+npm install -save-dev opfs-mock
+```
+
+## Limitations
+
+- `opfs-mock` requires **Node.js v20.0.0** or higher. It can work on Node v18.0.0 with either `--experimental-fetch` flag enabled or a global
+`File` polyfill.
+
+- `jsdom` testing environment is missing `File.prototype.text()` method, which is required for reading opfs files. Ensure your opfs-dependant tests are ran
+in `node` or `happy-dom` environment.
+
+## Usage
+
+It replicates the behavior of origin private file system, except data is not persisted to disk.
+
+The easiest way to use it is to import `opfs-mock`, which will polyfill OPFS API to global scope.
+
+```ts
+import "opfs-mock";
+```
+
+Alternatively, you can explicitly import `storageFactory`:
+
+```ts
+import { storageFactory } from "opfs-mock";
+
+test('Your test', async () => {
+  const storage = await storageFactory();
+  const root = await storage.getDirectory();
+  const directoryHandle = await root.getFileHandle('test-file.txt', { create: true });
+  // rest of your test
+});
+```
+
+`storageFactory` has `quota` and `usage` values set to `1024 ** 3 (1 GB)` and `0` respectively. When calling `storage.estimate()`, `usage` is dynamically calculated by summing the predefined usage value and any additional computed storage consumption.
+In case you need specific values, you can pass both as arguments to `storageFactory`.
+
+```ts
+import { storageFactory } from "opfs-mock";
+
+test('Your test', async () => {
+  const storage = await storageFactory({ quota: 1_000_000, usage: 1_000 });
+  const root = await storage.getDirectory();
+  const directoryHandle = await root.getFileHandle('test-file.txt', { create: true });
+  // rest of your test
+});
+```
+
+### Vitest
+
+To use `opfs-mock` in a single Vitest test suite, require `opfs-mock` at the beginning of the test file, as described above.
+
+To use it on all Vitest tests without having to include it in each file, add the auto setup script to the `test.setupFiles` in your Vite config:
+
+```ts
+// vite.config.ts
+
+import { defineConfig as defineViteConfig, mergeConfig } from 'vite';
+import { defineConfig as defineVitestConfig } from 'vitest/config';
+
+const viteConfig = defineViteConfig({
+  ...
+});
+
+const vitestConfig = defineVitestConfig({
+  test: {
+    setupFiles: ['opfs-mock'],
+  },
+});
+
+export default mergeConfig(viteConfig, vitestConfig);
+```
+
+Alternatively you can create a new setup file which then imports this module.
+
+```ts
+// vitest-setup.ts
+
+import "opfs-mock";
+```
+
+Add that file to your `test.setupFiles` array:
+
+```ts
+// vite.config.ts
+
+import { defineConfig as defineViteConfig, mergeConfig } from 'vite';
+import { defineConfig as defineVitestConfig } from 'vitest/config';
+
+const viteConfig = defineViteConfig({
+  ...
+});
+
+const vitestConfig = defineVitestConfig({
+  test: {
+    setupFiles: ['vitest-setup.ts'],
+  },
+});
+
+export default mergeConfig(viteConfig, vitestConfig);
+```
+
+
+### Jest
+
+To use `opfs-mock` in a single Jest test suite, require `opfs-mock` at the beginning of the test file, as described above.
+
+To use it on all Jest tests without having to include it in each file, add the auto setup script to the `setupFiles` in your Jest config:
+
+```ts
+// jest.config.js
+
+{
+  ...
+  "setupFiles": [
+    "opfs-mock"
+  ]
+}
+```
+
+Alternatively you can create a new setup file which then imports this module.
+
+```ts
+// jest-setup.ts
+
+import "opfs-mock";
+```
+
+Add that file to your `setupFiles` array:
+
+```ts
+// jest.config.js
+
+{
+  ...
+  "setupFiles": [
+    "jest-setup"
+  ]
+}
+```
+
+## Wiping/resetting the OPFS mock for a fresh state
+
+If you are keeping your tests completely isolated you might want to "reset" the state of the mocked OPFS. You can do this by using `resetMockOPFS` function, which creates a completely new instance of the mock.
+
+```ts
+import { resetMockOPFS } from 'opfs-mock';
+
+beforeEach(() => {
+  resetMockOPFS();
+});
+
+test('First isolated test', async () => {
+  // rest of your test
+});
+
+test('Second isolated test', async () => {
+  // rest of your test
+});
+```

package/dist/index.js

@@ -29,7 +29,7 @@ const fileSystemFileHandleFactory = (name, fileData) => {
 			let abortReason = "";
 			let isAborted = false;
 			let isClosed = false;
-			let content = keepExistingData ? fileData.content : "";
+			let content = keepExistingData ? new Uint8Array(fileData.content) : new Uint8Array();
 			let cursorPosition = keepExistingData ? fileData.content.length : 0;
 			const writableStream = new WritableStream({
 				write: () => {},
@@ -42,21 +42,46 @@ const fileSystemFileHandleFactory = (name, fileData) => {
 					if (isAborted) throw new Error(abortReason);
 					if (isClosed) throw new TypeError("Cannot write to a CLOSED writable stream");
 					if (chunk === void 0) throw new TypeError("Cannot write undefined data to the stream");
-					let chunkText;
-					if (typeof chunk === "string") chunkText = chunk;
-					else if (chunk instanceof Blob) chunkText = await chunk.text();
-					else if (ArrayBuffer.isView(chunk)) chunkText = new TextDecoder().decode(new Uint8Array(chunk.buffer));
+					if (typeof chunk === "object" && "type" in chunk && chunk.type === "truncate") {
+						if (typeof chunk.size !== "number" || chunk.size < 0) throw new TypeError("Invalid size value in truncate parameters");
+						if (chunk.size < content.length) content = content.slice(0, chunk.size);
+						else {
+							const extended = new Uint8Array(chunk.size);
+							extended.set(content);
+							content = extended;
+						}
+						cursorPosition = Math.min(cursorPosition, chunk.size);
+						return;
+					}
+					let encoded;
+					if (typeof chunk === "string") encoded = new TextEncoder().encode(chunk);
+					else if (chunk instanceof Blob) {
+						const text = await chunk.text();
+						encoded = new TextEncoder().encode(text);
+					} 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 (typeof chunk === "object" && "data" in chunk) {
 						if (chunk.position !== void 0 && (typeof chunk.position !== "number" || chunk.position < 0)) throw new TypeError("Invalid position value in write parameters");
 						if (chunk.size !== void 0 && (typeof chunk.size !== "number" || chunk.size < 0)) throw new TypeError("Invalid size value in write parameters");
 						if (chunk.position !== void 0 && chunk.position !== null) cursorPosition = chunk.position;
-						if (chunk.data) if (typeof chunk.data === "string") chunkText = chunk.data;
-						else if (chunk.data instanceof Blob) chunkText = await chunk.data.text();
-						else chunkText = new TextDecoder().decode(new Uint8Array(chunk.data instanceof ArrayBuffer ? chunk.data : chunk.data.buffer));
-						else chunkText = "";
+						const data = chunk.data;
+						if (data === void 0 || data === null) encoded = new Uint8Array();
+						else if (typeof data === "string") encoded = new TextEncoder().encode(data);
+						else if (data instanceof Blob) {
+							const text = await data.text();
+							encoded = new TextEncoder().encode(text);
+						} else if (ArrayBuffer.isView(data)) encoded = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+						else if (data instanceof ArrayBuffer) 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.");
-					content = content.slice(0, cursorPosition) + chunkText + content.slice(cursorPosition + chunkText.length);
-					cursorPosition += chunkText.length;
+					const requiredSize = cursorPosition + encoded.length;
+					if (content.length < requiredSize) {
+						const extended = new Uint8Array(requiredSize);
+						extended.set(content);
+						content = extended;
+					}
+					content.set(encoded, cursorPosition);
+					cursorPosition += encoded.length;
 				},
 				close: async function() {
 					if (isClosed) throw new TypeError("Cannot close a CLOSED writable stream");
@@ -73,11 +98,15 @@ const fileSystemFileHandleFactory = (name, fileData) => {
 				truncate: async function(size) {
 					if (size < 0) throw new DOMException("Invalid truncate size", "IndexSizeError");
 					if (size < content.length) content = content.slice(0, size);
-					else content = content.padEnd(size, "\0");
+					else if (size > content.length) {
+						const newBuffer = new Uint8Array(size);
+						newBuffer.set(content);
+						content = newBuffer;
+					}
 					cursorPosition = Math.min(cursorPosition, size);
 				},
 				seek: async function(position) {
-					if (position < 0 || position > content.length) throw new DOMException("Invalid seek position", "IndexSizeError");
+					if (position < 0) throw new DOMException("Invalid seek position", "IndexSizeError");
 					cursorPosition = position;
 				}
 			});
@@ -87,26 +116,41 @@ const fileSystemFileHandleFactory = (name, fileData) => {
 			return {
 				getSize: () => {
 					if (closed) throw new DOMException("InvalidStateError", "The access handle is closed");
-					return fileData.content.length;
+					return fileData.content.byteLength;
 				},
 				read: (buffer, { at = 0 } = {}) => {
 					if (closed) throw new DOMException("InvalidStateError", "The access handle is closed");
-					const text = new TextEncoder().encode(fileData.content);
-					const bytesRead = Math.min(buffer.length, text.length - at);
-					buffer.set(text.subarray(at, at + bytesRead));
-					return bytesRead;
+					const content = fileData.content;
+					if (at >= content.length) return 0;
+					const available = content.length - at;
+					const writable = buffer instanceof DataView ? buffer.byteLength : buffer.length;
+					const bytesToRead = Math.min(writable, available);
+					const slice = content.subarray(at, at + bytesToRead);
+					if (buffer instanceof DataView) for (let i = 0; i < slice.length; i++) buffer.setUint8(i, slice[i]);
+					else buffer.set(slice, 0);
+					return bytesToRead;
 				},
-				write: (data, options) => {
-					const at = options?.at ?? 0;
+				write: (data, { at = 0 } = {}) => {
 					if (closed) throw new DOMException("InvalidStateError", "The access handle is closed");
-					const newContent = new TextDecoder().decode(data);
-					if (at < fileData.content.length) fileData.content = fileData.content.slice(0, at) + newContent + fileData.content.slice(at + newContent.length);
-					else fileData.content += newContent;
-					return data.byteLength;
+					const writeLength = data instanceof DataView ? data.byteLength : data.length;
+					const requiredSize = at + writeLength;
+					if (fileData.content.length < requiredSize) {
+						const newBuffer = new Uint8Array(requiredSize);
+						newBuffer.set(fileData.content);
+						fileData.content = newBuffer;
+					}
+					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);
+					return writeLength;
 				},
 				truncate: (size) => {
 					if (closed) throw new DOMException("InvalidStateError", "The access handle is closed");
-					fileData.content = fileData.content.slice(0, size);
+					if (size < fileData.content.length) fileData.content = fileData.content.slice(0, size);
+					else if (size > fileData.content.length) {
+						const newBuffer = new Uint8Array(size);
+						newBuffer.set(fileData.content);
+						fileData.content = newBuffer;
+					}
 				},
 				flush: async () => {
 					if (closed) throw new DOMException("InvalidStateError", "The access handle is closed");
@@ -131,7 +175,7 @@ const fileSystemDirectoryHandleFactory = (name) => {
 			return other.name === name && other.kind === "directory";
 		},
 		getFileHandle: async (fileName, options) => {
-			if (!files.has(fileName) && options?.create) files.set(fileName, fileSystemFileHandleFactory(fileName, { content: "" }));
+			if (!files.has(fileName) && options?.create) files.set(fileName, fileSystemFileHandleFactory(fileName, { content: new Uint8Array() }));
 			const fileHandle = files.get(fileName);
 			if (!fileHandle) throw new DOMException(`File not found: ${fileName}`, "NotFoundError");
 			return fileHandle;
@@ -210,13 +254,10 @@ const mockOPFS = () => {
 		value: {},
 		writable: true
 	});
-	if (!globalThis.navigator.storage) {
-		const { getDirectory } = storageFactory();
-		Object.defineProperty(globalThis.navigator, "storage", {
-			value: { getDirectory },
-			writable: true
-		});
-	}
+	if (!globalThis.navigator.storage) Object.defineProperty(globalThis.navigator, "storage", {
+		value: storageFactory(),
+		writable: true
+	});
 };
 const resetMockOPFS = () => {
 	const root = fileSystemDirectoryHandleFactory("root");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opfs-mock",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "type": "module",
   "description": "Mock all origin private file system APIs for your Jest or Vitest tests",
   "author": "Jure Rotar <hello@jurerotar.com>",