File system operations and file handle I/O.

Use open() / openSync() to get a File handle with read, write, seek, truncate, and other operations. Most File methods yield by default; use the Sync suffix for non-yielding variants (e.g. readSync, writeSync).

Pure path manipulation lives under fs.path.*.

Summary

Classes

Functions

API Reference

Classes

File

Properties

path: string

The file path passed to open.

fd: number

The underlying file descriptor number.

isOpen: boolean

true if the file has not been closed.

readable: boolean

true if the file was opened for reading.

writable: boolean

true if the file was opened for writing.

File:read

⚠ Yields

Reads up to size bytes as a string. Pass nil to read remaining.

File:read(size: number?) → string

File:readSync

Reads up to size bytes as a string. Pass nil to read remaining.

File:readSync(size: number?) → string

File:readBuffer

⚠ Yields

Reads up to size bytes as a buffer. Pass nil to read remaining.

File:readBuffer(size: number?) → buffer

File:readBufferSync

Reads up to size bytes as a buffer. Pass nil to read remaining.

File:readBufferSync(size: number?) → buffer

File:write

⚠ Yields

Writes a string to the file, returns bytes written.

File:write(data: string) → number

File:writeSync

Writes a string to the file, returns bytes written.

File:writeSync(data: string) → number

File:writeBuffer

⚠ Yields

Writes a buffer to the file, returns bytes written.

File:writeBuffer(data: buffer) → number

File:writeBufferSync

Writes a buffer to the file, returns bytes written.

File:writeBufferSync(data: buffer) → number

File:seek

Moves the file cursor.

File:seek(offset: number, whence: ("set" | "cur" | "end")?) → number

Parameters

whence: ("set" | "cur" | "end")?

string: set is default if unspecified, and treats offset as an absolute position. cur treats offset as relative from the current position. end seeks relative to the end of the file.

Returns

number

number: The new file offset

File:tell

Returns the current file cursor position.

File:tell() → number

File:truncate

Truncates the file to size bytes, or at the current position if nil.

File:truncate(size: number?) → ()

File:size

Returns the file size in bytes.

File:size() → number

File:flush

⚠ Yields

Flushes buffered writes to disk.

File:flush() → ()

File:flushSync

Flushes buffered writes to disk.

File:flushSync() → ()

File:close

⚠ Yields

Closes the file. Yield is due to the implicit file flush.

File:close() → ()

File:closeSync

Closes the file.

File:closeSync() → ()

Functions

fs.open

⚠ Yields

Opens a file and returns a File handle. Mode: "r" (default), "w", "a", "r+", "w+", "a+".

fs.open(path: string, mode: string?) → File

fs.openSync

Opens a file and returns a File handle. Mode: "r" (default), "w", "a", "r+", "w+", "a+".

fs.openSync(path: string, mode: string?) → File

fs.exists

Returns true if the path exists on disk.

fs.exists(path: string) → boolean

fs.isFile

Returns true if the path is a regular file.

fs.isFile(path: string) → boolean

fs.isDirectory

Returns true if the path is a directory.

fs.isDirectory(path: string) → boolean

fs.mkdir

Creates a directory (and any missing parents). Returns true on success.

fs.mkdir(path: string) → boolean

fs.remove

Recursively removes a file or directory. Returns true on success.

fs.remove(path: string) → boolean

fs.rename

Atomically renames (moves) a file or directory.

fs.rename(oldPath: string, newPath: string) → ()

fs.copy

Copies a file or directory (recursively). Overwrites existing destinations.

fs.copy(src: string, dst: string) → ()

fs.listDir

Returns an array of filenames in the given directory.

fs.listDir(path: string) → { string }

fs.symlink

Creates a symlink at link pointing to target. type: "file" (default) or "directory". Auto-detected from target if omitted. On Windows, creating symlinks requires Developer Mode or administrator privileges.

fs.symlink(target: string, link: string, type: ("file" | "directory")?) → ()

fs.readlink

Reads the target of a symlink.

fs.readlink(path: string) → string

fs.isSymlink

Returns true if the path is a symbolic link (does not follow the link).

fs.isSymlink(path: string) → boolean

fs.stat

Returns file metadata. Set followSymlinks to false to inspect the link itself. The result always includes isSymlink regardless of followSymlinks.

fs.stat(path: string, followSymlinks: boolean?) → { size: number?, mtime: number?, isFile: boolean?, isDirectory: boolean?, isSymlink: boolean? }