@visulima/fs
Advanced tools
Human friendly file system utilities for Node.js
[
][typescript-url] [![npm-image]][npm-url] [![license-image]][license-url]
Daniel Bannert's open source work is supported by the community on GitHub Sponsors
npm install @visulima/fs
yarn add @visulima/fs
pnpm add @visulima/fs
Note: If you want to parse or write YAML, you'll need to install
yamlas well.
npm install yaml
yarn add yaml
pnpm add yaml
After installing
yaml, you can use thereadYaml,readYamlSyncandwriteYaml,writeYamlSyncfunctions from@visulima/fs/yaml.
import { walk } from "@visulima/fs";
const filesAndFolders: string[] = [];
for await (const index of walk(`${__dirname}/fixtures`, {})) {
filesAndFolders.push(index.path);
}
console.log(filesAndFolders);
import { walkSync } from "@visulima/fs";
const filesAndFolders: string[] = [];
for (const index of walkSync(`${__dirname}/fixtures`, {})) {
filesAndFolders.push(index.path);
}
console.log(filesAndFolders);
walk and walkSyncType: string
The directory to start from.
Type: object
Type: number
Default: Infinity
Optional: true
Description: The maximum depth of the file tree to be walked recursively.
Type: boolean
Default: true
Optional: true
Description: Indicates whether file entries should be included or not.
Type: boolean
Default: true
Optional: true
Description: Indicates whether directory entries should be included or not.
Type: boolean
Default: true
Optional: true
Description: Indicates whether symlink entries should be included or not. This option is meaningful only if followSymlinks is set to false.
Type: boolean
Default: false
Optional: true
Description: Indicates whether symlinks should be resolved or not.
Type: string[]
Default: undefined
Optional: true
Description: List of file extensions used to filter entries. If specified, entries without the file extension specified by this option are excluded.
Type: (RegExp | string)[]
Default: undefined
Optional: true
Description: List of regular expression or glob patterns used to filter entries. If specified, entries that do not match the patterns specified by this option are excluded.
Type: (RegExp | string)[]
Default: undefined
Optional: true
Description: List of regular expression or glob patterns used to filter entries. If specified, entries matching the patterns specified by this option are excluded.
Find a file or directory by walking up parent directories.
import { findUp } from "@visulima/fs";
// Returns a Promise for the found path or undefined if it could not be found.
const file = await findUp("package.json");
console.log(file);
Find a file or directory by walking up parent directories.
import { findUpSync } from "@visulima/fs";
// Returns the found path or undefined if it could not be found.
const file = findUpSync("package.json");
console.log(file);
findUp and findUpSyncType: string[] | string | ((directory: PathLike) => PathLike | Promise<PathLike | typeof FIND_UP_STOP> | typeof FIND_UP_STOP)
Sync Type: string[] | string | ((directory: PathLike) => PathLike | typeof FIND_UP_STOP)
The name of the file or directory to find.
If an array is specified, the first item that exists will be returned.
A function that will be called with each directory until it returns a string with the path, which stops the search, or the root directory has been reached and nothing was found. Useful if you want to match files with certain patterns, set of permissions, or other advanced use-cases.
When using async mode, the matcher may optionally be an async or promise-returning function that returns the path.
Type: object
Type: URL | string
Default: process.cwd()
The directory to start from.
Type: string
Default: 'file'
Values: 'file' | 'directory'
The type of path to match.
Type: URL | string
Default: Root directory
A directory path where the search halts if no matches are found before reaching this point.
Type: boolean
Default: true
Allow symbolic links to match if they point to the target file or directory.
Read a file.
import { readFile } from "@visulima/fs";
// Returns a Promise for the file contents.
const file = await readFile("package.json");
console.log(file);
Read a file.
import { readFileSync } from "@visulima/fs";
// Returns the file contents.
const file = readFileSync("package.json");
console.log(file);
readFile and readFileSyncType: string
The path to the file to read.
Type: object
Type: boolean
Default: true
Optional: true
Description: Indicates whether the file contents should be returned as a Buffer or a string.
Type: "brotli" | "gzip" | undefined
Default: undefined
Optional: true
Description: The file compression.
Type: "ascii" | "base64" | "base64url" | "hex" | "latin1" | "ucs-2" | "ucs2" | "utf-8" | "utf-16le" | "utf8" | "utf16le" | undefined
Default: utf8
Optional: true
Type: number | string | undefined
Default: 'r'
Optional: true
Check if a file or directory exists and is accessible.
import { isAccessible } from "@visulima/fs";
// Returns a Promise for the result.
const file = await isAccessible("package.json");
console.log(file);
Check if a file or directory exists and is accessible.
import { isAccessibleSync } from "@visulima/fs";
// Returns the result.
const file = isAccessibleSync("package.json");
console.log(file);
isAccessible and isAccessibleSyncType: string
The path to the file or directory to check.
Type: number
Default: fs.constants.F_OK
Optional: true
Description: The accessibility mode.
Parse JSON with more helpful errors.
import { parseJson, JSONError } from "@visulima/fs/utils";
const json = '{\n\t"foo": true,\n}';
JSON.parse(json);
/*
undefined:3
}
^
SyntaxError: Unexpected token }
*/
parseJson(json);
/*
JSONError: Unexpected token } in JSON at position 16 while parsing near '{ "foo": true,}'
1 | {
2 | "foo": true,
> 3 | }
| ^
*/
parseJson(json, "foo.json");
/*
JSONError: Unexpected token } in JSON at position 16 while parsing near '{ "foo": true,}' in foo.json
1 | {
2 | "foo": true,
> 3 | }
| ^
*/
parseJsonType: string
The JSON string to parse.
Type: Function
Prescribes how the value originally produced by parsing is transformed, before being returned. See JSON.parse docs for more.
Type: string
The filename to use in error messages.
JSONErrorExposed for use in instanceof checks.
Type: string
The filename displayed in the error message.
Type: string
The printable section of the JSON which produces the error.
Defined in: packages/fs/src/error/already-exists-error.ts:4
Error thrown when file already exists.
Errornew AlreadyExistsError(message): AlreadyExistsError
Defined in: packages/fs/src/error/already-exists-error.ts:9
Creates a new instance.
string
The error message.
Error.constructor
get code(): string
Defined in: packages/fs/src/error/already-exists-error.ts:14
string
set code(_name): void
Defined in: packages/fs/src/error/already-exists-error.ts:19
string
void
get name(): string
Defined in: packages/fs/src/error/already-exists-error.ts:24
string
set name(_name): void
Defined in: packages/fs/src/error/already-exists-error.ts:29
string
void
Error.name
static captureStackTrace(targetObject, constructorOpt?): void
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:91
Create .stack property on a target object
object
Function
void
Error.captureStackTrace
optional cause: unknown;
Defined in: node_modules/.pnpm/typescript@5.7.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
Error.cause
message: string;
Defined in: node_modules/.pnpm/typescript@5.7.3/node_modules/typescript/lib/lib.es5.d.ts:1077
Error.message
optional stack: string;
Defined in: node_modules/.pnpm/typescript@5.7.3/node_modules/typescript/lib/lib.es5.d.ts:1078
Error.stack
static optional prepareStackTrace: (err, stackTraces) => any;
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:98
Optional override for formatting stack traces
Error
CallSite[]
any
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
Error.prepareStackTrace
static stackTraceLimit: number;
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:100
Error.stackTraceLimit
Defined in: packages/fs/src/error/directory-error.ts:4
Error thrown when an operation is not allowed on a directory.
Errornew DirectoryError(message): DirectoryError
Defined in: packages/fs/src/error/directory-error.ts:9
Creates a new instance.
string
The error message.
Error.constructor
get code(): string
Defined in: packages/fs/src/error/directory-error.ts:14
string
set code(_name): void
Defined in: packages/fs/src/error/directory-error.ts:19
string
void
get name(): string
Defined in: packages/fs/src/error/directory-error.ts:24
string
set name(_name): void
Defined in: packages/fs/src/error/directory-error.ts:29
string
void
Error.name
static captureStackTrace(targetObject, constructorOpt?): void
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:91
Create .stack property on a target object
object
Function
void
Error.captureStackTrace
optional cause: unknown;
Defined in: node_modules/.pnpm/typescript@5.7.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
Error.cause
message: string;
Defined in: node_modules/.pnpm/typescript@5.7.3/node_modules/typescript/lib/lib.es5.d.ts:1077
Error.message
optional stack: string;
Defined in: node_modules/.pnpm/typescript@5.7.3/node_modules/typescript/lib/lib.es5.d.ts:1078
Error.stack
static optional prepareStackTrace: (err, stackTraces) => any;
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:98
Optional override for formatting stack traces
Error
CallSite[]
any
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
Error.prepareStackTrace
static stackTraceLimit: number;
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:100
Error.stackTraceLimit
Defined in: packages/fs/src/error/not-empty-error.ts:4
Error thrown when a directory is not empty.
Errornew NotEmptyError(message): NotEmptyError
Defined in: packages/fs/src/error/not-empty-error.ts:9
Creates a new instance.
string
The error message.
Error.constructor
get code(): string
Defined in: packages/fs/src/error/not-empty-error.ts:14
string
set code(_name): void
Defined in: packages/fs/src/error/not-empty-error.ts:19
string
void
get name(): string
Defined in: packages/fs/src/error/not-empty-error.ts:24
string
set name(_name): void
Defined in: packages/fs/src/error/not-empty-error.ts:29
string
void
Error.name
static captureStackTrace(targetObject, constructorOpt?): void
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:91
Create .stack property on a target object
object
Function
void
Error.captureStackTrace
optional cause: unknown;
Defined in: node_modules/.pnpm/typescript@5.7.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
Error.cause
message: string;
Defined in: node_modules/.pnpm/typescript@5.7.3/node_modules/typescript/lib/lib.es5.d.ts:1077
Error.message
optional stack: string;
Defined in: node_modules/.pnpm/typescript@5.7.3/node_modules/typescript/lib/lib.es5.d.ts:1078
Error.stack
static optional prepareStackTrace: (err, stackTraces) => any;
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:98
Optional override for formatting stack traces
Error
CallSite[]
any
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
Error.prepareStackTrace
static stackTraceLimit: number;
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:100
Error.stackTraceLimit
Defined in: packages/fs/src/error/not-found-error.ts:4
Error thrown when a file or directory is not found.
Errornew NotFoundError(message): NotFoundError
Defined in: packages/fs/src/error/not-found-error.ts:9
Creates a new instance.
string
The error message.
Error.constructor
get code(): string
Defined in: packages/fs/src/error/not-found-error.ts:14
string
set code(_name): void
Defined in: packages/fs/src/error/not-found-error.ts:19
string
void
get name(): string
Defined in: packages/fs/src/error/not-found-error.ts:24
string
set name(_name): void
Defined in: packages/fs/src/error/not-found-error.ts:29
string
void
Error.name
static captureStackTrace(targetObject, constructorOpt?): void
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:91
Create .stack property on a target object
object
Function
void
Error.captureStackTrace
optional cause: unknown;
Defined in: node_modules/.pnpm/typescript@5.7.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
Error.cause
message: string;
Defined in: node_modules/.pnpm/typescript@5.7.3/node_modules/typescript/lib/lib.es5.d.ts:1077
Error.message
optional stack: string;
Defined in: node_modules/.pnpm/typescript@5.7.3/node_modules/typescript/lib/lib.es5.d.ts:1078
Error.stack
static optional prepareStackTrace: (err, stackTraces) => any;
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:98
Optional override for formatting stack traces
Error
CallSite[]
any
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
Error.prepareStackTrace
static stackTraceLimit: number;
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:100
Error.stackTraceLimit
Defined in: packages/fs/src/error/permission-error.ts:4
Error thrown when an operation is not permitted.
Errornew PermissionError(message): PermissionError
Defined in: packages/fs/src/error/permission-error.ts:9
Creates a new instance.
string
The error message.
Error.constructor
get code(): string
Defined in: packages/fs/src/error/permission-error.ts:14
string
set code(_name): void
Defined in: packages/fs/src/error/permission-error.ts:19
string
void
get name(): string
Defined in: packages/fs/src/error/permission-error.ts:24
string
set name(_name): void
Defined in: packages/fs/src/error/permission-error.ts:29
string
void
Error.name
static captureStackTrace(targetObject, constructorOpt?): void
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:91
Create .stack property on a target object
object
Function
void
Error.captureStackTrace
optional cause: unknown;
Defined in: node_modules/.pnpm/typescript@5.7.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
Error.cause
message: string;
Defined in: node_modules/.pnpm/typescript@5.7.3/node_modules/typescript/lib/lib.es5.d.ts:1077
Error.message
optional stack: string;
Defined in: node_modules/.pnpm/typescript@5.7.3/node_modules/typescript/lib/lib.es5.d.ts:1078
Error.stack
static optional prepareStackTrace: (err, stackTraces) => any;
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:98
Optional override for formatting stack traces
Error
CallSite[]
any
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
Error.prepareStackTrace
static stackTraceLimit: number;
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:100
Error.stackTraceLimit
Defined in: packages/fs/src/error/walk-error.ts:7
Error thrown in walk or walkSync during iteration.
Errornew WalkError(cause, root): WalkError
Defined in: packages/fs/src/error/walk-error.ts:12
Constructs a new instance.
unknown
string
Error.constructor
get name(): string
Defined in: packages/fs/src/error/walk-error.ts:21
string
set name(_name): void
Defined in: packages/fs/src/error/walk-error.ts:26
string
void
Error.name
static captureStackTrace(targetObject, constructorOpt?): void
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:91
Create .stack property on a target object
object
Function
void
Error.captureStackTrace
optional cause: unknown;
Defined in: node_modules/.pnpm/typescript@5.7.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
Error.cause
message: string;
Defined in: node_modules/.pnpm/typescript@5.7.3/node_modules/typescript/lib/lib.es5.d.ts:1077
Error.message
root: string;
Defined in: packages/fs/src/error/walk-error.ts:9
File path of the root that's being walked.
optional stack: string;
Defined in: node_modules/.pnpm/typescript@5.7.3/node_modules/typescript/lib/lib.es5.d.ts:1078
Error.stack
static optional prepareStackTrace: (err, stackTraces) => any;
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:98
Optional override for formatting stack traces
Error
CallSite[]
any
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
Error.prepareStackTrace
static stackTraceLimit: number;
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:100
Error.stackTraceLimit
Re-exports JSONError
function collect(directory, options): Promise<string[]>
Defined in: packages/fs/src/find/collect.ts:4
string
WalkOptions = {}
Promise<string[]>
function collectSync(directory, options): string[]
Defined in: packages/fs/src/find/collect-sync.ts:4
string
WalkOptions = {}
string[]
function detect(content): "\n" | "\r\n"
Defined in: packages/fs/src/eol.ts:20
Detect the EOL character for string input. Returns null if no newline.
string
"\n" | "\r\n"
function emptyDir(dir, options?): Promise<void>
Defined in: packages/fs/src/remove/empty-dir.ts:19
Ensures that a directory is empty. Deletes directory contents if the directory is not empty. If the directory does not exist, it is created. The directory itself is not deleted.
string | URL
Promise<void>
function emptyDirSync(dir, options?): void
Defined in: packages/fs/src/remove/empty-dir-sync.ts:18
Ensures that a directory is empty. Deletes directory contents if the directory is not empty. If the directory does not exist, it is created. The directory itself is not deleted.
string | URL
void
function ensureDir(directory): Promise<void>
Defined in: packages/fs/src/ensure/ensure-dir.ts:12
Ensures that the directory exists. If the directory structure does not exist, it is created. Like mkdir -p.
string | URL
Promise<void>
function ensureDirSync(directory): void
Defined in: packages/fs/src/ensure/ensure-dir-sync.ts:12
Ensures that the directory exists. If the directory structure does not exist, it is created. Like mkdir -p.
string | URL
void
function ensureFile(filePath): Promise<void>
Defined in: packages/fs/src/ensure/ensure-file.ts:16
Ensures that the file exists. If the file that is requested to be created is in directories that do not exist, these directories are created. If the file already exists, it is NOTMODIFIED.
string | URL
Promise<void>
function ensureFileSync(filePath): void
Defined in: packages/fs/src/ensure/ensure-file-sync.ts:16
Ensures that the file exists. If the file that is requested to be created is in directories that do not exist, these directories are created. If the file already exists, it is NOTMODIFIED.
string | URL
void
function ensureLink(source, destination): Promise<void>
Defined in: packages/fs/src/ensure/ensure-link.ts:15
Ensures that the hard link exists. If the directory structure does not exist, it is created.
string | URL
string | URL
Promise<void>
function ensureLinkSync(source, destination): void
Defined in: packages/fs/src/ensure/ensure-link-sync.ts:15
Ensures that the hard link exists. If the directory structure does not exist, it is created.
string | URL
string | URL
void
function ensureSymlink(
target,
linkName,
type?): Promise<void>
Defined in: packages/fs/src/ensure/ensure-symlink.ts:28
Ensures that the link exists, and points to a valid file. If the directory structure does not exist, it is created. If the link already exists, it is not modified but error is thrown if it is not point to the given target.
the source file path
string | URL
the destination link path
string | URL
Type
the type of the symlink, or null to use automatic detection
Promise<void>
A void promise that resolves once the link exists.
function ensureSymlinkSync(
target,
linkName,
type?): void
Defined in: packages/fs/src/ensure/ensure-symlink-sync.ts:28
Ensures that the link exists, and points to a valid file. If the directory structure does not exist, it is created. If the link already exists, it is not modified but error is thrown if it is not point to the given target.
the source file path
string | URL
the destination link path
string | URL
Type
the type of the symlink, or null to use automatic detection
void
A void.
function findUp(name, options): Promise<string>
Defined in: packages/fs/src/find/find-up.ts:11
FindUpOptions = {}
Promise<string>
function findUpSync(name, options): string
Defined in: packages/fs/src/find/find-up-sync.ts:11
FindUpOptions = {}
string
function format(content, eol): string
Defined in: packages/fs/src/eol.ts:36
Format the file to the targeted EOL.
string
"\n" | "\r\n"
string
function isAccessible(path, mode?): Promise<boolean>
Defined in: packages/fs/src/is-accessible.ts:9
Returns a Promise that resolves to a boolean indicating if the path is accessible or not.
string | URL
number
Promise<boolean>
function isAccessibleSync(path, mode?): boolean
Defined in: packages/fs/src/is-accessible-sync.ts:9
Returns a boolean indicating if the path is accessible or not.
string | URL
number
boolean
function move(
sourcePath,
destinationPath,
options): Promise<void>
Defined in: packages/fs/src/move/index.ts:35
Move a file asynchronously.
string
The file you want to move.
string
Where you want the file moved.
MoveOptions = {}
Configuration options.
Promise<void>
A Promise that resolves when the file has been moved.
import { moveFile } from '@visulima/fs';
await moveFile('source/test.png', 'destination/test.png');
console.log('The file has been moved');
function moveSync(
sourcePath,
destinationPath,
options?): void
Defined in: packages/fs/src/move/index.ts:61
Move a file synchronously.
string
The file you want to move.
string
Where you want the file moved.
Configuration options.
void
Nothing is returned.
import { moveFileSync } from '@visulima/fs';
moveFileSync('source/test.png', 'destination/test.png');
console.log('The file has been moved');
function readFile<O>(path, options?): Promise<ContentType<O>>
Defined in: packages/fs/src/read/read-file.ts:20
• O extends ReadFileOptions<"brotli" | "gzip" | "none"> = undefined
string | URL
O
Promise<ContentType<O>>
function readFileSync<O>(path, options?): ContentType<O>
Defined in: packages/fs/src/read/read-file-sync.ts:18
• O extends ReadFileOptions<"brotli" | "gzip" | "none"> = undefined
string | URL
O
ContentType<O>
function readJson<T>(path, options?): Promise<T>
Defined in: packages/fs/src/read/read-json.ts:8
• T extends JsonValue
string | URL
Promise<T>
function readJson<T>(
path,
reviver,
options?): Promise<T>
Defined in: packages/fs/src/read/read-json.ts:10
• T extends JsonValue
string | URL
(this, key, value) => any
Promise<T>
function readJsonSync<T>(path, options?): T
Defined in: packages/fs/src/read/read-json-sync.ts:8
• T extends JsonValue
string | URL
T
function readJsonSync<T>(
path,
reviver,
options?): T
Defined in: packages/fs/src/read/read-json-sync.ts:10
• T extends JsonValue
string | URL
(this, key, value) => any
T
function remove(path, options): Promise<void>
Defined in: packages/fs/src/remove/remove.ts:5
string | URL
number
If an EBUSY, EMFILE, ENFILE, ENOTEMPTY, or
EPERM error is encountered, Node.js will retry the operation with a linear
backoff wait of retryDelay ms longer on each try. This option represents the
number of retries. This option is ignored if the recursive option is not
true.
Default
0
number
The amount of time in milliseconds to wait between retries.
This option is ignored if the recursive option is not true.
Default
100
Promise<void>
function removeSync(path, options): void
Defined in: packages/fs/src/remove/remove-sync.ts:5
string | URL
number
If an EBUSY, EMFILE, ENFILE, ENOTEMPTY, or
EPERM error is encountered, Node.js will retry the operation with a linear
backoff wait of retryDelay ms longer on each try. This option represents the
number of retries. This option is ignored if the recursive option is not
true.
Default
0
number
The amount of time in milliseconds to wait between retries.
This option is ignored if the recursive option is not true.
Default
100
void
function rename(
source,
destination,
options?): Promise<void>
Defined in: packages/fs/src/move/index.ts:85
Rename a file asynchronously.
string
The file you want to rename.
string
The name of the renamed file.
Configuration options.
Promise<void>
A Promise that resolves when the file has been renamed.
import { renameFile } from '@visulima/fs';
await renameFile('test.png', 'tests.png', {cwd: 'source'});
console.log('The file has been renamed');
function renameSync(
source,
destination,
options?): void
Defined in: packages/fs/src/move/index.ts:109
Rename a file synchronously.
string
The file you want to rename.
string
The name of the renamed file.
Configuration options.
void
A Promise that resolves when the file has been renamed.
import {renameFileSync} from '@visulima/fs';
renameFileSync('test.png', 'tests.png', {cwd: 'source'});
console.log('The file has been renamed');
function walk(directory, __namedParameters): AsyncIterableIterator<WalkEntry>
Defined in: packages/fs/src/find/walk.ts:52
Walks the file tree rooted at root, yielding each file or directory in the tree filtered according to the given options. Options:
string | URL
WalkOptions = {}
AsyncIterableIterator<WalkEntry>
function walkSync(directory, __namedParameters): IterableIterator<WalkEntry>
Defined in: packages/fs/src/find/walk-sync.ts:40
Same as walk but uses synchronous ops
string | URL
WalkOptions = {}
IterableIterator<WalkEntry>
function writeFile(
path,
content,
options?): Promise<void>
Defined in: packages/fs/src/write/write-file.ts:15
string | URL
string | ArrayBuffer | ArrayBufferView
Promise<void>
function writeFileSync(
path,
content,
options?): void
Defined in: packages/fs/src/write/write-file-sync.ts:15
string | URL
string | ArrayBuffer | ArrayBufferView
void
function writeJson(
path,
data,
options): Promise<void>
Defined in: packages/fs/src/write/write-json.ts:11
string | URL
unknown
WriteJsonOptions = {}
Promise<void>
function writeJsonSync(
path,
data,
options): void
Defined in: packages/fs/src/write/write-json-sync.ts:11
string | URL
unknown
WriteJsonOptions = {}
void
const CRLF: "\r\n";
Defined in: packages/fs/src/eol.ts:9
End-of-line character for Windows platforms.
const EOL: "\n" | "\r\n";
Defined in: packages/fs/src/eol.ts:14
End-of-line character evaluated for the current platform.
const F_OK: 0 = 0;
Defined in: packages/fs/src/constants.ts:2
Is the path visible to the calling process?
const FIND_UP_STOP: typeof FIND_UP_STOP;
Defined in: packages/fs/src/constants.ts:13
const LF: "\n";
Defined in: packages/fs/src/eol.ts:6
End-of-line character for POSIX platforms such as macOS and Linux.
const R_OK: 4 = 4;
Defined in: packages/fs/src/constants.ts:5
Is the path readable to the calling process?
const W_OK: 2 = 2;
Defined in: packages/fs/src/constants.ts:8
Is the path writable to the calling process?
const X_OK: 1 = 1;
Defined in: packages/fs/src/constants.ts:11
Is the path executable to the calling process?
Defined in: packages/fs/src/types.ts:56
Pick<Dirent, "isDirectory" | "isFile" | "isSymbolicLink" | "name">isDirectory(): boolean
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/fs.d.ts:190
Returns true if the fs.Dirent object describes a file system
directory.
boolean
v10.10.0
Pick.isDirectory
isFile(): boolean
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/fs.d.ts:184
Returns true if the fs.Dirent object describes a regular file.
boolean
v10.10.0
Pick.isFile
isSymbolicLink(): boolean
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/fs.d.ts:205
Returns true if the fs.Dirent object describes a symbolic link.
boolean
v10.10.0
Pick.isSymbolicLink
name: string;
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/fs.d.ts:222
The file name that this fs.Dirent object refers to. The type of this
value is determined by the options.encoding passed to readdir or readdirSync.
v10.10.0
Pick.name
path: string;
Defined in: packages/fs/src/types.ts:57
Defined in: packages/fs/src/types.ts:9
optional extensions: string[];
Defined in: packages/fs/src/types.ts:15
List of file extensions used to filter entries. If specified, entries without the file extension specified by this option are excluded.
{undefined}
optional followSymlinks: boolean;
Defined in: packages/fs/src/types.ts:20
Indicates whether symlinks should be resolved or not.
{false}
optional includeDirs: boolean;
Defined in: packages/fs/src/types.ts:25
Indicates whether directory entries should be included or not.
{true}
optional includeFiles: boolean;
Defined in: packages/fs/src/types.ts:30
Indicates whether file entries should be included or not.
{true}
optional includeSymlinks: boolean;
Defined in: packages/fs/src/types.ts:36
Indicates whether symlink entries should be included or not.
This option is meaningful only if followSymlinks is set to false.
{true}
optional match: (string | RegExp)[];
Defined in: packages/fs/src/types.ts:42
List of regular expression or glob patterns used to filter entries. If specified, entries that do not match the patterns specified by this option are excluded.
{undefined}
optional maxDepth: number;
Defined in: packages/fs/src/types.ts:47
The maximum depth of the file tree to be walked recursively.
{Infinity}
optional skip: (string | RegExp)[];
Defined in: packages/fs/src/types.ts:53
List of regular expression or glob patterns used to filter entries. If specified, entries matching the patterns specified by this option are excluded.
{undefined}
type CodeFrameLocation = object;
Defined in: packages/fs/src/types.ts:91
optional column: number;
line: number;
type EmptyDirOptions = object;
Defined in: packages/fs/src/types.ts:188
optional maxRetries: number;
If an EBUSY, EMFILE, ENFILE, ENOTEMPTY, or
EPERM error is encountered, Node.js will retry the operation with a linear
backoff wait of retryDelay ms longer on each try. This option represents the
number of retries. This option is ignored if the recursive option is not
true.
0
optional retryDelay: number;
The amount of time in milliseconds to wait between retries.
This option is ignored if the recursive option is not true.
100
type FindUpName =
| string[]
| string
| (directory) => FindUpNameFnResult;
Defined in: packages/fs/src/types.ts:180
type FindUpNameFnResult =
| PathLike
| Promise<PathLike | typeof FIND_UP_STOP>
| typeof FIND_UP_STOP
| undefined;
Defined in: packages/fs/src/types.ts:178
type FindUpNameSync =
| string[]
| string
| (directory) => FindUpNameSyncFnResult;
Defined in: packages/fs/src/types.ts:185
type FindUpNameSyncFnResult = PathLike | typeof FIND_UP_STOP | undefined;
Defined in: packages/fs/src/types.ts:183
type FindUpOptions = object;
Defined in: packages/fs/src/types.ts:170
optional allowSymlinks: boolean;
optional cwd: URL | string;
optional stopAt: URL | string;
optional type: "directory" | "file";
type JsonReplacer = (number | string)[] | (this, key, value) => unknown | null;
Defined in: packages/fs/src/types.ts:143
type JsonReviver = Parameters<typeof JSON["parse"]>["1"];
Defined in: packages/fs/src/types.ts:89
type MoveOptions = object;
Defined in: packages/fs/src/move/types.ts:3
optional cwd: URL | string;
The working directory to find source files. The source and destination path are relative to this.
process.cwd()
readonly optional directoryMode: FilePermissions;
Permissions for created directories.
It has no effect on Windows.
0o777
readonly optional overwrite: boolean;
Overwrite existing destination file.
true
type ReadFileEncoding =
| "ascii"
| "base64"
| "base64url"
| "hex"
| "latin1"
| "ucs-2"
| "ucs2"
| "utf-8"
| "utf-16le"
| "utf8"
| "utf16le";
Defined in: packages/fs/src/types.ts:61
type ReadFileOptions<C> = object;
Defined in: packages/fs/src/types.ts:63
• C
optional buffer: boolean;
Return content as a Buffer. Default: false
optional compression: C;
Compression method to decompress the file against. Default: none
optional encoding: ReadFileEncoding;
The encoding to use. Default: utf8
https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings
optional flag: number | string;
The flag used to open the file. Default: r
type ReadJsonOptions = CodeFrameOptions & object;
Defined in: packages/fs/src/types.ts:104
optional beforeParse: (source) => string;
string
string
type WriteFileOptions = object;
Defined in: packages/fs/src/types.ts:108
optional chown: object;
The group and user ID used to set the file ownership. Default: undefined
gid: number;
uid: number;
optional encoding: BufferEncoding | null;
The encoding to use. Default: utf8
optional flag: string;
The flag used to write the file. Default: w
optional mode: number;
The file mode (permission and sticky bits). Default: 0o666
optional overwrite: boolean;
Indicates whether the file should be overwritten if it already exists. Default: false
optional recursive: boolean;
Recursively create parent directories if needed. Default: true
type WriteJsonOptions = WriteFileOptions & object;
Defined in: packages/fs/src/types.ts:146
optional detectIndent: boolean;
Detect indentation automatically if the file exists. Default: false
optional indent: number | string;
The space used for pretty-printing.
Pass in undefined for no formatting.
optional replacer: JsonReplacer;
Passed into JSON.stringify.
optional stringify: (data, replacer, space) => string;
Override the default JSON.stringify method.
unknown
number | string | undefined
string
function brotliSize(input, options?): Promise<number>
Defined in: packages/fs/src/size.ts:109
Asynchronously calculates the Brotli compressed size of the input. Uses memory-efficient streaming for large inputs.
string | URL | Buffer | Readable
BrotliOptions
Promise<number>
function brotliSizeSync(input, options?): number
Defined in: packages/fs/src/size.ts:151
Synchronously calculates the Brotli compressed size of the input. Note: For large files, consider using the async brotliSize function instead.
string | URL | Buffer
BrotliOptions
number
function gzipSize(input, options?): Promise<number>
Defined in: packages/fs/src/size.ts:98
Asynchronously calculates the gzipped size of the input. Uses memory-efficient streaming for large inputs.
string | URL | Buffer | Readable
ZlibOptions
Promise<number>
function gzipSizeSync(input, options?): number
Defined in: packages/fs/src/size.ts:131
Synchronously calculates the gzipped size of the input. Note: For large files, consider using the async gzipSize function instead.
string | URL | Buffer
ZlibOptions
number
function rawSize(input): Promise<number>
Defined in: packages/fs/src/size.ts:120
Asynchronously gets the raw size of the input without compression. Uses memory-efficient streaming for large inputs.
string | URL | Buffer | Readable
Promise<number>
function rawSizeSync(input): number
Defined in: packages/fs/src/size.ts:171
Synchronously gets the raw size of the input without compression. Note: For large files, consider using the async rawSize function instead.
string | URL | Buffer
number
Defined in: packages/fs/src/error/json-error.ts:1
Errornew JSONError(message): JSONError
Defined in: packages/fs/src/error/json-error.ts:11
string
Error.constructor
get message(): string
Defined in: packages/fs/src/error/json-error.ts:21
string
set message(message): void
Defined in: packages/fs/src/error/json-error.ts:25
string
void
Error.message
static captureStackTrace(targetObject, constructorOpt?): void
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:91
Create .stack property on a target object
object
Function
void
Error.captureStackTrace
optional cause: unknown;
Defined in: node_modules/.pnpm/typescript@5.7.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
Error.cause
codeFrame: string;
Defined in: packages/fs/src/error/json-error.ts:4
fileName: string;
Defined in: packages/fs/src/error/json-error.ts:2
readonly name: "JSONError" = "JSONError";
Defined in: packages/fs/src/error/json-error.ts:7
Error.name
optional stack: string;
Defined in: node_modules/.pnpm/typescript@5.7.3/node_modules/typescript/lib/lib.es5.d.ts:1078
Error.stack
static optional prepareStackTrace: (err, stackTraces) => any;
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:98
Optional override for formatting stack traces
Error
CallSite[]
any
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
Error.prepareStackTrace
static stackTraceLimit: number;
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:100
Error.stackTraceLimit
function assertValidFileContents(contents): void
Defined in: packages/fs/src/utils/assert-valid-file-contents.ts:2
any
void
function assertValidFileOrDirectoryPath(fileOrDirectoryPath): void
Defined in: packages/fs/src/utils/assert-valid-file-or-directory-path.ts:2
any
void
function parseJson<T>(
string,
filename?,
options?): T
Defined in: packages/fs/src/utils/parse-json.ts:60
• T = JsonValue
string
string
CodeFrameOptions
T
function parseJson<T>(
string,
reviver,
fileName?,
options?): T
Defined in: packages/fs/src/utils/parse-json.ts:61
• T = JsonValue
string
(this, key, value) => any
string
CodeFrameOptions
T
function stripJsonComments(jsonString, __namedParameters): string
Defined in: packages/fs/src/utils/strip-json-comments.ts:5
string
boolean = true
string
function toPath(urlOrPath): string
Defined in: node_modules/.pnpm/@visulima+path@1.3.4/node_modules/@visulima/path/dist/utils.d.mts:7
string | URL
string
function readYaml<R>(path, options?): Promise<R>
Defined in: packages/fs/src/read/read-yaml.ts:6
• R = Record<string, unknown>
string | URL
ReadYamlOptions<"brotli" | "gzip" | "none">
Promise<R>
function readYaml<R>(
path,
reviver?,
options?): Promise<R>
Defined in: packages/fs/src/read/read-yaml.ts:7
• R = Record<string, unknown>
string | URL
YamlReviver
ReadYamlOptions<"brotli" | "gzip" | "none">
Promise<R>
function readYamlSync<R>(path, options?): R
Defined in: packages/fs/src/read/read-yaml-sync.ts:6
• R = Record<string, unknown>
string | URL
ReadYamlOptions<"brotli" | "gzip" | "none">
R
function readYamlSync<R>(
path,
reviver?,
options?): R
Defined in: packages/fs/src/read/read-yaml-sync.ts:7
• R = Record<string, unknown>
string | URL
YamlReviver
ReadYamlOptions<"brotli" | "gzip" | "none">
R
function writeYaml(
path,
data,
options?): Promise<void>
Defined in: packages/fs/src/write/write-yaml.ts:10
string | URL
any
Options
Promise<void>
function writeYaml(
path,
data,
replacer?,
options?): Promise<void>
Defined in: packages/fs/src/write/write-yaml.ts:16
string | URL
any
string | number | Options
Promise<void>
function writeYamlSync(
path,
data,
options?): void
Defined in: packages/fs/src/write/write-yaml-sync.ts:10
string | URL
any
Options
void
function writeYamlSync(
path,
data,
replacer?,
options?): void
Defined in: packages/fs/src/write/write-yaml-sync.ts:16
string | URL
any
string | number | Options
void
type YamlReplacer = JsonReplacer;
Defined in: packages/fs/src/types.ts:144
Libraries in this ecosystem make the best effort to track Node.js’ release schedule. Here’s a post on why we think this is important.
If you would like to help take a look at the list of issues and check our Contributing guild.
Note: please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
The visulima fs is open-sourced software licensed under the [MIT][license-url]
[typescript-url]: https://www.typescriptlang.org/ "TypeScript" "typescript" [license-image]: https://img.shields.io/npm/l/@visulima/fs?color=blueviolet&style=for-the-badge [license-url]: LICENSE.md "license" [npm-image]: https://img.shields.io/npm/v/@visulima/fs/latest.svg?style=for-the-badge&logo=npm [npm-url]: https://www.npmjs.com/package/@visulima/fs/v/latest "npm"
FAQs
Human friendly file system utilities for Node.js
We found that @visulima/fs demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OpenSSF has published OSPS Baseline, an initiative designed to establish a minimum set of security-related best practices for open source software projects.
Security News
Michigan TypeScript founder Dimitri Mitropoulos implements WebAssembly runtime in TypeScript types, enabling Doom to run after processing 177 terabytes of type definitions.
Security News
vlt's new "reproduce" tool verifies npm packages against their source code, outperforming traditional provenance adoption in the JavaScript ecosystem.