osjs-browserfs-adapter
OS.js BrowserFS Adapter
This is a BrowserFS VFS Adapter for OS.js.
OS.js is an open-source web desktop platform with a window manager, application APIs, GUI toolkit, filesystem abstractions and much more.
@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.
@BrowserFS is transient project (from BrowserFS towards @ZenFS).
@BrowserFS-iontach</ins> 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
[!IMPORTANT] Next version probably move back to original jVilk BrowserFS
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
```bibtex @inproceedings{VilkDoppio, author = {John Vilk and Emery D. Berger}, title = , 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} } ```references
```bibtex @inproceedings{PowersBrowsix, author = {Bobby Powers and John Vilk and Emery D. Berger}, title = , 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
This OS.js BrowserFS Adapter is licensed under the MIT License.
It embed a fork of Broofa mime that is under the MIT License.
OS.js, BrowserFS, and ZenFS are also licensed under the MIT License.
See LICENSE.txt and broofa-mime.js for details.
Installation
npm install saoirse-iontach/osjs-browserfs-adapter # @osjs/browserfs-adapter
Overriding BrowserFS dependencies
If you fork **@BrowserFS-iontach**, then add the following to your *package.json*:
```json
"scripts": {
"dependencies": "npx bfs-adapter-prepare",
"test": "npx bfs-adapter-test"
},
"dependencies": {
"@browserfs/core": "...",
"@browserfs/fs-dom": "..."
}
```
Then if you remove a ```@browserfs/*```, you must do ```npm ci```.
#### Testing
Run simple tests with `npx bfs-adapter-test`.\
Then analyze console output.
Usage
Register adapter in your src/client/index.js bootstrap file:
import bfsAdapter from '@osjs/browserfs-adapter';
osjs.register(VFSServiceProvider, {
args: {
adapters: {
bfs: bfsAdapter
}
}
});
Then create mountpoints in your src/client/config.js file:
(and provide missing mime type)
{
mime: {
filenames: {
// 'filename': 'mime/type'
'Makefile': 'text/x-makefile',
'.gitignore': 'text/plain'
},
define: {
// 'mime/type': ['ext']
'text/x-lilypond': ['ly', 'ily'],
'text/x-python': ['py'],
'application/tar+gzip': ['tgz']
}
},
vfs: {
mountpoints: [{
name: 'localstorage',
label: 'Browser low data',
adapter: 'bfs',
attributes: {
fs: 'Storage'
}
},{
name: 'opfs',
label: 'Browser files',
adapter: 'bfs',
attributes: {
fs: 'FileSystemAccess'
}
},{
name: 'debug-bfs',
label: 'BrowserFS internals',
adapter: 'bfs',
attributes: {
root: '/'
}
},{
name: 'test-shortcut',
label: 'My Documents',
adapter: 'bfs',
attributes: {
root: 'opfs:/MyDocuments'
}
}]
}
}
mountpoint.root is the vfs path prefix.
attributes.root is the bfs path prefix.
This is use for path translation on vfs operation.
attributes.fs is the bfs backend name.
attributes.mountpoint is the bfs mountpoint.
This is used (if provided) to mount a backend.
Use attributes['/subpath'] to mount a nested backend.
Then you can provide either a string for backend name,
or a nested object for backend config and inner nest.
attributes.options will be pass to backend.
Else others attributes.xxx will be pass as options.
advanced usage
```js
// Await all
import bfsAdapter from '@osjs/browserfs-adapter';
const {mime, core, dom, browserfs, adapter} = await bfsAdapter.default;
```
```js
// Await some
import bfsAdapter from '@osjs/browserfs-adapter';
const mime = await bfsAdapter.mime;
const adapter = await bfsAdapter.adapter;
```
```js
// Don't wait for the adapter
import bfsAdapter from '@osjs/browserfs-adapter';
const adapter = bfsAdapter.preload;
// adapter will wait to complete mount,
// andwill be updated to awaited bfsAdapter.adapter
```
```js
// internals api, to build your custom adapter
import bfsAdapter from '@osjs/browserfs-adapter';
const { browserfs, upgradeFs, mountHandler,
mountOperations, vfsOperations, mime, vfsMime }
= await bfsAdapter.adapter;
```
Open **`_index.html`** in a browser to have a view of exports.\
Then in the browser console, you can play with:
- `require`: the requirejs module loader
- `adapter`: the adapter factory (see basic usage)
- `modules`: the bundled submodules (see advanced usage)
Documentation
See the OS.js Official Manuals for articles, tutorials and guides.
See the BrowserFS Core
and the BrowserFS DOM for configuring backends.