opfs-mock 1.0.0

package/LICENSE.md

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

package/README.md

@@ -0,0 +1,129 @@
+# opfs-mock
+
+This is a pure JS 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.
+
+## Installation
+
+```shell
+npm install -save-dev opfs-mock
+```
+
+## 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 `storage`:
+
+```ts
+import { storage } from "opfs-mock";
+
+test('Your test', async () => {
+  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.js
+
+{
+  ...
+  test: {
+    setupFiles: ['opfs-mock'],
+  },
+}
+```
+
+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 } from 'vite'
+
+export default defineConfig({
+  test: {
+    setupFiles: ['vitest-setup.ts'],
+  }
+});
+```
+
+
+### 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.d.ts

@@ -0,0 +1,4 @@
+declare const storage: () => StorageManager;
+declare const mockOPFS: () => void;
+declare const resetMockOPFS: () => void;
+export { mockOPFS, resetMockOPFS, storage };

package/dist/index.js

@@ -0,0 +1,128 @@
+const g = (o, n) => ({
+  kind: "file",
+  name: o,
+  isSameEntry: async (t) => t.name === o && t.kind === "file",
+  getFile: async () => new File([n.content], o, {
+    type: "application/json"
+  }),
+  // @ts-ignore TODO: Implement options, add missing properties
+  createWritable: async (t) => new WritableStream({
+    write: (e) => {
+      const r = new TextDecoder().decode(e);
+      n.content += r;
+    },
+    close: () => {
+    },
+    abort: (e) => {
+    }
+  }).getWriter(),
+  createSyncAccessHandle: async () => ({
+    getSize: () => n.content.length,
+    read: (t, { at: s = 0 } = {}) => {
+      const e = new TextEncoder().encode(n.content), r = Math.min(t.length, e.length - s);
+      return t.set(e.subarray(s, s + r)), r;
+    },
+    write: (t, { at: s = 0 } = {}) => {
+      const e = new TextDecoder().decode(t), r = n.content.length;
+      return s < r ? n.content = n.content.slice(0, s) + e + n.content.slice(s + e.length) : n.content += e, t.byteLength;
+    },
+    // Flush is a no-op in memory
+    flush: async () => {
+    },
+    // Close is a no-op in memory
+    close: async () => {
+    },
+    truncate: async (t) => {
+      n.content = n.content.slice(0, t);
+    }
+  })
+}), y = (o) => {
+  const n = /* @__PURE__ */ new Map(), t = /* @__PURE__ */ new Map(), s = () => new Map([...n, ...t]);
+  return {
+    kind: "directory",
+    name: o,
+    isSameEntry: async (e) => e.name === o && e.kind === "directory",
+    getFileHandle: async (e, r) => {
+      !n.has(e) && (r != null && r.create) && n.set(e, g(e, { content: "" }));
+      const c = n.get(e);
+      if (!c)
+        throw new Error(`File not found: ${e}`);
+      return c;
+    },
+    getDirectoryHandle: async (e, r) => {
+      !t.has(e) && (r != null && r.create) && t.set(e, y(e));
+      const c = t.get(e);
+      if (!c)
+        throw new Error(`Directory not found: ${e}`);
+      return c;
+    },
+    removeEntry: async (e) => {
+      if (n.has(e))
+        n.delete(e);
+      else if (t.has(e))
+        t.delete(e);
+      else
+        throw new Error(`Entry not found: ${e}`);
+    },
+    entries: async function* () {
+      yield* s().entries();
+    },
+    keys: async function* () {
+      yield* s().keys();
+    },
+    values: async function* () {
+      yield* s().values();
+    },
+    resolve: async (e) => {
+      const r = async (c, a, l = []) => {
+        if (await c.isSameEntry(a))
+          return l;
+        for await (const [d, i] of c.entries())
+          if (i.kind === "directory") {
+            const u = await r(i, a, [...l, d]);
+            if (u)
+              return u;
+          } else if (i.kind === "file" && await i.isSameEntry(a))
+            return [...l, d];
+        return null;
+      };
+      return r(void 0, e);
+    }
+  };
+}, w = () => {
+  const o = y("root");
+  return {
+    estimate: async () => ({
+      usage: 0,
+      quota: 0
+    }),
+    getDirectory: async () => o,
+    persist: async () => !0,
+    persisted: async () => !0
+  };
+}, b = () => {
+  if ("navigator" in globalThis || Object.defineProperty(globalThis, "navigator", {
+    value: {},
+    writable: !0
+  }), !globalThis.navigator.storage) {
+    const { getDirectory: o } = w();
+    Object.defineProperty(globalThis.navigator, "storage", {
+      value: {
+        getDirectory: o
+      },
+      writable: !0
+    });
+  }
+}, h = () => {
+  const o = y("root");
+  Object.defineProperty(globalThis.navigator.storage, "getDirectory", {
+    value: () => o,
+    writable: !0
+  });
+};
+typeof globalThis < "u" && b();
+export {
+  b as mockOPFS,
+  h as resetMockOPFS,
+  w as storage
+};

package/dist/opfs.d.ts

@@ -0,0 +1 @@
+export declare const fileSystemDirectoryHandleFactory: (name: string) => FileSystemDirectoryHandle;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "opfs-mock",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Mock all origin private file system APIs for your Jest or Vitest tests",
+  "author": "jurerotar <hello@jurerotar.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/jurerotar/opfs-mock#README",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jurerotar/opfs-mock.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jurerotar/opfs-mock/issues"
+  },
+  "keywords": ["vitest", "jest", "test", "mock", "opfs", "storage", "node", "browser"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "module": "dist/index.js",
+  "files": ["dist"],
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "lint:check": "npx @biomejs/biome lint",
+    "lint": "npx @biomejs/biome lint --fix",
+    "format:check": "npx @biomejs/biome format",
+    "format": "npx @biomejs/biome format --write",
+    "type-check": "tsc --noEmit",
+    "test": "vitest",
+    "build:types": "tsc --emitDeclarationOnly",
+    "prepublishOnly": "npm run build && npm run build:types",
+    "release": "npm publish --access public"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "1.9.3",
+    "typescript": "5.6.2",
+    "vite": "5.4.8",
+    "vitest": "2.1.2"
+  }
+}