fsnamespacenamespace fsFiles 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 });fsnamespacenamespace fsfs.PathLiketypeno test imports ittype PathLike = string | URL;A path, as a string or a file: URL.
fs.FileInfotypeno test imports ittype 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 ittype 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 ittype 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 itfunction readTextFile(path: PathLike): Promise<string>A file's text, read as UTF-8.
fs.readTextFileSyncfunctionno test imports itfunction readTextFileSync(path: PathLike): stringA file's text, read as UTF-8, without waiting.
fs.readFilefunctionno test imports itfunction readFile(path: PathLike): Promise<Uint8Array<ArrayBufferLike>>A file's bytes.
fs.readFileSyncfunctionno test imports itfunction readFileSync(path: PathLike): Uint8Array<ArrayBufferLike>A file's bytes, without waiting.
fs.writeTextFilefunctionno test imports itfunction 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 itfunction writeTextFileSync(path: PathLike, data: string, options?: WriteFileOptions): voidText written to a file as UTF-8, without waiting.
fs.writeFilefunctionno test imports itfunction writeFile(path: PathLike, data: Uint8Array<ArrayBufferLike>, options?: WriteFileOptions): Promise<void>Bytes written to a file, replacing it unless append.
fs.writeFileSyncfunctionno test imports itfunction writeFileSync(path: PathLike, data: Uint8Array<ArrayBufferLike>, options?: WriteFileOptions): voidBytes written to a file, without waiting.
fs.RemoveOptionstypeno test imports ittype RemoveOptions = { readonly recursive?: boolean };How to remove: a folder and everything in it only with recursive.
fs.removefunctionno test imports itfunction 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 itfunction removeSync(path: PathLike, options?: RemoveOptions): voidThe same, without waiting.
fs.MkdirOptionstypeno test imports ittype 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 itfunction mkdir(path: PathLike, options?: MkdirOptions): Promise<void>A folder made.
fs.mkdirSyncfunctionno test imports itfunction mkdirSync(path: PathLike, options?: MkdirOptions): voidA folder made, without waiting.
fs.statfunctionno test imports itfunction stat(path: PathLike): Promise<FileInfo>What is at a path, following links.
fs.statSyncfunctionno test imports itfunction statSync(path: PathLike): FileInfoWhat is at a path, following links, without waiting.
fs.lstatfunctionno test imports itfunction lstat(path: PathLike): Promise<FileInfo>What is at a path; a link is described, not followed.
fs.lstatSyncfunctionno test imports itfunction lstatSync(path: PathLike): FileInfoWhat is at a path; a link is described, not followed; without waiting.
fs.readDirfunctionno test imports itfunction 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 itfunction readDirSync(path: PathLike): DirEntry[]The entries of a folder, without waiting.
fs.MakeTempOptionstypeno test imports ittype 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 itfunction makeTempDir(options?: MakeTempOptions): Promise<string>A new, empty, private folder, and its path.
fs.makeTempDirSyncfunctionno test imports itfunction makeTempDirSync(options?: MakeTempOptions): stringA new, empty, private folder, without waiting.
fs.makeTempFilefunctionno test imports itfunction makeTempFile(options?: MakeTempOptions): Promise<string>A new, empty, private file, and its path.
fs.renamefunctionno test imports itfunction rename(from: PathLike, to: PathLike): Promise<void>A file or folder moved to a new path, replacing a file there.
fs.renameSyncfunctionno test imports itfunction renameSync(from: PathLike, to: PathLike): voidThe same, without waiting.
fs.copyFilefunctionno test imports itfunction copyFile(from: PathLike, to: PathLike): Promise<void>A file's bytes copied to a new path, replacing a file there.
fs.chmodfunctionno test imports itfunction chmod(path: PathLike, mode: number): Promise<void>A file's mode changed (ignored on Windows, which has none).
fs.linkfunctionno test imports itfunction 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 itfunction 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 itfunction readLink(path: PathLike): Promise<string>Where a link points, as it was written.
fs.realPathfunctionno test imports itfunction realPath(path: PathLike): Promise<string>The absolute path with every link followed.
fs.truncatefunctionno test imports itfunction truncate(path: PathLike, length?: number): Promise<void>A file cut (or extended with zeros) to length bytes, 0 by default.
fs.utimefunctionno test imports itfunction utime(path: PathLike, atime: number | Date, mtime: number | Date): Promise<void>A file's access and modification times set.
fs.existsfunctionno test imports itfunction 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 itfunction existsSync(path: PathLike): booleanThe same, without waiting.
fs.readTextOrfunctionno test imports itfunction 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 itfunction ensureDir(path: PathLike): Promise<void>A folder and its parents made, where missing.
fs.writeIfChangedfunctionno test imports itfunction 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 itfunction listDirs(path: PathLike): Promise<string[]>The names of the folders directly in path, sorted; none where it does not exist.
fs.listFilesfunctionno test imports itfunction 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 itfunction 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 itfunction 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 itfunction 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 itfunction 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 itfunction symlinkSync(target: PathLike, path: PathLike, options?: { readonly type?: "dir" | "file" | "junction" | undefined; }): voidA link at path that points at target, without waiting; type matters on Windows only (junction: see symlink).
fs.OpenOptionstypeno test imports ittype 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 ittype 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 itclass FsFile implements Disposable, AsyncDisposableAn 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.
| Member | Type | What 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 | null | The 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>) => number | The 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) => number | The 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) => void | The same, without waiting. |
stat | () => Promise<FileInfo> | What the open file is. |
statSync | () => FileInfo | The same, without waiting. |
sync | () => Promise<void> | The file's data and metadata written through to the disk. |
syncSync | () => void | The same, without waiting. |
readable | ReadableStream<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. |
writable | WritableStream<Uint8Array<ArrayBufferLike>> | A stream whose chunks are written whole at the position, closing the file when it is closed or aborted. |
close | () => void | The file closed; closing it again does nothing. |
__@dispose@281474976713631 | () => void | Closed at the end of a using block. |
__@asyncDispose@281474976747252 | () => Promise<void> | Closed at the end of an await using block. |
fs.openfunctionno test imports itfunction 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 itfunction openSync(path: PathLike, options?: OpenOptions): FsFileThe same, without waiting.
fs.CopyOptionstypeno test imports ittype 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 itfunction 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 ittype 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 ittype 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 itfunction 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 ittype 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 itfunction 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 ittype PathLike = string | URL;A path, as a string or a file: URL.
FileInfotypeno test imports ittype 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 ittype DirEntry = { readonly name: string; readonly isFile: boolean; readonly isDirectory: boolean; readonly isSymlink: boolean };One entry of a folder, by these names.
WriteFileOptionstypeno test imports ittype 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.
readTextFilefunctionfunction readTextFile(path: PathLike): Promise<string>A file's text, read as UTF-8.
readTextFileSyncfunctionno test imports itfunction readTextFileSync(path: PathLike): stringA file's text, read as UTF-8, without waiting.
readFilefunctionfunction readFile(path: PathLike): Promise<Uint8Array<ArrayBufferLike>>A file's bytes.
readFileSyncfunctionno test imports itfunction readFileSync(path: PathLike): Uint8Array<ArrayBufferLike>A file's bytes, without waiting.
writeTextFilefunctionfunction writeTextFile(path: PathLike, data: string, options?: WriteFileOptions): Promise<void>Text written to a file as UTF-8, replacing it unless append.
writeTextFileSyncfunctionno test imports itfunction writeTextFileSync(path: PathLike, data: string, options?: WriteFileOptions): voidText written to a file as UTF-8, without waiting.
writeFilefunctionfunction writeFile(path: PathLike, data: Uint8Array<ArrayBufferLike>, options?: WriteFileOptions): Promise<void>Bytes written to a file, replacing it unless append.
writeFileSyncfunctionno test imports itfunction writeFileSync(path: PathLike, data: Uint8Array<ArrayBufferLike>, options?: WriteFileOptions): voidBytes written to a file, without waiting.
RemoveOptionstypeno test imports ittype RemoveOptions = { readonly recursive?: boolean };How to remove: a folder and everything in it only with recursive.
removefunctionfunction 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.
removeSyncfunctionno test imports itfunction removeSync(path: PathLike, options?: RemoveOptions): voidThe same, without waiting.
MkdirOptionstypeno test imports ittype 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.
mkdirfunctionfunction mkdir(path: PathLike, options?: MkdirOptions): Promise<void>A folder made.
mkdirSyncfunctionno test imports itfunction mkdirSync(path: PathLike, options?: MkdirOptions): voidA folder made, without waiting.
statfunctionfunction stat(path: PathLike): Promise<FileInfo>What is at a path, following links.
statSyncfunctionno test imports itfunction statSync(path: PathLike): FileInfoWhat is at a path, following links, without waiting.
lstatfunctionno test imports itfunction lstat(path: PathLike): Promise<FileInfo>What is at a path; a link is described, not followed.
lstatSyncfunctionno test imports itfunction lstatSync(path: PathLike): FileInfoWhat is at a path; a link is described, not followed; without waiting.
readDirfunctionno test imports itfunction 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 itfunction readDirSync(path: PathLike): DirEntry[]The entries of a folder, without waiting.
MakeTempOptionstypeno test imports ittype 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 itfunction makeTempDir(options?: MakeTempOptions): Promise<string>A new, empty, private folder, and its path.
makeTempDirSyncfunctionno test imports itfunction makeTempDirSync(options?: MakeTempOptions): stringA new, empty, private folder, without waiting.
makeTempFilefunctionno test imports itfunction makeTempFile(options?: MakeTempOptions): Promise<string>A new, empty, private file, and its path.
renamefunctionfunction rename(from: PathLike, to: PathLike): Promise<void>A file or folder moved to a new path, replacing a file there.
renameSyncfunctionno test imports itfunction renameSync(from: PathLike, to: PathLike): voidThe same, without waiting.
copyFilefunctionno test imports itfunction copyFile(from: PathLike, to: PathLike): Promise<void>A file's bytes copied to a new path, replacing a file there.
chmodfunctionfunction chmod(path: PathLike, mode: number): Promise<void>A file's mode changed (ignored on Windows, which has none).
linkfunctionno test imports itfunction 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 itfunction 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 itfunction readLink(path: PathLike): Promise<string>Where a link points, as it was written.
realPathfunctionfunction realPath(path: PathLike): Promise<string>The absolute path with every link followed.
truncatefunctionno test imports itfunction truncate(path: PathLike, length?: number): Promise<void>A file cut (or extended with zeros) to length bytes, 0 by default.
utimefunctionfunction utime(path: PathLike, atime: number | Date, mtime: number | Date): Promise<void>A file's access and modification times set.
existsfunctionfunction 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.
existsSyncfunctionno test imports itfunction existsSync(path: PathLike): booleanThe same, without waiting.
readTextOrfunctionno test imports itfunction 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 itfunction ensureDir(path: PathLike): Promise<void>A folder and its parents made, where missing.
writeIfChangedfunctionno test imports itfunction 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 itfunction listDirs(path: PathLike): Promise<string[]>The names of the folders directly in path, sorted; none where it does not exist.
listFilesfunctionno test imports itfunction 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 itfunction 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.
sha256Filefunctionfunction sha256File(path: PathLike): Promise<Sha256>The SHA-256 of a file, read as a stream so a large file is not held in memory.
withTempDirfunctionfunction 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.
chownfunctionno test imports itfunction 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 itfunction symlinkSync(target: PathLike, path: PathLike, options?: { readonly type?: "dir" | "file" | "junction" | undefined; }): voidA link at path that points at target, without waiting; type matters on Windows only (junction: see symlink).
OpenOptionstypeno test imports ittype 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 ittype 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 itclass FsFile implements Disposable, AsyncDisposableAn 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.
| Member | Type | What 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 | null | The 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>) => number | The 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) => number | The 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) => void | The same, without waiting. |
stat | () => Promise<FileInfo> | What the open file is. |
statSync | () => FileInfo | The same, without waiting. |
sync | () => Promise<void> | The file's data and metadata written through to the disk. |
syncSync | () => void | The same, without waiting. |
readable | ReadableStream<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. |
writable | WritableStream<Uint8Array<ArrayBufferLike>> | A stream whose chunks are written whole at the position, closing the file when it is closed or aborted. |
close | () => void | The file closed; closing it again does nothing. |
__@dispose@281474976713631 | () => void | Closed at the end of a using block. |
__@asyncDispose@281474976747252 | () => Promise<void> | Closed at the end of an await using block. |
openfunctionno test imports itfunction 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 itfunction openSync(path: PathLike, options?: OpenOptions): FsFileThe same, without waiting.
CopyOptionstypeno test imports ittype 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 itfunction 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 ittype 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 ittype 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 itfunction 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 ittype 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 itfunction 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.