Skip to main content

Crate renfs

Crate renfs 

Source
Expand description

📂 RenFS

Build Status crates.io

§About

RenFS provides bindings for ZenFS in Rust, delegating to browser APIs like:

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.js

Otherwise, 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::read or Dir::read_sync.
File
An object providing access to an open file on the filesystem.
Metadata
Metadata about a filesystem entry.
OpenOptions
Options and flags which can be used to configure how a file is opened.
ReadStream
A readable byte stream. Dropping it destroys the stream.
ReadStreamOptions
Options for a streaming read. end is an inclusive byte offset.
StatFs
Information about the filesystem containing a path.
TempDir
A temporary directory removed when this value is dropped.
WatchFileOptions
Options for polling changes to a file’s metadata.
WatchOptions
Options for watching file or directory changes.
Watcher
A filesystem watcher returned by fs::watch.
WriteStream
A writable byte stream. Call WriteStream::end to finish writing.
WriteStreamOptions
Options for a streaming write. ZenFS’s createWriteStream always opens with w, truncating the file before applying start.

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 recursive is true.
mkdir_sync
Creates a directory, creating missing parent directories when recursive is 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 to already exists.
rename_sync
Renames a file or directory to a new name, replacing the original file if to already 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_file listeners for a path.
unwatch_file_listener
Stops one watch_file listener by the ID returned from watch_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.

Type Aliases§

Error
The error type returned by filesystem operations on native platforms.
Result
The result type returned by filesystem operations.