fs

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

WARNING

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

Summary

Entry	Description
CreateDirectoryOptions	Options for createDirectory:
DirectoryEntry	A single entry returned by listDirectory, containing the entry's name and type.
File	An open file handle.
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:
RemoveDirectoryOptions	Options for removeDirectory:
WalkOptions	Options for walk:
WatchEvent	A filesystem change event, yielded by a Watcher.
WatchHandle	A handle to an active filesystem watcher, returned by watch.
close	Closes file, flushing any pending writes.
copy	Copies the file at src to dest.
createDirectory	Creates a directory at path. If options.makeParents is true, creates any missing parent directories as well.
exists	Returns true if a file or directory exists at path.
link	Creates a hard link at dest pointing to src.
listDirectory	Returns an array of DirectoryEntry values for the immediate children of the directory at path.
metadata	Returns metadata for the file or directory at 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 file and returns them as a string.
readFileToString	Returns the entire contents of the file at filepath as a string.
readIntoBuffer	Reads up to numBytes bytes from file at fileOffset into buf starting at bufferOffset.
remove	Removes the file at path.
removeDirectory	Removes the directory at path. If options.recursive is true, removes all contents first.
symbolicLink	Creates a symbolic link at dest pointing to src.
type	Returns the FileType of the entry at path (e.g. "file", "dir", "symlink").
walk	Returns an iterator over all paths under path. If options.recursive is true, descends into subdirectories.
watch	Watches path for filesystem changes. Returns a Watcher with a next method that returns the next
write	Writes contents to file.
writeStringToFile	Writes contents to the file at filepath, replacing any existing contents.

---

Types

CreateDirectoryOptions

Options for createDirectory:

• makeParents: If true, creates any missing parent directories. Defaults to false.

type CreateDirectoryOptions = {
	makeParents: boolean?,
}

---

DirectoryEntry

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

type DirectoryEntry = fs.DirectoryEntry

---

File

An open file handle.

type File = fs.FileHandle

---

FileMetadata

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

type FileMetadata = fs.FileMetadata

---

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 = fs.FileType

---

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 = fs.HandleMode

---

RemoveDirectoryOptions

Options for removeDirectory:

• recursive: If true, removes all contents of the directory before deleting it. Defaults to false.

type RemoveDirectoryOptions = {
	recursive: boolean?,
}

---

WalkOptions

Options for walk:

• recursive: If true, descends into subdirectories. Defaults to false.

type WalkOptions = {
	recursive: boolean?,
}

---

WatchEvent

A filesystem change event, yielded by a Watcher.

type WatchEvent = fs.WatchEvent

---

WatchHandle

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

type WatchHandle = fs.WatchHandle

---

Functions and Properties

fs.close

Closes file, flushing any pending writes.

(file: File) -> ()

---

fs.copy

Copies the file at src to dest.

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

---

fs.createDirectory

Creates a directory at path. If options.makeParents is true, creates any missing parent directories as well.

(path: Pathlike, options: CreateDirectoryOptions?) -> ()

---

fs.exists

Returns true if a file or directory exists at path.

(path: Pathlike) -> boolean

---

fs.link

Creates a hard link at dest pointing to src.

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

---

fs.listDirectory

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

(path: Pathlike) -> { DirectoryEntry }

---

fs.metadata

Returns metadata for the file or directory at path.

(path: Pathlike) -> FileMetadata

---

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: Pathlike, dest: Pathlike) -> ()

---

fs.open

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

(path: Pathlike, mode: HandleMode?) -> File

---

fs.read

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

(file: File) -> string

---

fs.readFileToString

Returns the entire contents of the file at filepath as a string.

(filepath: Pathlike) -> string

---

fs.readIntoBuffer

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

Returns the number of bytes actually read.

(file: File, buf: buffer, fileOffset: number, numBytes: number, bufferOffset: number?) -> number

---

fs.remove

Removes the file at path.

(path: Pathlike) -> ()

---

fs.removeDirectory

Removes the directory at path. If options.recursive is true, removes all contents first.

(path: Pathlike, options: RemoveDirectoryOptions?) -> ()

---

fs.symbolicLink

Creates a symbolic link at dest pointing to src.

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

---

fs.type

Returns the FileType of the entry at path (e.g. "file", "dir", "symlink").

(path: Pathlike) -> FileType

---

fs.walk

Returns an iterator over all paths under path. If options.recursive is true, descends into subdirectories.

See example/walk_directory.luau for usage.

(path: Pathlike, options: WalkOptions?) -> () -> Path?

---

fs.watch

Watches path for filesystem changes. Returns a Watcher with a next method that returns the next

WatchEvent, or nil if none is available, and a close method to stop watching.

Note: a while loop must be used rather than a for loop. See example/watch_directory.luau for usage.

(path: Pathlike) -> Watcher

---

fs.write

Writes contents to file.

(file: File, contents: string) -> ()

---

fs.writeStringToFile

Writes contents to the file at filepath, replacing any existing contents.

(filepath: Pathlike, contents: string) -> ()

---