Expand description
§About
RenFS provides bindings for ZenFS in Rust, delegating to browser APIs like:
- localStorage,
- IndexedDB, and
- OPFS.
For convenience, std::fs is used on native platforms and works out-of-the-box on the web with webfs.
§Usage
Please read the examples for guidance.
§Install ZenFS
RenFS has a CLI to automatically install a bundled version of ZenFS directly into a project:
cargo install renfs --locked # or cargo binstall renfs
renfs dist/zenfs.jsOtherwise, you can download it manually from https://github.com/egakareta/renfs_vendor.
§Configure imports
In your HTML file:
<script type="importmap">
{
"imports": {
"@zenfs/core": "./zenfs.js",
"@zenfs/dom": "./zenfs.js"
}
}
</script>§Configure a browser filesystem
For most use cases, configure ZenFS before Rust application initialization.
Trunk makes this easy with its data-initializer attribute:
<link data-trunk rel="rust" data-initializer="./init.mjs" />where ./init.mjs looks like:
import { configure, InMemory } from "@zenfs/core";
import { IndexedDB } from "@zenfs/dom";
await configure({
mounts: {
"/": IndexedDB,
"/tmp": InMemory,
},
});
export default () => ({});§When you just need something simple
You can just not set up ZenFS. If the webfs feature is enabled (it is by default), RenFS can
run on the web without any additional setup with localStorage.
The obvious tradeoffs are that localStorage is not a very generous API in terms of storage size and that a lot of advanced filesystem APIs such as symlinking or file stats will error or no-op.
§Q & A
Why use RenFS?
Crates such as opfs, rexie, idb are locked into one browser API and call it a day. For a long time, this was the tradeoff developers had to make if they wanted to persist code in browsers.
RenFS delegates to ZenFS, one of the most versatile and powerful filesystem solutions available in browsers.
Are write operations durable?
For synchronous APIs of some browser backends like IndexedDB and OPFS, no. If you write to a file then immediately refresh the browser window, there is no guarantee that your data has been saved. This is a fundamental limitation of ZenFS.
If you are using localStorage, you should be fine but this is subject to browser policy.
If you want durable operations, consider using asynchronous APIs such as write_file instead
of write_file_sync.
§License
Dual-licensed under the MIT License and the Apache License, Version 2.0. Choose whichever you prefer. This license only applies to RenFS code.
ZenFS is licensed under the LGPL 3.0 or later and COPYING.md. Copyright © James Prevett and other ZenFS contributors.
Modules§
- fs
- Filesystem manipulation operations.
Structs§
- Blob
- An in-memory snapshot of a file’s contents returned by
fs::open_as_blob. - Dir
- An open directory handle. Read entries one at a time and close it when finished.
- Directory
- A filesystem directory whose operations use paths relative to its root.
- Dirent
- A directory entry returned by
Dir::readorDir::read_sync. - File
- An object providing access to an open file on the filesystem.
- Metadata
- Metadata about a filesystem entry.
- Open
Options - Options and flags which can be used to configure how a file is opened.
- Read
Stream - A readable byte stream. Dropping it destroys the stream.
- Read
Stream Options - Options for a streaming read.
endis an inclusive byte offset. - StatFs
- Information about the filesystem containing a path.
- TempDir
- A temporary directory removed when this value is dropped.
- Watch
File Options - Options for polling changes to a file’s metadata.
- Watch
Options - Options for watching file or directory changes.
- Watcher
- A filesystem watcher returned by
fs::watch. - Write
Stream - A writable byte stream. Call
WriteStream::endto finish writing. - Write
Stream Options - Options for a streaming write. ZenFS’s
createWriteStreamalways opens withw, truncating the file before applyingstart.
Constants§
- F_OK
- Check whether a path exists, without checking permissions.
- R_OK
- Check whether a path is readable.
- W_OK
- Check whether a path is writable.
- X_OK
- Check whether a path is executable.
Traits§
- FileOps
- Filesystem operations that resolve paths before accessing the implementation.
Functions§
- access
- Checks whether a path can be accessed with the requested mode.
- access_
sync - Checks whether a path can be accessed with the requested mode.
- app_dir
- Creates and returns a directory for the named application.
- append_
file - Appends a byte slice to a file, creating it if it does not exist.
- append_
file_ sync - Appends a byte slice to a file, creating it if it does not exist.
- append_
text - Appends a string slice to a file.
- chmod
- Changes the permissions found on a file or a directory.
- chmod_
sync - Changes the permissions found on a file or a directory.
- chown
- Changes the owner and group of a file or directory.
- chown_
sync - Changes the owner and group of a file or directory.
- close
- Closes an open file.
- close_
sync - Closes an open file.
- copy_
file - Copies the contents of one file to another. This function will also copy the permission bits of the original file to the destination file.
- copy_
file_ sync - Copies the contents of one file to another. This function will also copy the permission bits of the original file to the destination file.
- cp
- Recursively copies a file or directory to a new path.
- cp_sync
- Recursively copies a file or directory to a new path.
- create_
dir - Creates a new, empty directory at the provided path.
- create_
dir_ all - Recursively create a directory and all of its parent components if they are missing.
- create_
read_ stream - Opens a file as a readable stream.
- create_
read_ stream_ with_ options - Opens a file as a readable stream with byte-range and chunk options.
- create_
write_ stream - Opens a file as a writable stream, replacing its contents.
- create_
write_ stream_ with_ options - Opens a file as a writable stream with the provided options.
- exists
- Returns
Ok(true)if the path points at an existing entity. - exists_
sync - Returns
Ok(true)if the path points at an existing entity. - fchmod
- Changes the permissions of an open file.
- fchmod_
sync - Changes the permissions of an open file.
- fchown
- Changes the owner and group of an open file.
- fchown_
sync - Changes the owner and group of an open file.
- fdatasync
- Synchronizes file content to the filesystem.
- fdatasync_
sync - Synchronizes file content to the filesystem.
- fstat
- Returns metadata for an open file.
- fstat_
sync - Returns metadata for an open file.
- fsync
- Synchronizes all file content and metadata to the filesystem.
- fsync_
sync - Synchronizes all file content and metadata to the filesystem.
- ftruncate
- Changes the size of an open file.
- ftruncate_
sync - Changes the size of an open file.
- futimes
- Changes the access and modification times of an open file.
- futimes_
sync - Changes the access and modification times of an open file.
- glob
- Returns paths matching a glob pattern.
- glob_
sync - Returns paths matching a glob pattern.
- glob_
to_ regex - Converts a glob pattern into a regular expression source.
- lchmod
- Changes the permissions of a symbolic link itself (if supported).
- lchmod_
sync - Changes the permissions of a symbolic link itself (if supported).
- lchown
- Changes the owner and group of a symbolic link itself.
- lchown_
sync - Changes the owner and group of a symbolic link itself.
- link
- Creates a new hard link on the filesystem.
- link_
sync - Creates a new hard link on the filesystem.
- lstat
- Queries the metadata about a file without following symlinks.
- lstat_
sync - Queries the metadata about a file without following symlinks.
- lutimes
- Changes the access and modification times of a symbolic link itself.
- lutimes_
sync - Changes the access and modification times of a symbolic link itself.
- mkdir
- Creates a directory, creating missing parent directories when
recursiveis true. - mkdir_
sync - Creates a directory, creating missing parent directories when
recursiveis true. - mkdtemp
- Creates a uniquely named temporary directory by appending to
prefix. - mkdtemp_
disposable_ sync - Creates a temporary directory removed when its guard is dropped.
- mkdtemp_
sync - Creates a uniquely named temporary directory by appending to
prefix. - normalize_
path - Normalizes the components of a path.
- open
- Opens a file with the provided options.
- open_
as_ blob - Opens a file and returns a snapshot of its contents.
- open_
sync - Opens a file synchronously with the provided options.
- opendir
- Opens a directory for iteration over its entry names.
- opendir_
sync - Opens a directory for iteration over its entry names.
- read
- Reads bytes from an open file into the provided buffer.
- read_
dir - Returns the names of the entries within a directory.
- read_
file - Reads the entire contents of a file into a bytes vector.
- read_
file_ sync - Reads the entire contents of a file into a bytes vector.
- read_
sync - Reads bytes from an open file into the provided buffer.
- read_
text - Reads the entire contents of a file into a string.
- readdir
- Reads the names of the entries in a directory.
- readdir_
sync - Reads the names of the entries in a directory.
- readlink
- Reads a symbolic link, returning the file that the link points to.
- readlink_
sync - Reads a symbolic link, returning the file that the link points to.
- readv
- Reads from multiple buffers.
- readv_
sync - Reads from multiple buffers.
- realpath
- Returns the canonical, absolute form of a path with all intermediate components normalized and symbolic links resolved.
- realpath_
sync - Returns the canonical, absolute form of a path with all intermediate components normalized and symbolic links resolved.
- remove_
file - Removes a file from the filesystem.
- rename
- Renames a file or directory to a new name, replacing the original file if
toalready exists. - rename_
sync - Renames a file or directory to a new name, replacing the original file if
toalready exists. - rm
- Removes a file or directory, optionally recursively or ignoring missing paths.
- rm_sync
- Removes a file or directory, optionally recursively or ignoring missing paths.
- rmdir
- Removes an empty directory.
- rmdir_
sync - Removes an empty directory.
- stat
- Given a path, queries the file system to get information about a file, directory, etc.
- stat_
sync - Given a path, queries the file system to get information about a file, directory, etc.
- statfs
- Returns information about the filesystem containing the specified path.
- statfs_
sync - Returns information about the filesystem containing the specified path.
- symlink
- Creates a new symbolic link on the filesystem.
- symlink_
sync - Creates a new symbolic link on the filesystem.
- truncate
- Truncates a file to the specified length.
- truncate_
sync - Truncates a file to the specified length.
- unlink
- Removes a file from the filesystem.
- unlink_
sync - Removes a file from the filesystem.
- unwatch_
file - Stops all
watch_filelisteners for a path. - unwatch_
file_ listener - Stops one
watch_filelistener by the ID returned fromwatch_file. - utimes
- Changes the timestamps of the file or directory at the specified path.
- utimes_
sync - Changes the timestamps of the file or directory at the specified path.
- watch
- Watches a file or directory for changes.
- watch_
file - Watches changes to a file using polling and returns an ID for its listener.
- watch_
file_ with_ options - Watches changes to a file with the provided polling options.
- watch_
with_ options - Watches a file or directory with the provided options.
- write
- Writes bytes from the provided buffer to an open file.
- write_
file - Writes a slice as the entire contents of a file.
- write_
file_ sync - Writes a slice as the entire contents of a file.
- write_
sync - Writes bytes from the provided buffer to an open file.
- write_
text - Writes a slice as the entire contents of a file.
- writev
- Writes from multiple buffers.
- writev_
sync - Writes from multiple buffers.