@BrowserFS / DOM Backends - iontach

@BrowserFS backends for DOM APIs.
DOM APIs are only available natively in browsers.

BrowserFS is an in-browser file system that emulates the Node JS file system API and supports storing and retrieving files from various backends. BrowserFS also integrates nicely with other tools.

Note

@ZenFS is an (breaking) update of BrowserFS, with a node:fs interface. _{As of April 2024, it is still in development, that's to say instable and not properly working (expectially encodings, with bad tests). More over contributors are actually dismissed. And citation of original academic papers was sadly discarded...}

@BrowserFS is transient project _{from BrowserFS towards @ZenFS, (illegitimacy?) claiming to be the next BrowserFS (in fact it is @ZenFS before rebranding)} [!IMPORTANT] @BrowserFS-iontach is a bugfixed fork of @BrowserFS @1.0.

Project	author	timeline	links
BrowserFS	John Vilk	2014 - 2017	npm github
@BrowserFS	dr-Vortex	09/2023 - 03/2024	npm github
@ZenFS	dr-Vortex	03/2024 - ...	npm github

^{dr-Vortext is an alias of James P}

Versions

versions details

@BrowserFS/fs-dom and @ZenFS/dom share the same repository:

• Versions <=v0.0.6 are @BrowserFS/fs-dom
• Versions >=v0.1.3 are @ZenFS/dom

Versions v0.0.6 - v0.2.14 are equivalent;
Some fixes, but mainly cosmetics.
But Worker and HTTPRequest backends were removed in v0.1.0.

Versions of this Iontach fork:

Iontach version	Description
v0.0.6	Original @BrowserFS version
v0.0.7-iontach	Inital Iontach bugfix
~v0.1.10	Newer Iontach bugfix
semver:0.1	Simplified Iontach release scheme

Packages saoirse-iontach/browser-fs-dom#semver:0.1
depends on saoirse-iontach/browser-fs-core#semver:0.1
which emulate node:fs v14.x.x.

Citing

BrowserFS is a component of the Doppio and Browsix research projects from the PLASMA lab at the University of Massachusetts Amherst. If you decide to use BrowserFS in a project that leads to a publication, please cite the academic papers on Doppio and Browsix.

citations

• John Vilk and Emery D. Berger. Doppio: Breaking the Browser Language Barrier. In Proceedings of the 35th ACM SIGPLAN Conference on Programming Language Design and Implementation (2014), pp. 508–518.

  references

  @inproceedings{VilkDoppio,
      author	= {John Vilk and Emery D. Berger},
      title	= {{Doppio: Breaking the Browser Language Barrier}},
      booktitle	= {Proceedings of the 35th {ACM} {SIGPLAN} Conference
      			on Programming Language Design and Implementation},
      pages	= {508--518},
      year	= {2014},
      url	= {http://doi.acm.org/10.1145/2594291.2594293},
      doi	= {10.1145/2594291.2594293}
  }

• Bobby Powers, John Vilk, and Emery D. Berger. Browsix: Bridging the Gap Between Unix and the Browser. In Proceedings of the Twenty-Second International Conference on Architectural Support for Programming Languages and Operating Systems (2017), pp. 253–266.

  references

  @inproceedings{PowersBrowsix,
      author	= {Bobby Powers and John Vilk and Emery D. Berger},
      title	= {{Browsix: Bridging the Gap Between Unix and the Browser}},
      booktitle	= {Proceedings of the Twenty-Second International Conference
      			on Architectural Support for Programming Languages and Operating Systems},
      pages	= {253--266},
      year	= {2017},
      url	= {http://doi.acm.org/10.1145/3037697.3037727},
      doi	= {10.1145/3037697.3037727}
  }

License

BrowserFS and ZenFS are licensed under the MIT License. See LICENSE for details.

Backends

• HTTPRequest: Downloads files on-demand from a webserver using fetch.
• Storage: Stores files in a Storage object, like localStorage and seesionStorage.
• IndexedDB: Stores files into an IndexedDB object database.
• WorkerFS: Lets you mount the BrowserFS file system configured in the main thread in a WebWorker, or the other way around!

For more information, see the API documentation.

Installing

npm install saoirse-iontach/browser-fs-dom    # @browserfs/fs-dom

Building

• Make sure you have Node and NPM installed. You must have Node v18 or newer.
• Install dependencies with npm install
• Build using npm run build
• You can find the built code in dist.

Testing

Run unit tests with npm test.

Usage

🛈 The examples are written in ESM. If you are using CJS, you can require the package. If running in a browser you can add a script tag to your HTML pointing to the browser.min.js and use BrowserFS DOM via the global BrowserFS_DOM object.

You can use DOM backends, though you must register them if you plan on using configure:

import { configure, fs, registerBackend } from '@browserfs/core';
import { Storage } from '@browserfs/fs-dom';

registerBackend(Storage);
await configure({ fs: 'Storage', options: { storage: localStorage } });

if (!fs.existsSync('/test.txt')) {
	fs.writeFileSync('/test.txt', 'This will persist across reloads!');
}

const contents = fs.readFileSync('/test.txt', 'utf-8');
console.log(contents);