IF Commons GitHub

fs

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-system FR-002

Files and folders (commons 0001-system FR-002), on node:fs alone, so the same code runs on Bun and Node. The functions have short, plain names and shapes (readTextFile, writeTextFile, remove, mkdir, stat, readDir, makeTempDir, ...); every failure is thrown as an error of ./errors.ts (NotFound, AlreadyExists, ...). The helpers Stolos wrote over them (exists, readTextOr, ensureDir, writeIfChanged, listDirs, listFiles, walkFiles) and the setup's sha256File are here too.

readDir is an async iterable, with chown and symlinkSync (FR-048); open and openSync give an FsFile with no lock, which is ./lock.ts's (FR-049); copy and walk are @std/fs's (FR-050), and expandGlob gives the entries a glob of ../kernel/glob.ts matches, in byte order (FR-058).

import { makeTempDir, readTextFile, remove, writeTextFile } from "./fs.ts";
const dir = await makeTempDir({ prefix: "example-" });
await writeTextFile(`${dir}/a.txt`, "hello");
await readTextFile(`${dir}/a.txt`); // "hello"
await remove(dir, { recursive: true });

Source: commons/system/src/fs.ts

14 of 124 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

fsnamespace
namespace fs
fs.PathLiketypeno test imports it
type PathLike = string | URL;

A path, as a string or a file: URL.

fs.FileInfotypeno test imports it
type FileInfo = { readonly isFile: boolean; readonly isDirectory: boolean; readonly isSymlink: boolean; readonlyโ€ฆ (447 characters)
type FileInfo = {
  readonly isFile: boolean;
  readonly isDirectory: boolean;
  readonly isSymlink: boolean;
  readonly size: number;
  readonly mtime: Date | null;
  readonly atime: Date | null;
  readonly birthtime: Date | null;
  readonly ctime: Date | null;
  readonly mode: number | null;
  readonly uid: number | null;
  readonly gid: number | null;
  readonly dev: number;
  readonly ino: number | null;
  readonly nlink: number | null;
};

What stat knows of a file, by these names. A time the file system does not keep is null.

fs.DirEntrytypeno test imports it
type DirEntry = { readonly name: string; readonly isFile: boolean; readonly isDirectory: boolean; readonly isSymlink: boolean };

One entry of a folder, by these names.

fs.WriteFileOptionstypeno test imports it
type WriteFileOptions = {
  readonly append?: boolean;
  readonly create?: boolean;
  readonly createNew?: boolean;
  readonly mode?: number;
};

How to write a file: append instead of replacing, refuse to make it (create: false), refuse where it exists (createNew), its mode.

fs.readTextFilefunctionno test imports it
function readTextFile(path: PathLike): Promise<string>

A file's text, read as UTF-8.

fs.readTextFileSyncfunctionno test imports it
function readTextFileSync(path: PathLike): string

A file's text, read as UTF-8, without waiting.

fs.readFilefunctionno test imports it
function readFile(path: PathLike): Promise<Uint8Array<ArrayBufferLike>>

A file's bytes.

fs.readFileSyncfunctionno test imports it
function readFileSync(path: PathLike): Uint8Array<ArrayBufferLike>

A file's bytes, without waiting.

fs.writeTextFilefunctionno test imports it
function writeTextFile(path: PathLike, data: string, options?: WriteFileOptions): Promise<void>

Text written to a file as UTF-8, replacing it unless append.

fs.writeTextFileSyncfunctionno test imports it
function writeTextFileSync(path: PathLike, data: string, options?: WriteFileOptions): void

Text written to a file as UTF-8, without waiting.

fs.writeFilefunctionno test imports it
function writeFile(path: PathLike, data: Uint8Array<ArrayBufferLike>, options?: WriteFileOptions): Promise<void>

Bytes written to a file, replacing it unless append.

fs.writeFileSyncfunctionno test imports it
function writeFileSync(path: PathLike, data: Uint8Array<ArrayBufferLike>, options?: WriteFileOptions): void

Bytes written to a file, without waiting.

fs.RemoveOptionstypeno test imports it
type RemoveOptions = { readonly recursive?: boolean };

How to remove: a folder and everything in it only with recursive.

fs.removefunctionno test imports it
function remove(path: PathLike, options?: RemoveOptions): Promise<void>

A file, a link or an empty folder removed; with recursive, a folder and everything in it. NotFound where nothing is there; the error is of ./errors.ts.

fs.removeSyncfunctionno test imports it
function removeSync(path: PathLike, options?: RemoveOptions): void

The same, without waiting.

fs.MkdirOptionstypeno test imports it
type MkdirOptions = { readonly recursive?: boolean; readonly mode?: number };

How to make a folder: its parents too (and no error where it exists) with recursive, and its mode.

fs.mkdirfunctionno test imports it
function mkdir(path: PathLike, options?: MkdirOptions): Promise<void>

A folder made.

fs.mkdirSyncfunctionno test imports it
function mkdirSync(path: PathLike, options?: MkdirOptions): void

A folder made, without waiting.

fs.statfunctionno test imports it
function stat(path: PathLike): Promise<FileInfo>

What is at a path, following links.

fs.statSyncfunctionno test imports it
function statSync(path: PathLike): FileInfo

What is at a path, following links, without waiting.

fs.lstatfunctionno test imports it
function lstat(path: PathLike): Promise<FileInfo>

What is at a path; a link is described, not followed.

fs.lstatSyncfunctionno test imports it
function lstatSync(path: PathLike): FileInfo

What is at a path; a link is described, not followed; without waiting.

fs.readDirfunctionno test imports it
function readDir(path: PathLike): AsyncIterable<DirEntry>

The entries of a folder, in the order the file system gives them (FR-048); NotFound at the first step where it is not there.

fs.readDirSyncfunctionno test imports it
function readDirSync(path: PathLike): DirEntry[]

The entries of a folder, without waiting.

fs.MakeTempOptionstypeno test imports it
type MakeTempOptions = { readonly dir?: string; readonly prefix?: string; readonly suffix?: string };

Where and how a temporary file or folder is named: in dir (the system's by default), with a prefix and suffix.

fs.makeTempDirfunctionno test imports it
function makeTempDir(options?: MakeTempOptions): Promise<string>

A new, empty, private folder, and its path.

fs.makeTempDirSyncfunctionno test imports it
function makeTempDirSync(options?: MakeTempOptions): string

A new, empty, private folder, without waiting.

fs.makeTempFilefunctionno test imports it
function makeTempFile(options?: MakeTempOptions): Promise<string>

A new, empty, private file, and its path.

fs.renamefunctionno test imports it
function rename(from: PathLike, to: PathLike): Promise<void>

A file or folder moved to a new path, replacing a file there.

fs.renameSyncfunctionno test imports it
function renameSync(from: PathLike, to: PathLike): void

The same, without waiting.

fs.copyFilefunctionno test imports it
function copyFile(from: PathLike, to: PathLike): Promise<void>

A file's bytes copied to a new path, replacing a file there.

fs.chmodfunctionno test imports it
function chmod(path: PathLike, mode: number): Promise<void>

A file's mode changed (ignored on Windows, which has none).

fs.linkfunctionno test imports it
function link(from: PathLike, to: PathLike): Promise<void>

A second name, to, for the file at from (a hard link), refused with AlreadyExists where to is taken: a file put in place whole, or not at all.

fs.symlinkfunctionno test imports it
function symlink(target: PathLike, path: PathLike, options?: { readonly type?: "dir" | "file" | "junction" | undefined; }): Promise<void>

A link at path that points at target; type matters on Windows only. junction (a folder, FR-073) is the Windows link any account may make (a symbolic link needs administrator rights or Developer Mode there): its target is made absolute, as Windows requires; on Linux and macOS it is an ordinary symbolic link.

fs.readLinkfunctionno test imports it
function readLink(path: PathLike): Promise<string>

Where a link points, as it was written.

fs.realPathfunctionno test imports it
function realPath(path: PathLike): Promise<string>

The absolute path with every link followed.

fs.truncatefunctionno test imports it
function truncate(path: PathLike, length?: number): Promise<void>

A file cut (or extended with zeros) to length bytes, 0 by default.

fs.utimefunctionno test imports it
function utime(path: PathLike, atime: number | Date, mtime: number | Date): Promise<void>

A file's access and modification times set.

fs.existsfunctionno test imports it
function exists(path: PathLike): Promise<boolean>

Whether something is at path (a file, folder or link; a broken link counts). An error other than NotFound is thrown.

fs.existsSyncfunctionno test imports it
function existsSync(path: PathLike): boolean

The same, without waiting.

fs.readTextOrfunctionno test imports it
function readTextOr<F extends string | undefined = undefined>(path: PathLike, fallback?: F | undefined): Promise<string | F>

A text file's content, or fallback (undefined unless given) where nothing is there. Other errors are thrown.

fs.ensureDirfunctionno test imports it
function ensureDir(path: PathLike): Promise<void>

A folder and its parents made, where missing.

fs.writeIfChangedfunctionno test imports it
function writeIfChanged(path: PathLike, content: string): Promise<boolean>

A text file written only where its content changed, in one step (a file beside it renamed over it, so a reader never sees half of it), its folder made where missing. Whether it was written.

fs.listDirsfunctionno test imports it
function listDirs(path: PathLike): Promise<string[]>

The names of the folders directly in path, sorted; none where it does not exist.

fs.listFilesfunctionno test imports it
function listFiles(path: PathLike, suffix?: string): Promise<string[]>

The names of the files directly in path that end in suffix, sorted; none where it does not exist.

fs.walkFilesfunctionno test imports it
function walkFiles(root: PathLike, rel?: string): Promise<string[]>

Every file under a folder (links included, not followed), by its path relative to it with / between parts, sorted; none where it does not exist.

fs.sha256Filefunctionno test imports it
function sha256File(path: PathLike): Promise<Sha256>

The SHA-256 of a file, read as a stream so a large file is not held in memory.

fs.withTempDirfunctionno test imports it
function withTempDir<T>(f: (dir: string) => Promise<T>, options?: MakeTempOptions): Promise<T>

A temporary folder for the length of f, removed with everything in it afterwards, whatever f does.

fs.chownfunctionno test imports it
function chown(path: PathLike, uid: number | null, gid: number | null): Promise<void>

A file's owner and group changed; null keeps one as it is. Ignored on Windows, which has no POSIX owners (FR-018).

fs.symlinkSyncfunctionno test imports it
function symlinkSync(target: PathLike, path: PathLike, options?: { readonly type?: "dir" | "file" | "junction" | undefined; }): void

A link at path that points at target, without waiting; type matters on Windows only (junction: see symlink).

fs.OpenOptionstypeno test imports it
type OpenOptions = {
  readonly read?: boolean;
  readonly write?: boolean;
  readonly append?: boolean;
  readonly truncate?: boolean;
  readonly create?: boolean;
  readonly createNew?: boolean;
  readonly mode?: number;
};

How to open a file, by these names: read alone where none is given. append writes at the end and implies write.

fs.SeekWhencetypeno test imports it
type SeekWhence = "start" | "current" | "end";

Where seek counts from: the start of the file, the handle's position, or the end (start, current, end).

fs.FsFileclassno test imports it
class FsFile implements Disposable, AsyncDisposable

An open file: it reads and writes at its position (a handle opened with append always writes at the end), seeks, truncates, stats and syncs, gives its bytes as a web ReadableStream and takes them as a WritableStream (each closes the file when it ends), and is closed by close, using or await using. It has no lock: one run at a time is ./lock.ts (FR-039, FR-049). Made by open and openSync.

MemberTypeWhat it is
read(buffer: Uint8Array<ArrayBufferLike>) => Promise<number | null>Bytes read into buffer from the position, which moves past them: how many, or null at the end of the file.
readSync(buffer: Uint8Array<ArrayBufferLike>) => number | nullThe same, without waiting.
write(data: Uint8Array<ArrayBufferLike>) => Promise<number>Bytes written at the position (at the end with append), which moves past them: how many, which may be fewer than given.
writeSync(data: Uint8Array<ArrayBufferLike>) => numberThe same, without waiting.
seek(offset: number, whence?: SeekWhence) => Promise<number>The position moved by offset from the start, the position or the end; the new position, from the start.
seekSync(offset: number, whence?: SeekWhence) => numberThe same, without waiting.
truncate(length?: number) => Promise<void>The file cut (or extended with zeros) to length bytes, 0 by default; the position is kept.
truncateSync(length?: number) => voidThe same, without waiting.
stat() => Promise<FileInfo>What the open file is.
statSync() => FileInfoThe same, without waiting.
sync() => Promise<void>The file's data and metadata written through to the disk.
syncSync() => voidThe same, without waiting.
readableReadableStream<Uint8Array<ArrayBufferLike>>The file's bytes from the position to the end, as a stream that closes the file when it ends or is cancelled.
writableWritableStream<Uint8Array<ArrayBufferLike>>A stream whose chunks are written whole at the position, closing the file when it is closed or aborted.
close() => voidThe file closed; closing it again does nothing.
__@dispose@281474976713631() => voidClosed at the end of a using block.
__@asyncDispose@281474976747252() => Promise<void>Closed at the end of an await using block.
fs.openfunctionno test imports it
function open(path: PathLike, options?: OpenOptions): Promise<FsFile>

A file opened for reading where no options are given. AlreadyExists with createNew, NotFound without create.

fs.openSyncfunctionno test imports it
function openSync(path: PathLike, options?: OpenOptions): FsFile

The same, without waiting.

fs.CopyOptionstypeno test imports it
type CopyOptions = { readonly overwrite?: boolean; readonly preserveTimestamps?: boolean };

How to copy: replace what is at the destination (overwrite), keep the access and modification times (preserveTimestamps).

fs.copyfunctionno test imports it
function copy(from: PathLike, to: PathLike, options?: CopyOptions): Promise<void>

A file, a link or a folder with everything in it copied, as @std/fs's copy does: a link is copied as a link, modes are kept (not on Windows, FR-018), and what is at the destination is AlreadyExists unless overwrite. A folder cannot be copied into itself.

fs.WalkEntrytypeno test imports it
type WalkEntry = DirEntry & { readonly path: string };

One entry of a walk: what readDir gives, with its path (the root's joined with the names, by the platform's separator).

fs.WalkOptionstypeno test imports it
type WalkOptions = {
  readonly maxDepth?: number;
  readonly includeFiles?: boolean;
  readonly includeDirs?: boolean;
  readonly includeSymlinks?: boolean;
  readonly followSymlinks?: boolean;
  readonly canonicalize?: boolean;
  readonly exts?: readonly string[];
  readonly match?: readonly RegExp[];
  readonly skip?: readonly RegExp[];
};

What a walk gives, as @std/fs's walk takes it: how deep (maxDepth, the root being 0), which kinds (includeFiles, includeDirs, includeSymlinks, all true by default), whether links are followed (followSymlinks, false) and then given by their real path (canonicalize, true), and which paths: ending in one of exts, matching one of match, matching none of skip. The expressions are tested against the path with / between its parts on every platform, so one expression serves Windows too.

fs.walkfunctionno test imports it
function walk(root: PathLike, options?: WalkOptions): AsyncGenerator<WalkEntry, any, any>

Every entry under a folder, as @std/fs's walk gives them (see WalkOptions), depth first and in the byte order of the names at each level, so a walk is the same every time; the root first, where folders are included; a file as the root is the walk's one entry. NotFound where the root is not there.

fs.ExpandGlobOptionstypeno test imports it
type ExpandGlobOptions = GlobOptions & {
  readonly root?: PathLike;
  readonly exclude?: readonly string[];
  readonly includeDirs?: boolean;
  readonly followSymlinks?: boolean;
};

How expandGlob reads its glob: the folder it is relative to (root, the working folder by default), globs whose matches (and all under them) are left out (exclude), whether folders are given (includeDirs, true) and links followed (followSymlinks, false), and the glob's own options (extended, globstar, caseInsensitive).

fs.expandGlobfunctionno test imports it
function expandGlob(glob: string, options?: ExpandGlobOptions): AsyncGenerator<WalkEntry, any, any>

The entries a glob matches (src/**\/*.ts; see ../kernel/glob.ts), as @std/fs's expandGlob gives them, sorted in the byte order of their paths so the result is the same every time. A glob is written with /, also on Windows, and may be absolute (/srv/*.log, C:/x/*); a relative one is read from root. Entries are matched by their path relative to where the glob starts. A glob that begins with ! is refused as InvalidData; a folder that is not there has no entries.

PathLiketypeno test imports it
type PathLike = string | URL;

A path, as a string or a file: URL.

FileInfotypeno test imports it
type FileInfo = { readonly isFile: boolean; readonly isDirectory: boolean; readonly isSymlink: boolean; readonlyโ€ฆ (447 characters)
type FileInfo = {
  readonly isFile: boolean;
  readonly isDirectory: boolean;
  readonly isSymlink: boolean;
  readonly size: number;
  readonly mtime: Date | null;
  readonly atime: Date | null;
  readonly birthtime: Date | null;
  readonly ctime: Date | null;
  readonly mode: number | null;
  readonly uid: number | null;
  readonly gid: number | null;
  readonly dev: number;
  readonly ino: number | null;
  readonly nlink: number | null;
};

What stat knows of a file, by these names. A time the file system does not keep is null.

DirEntrytypeno test imports it
type DirEntry = { readonly name: string; readonly isFile: boolean; readonly isDirectory: boolean; readonly isSymlink: boolean };

One entry of a folder, by these names.

WriteFileOptionstypeno test imports it
type WriteFileOptions = {
  readonly append?: boolean;
  readonly create?: boolean;
  readonly createNew?: boolean;
  readonly mode?: number;
};

How to write a file: append instead of replacing, refuse to make it (create: false), refuse where it exists (createNew), its mode.

readTextFilefunction
function readTextFile(path: PathLike): Promise<string>

A file's text, read as UTF-8.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

readTextFileSyncfunctionno test imports it
function readTextFileSync(path: PathLike): string

A file's text, read as UTF-8, without waiting.

readFilefunction
function readFile(path: PathLike): Promise<Uint8Array<ArrayBufferLike>>

A file's bytes.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

readFileSyncfunctionno test imports it
function readFileSync(path: PathLike): Uint8Array<ArrayBufferLike>

A file's bytes, without waiting.

writeTextFilefunction
function writeTextFile(path: PathLike, data: string, options?: WriteFileOptions): Promise<void>

Text written to a file as UTF-8, replacing it unless append.

Imported by 42 tests of the run (42 passed, 0 failed): the library's results

writeTextFileSyncfunctionno test imports it
function writeTextFileSync(path: PathLike, data: string, options?: WriteFileOptions): void

Text written to a file as UTF-8, without waiting.

writeFilefunction
function writeFile(path: PathLike, data: Uint8Array<ArrayBufferLike>, options?: WriteFileOptions): Promise<void>

Bytes written to a file, replacing it unless append.

Imported by 3 tests of the run (3 passed, 0 failed): the library's results

writeFileSyncfunctionno test imports it
function writeFileSync(path: PathLike, data: Uint8Array<ArrayBufferLike>, options?: WriteFileOptions): void

Bytes written to a file, without waiting.

RemoveOptionstypeno test imports it
type RemoveOptions = { readonly recursive?: boolean };

How to remove: a folder and everything in it only with recursive.

removefunction
function remove(path: PathLike, options?: RemoveOptions): Promise<void>

A file, a link or an empty folder removed; with recursive, a folder and everything in it. NotFound where nothing is there; the error is of ./errors.ts.

Imported by 3 tests of the run (3 passed, 0 failed): the library's results

removeSyncfunctionno test imports it
function removeSync(path: PathLike, options?: RemoveOptions): void

The same, without waiting.

MkdirOptionstypeno test imports it
type MkdirOptions = { readonly recursive?: boolean; readonly mode?: number };

How to make a folder: its parents too (and no error where it exists) with recursive, and its mode.

mkdirfunction
function mkdir(path: PathLike, options?: MkdirOptions): Promise<void>

A folder made.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

mkdirSyncfunctionno test imports it
function mkdirSync(path: PathLike, options?: MkdirOptions): void

A folder made, without waiting.

statfunction
function stat(path: PathLike): Promise<FileInfo>

What is at a path, following links.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

statSyncfunctionno test imports it
function statSync(path: PathLike): FileInfo

What is at a path, following links, without waiting.

lstatfunctionno test imports it
function lstat(path: PathLike): Promise<FileInfo>

What is at a path; a link is described, not followed.

lstatSyncfunctionno test imports it
function lstatSync(path: PathLike): FileInfo

What is at a path; a link is described, not followed; without waiting.

readDirfunctionno test imports it
function readDir(path: PathLike): AsyncIterable<DirEntry>

The entries of a folder, in the order the file system gives them (FR-048); NotFound at the first step where it is not there.

readDirSyncfunctionno test imports it
function readDirSync(path: PathLike): DirEntry[]

The entries of a folder, without waiting.

MakeTempOptionstypeno test imports it
type MakeTempOptions = { readonly dir?: string; readonly prefix?: string; readonly suffix?: string };

Where and how a temporary file or folder is named: in dir (the system's by default), with a prefix and suffix.

makeTempDirfunctionno test imports it
function makeTempDir(options?: MakeTempOptions): Promise<string>

A new, empty, private folder, and its path.

makeTempDirSyncfunctionno test imports it
function makeTempDirSync(options?: MakeTempOptions): string

A new, empty, private folder, without waiting.

makeTempFilefunctionno test imports it
function makeTempFile(options?: MakeTempOptions): Promise<string>

A new, empty, private file, and its path.

renamefunction
function rename(from: PathLike, to: PathLike): Promise<void>

A file or folder moved to a new path, replacing a file there.

Imported by 3 tests of the run (3 passed, 0 failed): the library's results

renameSyncfunctionno test imports it
function renameSync(from: PathLike, to: PathLike): void

The same, without waiting.

copyFilefunctionno test imports it
function copyFile(from: PathLike, to: PathLike): Promise<void>

A file's bytes copied to a new path, replacing a file there.

chmodfunction
function chmod(path: PathLike, mode: number): Promise<void>

A file's mode changed (ignored on Windows, which has none).

Imported by 2 tests of the run (2 passed, 0 failed): the library's results

linkfunctionno test imports it
function link(from: PathLike, to: PathLike): Promise<void>

A second name, to, for the file at from (a hard link), refused with AlreadyExists where to is taken: a file put in place whole, or not at all.

symlinkfunctionno test imports it
function symlink(target: PathLike, path: PathLike, options?: { readonly type?: "dir" | "file" | "junction" | undefined; }): Promise<void>

A link at path that points at target; type matters on Windows only. junction (a folder, FR-073) is the Windows link any account may make (a symbolic link needs administrator rights or Developer Mode there): its target is made absolute, as Windows requires; on Linux and macOS it is an ordinary symbolic link.

readLinkfunctionno test imports it
function readLink(path: PathLike): Promise<string>

Where a link points, as it was written.

realPathfunction
function realPath(path: PathLike): Promise<string>

The absolute path with every link followed.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

truncatefunctionno test imports it
function truncate(path: PathLike, length?: number): Promise<void>

A file cut (or extended with zeros) to length bytes, 0 by default.

utimefunction
function utime(path: PathLike, atime: number | Date, mtime: number | Date): Promise<void>

A file's access and modification times set.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

existsfunction
function exists(path: PathLike): Promise<boolean>

Whether something is at path (a file, folder or link; a broken link counts). An error other than NotFound is thrown.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

existsSyncfunctionno test imports it
function existsSync(path: PathLike): boolean

The same, without waiting.

readTextOrfunctionno test imports it
function readTextOr<F extends string | undefined = undefined>(path: PathLike, fallback?: F | undefined): Promise<string | F>

A text file's content, or fallback (undefined unless given) where nothing is there. Other errors are thrown.

ensureDirfunctionno test imports it
function ensureDir(path: PathLike): Promise<void>

A folder and its parents made, where missing.

writeIfChangedfunctionno test imports it
function writeIfChanged(path: PathLike, content: string): Promise<boolean>

A text file written only where its content changed, in one step (a file beside it renamed over it, so a reader never sees half of it), its folder made where missing. Whether it was written.

listDirsfunctionno test imports it
function listDirs(path: PathLike): Promise<string[]>

The names of the folders directly in path, sorted; none where it does not exist.

listFilesfunctionno test imports it
function listFiles(path: PathLike, suffix?: string): Promise<string[]>

The names of the files directly in path that end in suffix, sorted; none where it does not exist.

walkFilesfunctionno test imports it
function walkFiles(root: PathLike, rel?: string): Promise<string[]>

Every file under a folder (links included, not followed), by its path relative to it with / between parts, sorted; none where it does not exist.

sha256Filefunction
function sha256File(path: PathLike): Promise<Sha256>

The SHA-256 of a file, read as a stream so a large file is not held in memory.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

withTempDirfunction
function withTempDir<T>(f: (dir: string) => Promise<T>, options?: MakeTempOptions): Promise<T>

A temporary folder for the length of f, removed with everything in it afterwards, whatever f does.

Imported by 48 tests of the run (48 passed, 0 failed): the library's results

chownfunctionno test imports it
function chown(path: PathLike, uid: number | null, gid: number | null): Promise<void>

A file's owner and group changed; null keeps one as it is. Ignored on Windows, which has no POSIX owners (FR-018).

symlinkSyncfunctionno test imports it
function symlinkSync(target: PathLike, path: PathLike, options?: { readonly type?: "dir" | "file" | "junction" | undefined; }): void

A link at path that points at target, without waiting; type matters on Windows only (junction: see symlink).

OpenOptionstypeno test imports it
type OpenOptions = {
  readonly read?: boolean;
  readonly write?: boolean;
  readonly append?: boolean;
  readonly truncate?: boolean;
  readonly create?: boolean;
  readonly createNew?: boolean;
  readonly mode?: number;
};

How to open a file, by these names: read alone where none is given. append writes at the end and implies write.

SeekWhencetypeno test imports it
type SeekWhence = "start" | "current" | "end";

Where seek counts from: the start of the file, the handle's position, or the end (start, current, end).

FsFileclassno test imports it
class FsFile implements Disposable, AsyncDisposable

An open file: it reads and writes at its position (a handle opened with append always writes at the end), seeks, truncates, stats and syncs, gives its bytes as a web ReadableStream and takes them as a WritableStream (each closes the file when it ends), and is closed by close, using or await using. It has no lock: one run at a time is ./lock.ts (FR-039, FR-049). Made by open and openSync.

MemberTypeWhat it is
read(buffer: Uint8Array<ArrayBufferLike>) => Promise<number | null>Bytes read into buffer from the position, which moves past them: how many, or null at the end of the file.
readSync(buffer: Uint8Array<ArrayBufferLike>) => number | nullThe same, without waiting.
write(data: Uint8Array<ArrayBufferLike>) => Promise<number>Bytes written at the position (at the end with append), which moves past them: how many, which may be fewer than given.
writeSync(data: Uint8Array<ArrayBufferLike>) => numberThe same, without waiting.
seek(offset: number, whence?: SeekWhence) => Promise<number>The position moved by offset from the start, the position or the end; the new position, from the start.
seekSync(offset: number, whence?: SeekWhence) => numberThe same, without waiting.
truncate(length?: number) => Promise<void>The file cut (or extended with zeros) to length bytes, 0 by default; the position is kept.
truncateSync(length?: number) => voidThe same, without waiting.
stat() => Promise<FileInfo>What the open file is.
statSync() => FileInfoThe same, without waiting.
sync() => Promise<void>The file's data and metadata written through to the disk.
syncSync() => voidThe same, without waiting.
readableReadableStream<Uint8Array<ArrayBufferLike>>The file's bytes from the position to the end, as a stream that closes the file when it ends or is cancelled.
writableWritableStream<Uint8Array<ArrayBufferLike>>A stream whose chunks are written whole at the position, closing the file when it is closed or aborted.
close() => voidThe file closed; closing it again does nothing.
__@dispose@281474976713631() => voidClosed at the end of a using block.
__@asyncDispose@281474976747252() => Promise<void>Closed at the end of an await using block.
openfunctionno test imports it
function open(path: PathLike, options?: OpenOptions): Promise<FsFile>

A file opened for reading where no options are given. AlreadyExists with createNew, NotFound without create.

openSyncfunctionno test imports it
function openSync(path: PathLike, options?: OpenOptions): FsFile

The same, without waiting.

CopyOptionstypeno test imports it
type CopyOptions = { readonly overwrite?: boolean; readonly preserveTimestamps?: boolean };

How to copy: replace what is at the destination (overwrite), keep the access and modification times (preserveTimestamps).

copyfunctionno test imports it
function copy(from: PathLike, to: PathLike, options?: CopyOptions): Promise<void>

A file, a link or a folder with everything in it copied, as @std/fs's copy does: a link is copied as a link, modes are kept (not on Windows, FR-018), and what is at the destination is AlreadyExists unless overwrite. A folder cannot be copied into itself.

WalkEntrytypeno test imports it
type WalkEntry = DirEntry & { readonly path: string };

One entry of a walk: what readDir gives, with its path (the root's joined with the names, by the platform's separator).

WalkOptionstypeno test imports it
type WalkOptions = {
  readonly maxDepth?: number;
  readonly includeFiles?: boolean;
  readonly includeDirs?: boolean;
  readonly includeSymlinks?: boolean;
  readonly followSymlinks?: boolean;
  readonly canonicalize?: boolean;
  readonly exts?: readonly string[];
  readonly match?: readonly RegExp[];
  readonly skip?: readonly RegExp[];
};

What a walk gives, as @std/fs's walk takes it: how deep (maxDepth, the root being 0), which kinds (includeFiles, includeDirs, includeSymlinks, all true by default), whether links are followed (followSymlinks, false) and then given by their real path (canonicalize, true), and which paths: ending in one of exts, matching one of match, matching none of skip. The expressions are tested against the path with / between its parts on every platform, so one expression serves Windows too.

walkfunctionno test imports it
function walk(root: PathLike, options?: WalkOptions): AsyncGenerator<WalkEntry, any, any>

Every entry under a folder, as @std/fs's walk gives them (see WalkOptions), depth first and in the byte order of the names at each level, so a walk is the same every time; the root first, where folders are included; a file as the root is the walk's one entry. NotFound where the root is not there.

ExpandGlobOptionstypeno test imports it
type ExpandGlobOptions = GlobOptions & {
  readonly root?: PathLike;
  readonly exclude?: readonly string[];
  readonly includeDirs?: boolean;
  readonly followSymlinks?: boolean;
};

How expandGlob reads its glob: the folder it is relative to (root, the working folder by default), globs whose matches (and all under them) are left out (exclude), whether folders are given (includeDirs, true) and links followed (followSymlinks, false), and the glob's own options (extended, globstar, caseInsensitive).

expandGlobfunctionno test imports it
function expandGlob(glob: string, options?: ExpandGlobOptions): AsyncGenerator<WalkEntry, any, any>

The entries a glob matches (src/**\/*.ts; see ../kernel/glob.ts), as @std/fs's expandGlob gives them, sorted in the byte order of their paths so the result is the same every time. A glob is written with /, also on Windows, and may be absolute (/srv/*.log, C:/x/*); a relative one is read from root. Entries are matched by their path relative to where the glob starts. A glob that begins with ! is refused as InvalidData; a folder that is not there has no entries.

Titles, headings, exports, tables, columns and requirements. Esc closes.