Driver Interface
FsDriver defines the driver API. Four small structural types support it.
import { S_IFDIR, S_IFMT, S_IFREG } from "mountx";
import type { DirentLike, FileHandleLike, FsDriver, StatsLike } from "mountx";For a complete driver that you can run, see Writing a driver.
#FsDriver
A driver must implement three methods. All other methods are optional. A missing method means that the related capability is not available.
interface FsDriver {
readonly capabilities?: FsCapabilities;
readonly mountx?: MountxExtensions;
// required
stat(path: string): Promise<StatsLike>;
readdir(path: string, options: { withFileTypes: true }): Promise<DirentLike[]>;
open(path: string, flags?: string | number, mode?: number): Promise<FileHandleLike>;
// optional
lstat?(path: string): Promise<StatsLike>;
statfs?(path: string): Promise<StatsFsLike>;
mkdir?(path: string, options?: MkdirOptions): Promise<string | undefined>;
rmdir?(path: string): Promise<void>;
unlink?(path: string): Promise<void>;
rename?(oldPath: string, newPath: string): Promise<void>;
link?(existingPath: string, newPath: string): Promise<void>;
symlink?(target: string, path: string, type?: string | null): Promise<void>;
readlink?(path: string): Promise<string>;
chmod?(path: string, mode: number): Promise<void>;
chown?(path: string, uid: number, gid: number): Promise<void>;
lchown?(path: string, uid: number, gid: number): Promise<void>;
truncate?(path: string, length?: number): Promise<void>;
utimes?(path: string, atime: TimeLike, mtime: TimeLike): Promise<void>;
lutimes?(path: string, atime: TimeLike, mtime: TimeLike): Promise<void>;
}Before the driver receives a path, mountx makes it absolute, normalized, and POSIX-style.
FullFsDriver has the same shape, but all optional methods are required. The memory and node-fs drivers implement FullFsDriver. node:fs/promises also implements it.
FsDriverMethod is the union of the optional method names.
See Capabilities for the two readonly members.
#Structural types
These types contain only the fields that transports need. Node's Stats, StatsFs, Dirent, and FileHandle already match them. You can return Node values without changing them.
#StatsLike
interface StatsLike {
dev: number;
ino: number;
mode: number; // S_IFMT type bits | permission bits
nlink: number;
uid: number;
gid: number;
rdev: number;
size: number;
blksize: number;
blocks: number;
atimeMs: number;
mtimeMs: number;
ctimeMs: number;
birthtimeMs: number;
isFile(): boolean;
isDirectory(): boolean;
isSymbolicLink(): boolean;
isBlockDevice(): boolean;
isCharacterDevice(): boolean;
isFIFO(): boolean;
isSocket(): boolean;
}#DirentLike
DirentLike contains { name: string; parentPath?: string } and the same seven file-type methods as StatsLike.
#StatsFsLike
StatsFsLike contains { type, bsize, blocks, bfree, bavail, files, ffree }. These fields support statfs(2) and df.
#FileHandleLike
interface FileHandleLike {
readonly fd?: number;
read(
buffer: Uint8Array,
offset?: number | null,
length?: number | null,
position?: number | null,
): Promise<{ bytesRead: number; buffer: Uint8Array }>;
write(
buffer: Uint8Array,
offset?: number | null,
length?: number | null,
position?: number | null,
): Promise<{ bytesWritten: number; buffer: Uint8Array }>;
stat(): Promise<StatsLike>;
truncate(length?: number): Promise<void>;
close(): Promise<void>;
sync?(): Promise<void>; // absent = nothing to flush
datasync?(): Promise<void>;
}The handles capability states whether a handle contains real per-open state. This capability is one of the four capabilities that mountx cannot infer.
#File-type constants
S_IFMT, S_IFREG, S_IFDIR, S_IFLNK, S_IFBLK, S_IFCHR, S_IFIFO, and S_IFSOCK are POSIX mode bits. Use them to create or inspect StatsLike.mode.
import { S_IFDIR, S_IFMT } from "mountx";
const isDirectory = (mode: number) => (mode & S_IFMT) === S_IFDIR;#Next
- Capabilities explains declarations and method-based inference.
- Errors explains which errors driver methods must throw.