velt/fs
API referenceFile system access, with Node's names, behavior and error messages. Every operation has an async form, which runs on the runtime's blocking pool so other tasks keep running, and a *Sync form, which blocks the calling thread. For a walkthrough, read the guide.
Exports
appendFile, blocking the calling thread.readFileReads a UTF-8 text file (EILSEQ if it is not valid UTF-8).readFileBytesReads a file's bytes.readFileBytesSyncreadFileBytes, blocking the calling thread.readFileSyncreadFile, blocking the calling thread.writeFileCreates or truncates the file.writeFileSyncwriteFile, blocking the calling thread.mkdirCreates the directory path (and with recursive its missing parents).mkdirSyncmkdir, blocking the calling thread.readDirEntry names (not paths), sorted.readDirEntriesEntries with their types, sorted by name: Node's readdir(path, { withFileTypes: true }).readDirEntriesSyncreadDirEntries, blocking the calling thread.readDirSyncreadDir, blocking the calling thread.copyFileCopies the file from to to, replacing a file at to.copyFileSynccopyFile, blocking the calling thread.existsNever throws: any failure to reach path reads as false.existsSyncexists, blocking the calling thread.removeRemoves a file, symlink or empty directory (with recursive, a directory and its contents).removeSyncremove, blocking the calling thread.renameRenames (moves) from to to, replacing a file at to.renameSyncrename, blocking the calling thread.lstatMetadata of path itself: a symlink is described, not followed.lstatSynclstat, blocking the calling thread.readlinkThe target of the symlink path, as stored in the link (EINVAL if it is not a link).readlinkSyncreadlink, blocking the calling thread.statMetadata of path, following symlinks.statSyncstat, blocking the calling thread.symlinkCreates a symlink at path pointing to target (relative to the link's directory).symlinkSyncsymlink, blocking the calling thread.openReadOpens path for chunked reading.openWriteCreates (or truncates, or with append extends) path for buffered writing.closeSyncCloses the file descriptor fd (Node's fs.closeSync).openSyncOpens path and returns its file descriptor (Node's fs.openSync).unlinkSyncRemoves the file path (Node's fs.unlinkSync; not a directory: EPERM or EISDIR).readSyncReads up to length bytes into buffer from byte offset on (Node's fs.readSync): at position in the file, or at the file's own position (which then advances) when position is left out, null or -1.writeSyncWrites length bytes of buffer from byte offset on (Node's fs.writeSync): at position in the file, or at the file's own position when position is left out, null or not a valid byte offset (at its end for a file opened to append).fdatasyncSyncFlushes the file's data to the disk (Node's fs.fdatasyncSync).fstatSyncThe metadata of the open file fd (Node's fs.fstatSync): its size, modification time and type, from the system's fstat.fsyncSyncFlushes the file's data and metadata to the disk (Node's fs.fsyncSync).ftruncateSyncSets the file's size to len bytes, cutting or extending it with zeros (Node's fs.ftruncateSync).MkdirOptionsThe options of mkdir.RemoveOptionsThe options of remove.DirentA directory entry from readDirEntries, as Node's fs.Dirent.StatsFile metadata, as Node's fs.Stats: from stat (which follows symlinks) or lstat (which describes a symlink itself).FileReaderA file open for reading.FileWriterA file open for writing, buffered (64 KiB).OpenWriteOptionsThe options of openWrite.Re-exported from velt/fs/files
async function appendFile(path: string, data: string): Promise<void>Appends, creating the file if needed.
Re-exported from velt/fs/files
function appendFileSync(path: string, data: string)appendFile, blocking the calling thread.
Re-exported from velt/fs/files
async function readFile(path: string): Promise<string>Reads a UTF-8 text file (EILSEQ if it is not valid UTF-8).
Re-exported from velt/fs/files
async function readFileBytes(path: string): Promise<u8[]>Reads a file's bytes.
Re-exported from velt/fs/files
function readFileBytesSync(path: string): u8[]readFileBytes, blocking the calling thread.
Re-exported from velt/fs/files
function readFileSync(path: string): stringreadFile, blocking the calling thread.
Re-exported from velt/fs/files
async function writeFile(path: string, data: string): Promise<void>Creates or truncates the file.
Re-exported from velt/fs/files
function writeFileSync(path: string, data: string)writeFile, blocking the calling thread.
Re-exported from velt/fs/dirs
async function mkdir(path: string, opts: MkdirOptions = {}): Promise<void>Creates the directory path (and with recursive its missing parents).
Re-exported from velt/fs/dirs
function mkdirSync(path: string, opts: MkdirOptions = {})mkdir, blocking the calling thread.
Re-exported from velt/fs/dirs
async function readDir(path: string): Promise<string[]>Entry names (not paths), sorted.
Re-exported from velt/fs/dirs
async function readDirEntries(path: string): Promise<Dirent[]>Entries with their types, sorted by name: Node's readdir(path, { withFileTypes: true }).
Faster than readDir plus a stat per entry, since the listing carries the types.
Re-exported from velt/fs/dirs
function readDirEntriesSync(path: string): Dirent[]readDirEntries, blocking the calling thread.
Re-exported from velt/fs/dirs
function readDirSync(path: string): string[]readDir, blocking the calling thread.
Re-exported from velt/fs/entries
async function copyFile(from: string, to: string): Promise<void>Copies the file from to to, replacing a file at to.
Re-exported from velt/fs/entries
function copyFileSync(from: string, to: string)copyFile, blocking the calling thread.
Re-exported from velt/fs/entries
async function exists(path: string): Promise<bool>Never throws: any failure to reach path reads as false.
Re-exported from velt/fs/entries
function existsSync(path: string): boolexists, blocking the calling thread.
Re-exported from velt/fs/entries
async function remove(path: string, opts: RemoveOptions = {}): Promise<void>Removes a file, symlink or empty directory (with recursive, a directory and its contents).
Re-exported from velt/fs/entries
function removeSync(path: string, opts: RemoveOptions = {})remove, blocking the calling thread.
Re-exported from velt/fs/entries
async function rename(from: string, to: string): Promise<void>Renames (moves) from to to, replacing a file at to.
Re-exported from velt/fs/entries
function renameSync(from: string, to: string)rename, blocking the calling thread.
Re-exported from velt/fs/metadata
async function lstat(path: string): Promise<Stats>Metadata of path itself: a symlink is described, not followed.
Re-exported from velt/fs/metadata
function lstatSync(path: string): Statslstat, blocking the calling thread.
Re-exported from velt/fs/metadata
async function readlink(path: string): Promise<string>The target of the symlink path, as stored in the link (EINVAL if it is not a link).
Re-exported from velt/fs/metadata
function readlinkSync(path: string): stringreadlink, blocking the calling thread.
Re-exported from velt/fs/metadata
async function stat(path: string): Promise<Stats>Metadata of path, following symlinks.
Re-exported from velt/fs/metadata
function statSync(path: string): Statsstat, blocking the calling thread.
Re-exported from velt/fs/metadata
async function symlink(target: string, path: string): Promise<void>Creates a symlink at path pointing to target (relative to the link's directory). On
Windows the link is a directory link when target is a directory, as in Node, and creating
one needs Developer Mode or administrator rights (EACCES otherwise).
Re-exported from velt/fs/metadata
function symlinkSync(target: string, path: string)symlink, blocking the calling thread.
Re-exported from velt/fs/stream
async function openRead(path: string): Promise<FileReader>Opens path for chunked reading.
Re-exported from velt/fs/stream
async function openWrite(
path: string,
opts: OpenWriteOptions = {},
): Promise<FileWriter>Creates (or truncates, or with append extends) path for buffered writing.
Re-exported from velt/fs/fd/open
function closeSync(fd: number)Closes the file descriptor fd (Node's fs.closeSync).
Re-exported from velt/fs/fd/open
function openSync(
path: string,
flags: string | number = "r",
mode: number = 0o666,
): numberOpens path and returns its file descriptor (Node's fs.openSync). flags is one of Node's
strings ("r", "r+", "w", "wx", "w+", "a", "ax", "a+", ... and the s
forms) or the system's O_* bits as a number; mode is the permission of a file it
creates (before the umask).
Re-exported from velt/fs/fd/open
function unlinkSync(path: string)Removes the file path (Node's fs.unlinkSync; not a directory: EPERM or EISDIR).
Re-exported from velt/fs/fd/read
function readSync(
fd: number,
buffer: u8[] | ArrayBufferView,
offset: number | null = 0,
length?: number | null,
position?: number | null,
): numberReads up to length bytes into buffer from byte offset on (Node's fs.readSync): at
position in the file, or at the file's own position (which then advances) when position
is left out, null or -1. Returns the number of bytes read, 0 at the end of the file.
offset defaults to 0 and length to the rest of the buffer; a number is coerced as Node
does (length truncated to a 32-bit integer, position validated strictly). buffer is a
u8[] (Node's Buffer), a typed array or a DataView; offset and length count bytes of
it. Velt's typed API takes positional arguments, not Node's (fd, buffer, options) object.
Re-exported from velt/fs/fd/write
function writeSync(
fd: number,
buffer: u8[] | ArrayBufferView | string,
offset: number | null = null,
length?: number | null,
position?: number | null,
): numberWrites length bytes of buffer from byte offset on (Node's fs.writeSync): at
position in the file, or at the file's own position when position is left out, null or
not a valid byte offset (at its end for a file opened to append). Returns the number of bytes
written. offset defaults to 0 and length to the rest of the buffer. buffer is a u8[]
(Node's Buffer), a typed array or a DataView; a string is written as UTF-8, and its third
argument is then the position.
Re-exported from velt/fs/fd/sync
function fdatasyncSync(fd: number)Flushes the file's data to the disk (Node's fs.fdatasyncSync).
Re-exported from velt/fs/fd/sync
function fstatSync(fd: number): StatsThe metadata of the open file fd (Node's fs.fstatSync): its size, modification time and
type, from the system's fstat.
Re-exported from velt/fs/fd/sync
function fsyncSync(fd: number)Flushes the file's data and metadata to the disk (Node's fs.fsyncSync).
Re-exported from velt/fs/fd/sync
function ftruncateSync(fd: number, len: number = 0)Sets the file's size to len bytes, cutting or extending it with zeros (Node's fs.ftruncateSync).
Re-exported from velt/fs/dirs
The options of mkdir.
| Field | Type | Description |
|---|---|---|
| recursive? | bool | Create missing parents; an existing directory is then not an error. |
Re-exported from velt/fs/entries
The options of remove.
Parameter ofremoveremoveSync
| Field | Type | Description |
|---|---|---|
| recursive? | bool | Remove a directory and everything in it (otherwise only files, symlinks, empty dirs). |
Re-exported from velt/fs/dirent
A directory entry from readDirEntries, as Node's fs.Dirent. Its type comes with the listing
(no stat per entry) and describes the entry itself: a symlink is isSymbolicLink(), whatever
it points to.
Returned byreadDirEntriesreadDirEntriesSync
| Field | Type | Description |
|---|---|---|
| name | string | The entry's name (not a path). |
isFile(): boolTrue for a regular file.
isDirectory(): boolTrue for a directory.
isSymbolicLink(): boolTrue for a symbolic link (not followed).
Re-exported from velt/fs/stats
File metadata, as Node's fs.Stats: from stat (which follows symlinks) or lstat (which
describes a symlink itself). The field order is the runtime's VeltStat layout
{ u64 size; f64 mtime_ms; u8 is_file; u8 is_dir; u8 is_symlink }, so results are used without
conversion.
Returned byfstatSynclstatlstatSyncstatstatSync
| Field | Type | Description |
|---|---|---|
| size | u64 | Size in bytes (of a symlink from lstat: the length of its target path). |
| mtimeMs | f64 | Last modification, in milliseconds since the Unix epoch (0 if unavailable). |
isFile(): boolTrue for a regular file.
isDirectory(): boolTrue for a directory.
isSymbolicLink(): boolTrue for a symbolic link: only ever from lstat, since stat follows links.
Re-exported from velt/fs/file_reader
A file open for reading.
Returned byopenRead
async read(max: u64 = 0): Promise<u8[]>The next 1..max bytes; empty at end of file (max 0 = up to 64 KiB).
async readString(max: u64 = 0): Promise<string>The next chunk as UTF-8 text ("" at end of file); a character split between chunks is completed by the next call.
async readLine(): Promise<string | null>The next line without "\n" / "\r\n", or null at end of file. Don't mix with readString.
async * lines(): AsyncGenerator<string, IoError>The remaining lines, as readLine reads them: for await (const line of r.lines()).
Leaving the loop early keeps the reader open at the next line.
close()Closes the file (reads in flight finish first).
Re-exported from velt/fs/file_writer
A file open for writing, buffered (64 KiB).
Returned byopenWrite
async write(data: string): Promise<void>Writes data as UTF-8 (buffered).
async writeBytes(data: u8[]): Promise<void>Writes data (buffered).
async flush(): Promise<void>Pushes buffered data to the operating system.
async close(): Promise<void>Flushes and closes the file, then releases the handle; throws if the final flush fails.
Re-exported from velt/fs/stream
The options of openWrite.
Parameter ofopenWrite
| Field | Type | Description |
|---|---|---|
| append? | bool | Append to the file instead of truncating it. |