All Symbols - fs documentation

default

Streaming file-system utilities for the anabranch ecosystem.

Examples

Read all lines from a file

import { readLines } from "@anabranch/fs";

const { successes } = await readLines("./data.txt").partition();
console.log(successes.join("\n"));

Walk a directory and find TypeScript files

import { glob } from "@anabranch/fs";

const results = await glob("./src", "*.ts").collect();
console.log(results.map((e) => e.path));

Classes

c

path: string | URL,

message: string

File already exists when it should not.

name: "AlreadyExists"

c

path: string | URL,

message: string

Structured error types for file-system operations.

c

path: string | URL,

message: string,

cause?: unknown

File content is invalid (e.g., malformed JSON).

c

path: string | URL,

message: string

Path is a directory when a file was expected.

name: "IsDirectory"

c

path: string | URL,

message: string

Path is not a directory when a directory was expected.

name: "NotDirectory"

c

path: string | URL,

message: string

name: "NotFound"

c

PermissionDenied(

path: string | URL,

message: string

Permission denied accessing the file system.

name: "PermissionDenied"

c

path: string | URL,

message: string

Error reading from the file system.

name: "ReadError"

c

path: string | URL,

message: string,

cause?: unknown

Unknown file system error.

c

path: string | URL,

message: string

Error writing to the file system.

name: "WriteError"

Functions

f

src: string | URL,

dst: string | URL

): Task<void, CopyFileError>

Copies a single file from src to dst.

f

ensureDir(path: string | URL): Task<void, EnsureDirError>

Creates a directory and any missing parents, like mkdir -p.

f

exists(path: string | URL): Task<boolean, ExistsError>

Checks whether a path exists.

f

root: string | URL,

pattern: string,

options?: GlobOptions

): Source<WalkEntry, DirError>

Finds all entries under root whose relative path matches the glob pattern.

f

nodeErrorToFSError(

error: unknown,

path: string | URL

f

readDir(path: string | URL): Source<DirEntry, DirError>

Lists the immediate children of a directory.

f

readFile(path: string | URL): Task<Uint8Array, ReadFileError>

Reads an entire file as a Uint8Array.

f

readJson<T extends Record<string, any> = Record<string, any>>(path: string | URL): Task<T, ReadJsonError>

Reads a JSON file and parses it, returning the value typed as T.

f

readLines(path: string | URL): Source<string, ReadFileError>

Streams lines from a text file one at a time using node:readline.

f

readTextFile(path: string | URL): Task<string, ReadFileError>

Reads an entire file as a UTF-8 string.

f

remove(path: string | URL): Task<void, RemoveError>

Removes a file or directory recursively. No error if the path doesn't exist.

f

stat(path: string | URL): Task<StatInfo, StatError>

Returns metadata for a path without reading its contents.

f

root: string | URL,

options?: WalkOptions

): Source<WalkEntry, DirError>

Recursively walks a directory tree, yielding each entry.

f

path: string | URL,

options?: WatchOptions

): Stream<FsEvent, WatchError>

Watches path for file-system changes, yielding a FsEvent for each.

f

path: string | URL,

data: Uint8Array

): Task<void, WriteFileError>

Writes a Uint8Array to a file, creating or overwriting it.

f

path: string | URL,

): Task<void, WriteFileError>

Serialises value as JSON and writes it to a file, creating or overwriting it.

f

path: string | URL,

content: string

): Task<void, WriteFileError>

Writes a UTF-8 string to a file, creating or overwriting it.

Interfaces

I

An entry in a directory listing.

isDirectory: boolean
Whether the entry is a directory.
isFile: boolean
Whether the entry is a regular file.
isSymlink: boolean
Whether the entry is a symbolic link.
name: string
The entry's file name (not the full path).

I

A file-system change event, as yielded by watch.

kind: "create" | "modify" | "remove"
The type of change.
paths: string[]
Absolute paths of the affected files.

I

Options for glob. Same as WalkOptions without match.

I

File metadata returned by stat.

atime: Date
Last access time.
birthtime: Date
Creation time.
isDirectory: boolean
Whether the path is a directory.
isFile: boolean
Whether the path is a regular file.
isSymlink: boolean
Whether the path is a symbolic link.
mtime: Date
Last modification time.
size: number
Size in bytes.

I

A directory entry with its full path, as yielded by walk and glob.

path: string
The absolute path to the entry.

I

Options for walk.

includeDirs: boolean
Whether to include directories in results.
includeFiles: boolean
Whether to include regular files in results.
includeSymlinks: boolean
Whether to include symbolic links in results.
match: RegExp[]
Only yield entries whose path (relative to root) matches at least one pattern. When omitted all entries are included.
maxDepth: number
Maximum recursion depth. 0 means only immediate children of root.
skip: RegExp[]
Skip entries whose path (relative to root) matches any of these patterns.

I

Options for watch.

recursive: boolean
Whether to watch subdirectories recursively.

Type Aliases

T

CopyFileError = NotFound | PermissionDenied | Unknown

Errors that can occur when copying a file.

T

DirError = NotFound | NotDirectory | PermissionDenied | Unknown

Errors that can occur when reading directories.

T

EnsureDirError = PermissionDenied | Unknown

Errors that can occur when ensuring a directory.

T

ExistsError = PermissionDenied | Unknown

Errors that can occur when checking existence.

T

ReadFileError = NotFound | PermissionDenied | ReadError | Unknown

Errors that can occur when reading files.

T

ReadJsonError =

NotFound
| PermissionDenied
| ReadError
| InstanceType<InvalidData>
| Unknown

Errors that can occur when reading JSON files.

T

RemoveError = PermissionDenied | Unknown

Errors that can occur when removing a path.

T

StatError = NotFound | PermissionDenied | Unknown

Errors that can occur when stat-ing a path.

T

WatchError = NotFound | PermissionDenied

Errors that can occur when watching the file system.

T

WriteFileError =

NotFound
| IsDirectory
| PermissionDenied
| WriteError
| Unknown

Errors that can occur when writing files.