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 @eryx/path. fs.path.* remains as a legacy compatibility surface.

Summary

Classes

Functions

API Reference

Classes

BaseFile

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.

BaseFile:truncate

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

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

BaseFile:size

Returns the file size in bytes.

BaseFile:size() → number

BaseFile:__iter

Iterates lines as (number, line, ending). ending is "\n", "\r\n", "\r", or "" for the final unterminated line.

BaseFile.__iter(self: BaseFile) → (FileLineNext, any, number?)

WalkIterator

Properties

WalkIterator:__iter

WalkIterator.__iter(self: WalkIterator) → (WalkNext, any, nil)

Functions

fs.open

⚠ Yields

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

fs.open(path: PathLike, mode: nil) → ReadableFile

Parameters

path: PathLike

File path to open.

mode: nil

File mode string.

Returns

ReadableFile

Open file handle.

fs.open(path: PathLike, mode: "r") → ReadableFile

Parameters

path: PathLike

File path to open.

mode: "r"

File mode string.

Returns

ReadableFile

Open file handle.

fs.open(path: PathLike, mode: "w") → WritableFile

Parameters

path: PathLike

File path to open.

mode: "w"

File mode string.

Returns

WritableFile

Open file handle.

fs.open(path: PathLike, mode: "a") → WritableFile

Parameters

path: PathLike

File path to open.

mode: "a"

File mode string.

Returns

WritableFile

Open file handle.

fs.open(path: PathLike, mode: "r+") → ReadWriteFile

Parameters

path: PathLike

File path to open.

mode: "r+"

File mode string.

Returns

ReadWriteFile

Open file handle.

fs.open(path: PathLike, mode: "w+") → ReadWriteFile

Parameters

path: PathLike

File path to open.

mode: "w+"

File mode string.

Returns

ReadWriteFile

Open file handle.

fs.open(path: PathLike, mode: "a+") → ReadWriteFile

Parameters

path: PathLike

File path to open.

mode: "a+"

File mode string.

Returns

ReadWriteFile

Open file handle.

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

Parameters

path: PathLike

File path to open.

mode: string

File mode string.

Returns

File

Open file handle.

fs.openSync

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

fs.openSync(path: PathLike, mode: "r") → ReadableFile

Parameters

path: PathLike

File path to open.

mode: "r"

File mode string.

Returns

ReadableFile

Open file handle.

fs.openSync(path: PathLike, mode: nil) → ReadableFile

Parameters

path: PathLike

File path to open.

mode: nil

File mode string.

Returns

ReadableFile

Open file handle.

fs.openSync(path: PathLike, mode: "w") → WritableFile

Parameters

path: PathLike

File path to open.

mode: "w"

File mode string.

Returns

WritableFile

Open file handle.

fs.openSync(path: PathLike, mode: "a") → WritableFile

Parameters

path: PathLike

File path to open.

mode: "a"

File mode string.

Returns

WritableFile

Open file handle.

fs.openSync(path: PathLike, mode: "r+") → ReadWriteFile

Parameters

path: PathLike

File path to open.

mode: "r+"

File mode string.

Returns

ReadWriteFile

Open file handle.

fs.openSync(path: PathLike, mode: "w+") → ReadWriteFile

Parameters

path: PathLike

File path to open.

mode: "w+"

File mode string.

Returns

ReadWriteFile

Open file handle.

fs.openSync(path: PathLike, mode: "a+") → ReadWriteFile

Parameters

path: PathLike

File path to open.

mode: "a+"

File mode string.

Returns

ReadWriteFile

Open file handle.

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

Parameters

path: PathLike

File path to open.

mode: string

File mode string.

Returns

File

Open file handle.

fs.exists

fs.exists(path: PathLike) → boolean

Parameters

path: PathLike

Path to check.

Returns

boolean

true when the path exists.

fs.isFile

fs.isFile(path: PathLike) → boolean

Parameters

path: PathLike

Path to check.

Returns

boolean

true when the path is a regular file.

fs.isDirectory

fs.isDirectory(path: PathLike) → boolean

Parameters

path: PathLike

Path to check.

Returns

boolean

true when the path is a directory.

fs.mkdir

fs.mkdir(path: PathLike) → boolean

Parameters

path: PathLike

Directory path to create.

Returns

boolean

true when directory creation succeeds.

fs.remove

fs.remove(path: PathLike) → boolean

Parameters

path: PathLike

File or directory path to remove recursively.

Returns

boolean

true when removal succeeds.

fs.rename

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

Parameters

oldPath: PathLike

Existing path.

newPath: PathLike

Destination path.

fs.copy

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

Parameters

src: PathLike

Source path.

dst: PathLike

Destination path.

fs.listDir

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

Parameters

path: PathLike

Directory path.

Returns

{ string }

Entry names from the directory.

fs.walk

Returns an iterator over entries in root.

fs.walk(root: PathLike, options: WalkOptions?) → WalkIterator

Parameters

root: PathLike

Directory to walk.

options: WalkOptions?

Walk options. recursive and followSymlinks default to false.

Returns

WalkIterator

Iterator yielding WalkEntry tables.

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: PathLike, link: PathLike, type: ("file" | "directory")?) → ()

Parameters

target: PathLike

Symlink target path.

link: PathLike

Symlink path to create.

type: ("file" | "directory")?

Optional symlink type hint.

fs.readlink

fs.readlink(path: PathLike) → string

Parameters

path: PathLike

Symlink path.

Returns

string

Symlink target path.

fs.isSymlink

fs.isSymlink(path: PathLike) → boolean

Parameters

path: PathLike

Path to inspect.

Returns

boolean

true when the path itself is a symbolic link.

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: PathLike, followSymlinks: boolean?) → FileStat

Parameters

path: PathLike

Path to inspect.

followSymlinks: boolean?

Whether symlinks should be followed. Defaults to true.

Returns

FileStat

Metadata for the path, or an empty-like table when missing.

fs.hasPermission

Checks whether a principal has a specific permission on a path. If options is omitted, checks the current effective principal.

fs.hasPermission(path: PathLike, permission: PermissionToken, options: PermissionCheckOptions?) → boolean

Parameters

path: PathLike

Target path.

permission: PermissionToken

Permission to test.

options: PermissionCheckOptions?

Optional principal/group override.

Returns

boolean

true when permission is granted.

fs.chmod

Changes POSIX mode bits.

Warning

POSIX only. On Windows, use setReadonly and setAcl.

fs.chmod(path: PathLike, mode: number) → ()

Parameters

path: PathLike

Target path.

mode: number

POSIX mode bits (for example 0o644).

fs.chown

Changes owner (uid on POSIX, SID string on Windows).

fs.chown(path: PathLike, owner: number | string) → ()

Parameters

path: PathLike

Target path.

owner: number | string

Owner uid (POSIX) or SID string (Windows).

fs.chgrp

Changes group (gid on POSIX).

Warning

POSIX only.

fs.chgrp(path: PathLike, group: number) → ()

Parameters

path: PathLike

Target path.

group: number

Group id.

fs.getReadonly

Gets whether the path has the readonly attribute/effective readonly state.

fs.getReadonly(path: PathLike) → boolean

Parameters

path: PathLike

Target path.

Returns

boolean

true when readonly is enabled.

fs.setReadonly

Sets whether the path is readonly.

fs.setReadonly(path: PathLike, value: boolean) → ()

Parameters

path: PathLike

Target path.

value: boolean

Desired readonly state.

fs.getHidden

Gets whether the path has the hidden attribute.

Warning

This API is only available in Windows environments.

fs.getHidden(path: PathLike) → boolean

Parameters

path: PathLike

Target path.

Returns

boolean

true when hidden is enabled.

fs.setHidden

Sets whether the path has the hidden attribute.

Warning

This API is only available in Windows environments.

fs.setHidden(path: PathLike, value: boolean) → ()

Parameters

path: PathLike

Target path.

value: boolean

Desired hidden state.

fs.getSystem

Gets whether the path has the system attribute.

Warning

This API is only available in Windows environments.

fs.getSystem(path: PathLike) → boolean

Parameters

path: PathLike

Target path.

Returns

boolean

true when the system attribute is enabled.

fs.setSystem

Sets whether the path has the system attribute.

Warning

This API is only available in Windows environments.

fs.setSystem(path: PathLike, value: boolean) → ()

Parameters

path: PathLike

Target path.

value: boolean

Desired system-attribute state.

fs.getAcl

Reads ACL entries for a path.

Warning

This API is only available in Windows environments.

fs.getAcl(path: PathLike) → { AclEntry }

Parameters

path: PathLike

Target path.

Returns

{ AclEntry }

Ordered ACL entries.

fs.setAcl

Writes ACL entries for a path.

Warning

This API is only available in Windows environments.

fs.setAcl(path: PathLike, entries: { AclEntry }) → ()

Parameters

path: PathLike

Target path.

entries: { AclEntry }

ACL entries applied in order.

path

fs.path.dirname

Returns the parent directory of the path ("a/b/c.txt" -> "a/b").

fs.path.dirname(path: PathLike) → string

Parameters

path: PathLike

Input path.

Returns

string

Parent directory path.

fs.path.basename

Returns the filename component of the path ("a/b/c.txt" -> "c.txt").

fs.path.basename(path: PathLike) → string

Parameters

path: PathLike

Input path.

Returns

string

Basename component.

fs.path.stem

Returns the filename without its extension ("a/b/c.txt" -> "c").

fs.path.stem(path: PathLike) → string

Parameters

path: PathLike

Input path.

Returns

string

Stem component.

fs.path.extension

Returns the file extension including the dot ("a/b/c.txt" -> ".txt").

fs.path.extension(path: PathLike) → string

Parameters

path: PathLike

Input path.

Returns

string

Extension including leading dot, or empty string.

fs.path.canonicalize

Resolves a path to an absolute, canonical form.

fs.path.canonicalize(path: PathLike) → string

Parameters

path: PathLike

Input path.

Returns

string

Canonical absolute path.

fs.path.join

Joins path segments with the platform separator.

fs.path.join(path: PathLike, ...: PathLike) → string

Parameters

path: PathLike

First path segment.

...: PathLike

Additional path segments.

Returns

string

Joined path.

Types

ReadableFile

type ReadableFile = BaseFile & stream.StreamThatCanSeek & stream.StreamThatCanFlush & stream.ReadOnlyStream

Implements: BaseFile, stream.StreamThatCanSeek, stream.StreamThatCanFlush, stream.ReadOnlyStream

WritableFile

type WritableFile = BaseFile & stream.StreamThatCanSeek & stream.StreamThatCanFlush & stream.WriteOnlyStream

Implements: BaseFile, stream.StreamThatCanSeek, stream.StreamThatCanFlush, stream.WriteOnlyStream

ReadWriteFile

type ReadWriteFile = BaseFile & stream.StreamThatCanSeek & stream.StreamThatCanFlush & stream.ReadWriteStream

Implements: BaseFile, stream.StreamThatCanSeek, stream.StreamThatCanFlush, stream.ReadWriteStream

File

Union of all file-handle variants returned by fs.open/fs.openSync.

type File = ReadableFile | WritableFile | ReadWriteFile

PermissionToken

Permission token used by hasPermission and ACL entry rights.

type PermissionToken = "read" | "write" | "execute" | "delete" | "readAcl" | "writeAcl" | "writeOwner"

AclAppliesTo

ACL inheritance scope.

type AclAppliesTo = "this" | "children" | "this_and_children"

AclEntry

Single ACL entry. Windows-focused in this release.

type AclEntry = { type: "allow" | "deny", principal: string, rights: { PermissionToken }, inherits: boolean?, inherited: boolean?, appliesTo: AclAppliesTo? }

type: "allow" | "deny"

Entry type.

principal: string

Principal identifier (SID on Windows).

rights: { PermissionToken }

Rights granted/denied by this entry.

inherits: boolean?

Whether this rule participates in inheritance.

inherited: boolean?

Whether this entry was inherited from a parent ACL.

appliesTo: AclAppliesTo?

Scope this entry applies to.

PermissionCheckOptions

Optional overrides for hasPermission checks.

type PermissionCheckOptions = { principal: number | string?, groups: { number | string }?, followSymlinks: boolean? }

principal: number | string?

Principal id override (uid/gid on POSIX, SID on Windows when supported).

groups: { number | string }?

Supplemental group ids/identifiers for permission evaluation.

followSymlinks: boolean?

Whether symlinks should be followed while evaluating access.

FileStat

Metadata returned by stat.

type FileStat = { size: number?, mtime: number?, isFile: boolean?, isDirectory: boolean?, isSymlink: boolean?, readonly: boolean? }

size: number?

File size in bytes when available.

mtime: number?

Last modification time as Unix timestamp seconds.

isFile: boolean?

true when the path is a regular file.

isDirectory: boolean?

true when the path is a directory.

isSymlink: boolean?

true when the path itself is a symlink.

readonly: boolean?

true when readonly is enabled/effective.

WalkOptions

type WalkOptions = { recursive: boolean?, followSymlinks: boolean? }

recursive: boolean?

Whether to descend into child directories.

followSymlinks: boolean?

Whether directory symlinks should be followed while walking.

WalkEntry

type WalkEntry = { name: string, directory: string, path: string }

name: string

Filename component.

directory: string

Parent directory path.

path: string

Full entry path.