ZenFS Core

The Internal API is the foundational interface used to manage file systems and file operations within ZenFS. It ensures that all backends are compatible with the Virtual File System (VFS) and any applications built on top of ZenFS.

To create a compatible backend, you must instantiate a FileSystem implementation that conforms to this API. This abstraction allows the VFS to interact with diverse storage backends (like in-memory, cloud storage, or local disk) using a standardized set of operations.

Each filesystem maintains a VCache to track its vnodes, modeled after Linux's dcache and icache.

Key Mechanics:

• Keying: Vnodes are keyed by ino (inode number), meaning hard links naturally share a single vnode.
• Lifecycle: Vnodes are reference-counted using ref and unref. A vnode remains in the cache as long as it is either referenced (e.g., an open file) or dirty (contains unsynced changes). Once both conditions are met, it is evicted.
• Path Index: A separate index is maintained for path lookups and is updated during rename, link, and unlink operations.
• Authoritative Reads: When performing a stat operation, the VFS checks the cache first. A cached vnode's inode takes precedence over the backend if the vnode is dirty.

const stats = cacheOf(fs).get(path)?.inode ?? fs.statSync(path);

Important Security Warning

Since ZenFS exists purely client-side, it does not constitute a true security boundary. Security mechanisms like permissions enforcement and chroot are handled at the Virtual File System (VFS) level to ensure file operations comply with access control rules before interacting with backends, but they cannot protect against a malicious actor who has control over the client environment itself.

The Virtual File System (VFS) is an abstraction layer in ZenFS that emulates the Node.js node:fs API. It provides a unified interface for interacting with diverse storage backends (local filesystems, in-memory stores, cloud providers like Google Drive, etc.) by handling path resolution, mounting, and file system contexts.

Key responsibilities include:

• Path Translation: Converting user paths into normalized absolute paths and resolving them to the correct mounted backend.
• node:fs Emulation: Providing full type compatibility with Node.js's built-in file system module.
• Mount Management: Allowing multiple backends to be mounted simultaneously with support for hot-swapping and per-mount configurations.
• Contexts: Encapsulating operations within execution scopes to manage permissions and effectively chroot operations.

The FileSystem class is the central component of the internal API. It provides a unified interface for several critical responsibilities:

• Storage Abstraction: Defines how files and directories are represented within a specific backend.
• Usage Information (UsageInfo): Provides tracking for available storage capacity, block sizes, and inode counts.
• File Operations: Implements standard actions such as creating, reading, writing, and deleting files.
• Error Handling: Provides a standardized way to handle and report file system errors.
• Metadata Management: Provides metadata used by the VFS to identify and configure the file system.

ZenFS uses a modular system of backends to store and retrieve data. A backend is a storage engine (e.g., InMemory, Zip, IndexedDB).

To use specific storage, you must mount a backend to a path. You can manage these mounts using the configure or configureSingle functions.

When configuring a mount point, you can provide:

1. A Backend object (if it requires no options).
2. An object containing backend options and a backend property (the Backend object).
3. An existing FileSystem instance.

Multiple backends can be mounted simultaneously to different paths, allowing you to treat different storage types (like a Zip file and an IndexedDB instance) as part of a single unified filesystem tree.

ZenFS supports device files that follow Linux-like behavior. You can automatically enable standard devices (such as /dev/null and /dev/random) by setting the addDevices configuration option to true within the configure function.

await configure({
	mounts: {/* ... */},
	addDevices: true,
});

// Example usage of enabled devices:
fs.writeFileSync('/dev/null', 'Some data to be discarded');

const randomData = new Uint8Array(100);
const random = fs.openSync('/dev/random', 'r');
fs.readSync(random, randomData);
fs.closeSync(random);

When defining backends, ZenFS uses a specific pattern to ensure high-fidelity type errors and usability. If you are building a backend, follow this pattern:

1. Use as const satisfies Backend<FileSystem, Options> to enable the strictest possible type checking.
2. Use a type alias for the implementation object.
3. Export an interface that extends that type. This ensures that if a user misconfigures the backend, the TypeScript error message displays the clear interface name instead of the entire expanded object structure.
4. Export the implementation object using the interface type.

const _InMemory = {
	// ... implementation
} as const satisfies Backend<StoreFS<InMemoryStore>, { name?: string }>;

type _InMemory = typeof _InMemory;
export interface InMemory extends _InMemory {}
export const InMemory: InMemory = _InMemory;