fs

local fs = require("@lute/fs")

WARNING

These APIs are still open to future evolution. In new major versions, they may change in backwards incompatible ways.

Summary

Entry	Description
DirectoryEntry	A single entry returned by fs.listdir, containing the entry's name and type.
FileHandle	An open file handle returned by fs.open.
FileMetadata	Metadata about a filesystem entry, such as size, type, and timestamps.
FileType	The type of a filesystem entry:
HandleMode	How a file should be opened:
WatchEvent	A filesystem change event passed to the fs.watch callback.
WatchHandle	A handle to an active filesystem watcher, returned by fs.watch.
close	Closes handle, flushing any pending writes.
copy	Copies the file at src to dest.
exists	Returns true if a file or directory exists at path.
link	Creates a hard link at dest pointing to src.
listdir	Returns an array of DirectoryEntry values for the immediate children of the directory at path.
mkdir	Creates a directory at the specified path.
move	Moves the file or directory at src to dest.
open	Opens the file at path in the given mode (defaults to "r"). Returns a file handle.
read	Reads the full contents of handle and returns them as a string.
readIntoBuffer	Reads up to numBytes bytes from handle at fileOffset into buf starting at bufferOffset.
remove	Removes the file at path.
rmdir	Removes the directory at path.
stat	Returns metadata for the file or directory at path.
symlink	Creates a symbolic link at dest pointing to src.
type	Returns the FileType of the entry at path.
watch	Watches path for filesystem changes, calling callback with the filename and event on each change.
write	Writes contents to handle.

---

Types

DirectoryEntry

A single entry returned by fs.listdir, containing the entry's name and type.

type DirectoryEntry = {
	name: string,
	type: FileType,
}

---

FileHandle

An open file handle returned by fs.open.

type FileHandle = {
	fd: number,
	err: number,
}

---

FileMetadata

Metadata about a filesystem entry, such as size, type, and timestamps.

type FileMetadata = {
	type: FileType,
	permissions: { readonly: boolean },
	size: number,
	created: time.Duration,
	accessed: time.Duration,
	modified: time.Duration,
}

---

FileType

The type of a filesystem entry:

• "file": A regular file.

• "dir": A directory.

• "link": A symbolic link.

• "fifo": A named pipe (FIFO).

• "socket": A Unix domain socket.

• "char": A character device.

• "block": A block device.

• "unknown": An entry whose type could not be determined.

type FileType = "file" | "dir" | "link" | "fifo" | "socket" | "char" | "block" | "unknown"

---

HandleMode

How a file should be opened:

• "r": Open for reading. Fails if the file does not exist.

• "w": Open for writing; creates the file if absent, truncates it if present.

• "x": Open for exclusive creation. Fails if the file already exists.

• "a": Open for appending; creates the file if absent, writes go to the end.

• "r+": Open for reading and writing. Fails if the file does not exist.

• "w+": Open for reading and writing; creates the file if absent, truncates it if present.

• "x+": Open for reading and exclusive creation. Fails if the file already exists.

• "a+": Open for reading and appending; creates the file if absent, writes go to the end.

type HandleMode = "r" | "w" | "x" | "a" | "r+" | "w+" | "x+" | "a+"

---

WatchEvent

A filesystem change event passed to the fs.watch callback.

type WatchEvent = {
	change: boolean,
	rename: boolean,
}

---

WatchHandle

A handle to an active filesystem watcher, returned by fs.watch.

type WatchHandle = {
	close: (self: WatchHandle) -> (),
}

---

Functions and Properties

fs.close

Closes handle, flushing any pending writes.

(handle: FileHandle) -> ()

---

fs.copy

Copies the file at src to dest.

(src: string, dest: string) -> ()

---

fs.exists

Returns true if a file or directory exists at path.

(path: string) -> boolean

---

fs.link

Creates a hard link at dest pointing to src.

(src: string, dest: string) -> ()

---

fs.listdir

Returns an array of DirectoryEntry values for the immediate children of the directory at path.

(path: string) -> { DirectoryEntry }

---

fs.mkdir

Creates a directory at the specified path.

To set the permissions mode for a directory (Unix only), see @std/process for run or system to shell out to chmod or the equivalent.

(path: string) -> ()

---

fs.move

Moves the file or directory at src to dest.

Falls back to a copy-then-remove if src and dest are on different filesystems.

(src: string, dest: string) -> ()

---

fs.open

Opens the file at path in the given mode (defaults to "r"). Returns a file handle.

(path: string, mode: HandleMode?) -> FileHandle

---

fs.read

Reads the full contents of handle and returns them as a string.

(handle: FileHandle) -> string

---

fs.readIntoBuffer

Reads up to numBytes bytes from handle at fileOffset into buf starting at bufferOffset.

Returns the number of bytes actually read (may be less than count if EOF is reached).

• bufferOffset defaults to 0.

(handle: FileHandle, buf: buffer, fileOffset: number, numBytes: number, bufferOffset: number?) -> number

---

fs.remove

Removes the file at path.

(path: string) -> ()

---

fs.rmdir

Removes the directory at path.

(path: string) -> ()

---

fs.stat

Returns metadata for the file or directory at path.

(path: string) -> FileMetadata

---

fs.symlink

Creates a symbolic link at dest pointing to src.

(src: string, dest: string) -> ()

---

fs.type

Returns the FileType of the entry at path.

(path: string) -> FileType

---

fs.watch

Watches path for filesystem changes, calling callback with the filename and event on each change.

(path: string, callback: (filename: string, event: WatchEvent) -> ()) -> WatchHandle

---

fs.write

Writes contents to handle.

(handle: FileHandle, contents: string) -> ()

---