Use OPFS Happily (@themartiancompany/happy-opfs)

Browser-compatible fs module leveraging the Origin Private File System (OPFS) specification which references the Deno Runtime File System and Deno @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 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 module by Jian Jie.

Installation

To install a locally built version of the library run

$ make \
    all

An opfs-<version>.tgz npm archive will be generated in the root of the repository.

To install the library system-wide run

# make \
    install-npm

To install it as a DogeOS system package from the Ur uncensorable user repository and application store run

ur \
  "nodejs-happy-opfs"

A mirror of the Ur universal recipe has been made available on The Martian Company's Github at nodejs-happy-opfs-ur.

To download the library from the NPM Registry run

npm \
  install \
  --save \
    "@themartiancompany/happy-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, 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 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 program, written using the Crash Javascript and Crash Bash libraries.

Refer to the Ahsi repository for more information about installing and running it.

Typescript

Typescript asynchronous (tests/async.ts) and synchronous examples (tests/sync.ts) are made available in the tests directory.

To build them and make them available in an HTTP server run

npm \
  run \
    start

then open https://localhost:8443/ in your browser and open the developer tools to observe the console output.

Documentation

Module API is in the docs 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.