nx.fs

nx.fs.stat(path)

nx.fs.stat(path) -> promise of { type, size, mtime, atime, mode } (follows links)

_{Defined in fs.lua.}

nx.fs.lstat(path)

nx.fs.lstat(path) -> like stat but does NOT follow a symlink (type may be “link”).

_{Defined in fs.lua.}

nx.fs.exists(path)

nx.fs.exists(path) -> promise of a boolean. The one op that never rejects: a missing path (or any error) resolves false. Existence of the entry itself, so a dangling symlink is true. (The exists job resolves a bool rather than rejecting, so no reject-to-false mapping is needed in the wrapper.)

_{Defined in fs.lua.}

nx.fs.readdir(path)

nx.fs.readdir(path) -> promise of { { name=, type=“file”|“directory”|“link” }, … }, the entries directly under path (no “.”/“..”), each with its dirent kind in the SAME call (no per-entry stat). type is lstat-flavoured (a symlink reports “link”).

_{Defined in fs.lua.}

nx.fs.walk(dir, opts)

nx.fs.walk(dir[, opts]) -> promise of a LIST of file paths relative to dir, a recursive directory listing built from readdir. The transport-agnostic file enumeration the codebase reaches for when rg/fd aren’t available (the pure web client, where a spawn has no real shell) — it rides the same off-tick fs seam as every other nx.fs op, so it works against local disk, a daemon, and OPFS alike. opts: max cap on files returned (default 50000) — a runaway guard on huge trees hidden include dotfiles / dotdirs (default false) skip set of directory basenames to prune (default { [“.git”] = true }) An unreadable subdirectory is skipped (not fatal). MUST be awaited inside nx.async.

_{Defined in fs.lua.}

nx.fs.grep(dir, query, opts)

nx.fs.grep(dir, query[, opts]) -> promise of a LIST of matches, each { path = <rel>, row = <1-based lnum>, col = <1-based>, text = <line> }: a recursive, transport-agnostic plain-substring search. The fallback the grep picker reaches for when rg/grep aren’t available (the pure web client) — it rides the same off-tick fs seam as every other nx.fs op, so it works against local disk, a daemon, and OPFS. Walks dir (nx.fs.walk), reads each file (nx.fs.read_text), and matches query as a LITERAL substring per line. Binary / unreadable files (read_text rejects) are skipped. opts pass through to nx.fs.walk (max / hidden / skip). MUST be awaited inside nx.async.

_{Defined in fs.lua.}

nx.fs.read(path)

nx.fs.read(path) -> promise of the file’s RAW bytes (a Lua byte-string).

_{Defined in fs.lua.}

nx.fs.read_text(path, opts)

nx.fs.read_text(path[, { encoding = “utf-8” }]) -> promise of decoded text. Decodes through the encoding seam and REJECTS (EILSEQ) on invalid input — never lossy replacement text. Use nx.fs.read for raw bytes.

_{Defined in fs.lua.}

nx.fs.write(path, data)

nx.fs.write(path, data) -> promise (resolves nil). Truncates / creates.

_{Defined in fs.lua.}

nx.fs.append(path, data)

nx.fs.append(path, data) -> promise (resolves nil). Creates if absent.

_{Defined in fs.lua.}

nx.fs.mkdir(path, opts)

nx.fs.mkdir(path[, { recursive = false, mode = 0o755 }]) -> promise (resolves nil). mode is the Unix permission bits applied to every directory created (defaults to 0o755 in Rust when omitted; ignored off Unix) — pass it to keep a private data/state dir from being created world-readable.

_{Defined in fs.lua.}

nx.fs.rename(from, to)

nx.fs.rename(from, to) -> promise (resolves nil).

_{Defined in fs.lua.}

nx.fs.remove(path, opts)

nx.fs.remove(path[, { recursive = false }]) -> promise (resolves nil). A file is unlinked; a directory needs recursive unless already empty.

_{Defined in fs.lua.}

nx.fs.copy(src, dst, opts)

nx.fs.copy(src, dst[, { recursive = false }]) -> promise (resolves nil). A file copies (overwriting); a directory needs recursive.

_{Defined in fs.lua.}

nx.fs.realpath(path)

nx.fs.realpath(path) -> promise of the canonical absolute path (symlinks resolved).

_{Defined in fs.lua.}

nx.fs.watch(path, opts)

No documentation comment in the prelude.

_{Defined in fs.lua.}