zena:fs
zena
import {…} from 'zena:fs';
File system operations: reading, writing, querying metadata, and directory traversal.
In WebAssembly environments, filesystem access is restricted to preopened
directories provided by the host runtime. High-level functions such as
readFile, writeFile, and readDir operate relative to the default
preopened directory. getPreopens() and Descriptor allow explicit access
to multiple preopened directories.
Examples
zena
import { readFile, writeFile, exists } from 'zena:fs';
writeFile('example.txt', 'Hello, Zena!');
if (exists('example.txt')) {
let content = readFile('example.txt');
}
Classes
FsError
zena
class FsError extends Error
Constructors
zena
new(errno: i32, message: String)
Descriptor
zena
class Descriptor
A handle for an open file or directory.
Descriptors are obtained either from getPreopens() (for preopened
directories) or by opening files/directories relative to an existing
descriptor using openAt() or createAt().
In WASI's capability model, a Descriptor acts as a capability token - you can only access files that are reachable from a Descriptor you already have.
Always call close() when done to release the underlying resource.
Constructors
zena
new(fd: i32)
Properties
zena
fd: i32 { get; }
Methods
zena
readAllBytes(): ByteArray
zena
readString(): String
zena
writeBytes(data: ByteArray): void
zena
writeString(data: String): void
zena
openAt(path: String, flags: DescriptorFlags): Descriptor
zena
createAt(path: String): Descriptor
zena
stat(): FileStat
zena
statAt(path: String): FileStat
zena
readDir(): Array<DirEntry>
zena
mkdirAt(path: String): void
zena
unlinkAt(path: String): void
zena
rmdirAt(path: String): void
zena
close(): void
GlobOptions
zena
class GlobOptions
Options for directory globbing.
Enums
FsErrorCode
zena
enum FsErrorCode
FileType
zena
enum FileType
OpenFlags
DescriptorFlags
Type aliases
FileStat
zena
type FileStat = {fileType: FileType, size: i64, modified: i64}
DirEntry
zena
type DirEntry = {name: String, fileType: FileType}
When the contents last changed, in nanoseconds since the Unix epoch.
Functions
getPreopens
zena
function getPreopens(): Array<(Descriptor, String)>
Returns all preopened directories granted to this WASM module.
Preopened directories are the ONLY filesystem locations this program can
access. They are granted by the host environment at startup (e.g., via
wasmtime's --dir flag).
Each entry is a tuple of [Descriptor, path] where:
Descriptoris a handle for filesystem operations within that directorypathis the guest path (e.g., "/tmp", "/data", or "." for current dir)
Returns an empty array if no directories were preopened (the program has no filesystem access).
getRootDir
zena
function getRootDir(): Descriptor
Returns the first preopened directory, used as the "root" for high-level file operations.
This is typically the current working directory (".") or the first --dir
flag passed to the WASI runtime.
readFile
zena
function readFile(path: String): String
readFileBytes
zena
function readFileBytes(path: String): ByteArray
Reads the entire contents of a file as raw bytes.
The path is relative to the first preopened directory.
writeFile
zena
function writeFile(path: String, content: String): void
Writes a string to a file as UTF-8, creating or truncating the file.
The path is relative to the first preopened directory.
writeFileBytes
zena
function writeFileBytes(path: String, content: ByteArray): void
Writes raw bytes to a file, creating or truncating the file.
The path is relative to the first preopened directory.
listDir
zena
function listDir(path: String): Array<DirEntry>
Lists the contents of a directory.
The path is relative to the first preopened directory. Use "." to list the root preopened directory itself.
exists
zena
function exists(path: String): boolean
Checks if a path exists (file or directory).
The path is relative to the first preopened directory.
isFile
zena
function isFile(path: String): boolean
Checks if a path is a regular file.
isDirectory
zena
function isDirectory(path: String): boolean
Checks if a path is a directory.
mkdir
zena
function mkdir(path: String): void
Creates a directory.
The path is relative to the first preopened directory. Parent directories must already exist.
unlink
zena
function unlink(path: String): void
Deletes a file.
The path is relative to the first preopened directory.
rename
zena
function rename(from: String, to: String): void
Renames a file or directory. When to is an existing file it is
replaced in one step, so a reader opening to sees either the old file
or the new one and never a partly written file. Writing to a temporary
name and renaming it into place relies on this.
stat
zena
function stat(path: String): FileStat
The type, size and modification time of a file or directory.
rmdir
zena
function rmdir(path: String): void
Deletes an empty directory.
The path is relative to the first preopened directory. The directory must be empty.
glob
zena
function glob(pattern: String, options: GlobOptions | null = null): Array<String>
Searches the filesystem for files and directories matching pattern.