@themartiancompany/opfs 1.8.11 → 2.0.0

package/README.md

@@ -19,7 +19,7 @@
 [comment]: <> (License along with this program.)
 [comment]: <> (If not, see <https://www.gnu.org/licenses/>.)
 
-# Origin Private File System module (`@themartiancompany/opfs`)
+# OPFS Module (`@themartiancompany/opfs`)
 
 [![NPM version](
   https://img.shields.io/npm/v/@themartiancompany/opfs.svg)](
@@ -29,63 +29,17 @@
   https://img.shields.io/badge/lang-cn-red.svg)](
   README.cn.md)
 
-Browser-compatible `fs` module leveraging the
-[Origin Private File System](
-  https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system)
-(OPFS) specification  which references the
-[Deno Runtime File System](
-  https://deno.land/api#File_System) and
-[Deno `@std/fs`](
-  https://jsr.io/@std/fs)
-APIs.
+Browser-compatible `fs` module obtained combining the
+[Happy OPFS](
+  https://github.com/themartiancompany/happy-opfs)
+and the
+[OPFS Tools](
+  https://github.com/hughfenghen/opfs-tools).
 
 OPFS stands for *origin private file system* 
 and it is a file system API for manipulating local
 files in a browser environment.
 
-There are significant differences between the
-standard OPFS API and familiar file system APIs
-based on path operations, such as those of
-Node.js and Deno.
-The purpose of this module is to implement an API
-similar to those in the browser, allowing for
-convenient file operations.
-
-The return values of asynchronous APIs are of the
-[Result](
-  https://github.com/JiangJie/happy-rusty)
-type, similar to Rust's `Result` enum type,
-providing a more user-friendly error handling approach.
-
-As to why the library targets Deno, that's because:
-
-- early versions of the Node.js fs API were based
-  on callback syntax, although newer versions support
-  Promise syntax;
-  on the other hand, the Deno fs API was designed from
-  the beginning with Promise syntax. Therefore, Deno has
-  less historical baggage, making it a more suitable choice
-  for implementing a native-compatible API;
-- Deno natively supports TypeScript, while Node.js
-  currently does not without the use of additional tools.
-
-Originally based on the 
-[Happy OPFS](
-  https://github.com/JiangJie/happy-opfs)
-module by Jian Jie and renamed
-because I've noticed there was no
-`fs.createReadStream` implementation,
-while the other available
-[OPFS Tools](
-  https://github.com/hughfenghen/opfs-tools)
-module had but didn't call it verbatim
-so I've thought it may have
-been appropriate to make everybody including
-the module potentially less happy and check
-whether if a third module including the function
-and simply called `opfs` can show how much the
-`namespace/package` model works on the field.
-
 ## Installation
 
 To install a locally built version of the
@@ -136,44 +90,16 @@ npm \
     "@themartiancompany/opfs"
 ```
 
-## Synchronous support
-
-> [!NOTE]
-The asynchronous interface is to be preferred
-because the main thread does not provide a synchronous interface,
-so in order to force the implementation of synchronous syntax,
-the I/O operation needs to be moved a
-[`Worker`](
-  https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API),
-and the main thread needs to be blocked until the
-`Worker` completes its I/O operation, which obviously
-causes performance loss.
-
-Also since the `Worker` needs to be started first
-the synchronous interface can only be used after start completion,
-such that any reading and writing before that will fail.
-
-**Please note** that in order to share data
-between the main thread and the `Worker`,
-`SharedArrayBuffer` needs to be used and so
-two additional `HTTP Response Headers` are required for this:
-`'Cross-Origin-Opener-Policy': 'same-origin'`
-and
-`'Cross-Origin-Embedder-Policy': 'require-corp'`,
-otherwise a `ReferenceError: SharedArrayBuffer is not defined`
-error will be thrown.
-
-The headers are automatically set up respectively by
-Parcel and Serve in the Typescript and
-Javascript examples below.
-
-## Examples
+### Documentation
 
-To visually inspect file system status in-browser
-it is available the
-[OPFS Explorer](
-  https://chromewebstore.google.com/detail/acndjpgkpaclldomagafnognkcgjignd)
-extension.
+For API documentation
+refer to the
+[Happy OPFS](
+  https://github.com/themartiancompany/happy-opfs/blob/main/docs/README.md),
+[OPFS Tools](
+  https://github.com/hughfenghen/opfs-tools/blob/main/docs/api.md) and
+[File System API](
+  https://nodejs.org/api/fs.html).
 
 ### Javascript
 
@@ -198,44 +124,8 @@ libraries.
 Refer to the Ahsi repository for more information
 about installing and running it.
 
-### Typescript
-
-Typescript asynchronous
-([tests/async.ts](
-  tests/async.ts))
-and synchronous examples 
-([tests/sync.ts](
-  tests/sync.ts))
-are made available in the `tests` directory.
-
-To build them and make them available in an
-HTTP server run
-
-```bash
-npm \
-  run \
-    start
-```
-
-then open
-[https://localhost:8443/](
-  https://localhost:8443/)
-in your browser and open the developer
-tools to observe the console output.
-
-## Documentation
-
-Module API is in the
-[docs](
-  docs/README.md)
-directory.
-
 ## License
 
-This software repository by Jian Jie
-and Pellegrino Prevete is released
+This software repository is released
 under the terms of the GNU Affero
 General Public License version 3.
-Portions of the works authored by
-Jian are released under GNU General
-Public License version 3.

package/{src/fs/support.ts → opfs}

@@ -1,4 +1,6 @@
-// SPDX-License-Identifier: GPL-3.0-or-later
+#!/usr/bin/env node
+
+// SPDX-License-Identifier: AGPL-3.0-or-later
 
 /**    ----------------------------------------------------------------------
  *     Copyright ©
@@ -24,13 +26,33 @@
  *     along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-/**
- * Checks if the Origin Private File System (OPFS) is supported in the current environment.
- *
- * @returns A boolean indicating whether OPFS is supported.
- */
-export function
-  isOPFSSupported():
-    boolean {
-    return typeof navigator?.storage?.getDirectory === 'function';
+const
+  _opfs =
+    require(
+      "happy-opfs");
+const
+  _opfs_tools =
+    require(
+      "opfs-tools");
+_file =
+  _opfs_tools.file;
+
+function
+  _read_stream_create(
+    _input_file,
+    _options) {
+  const
+    _file_obj =
+      _file(
+        _input_file);
+    const
+      _writer =
+        _file_obj.createWriter();
+  return _writer;
 }
+
+_opfs.createReadStream =
+  _read_stream_create;
+
+module.exports =
+  _opfs;

package/package.json

@@ -4,31 +4,23 @@
   "description":
     "Browser-compatible (OPFS) Node/Deno 'fs' module.",
   "version":
-    "1.8.11",
+    "2.0.0",
   "homepage":
     "https://github.com/themartiancompany/opfs",
   "license":
-    "GPL-3.0",
+    "AGPL-3.0",
   "bugs": {
     "url":
       "https://github.com/themartiancompany/opfs/issues"
   },
-  "author": {
-    "name":
-      "Jiang Jie",
-    "email":
-      "jiang115jie@gmail.com",
-    "url":
-      "https://github.com/JiangJie"
+  "author":
+    { "name":
+        "Pellegrino Prevete",
+      "email":
+        "pellegrinoprevete@gmail.com",
+      "url":
+        "https://github.com/tallero"
   },
-  "contributors": [ {
-    "name":
-      "Pellegrino Prevete",
-    "email":
-      "pellegrinoprevete@gmail.com",
-    "url":
-      "https://github.com/tallero"
-  } ],
   "keywords": [
     "fs",
     "system",
@@ -50,41 +42,28 @@
   "files": [
     "COPYING",
     "README.md",
-    "README.cn.md",
-    "package.json",
-    "docs",
-    "src",
-    "dist"
+    "opfs",
+    "package.json"
   ],
   "source":
     "src/mod.ts",
   "man":
     "man/opfs.1",
   "main":
-    "dist/main.cjs",
+    "opfs",
   "module":
-    "dist/main.mjs",
-  "types":
-    "dist/types.d.ts",
+    "opfs",
   "sideEffects":
     false,
   "scripts": {
-    "clean":
-      "npx dlx rimraf .parcel-cache dist",
-    "check":
-      "npx tsc --noEmit",
     "lint":
       "npx eslint .",
     "prebuild":
-      "npx rimraf dist && npm run check && npm run lint",
+      "npm run lint",
     "build":
-      "npm install --save-dev && npx rollup --config rollup.config.mjs",
+      "npm install --save-dev",
     "docs":
-      "typedoc",
-    "prepublishOnly":
-      "npx rollup --config rollup.config.mjs",
-    "start":
-      "npx parcel serve tests/index.html --dist-dir dist/dev --port 8443 --https --no-cache"
+      "typedoc"
   },
   "repository": {
     "type": "git",
@@ -93,49 +72,13 @@
   "devDependencies": {
     "@eslint/js":
       "^9.32.0",
-    "@parcel/packager-ts":
-      "^2.16.0",
-    "@parcel/transformer-typescript-types":
-      "^2.16.0",
-    "dlx":
-      "^0.2.1",
     "eslint":
-      "^9.32.0",
-    "parcel":
-      "^2.16.0",
-    "rimraf":
-      "^6.1.0",
-    "rollup":
-      "^4.52.5",
-    "rollup-plugin-dts":
-      "^6.2.1",
-    "rollup-plugin-esbuild":
-      "^6.2.1",
-    "typedoc":
-      "^0.27.9",
-    "typedoc-plugin-markdown":
-      "4.4.2",
-    "typescript":
-      "^5.8.3",
-    "typescript-eslint":
-      "^8.38.0"
+      "^9.32.0"
   },
   "dependencies": {
-    "@happy-ts/fetch-t":
-      "^1.3.2",
-    "@std/path":
-      "npm:@themartiancompany/std__path@^1.1.1",
-    "fflate":
-      "^0.8.2",
-    "happy-rusty":
-      "^1.5.0",
-    "tiny-future":
-      "^1.1.0",
-    "tiny-invariant":
-      "^1.3.3"
-  },
-  "@parcel/resolver-default": {
-    "packageExports":
-      true
+    "happy-opfs":
+      "npm:@themartiancompany/happy-opfs@^1.8.12",
+    "opfs-tools":
+      "0.7.4"
   }
 }

package/README.cn.md

@@ -1,301 +0,0 @@
-[comment]: <> (SPDX-License-Identifier: AGPL-3.0)
-
-[comment]: <> (-------------------------------------------------------------)
-[comment]: <> (Copyright © 2024, 2025  Pellegrino Prevete)
-[comment]: <> (All rights reserved)
-[comment]: <> (-------------------------------------------------------------)
-
-[comment]: <> (This program is free software: you can redistribute)
-[comment]: <> (it and/or modify it under the terms of the GNU Affero)
-[comment]: <> (General Public License as published by the Free)
-[comment]: <> (Software Foundation, either version 3 of the License.)
-
-[comment]: <> (This program is distributed in the hope that it will be useful,)
-[comment]: <> (but WITHOUT ANY WARRANTY; without even the implied warranty of)
-[comment]: <> (MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the)
-[comment]: <> (GNU Affero General Public License for more details.)
-
-[comment]: <> (You should have received a copy of the GNU Affero General Public)
-[comment]: <> (License along with this program.)
-[comment]: <> (If not, see <https://www.gnu.org/licenses/>.)
-
-
-# 快乐地使用 OPFS
-
-[![NPM version](
-     http://img.shields.io/npm/v/@themartiancompany/opfs.svg)](
-       https://npmjs.org/package/@themartiancompany/opfs)
-
-[![en](
-  https://img.shields.io/badge/lang-en-black.svg)](
-  README.md)
-
-
-这是一套参考 [Deno Runtime File System](
-  https://deno.land/api#File_System)
-和 [Deno @std/fs](
-  https://jsr.io/@std/fs)
-API，基于 OPFS 实现的浏览器可用的 fs 模块。
-
-## 安装
-
-```sh
-npm \
-  install \
-  --save \
-  "@themartiancompany/opfs"
-```
-
-## 什么是 OPFS
-
-OPFS 是 [Origin private file system](
-  https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system)
-的简称，旨在为浏览器环境提供一套文件系统 API 来操作本地文件。
-
-## 为什么会有 'opfs`
-
-标准的 OPFS API 和我们熟知的基于路径操作的文件系统 API 如 Node.js、Deno
-存在较大的区别，本项目即是为了实现在浏览器中也能拥有 Deno
-一样的 API 方便地操作文件而生。
-
-异步 API 的返回值都是 [Result](
-                         https://github.com/JiangJie/happy-rusty)
-类型，类似 Rust 的 `Result`
-枚举类型，提供更友好的错误处理方式。
-
-## 为什么参考 Deno 而不是 Node.js
-
--   早期的 Node.js fs API
-    是基于回调的语法，虽然较新的版本支持了 Promise
-    语法，而 Deno fs API 则一开始就是基于 Promise
-    语法，这样来说的话，Deno 有更少的历史包袱，要实现和 Native
-    兼容的 API，选择 Deno 做为参考显然更合适。
--   Deno 原生支持 TypeScript，而 Node.js
-    在不借助于其它工具的情况下暂不支持。
-
-## 是否支持同步接口
-
-**支持**
-
-> [!NOTE]
-但更推荐使用异步接口，因为主线程并未提供同步接口，为了强制实现同步语法，需要将 I/O 操作移到 `Worker` 进行，同时主线程需要处于阻塞状态，直到 `Worker` 完成 I/O 操作，这显然会带来性能上的损失。
-
-并且由于需要启动 `Worker，同步接口需要在`
-`Worker` 启动后才能使用，在此之前任何读写都会失败。
-
-**请注意**，为了在主线程和 `Worker`
-之间共享数据，需要使用 `SharedArrayBuffer`，为此需要两个额外的 `HTTP Response Header`:
-`'Cross-Origin-Opener-Policy': 'same-origin'`
-`'Cross-Origin-Embedder-Policy': 'require-corp'`。
-否则会报错 `ReferenceError: SharedArrayBuffer is not defined`。
-
-## 示例
-
-```ts
-import * as fs from 'opfs';
-
-(async () => {
-    const mockServer = 'https://16a6dafa-2258-4a83-88fa-31a409e42b17.mock.pstmn.io';
-    const mockTodos = `${ mockServer }/todos`;
-    const mockTodo1 = `${ mockTodos }/1`;
-
-    // Check if OPFS is supported
-    console.log(`OPFS is${ isOPFSSupported() ? '' : ' not' } supported`);
-
-    // Clear all files and folders
-    await fs.emptyDir(fs.ROOT_DIR);
-    // Recursively create the /happy/opfs directory
-    await fs.mkdir('/happy/opfs');
-    // Create and write file content
-    await fs.writeFile('/happy/opfs/a.txt', 'hello opfs');
-    await fs.writeFile('/happy/op-fs/fs.txt', 'hello opfs');
-    // Move the file
-    await fs.move('/happy/opfs/a.txt', '/happy/b.txt');
-    // Append content to the file
-    await fs.appendFile('/happy/b.txt', new TextEncoder().encode(' happy opfs'));
-
-    // File no longer exists
-    const statRes = await fs.stat('/happy/opfs/a.txt');
-    console.assert(statRes.isErr());
-
-    console.assert((await fs.readFile('/happy/b.txt')).unwrap().byteLength === 21);
-    // Automatically normalize the path
-    console.assert((await fs.readTextFile('//happy///b.txt//')).unwrap() === 'hello opfs happy opfs');
-
-    console.assert((await fs.remove('/happy/not/exists')).isOk());
-    console.assert((await fs.remove('/happy/opfs')).isOk());
-
-    console.assert(!(await fs.exists('/happy/opfs')).unwrap());
-    console.assert((await fs.exists('/happy/b.txt')).unwrap());
-    console.assert(fs.isFileHandle((await fs.stat('/happy/b.txt')).unwrap()));
-
-    // Download a file
-    const downloadTask = fs.downloadFile(mockSingle, '/todo.json', {
-        timeout: 1000,
-        onProgress(progressResult): void {
-            progressResult.inspect(progress => {
-                console.log(`Downloaded ${ progress.completedByteLength }/${ progress.totalByteLength } bytes`);
-            });
-        },
-    });
-    const downloadRes = await downloadTask.response;
-    if (downloadRes.isOk()) {
-        console.assert(downloadRes.unwrap() instanceof Response);
-
-        const postData = (await fs.readTextFile('/todo.json')).unwrap();
-        const postJson: {
-            id: number;
-            title: string;
-        } = JSON.parse(postData);
-        console.assert(postJson.id === 1);
-
-        // Modify the file
-        postJson.title = 'happy-opfs';
-        await fs.writeFile('/todo.json', JSON.stringify(postJson));
-
-        // Upload a file
-        console.assert((await fs.uploadFile('/todo.json', mockAll).response).unwrap() instanceof Response);
-    } else {
-        console.assert(downloadRes.unwrapErr() instanceof Error);
-    }
-
-    {
-        // Download a file to a temporary file
-        const downloadTask = fs.downloadFile(mockSingle);
-        const downloadRes = await downloadTask.response;
-        downloadRes.inspect(x => {
-            console.assert(fs.isTempPath(x.tempFilePath));
-            console.assert(x.rawResponse instanceof Response);
-        });
-        if (downloadRes.isOk()) {
-            await fs.remove(downloadRes.unwrap().tempFilePath);
-        }
-    }
-
-    // Will create directory
-    await fs.emptyDir('/not-exists');
-
-    // Zip/Unzip
-    console.assert((await fs.zip('/happy', '/happy.zip')).isOk());
-    console.assert((await fs.zip('/happy')).unwrap().byteLength === (await fs.readFile('/happy.zip')).unwrap().byteLength);
-    console.assert((await fs.unzip('/happy.zip', '/happy-2')).isOk());
-    console.assert((await fs.unzipFromUrl(mockZipUrl, '/happy-3', {
-        onProgress(progressResult) {
-            progressResult.inspect(progress => {
-                console.log(`Unzipped ${ progress.completedByteLength }/${ progress.totalByteLength } bytes`);
-            });
-        },
-    })).isOk());
-    console.assert((await fs.zipFromUrl(mockZipUrl, '/test-zip.zip')).isOk());
-    console.assert((await fs.zipFromUrl(mockZipUrl)).unwrap().byteLength === (await fs.readFile('/test-zip.zip')).unwrap().byteLength);
-
-    // Temp
-    console.log(`temp txt file: ${ fs.generateTempPath({
-        basename: 'opfs',
-        extname: '.txt',
-    }) }`);
-    console.log(`temp dir: ${ fs.generateTempPath({
-        isDirectory: true,
-    }) }`);
-    (await fs.mkTemp()).inspect(path => {
-        console.assert(path.startsWith('/tmp/tmp-'));
-    });
-    const expired = new Date();
-    (await fs.mkTemp({
-        basename: 'opfs',
-        extname: '.txt',
-    })).inspect(path => {
-        console.assert(path.startsWith('/tmp/opfs-'));
-        console.assert(path.endsWith('.txt'));
-    });
-    (await fs.mkTemp({
-        isDirectory: true,
-        basename: '',
-    })).inspect(path => {
-        console.assert(path.startsWith('/tmp/'));
-    });
-    console.assert((await Array.fromAsync((await fs.readDir(fs.TMP_DIR)).unwrap())).length === 3);
-    await fs.pruneTemp(expired);
-    console.assert((await Array.fromAsync((await fs.readDir(fs.TMP_DIR)).unwrap())).length === 2);
-    // await fs.deleteTemp();
-    // console.assert(!(await fs.exists(fs.TMP_DIR)).unwrap());
-
-    // Copy
-    await fs.mkdir('/happy/copy');
-    console.assert((await fs.copy('/happy/b.txt', '/happy-2')).isErr());
-    console.assert((await fs.copy('/happy', '/happy-copy')).isOk());
-    await fs.appendFile('/happy-copy/b.txt', ' copy');
-    console.assert((await fs.readFile('/happy-copy/b.txt')).unwrap().byteLength === 26);
-    await fs.appendFile('/happy/op-fs/fs.txt', ' copy');
-    await fs.copy('/happy', '/happy-copy', {
-        overwrite: false,
-    });
-    console.assert((await fs.readFile('/happy-copy/b.txt')).unwrap().byteLength === 26);
-
-    // List all files and folders in the root directory
-    for await (const { path, handle } of (await fs.readDir(fs.ROOT_DIR, {
-        recursive: true,
-    })).unwrap()) {
-        const handleLike = await fs.toFileSystemHandleLike(handle);
-        if (fs.isFileHandleLike(handleLike)) {
-            console.log(`${ path } is a ${ handleLike.kind }, name = ${ handleLike.name }, type = ${ handleLike.type }, size = ${ handleLike.size }, lastModified = ${ handleLike.lastModified }`);
-        } else {
-            console.log(`${ path } is a ${ handleLike.kind }, name = ${ handleLike.name }`);
-        }
-    }
-
-    // Comment this line to view using OPFS Explorer
-    await fs.remove(fs.ROOT_DIR);
-})();
-```
-
-以上示例代码可以在 [tests/async.ts](
-                      tests/async.ts)
-找到，也可以通过以下方式查看运行时效果。
-
-```
-git clone https://github.com/themartiancompany/opfs.git
-cd opfs
-pnpm install
-pnpm start
-```
-
-通过浏览器打开 [https://localhost:8443/](
-                  https://localhost:8443/)，打开开发者工具观察 console
-的输出。
-
-你也可以安装 [OPFS Explorer](
-                https://chromewebstore.google.com/detail/acndjpgkpaclldomagafnognkcgjignd)
-浏览器扩展，以便直观地查看文件系统状态。
-
-### 同步示例
-
-`worker.ts`
-```ts
-import { startSyncAgent } from 'happy-opfs';
-
-startSyncAgent();
-```
-
-`index.ts`
-```ts
-import { connectSyncAgent, mkdirSync } from 'happy-opfs';
-
-await connectSyncAgent({
-    worker: new Worker(new URL('worker.ts', import.meta.url), {
-        type: 'module'
-    }),
-    // SharedArrayBuffer size between main thread and worker
-    bufferLength: 10 * 1024 * 1024,
-    // max wait time at main thread per operation
-    opTimeout: 3000,
-});
-
-mkdirSync('/happy/opfs');
-// other sync operations
-```
-
-详见 [tests/sync.ts](
-        tests/sync.ts)。
-
-## [文档](docs/README.md)