@themartiancompany/opfs 1.8.11

package/README.cn.md

@@ -0,0 +1,301 @@
+[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)

package/README.md

@@ -0,0 +1,241 @@
+[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/>.)
+
+# Origin Private File System module (`@themartiancompany/opfs`)
+
+[![NPM version](
+  https://img.shields.io/npm/v/@themartiancompany/opfs.svg)](
+    https://npmjs.org/package/@themartiancompany/opfs)
+
+[![cn](
+  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.
+
+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
+library run
+
+```bash
+$ make \
+    all
+```
+
+An `opfs-<version>.tgz` npm archive will be generated
+in the root of the repository.
+
+To install the library system-wide run
+
+```bash
+# make \
+    install-npm
+```
+
+To install it as a
+[DogeOS](
+  https://githubcom/themartiancompany/dogeos)
+system package from the
+[Ur](
+  https://github.com/themartiancompany/ur)
+uncensorable user repository and application
+store run
+
+```bash
+ur \
+  "nodejs-opfs"
+```
+
+A mirror of the Ur universal recipe
+has been made available on The Martian
+Company's Github at
+[`nodejs-opfs-ur`](
+  https://github.com/themartiancompany/nodejs-opfs-ur).
+
+To download the library from
+the NPM Registry run
+
+```bash
+npm \
+  install \
+  --save \
+    "@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
+
+To visually inspect file system status in-browser
+it is available the
+[OPFS Explorer](
+  https://chromewebstore.google.com/detail/acndjpgkpaclldomagafnognkcgjignd)
+extension.
+
+### Javascript
+
+If you are looking for an example of how
+to write a full computer application
+composed of only Bash programs and
+Node modules but which runs the
+same and with zero modifications
+regardless of whether it has available
+for display a terminal or a browser window,
+you can look at the
+[Ahsi](
+  https://github.com/themartiancompany/ahsi)
+program, written using the
+[Crash Javascript](
+  https://github.com/themartiancompany/crash-js)
+and
+[Crash Bash](
+  https://github.com/themartiancompany/crash-bash)
+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
+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.