Guide Manual Packages Playground

@std/fs

API Reference

class File

Buffered OS file handle with a cursor. Open with `open` or `create` and always `close` what you open. A refused open gives `isOpen == false` instead of throwing; every other fallible operation answers `Result`.

init(handle: Int, path: String)

fields

  • handle: Int
  • isOpen: Bool
  • path: String
fn close()

Release the handle and mark isOpen false. Closing twice is safe.

fn create(path: String, mode: WriteMode): File

Create or open a file for writing.

path — file to create.

mode — `.CreateNew` fails when the file exists, `.Create` keeps existing content, `.Overwrite` truncates, `.Append` writes at the end.

returns — handle whose isOpen is false when the OS refused the create.

fn flush()

Flush buffered writes to the OS. No-op when closed.

fn fromHandle(fd: Int, label: String, mode: OpenMode): File

Wrap an already-open descriptor without opening a path.

fd — descriptor number, 0, 1, or 2 for the standard streams.

label — handle name used in errors, such as "stdin".

mode — `.Read`, `.Write`, `.Append`, or `.ReadWrite`, used for the read/write checks only.

returns — handle whose isOpen is false when the descriptor is bad. The handle never owns the descriptor: `close()` detaches from it while descriptors 0, 1, and 2 stay usable, and a second `close()` is a no-op. No path guard applies since descriptors are not paths.

fn len(): Result<Int, String>

File length in bytes, flushed before measuring.

returns — Ok(length), Err(message) when closed or stat fails.

fn lockSync()

Take the advisory lock for this path, blocking until it is free. The lock is shared by every handle on the same path across threads; it is not reentrant, so the holding thread must not lock twice. Ids hash the path into a shared range, so unrelated paths can rarely share an id and over-serialize; never rely on it for safety.

fn open(path: String, mode: OpenMode): File

Open a file.

path — file to open.

mode — `.Read`, `.Write`, `.Append`, or `.ReadWrite`.

returns — handle whose isOpen is false when the OS refused the open.

fn readBytes(buf: ByteBuffer, offset: Int, len: Int): Result<Int, String>

Read raw bytes at the cursor into a buffer.

buf — destination buffer.

offset — first buffer byte to fill, defaults to 0.

len — bytes to read, defaults to the rest of the buffer (-1).

returns — Ok(bytes read, 0 on EOF), Err(message) when closed.

fn readText(): Result<String, String>

Read the whole remaining content as text, from the cursor to the end.

returns — Ok(content), Err(message) when the handle is closed or not open for reading (a write-only handle answers Err, never traps).

fn seek(pos: Int): Result<Int, String>

Move the cursor to an absolute byte position.

pos — byte offset from the start of the file, never negative.

returns — Ok(pos) after repositioning, Err(message) otherwise.

fn sync(): Result<Bool, String>

Flush buffered writes and force the OS to durable storage.

returns — Ok(true) once durable, Err(message) otherwise.

fn tell(): Int

Current cursor position in bytes, or -1 when the handle is closed.

returns — byte offset from the start of the file.

fn truncate(n: Int): Result<Bool, String>

Resize the file, padding with zeros when growing.

n — new length in bytes, never negative.

returns — Ok(true) after resizing, Err(message) otherwise.

fn tryLockSync(): Bool

Take the advisory lock for this path only when it is free.

returns — true when this call took the lock, false when another handle holds it. Unlock only when this returns true.

fn unlockSync()

Release the advisory lock taken by `lockSync` or `tryLockSync`.

fn writeBytes(buf: ByteBuffer, offset: Int, len: Int): Result<Int, String>

Write raw buffer bytes at the cursor.

buf — source buffer.

offset — first buffer byte to write, defaults to 0.

len — bytes to write, defaults to the rest of the buffer (-1).

returns — Ok(bytes written), Err(message) when the handle is closed.

fn writeText(text: String): Result<Int, String>

Write text at the cursor.

text — content to write.

returns — Ok(bytes written), Err(message) when the handle is closed.

class FileStat

Metadata snapshot for one path, as reported by `stat`. A symlink reports itself, not its target: `isLink` is true and `size` is the length of the stored target path.

init(size: Int, isFile: Bool, isDir: Bool, isLink: Bool, modified: Int, mode: Int)

fields

  • isDir: Bool
  • isFile: Bool
  • isLink: Bool
  • mode: Int
  • modified: Int
  • size: Int
class FsBytesReq

Request bundle for one pooled byte read.

init(path: String, wr: PromiseWithResolvers<Result<ByteBuffer, String>>)

fields

  • path: Any
  • wr: Any
class FsCopyReq

Request bundle for one pooled copy.

init(src: String, dst: String, mode: Int, wr: PromiseWithResolvers<Result<Bool, String>>)

fields

  • dst: Any
  • mode: Int
  • src: Any
  • wr: Any
class FsDirReq

Request bundle for one pooled directory listing or glob.

init(path: String, wr: PromiseWithResolvers<Result<Array<String>, String>>)

fields

  • path: Any
  • wr: Any
class FsMoveReq

Request bundle for one pooled move or rename.

init(src: String, dst: String, wr: PromiseWithResolvers<Result<Bool, String>>)

fields

  • dst: Any
  • src: Any
  • wr: Any
class FsStatReq

Request bundle for one pooled stat call.

init(path: String, wr: PromiseWithResolvers<Result<FileStat, String>>)

fields

  • path: Any
  • wr: Any
class FsTextReq

Request bundle for one pooled text read. The pool worker receives the whole bundle through the readText channel, so arguments and the settling handle travel together and concurrent calls cannot interleave. Fields stay Any because a concrete heap-typed field needs a native field release the backends cannot build for generic payloads.

init(path: String, wr: PromiseWithResolvers<Result<String, String>>)

fields

  • path: Any
  • wr: Any
class FsWriteBytesReq

Request bundle for one pooled byte write. Bytes travel as an array because a native buffer handle cannot cross threads by itself.

init(path: String, data: Array<Int>, mode: Int, wr: PromiseWithResolvers<Result<Int, String>>)

fields

  • data: Any
  • mode: Int
  • path: Any
  • wr: Any
class FsWriteTextReq

Request bundle for one pooled text write.

init(path: String, text: String, mode: Int, wr: PromiseWithResolvers<Result<Int, String>>)

fields

  • mode: Int
  • path: Any
  • text: Any
  • wr: Any
class Mmap

Live memory mapping of a file or of anonymous pages. Build one with `mmap` for a file or `mmapAnon` for blank pages, then take the raw start with `address()` inside `unsafe` and hand it to `Pointer.fromAddress<Byte>`. Writes through a `.ReadWrite` file map reach the file once `flush()` runs. The address stays valid until `close()`. Closing unmaps the region, so every address taken from it must be forgotten first: using one afterwards reads or writes freed memory. `close()` twice is safe, `flush()` on a closed map does nothing, and `address()` on a closed map answers 0. The mapped length is fixed at build time and stays readable through `len()` after `close()`. A file map tracks the file it was built from. When another process truncates the file below a page the program then touches, the fault is not catchable: the OS delivers SIGBUS on POSIX (an access violation on Windows), which no `Result` and no `catch` can cover. Size the file before mapping it and never truncate a mapped file. WebAssembly has no mapping support: `mmap` and `mmapAnon` both answer Err("mmap is not supported on this target") there.

init(handle: Int, length: Int)

fields

  • handle: Int
  • isOpen: Bool
  • length: Int
fn address(): Int

Raw address of the first mapped byte, for `Pointer.fromAddress` inside `unsafe` blocks. The map must outlive every pointer made from it, and the address must be forgotten before `close()`.

returns — address of byte 0, or 0 when the map is closed.

fn close()

Unmap the region and mark isOpen false. Closing twice is safe. Every address from `address()` must be forgotten first.

fn flush()

Write dirty pages back to the file. No-op when closed, and a no-op for read-only and anonymous maps, which have nothing to write back.

fn len(): Int

Mapped length in bytes, as fixed when the map was built.

returns — byte count covered by the map.

class Path

Path strings plus read-only filesystem queries. The string helpers are pure; only exists(), isFile(), and isDir() touch the filesystem.

fn base(p: String): String

Final segment of a path, with trailing slashes ignored.

p — path to inspect.

returns — file or directory name, "/" for the root, "" for empty input.

fn dir(p: String): String

Directory holding a path, with trailing slashes ignored.

p — path to inspect.

returns — parent directory, "/" for a top-level absolute path, "." when the path holds no separator.

fn exists(p: String): Bool

True when a path exists on the filesystem.

p — path to probe.

returns — true for any existing file, directory, or live link.

fn ext(p: String): String

Extension of a path, including the leading dot.

p — path to inspect.

returns — suffix from the last dot in the final segment (".txt"), or "" when the name has no dot past its first character.

fn isAbs(p: String): Bool

True for absolute paths starting with "/".

p — path to inspect.

returns — true when p names from the filesystem root.

fn isDir(p: String): Bool

True when a path is a directory.

p — path to probe.

returns — true for a directory, false otherwise.

fn isFile(p: String): Bool

True when a path is a regular file.

p — path to probe.

returns — true for a regular file, false for missing paths and links.

fn join(a: String, b: String): String

Join two path segments with a separator.

a — parent segment, may be empty.

b — child segment, may be empty.

returns — a + "/" + b, or whichever side is non-empty.

enum CopyMode
  • Overwrite
  • SkipExisting
enum OpenMode
  • Append
  • Read
  • ReadWrite
  • Write
enum WriteMode
  • Append
  • Create
  • CreateNew
  • Overwrite

Functions

fn chmod(path: String, mode: Int): Result<Bool, String>

Set Unix permission bits such as 493 (`0o755`).

path — file to change.

mode — permission bits.

returns — Ok(true) on success, Err(message) otherwise.

fn copy(src: String, dst: String, mode: CopyMode): Result<Bool, String>

Copy one file.

from — source file.

to — destination file.

mode — `.Overwrite` replaces the destination, `.SkipExisting` keeps it and reports success without copying.

returns — Ok(true) on success, Err(message) otherwise.

fn copyAsync(src: String, dst: String, mode: CopyMode): Promise<Result<Bool, String>>

Copy one file on the fs pool.

from — source file.

to — destination file.

mode — `.Overwrite` replaces the destination, `.SkipExisting` keeps it and reports success without copying.

returns — pending promise settling with Ok(true) or Err(message).

fn exists(path: String): Bool

True when a path exists, false for anything missing.

path — path to probe.

returns — true when the path exists.

fn fileLockId(path: String): Int

Registry slot for the advisory lock on one path. Every handle opened on the same path hashes to the same slot, so `lockSync` on one handle excludes `tryLockSync` on another. Slots live in the high id range to stay clear of hand-picked `@std/sync` ids.

path — file whose lock slot to compute.

returns — stable non-negative registry id for the path.

fn fsPoolSize(): Int

Worker count the fs pool was sized with, 0 when never sized. Internal: `fsWorkers` fills it on first use, `setWorkers` sets it.

returns — live pool size, or 0 before the first async call.

fn fsWorkers(): Int

Worker count for the next pool ensure. The first call measures the machine with `__rnx_os_cpu_count` and clamps into 1..8.

returns — worker count between 1 and 8.

fn fsWriteModeOf(m: Int): WriteMode

Map a stored write mode back onto `WriteMode`.

m — 0 CreateNew, 1 Create, 2 Overwrite, anything else Append.

returns — the matching mode.

fn fsync(path: String): Result<Bool, String>

Flush file content to durable storage.

path — file to sync.

returns — Ok(true) on success, Err(message) otherwise.

fn glob(pattern: String): Result<Array<String>, String>

Paths matching a pattern, sorted for deterministic builds. Supports `*` and `?` within a path component and `**` for any depth of directories. A pattern with no match gives an empty array.

pattern — glob such as `src/*.rnx`.

returns — Ok(paths) sorted lexicographically, Err(message) on misuse.

fn globAsync(pattern: String): Promise<Result<Array<String>, String>>

Paths matching a pattern on the fs pool, sorted for deterministic builds. Supports `*` and `?` within a path component and `**` for any depth of directories.

pattern — glob such as `src/*.rnx`.

returns — pending promise settling with Ok(paths) or Err(message).

fn isDir(path: String): Bool

True when a path is a directory.

path — path to probe.

returns — true for a directory, false otherwise.

fn isFile(path: String): Bool

True when a path is a regular file.

path — path to probe.

returns — true for a regular file, false for missing paths and links.

fn mkdir(path: String): Result<Bool, String>

Create one directory, failing when the parent is missing.

path — directory to create.

returns — Ok(true) on success, Err(message) otherwise.

fn mkdirAll(path: String): Result<Bool, String>

Create a directory and every missing parent.

path — directory to create.

returns — Ok(true) on success, Err(message) otherwise.

fn mmap(path: String, mode: OpenMode): Result<Mmap, String>

Map a whole file into memory. `.Read` gives a read-only view, `.ReadWrite` a writable one; the other modes behave as `.ReadWrite`. The file must exist and must not be empty: size it with `writeText`, `writeBytes`, or `truncate` first. A writable map of a protected path traps with S301. When another process truncates the file below a page the program then touches, the fault is not catchable: the OS delivers SIGBUS on POSIX (an access violation on Windows), which no `Result` and no `catch` can cover. Never truncate a mapped file.

path — file to map.

mode — `.Read` for a read-only view, `.ReadWrite` for writes.

returns — Ok(map) on success, Err(message) otherwise.

fn mmapAnon(len: Int): Result<Mmap, String>

Map anonymous zeroed pages, backed by nothing on disk.

len — byte count to map, must be positive.

returns — Ok(map) covering len zeroed bytes, Err(message) otherwise.

fn move(src: String, dst: String): Result<Bool, String>

Move a file, falling back to copy plus remove across filesystems.

from — source path.

to — destination path.

returns — Ok(true) on success, Err(message) otherwise.

fn moveAsync(src: String, dst: String): Promise<Result<Bool, String>>

Move a file on the fs pool, falling back to copy plus remove across filesystems.

from — source path.

to — destination path.

returns — pending promise settling with Ok(true) or Err(message).

fn readBytes(path: String): Result<ByteBuffer, String>

Read a whole file as bytes.

path — file to read.

returns — Ok(buffer) on success, Err(message) when missing.

fn readBytesAsync(path: String): Promise<Result<ByteBuffer, String>>

Read a whole file as bytes on the fs pool.

path — file to read.

returns — pending promise settling with Ok(buffer) or Err(message).

fn readDir(path: String): Result<Array<String>, String>

Entry names inside a directory, sorted for deterministic builds.

path — directory to list.

returns — Ok(names) sorted lexicographically, Err(message) when unreadable.

fn readDirAsync(path: String): Promise<Result<Array<String>, String>>

Entry names inside a directory on the fs pool, sorted for deterministic builds.

path — directory to list.

returns — pending promise settling with Ok(names) or Err(message).

fn readText(path: String): Result<String, String>

Read a whole file as text.

path — file to read.

returns — Ok(content) on success, Err(message) when missing.

fn readTextAsync(path: String): Promise<Result<String, String>>

Read a whole file as text on the fs pool.

path — file to read.

returns — pending promise settling with Ok(content) or Err(message).

fn remove(path: String): Result<Bool, String>

Remove one file, symlink, or empty directory.

path — file or empty directory to remove.

returns — Ok(true) when something was removed, Ok(false) when the path was already missing, Err(message) otherwise.

fn removeAll(path: String): Result<Bool, String>

Remove a file or a directory tree.

path — file or directory to remove with all its content.

returns — Ok(true) when something was removed, Ok(false) when the path was already missing, Err(message) otherwise.

fn rename(src: String, dst: String): Result<Bool, String>

Rename a file without cross-filesystem fallback.

from — source path.

to — destination path.

returns — Ok(true) on success, Err(message) otherwise.

fn renameAsync(src: String, dst: String): Promise<Result<Bool, String>>

Rename a file on the fs pool without cross-filesystem fallback.

from — source path.

to — destination path.

returns — pending promise settling with Ok(true) or Err(message).

fn setWorkers(n: Int): Int

Resize the process-wide fs pool, clamped into 1..8. The default is the CPU count capped at 8. Call it only when no async operation is in flight: resizing stops the old pool, so anything still queued never runs and its promise never settles.

n — desired worker count, clamped into 1..8.

returns — the clamped count the pool was sized with.

fn stat(path: String): Result<FileStat, String>

Metadata for a path.

path — file or directory to inspect.

returns — Ok(stat) on success, Err(message) when the path is missing.

fn statAsync(path: String): Promise<Result<FileStat, String>>

Metadata for a path on the fs pool.

path — file or directory to inspect.

returns — pending promise settling with Ok(stat) or Err(message).

fn truncate(path: String, len: Int): Result<Bool, String>

Resize a file, padding with zeros when growing.

path — file to resize.

len — new length in bytes, never negative.

returns — Ok(true) on success, Err(message) otherwise.

fn writeBytes(path: String, buf: ByteBuffer, mode: WriteMode): Result<Int, String>

Write a whole file from a byte buffer.

path — file to write.

buf — content to store.

mode — `.CreateNew` fails when the file exists, `.Create` keeps existing content past the write, `.Overwrite` truncates, `.Append` writes at the end.

returns — Ok(bytes written) on success, Err(message) otherwise.

fn writeBytesAsync(path: String, buf: ByteBuffer, mode: WriteMode): Promise<Result<Int, String>>

Write a whole file from a byte buffer on the fs pool.

path — file to write.

buf — content to store.

mode — `.CreateNew` fails when the file exists, `.Create` keeps existing content past the write, `.Overwrite` truncates, `.Append` writes at the end.

returns — pending promise settling with Ok(bytes written) or Err(message).

fn writeText(path: String, text: String, mode: WriteMode): Result<Int, String>

Write a whole file from text.

path — file to write.

text — content to store.

mode — `.CreateNew` fails when the file exists, `.Create` keeps existing content past the write, `.Overwrite` truncates, `.Append` writes at the end.

returns — Ok(bytes written) on success, Err(message) otherwise.

fn writeTextAsync(path: String, text: String, mode: WriteMode): Promise<Result<Int, String>>

Write a whole file from text on the fs pool.

path — file to write.

text — content to store.

mode — `.CreateNew` fails when the file exists, `.Create` keeps existing content past the write, `.Overwrite` truncates, `.Append` writes at the end.

returns — pending promise settling with Ok(bytes written) or Err(message).