visulimaVisulima fs
Human friendly file system utilities for Node.js
Daniel Bannert's open source work is supported by the community on GitHub Sponsors
Install
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.
Usage
walk
import { walk } from "@visulima/fs";
const filesAndFolders: string[] = [];
for await (const index of walk(`${__dirname}/fixtures`, {})) {
filesAndFolders.push(index.path);
}
console.log(filesAndFolders);
walkSync
import { walkSync } from "@visulima/fs";
const filesAndFolders: string[] = [];
for (const index of walkSync(`${__dirname}/fixtures`, {})) {
filesAndFolders.push(index.path);
}
console.log(filesAndFolders);
API for walk and walkSync
path
Type: string
The directory to start from.
options
Type: object
maxDepth
Type: number
Default: Infinity
Optional: true
Description: The maximum depth of the file tree to be walked recursively.
includeFiles
Type: boolean
Default: true
Optional: true
Description: Indicates whether file entries should be included or not.
includeDirs
Type: boolean
Default: true
Optional: true
Description: Indicates whether directory entries should be included or not.
includeSymlinks
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.
followSymlinks
Type: boolean
Default: false
Optional: true
Description: Indicates whether symlinks should be resolved or not.
extensions
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.
match
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.
skip
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.
findUp
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);
findUpSync
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);
API for findUp and findUpSync
name
Type: 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.
options
Type: object
cwd
Type: URL | string\
Default: process.cwd()
The directory to start from.
type
Type: string\
Default: 'file'\
Values: 'file' | 'directory'
The type of path to match.
stopAt
Type: URL | string\
Default: Root directory
A directory path where the search halts if no matches are found before reaching this point.
allowSymlinks
Type: boolean\
Default: true
Allow symbolic links to match if they point to the target file or directory.
readFile
Read a file.
import { readFile } from "@visulima/fs";
// Returns a Promise for the file contents.
const file = await readFile("package.json");
console.log(file);
readFileSync
Read a file.
import { readFileSync } from "@visulima/fs";
// Returns the file contents.
const file = readFileSync("package.json");
console.log(file);
API for readFile and readFileSync
path
Type: string
The path to the file to read.
options
Type: object
buffer
Type: boolean
Default: true
Optional: true
Description: Indicates whether the file contents should be returned as a Buffer or a string.
compression
Type: "brotli" | "gzip" | undefined
Default: undefined
Optional: true
Description: The file compression.
encoding
Type: "ascii" | "base64" | "base64url" | "hex" | "latin1" | "ucs-2" | "ucs2" | "utf-8" | "utf-16le" | "utf8" | "utf16le" | undefined
Default: utf8
Optional: true
flag
Type: number | string | undefined
Default: 'r'
Optional: true
isAccessible
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);
isAccessibleSync
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);
API for isAccessible and isAccessibleSync
path
Type: string
The path to the file or directory to check.
mode
Type: number
Default: fs.constants.F_OK
Optional: true
Description: The accessibility mode.
Utilities
parseJson
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 | }
| ^
*/
API for parseJson
json
Type: string
The JSON string to parse.
reviver
Type: Function
Prescribes how the value originally produced by parsing is transformed, before being returned. See JSON.parse docs for more.
filename
Type: string
The filename to use in error messages.
API for JSONError
Exposed for use in instanceof checks.
fileName
Type: string
The filename displayed in the error message.
codeFrame
Type: string
The printable section of the JSON which produces the error.
Api Docs
eol
Functions
detect()
function detect(content): "\n" | "\r\n";
Defined in: packages/fs/src/eol.ts:29
Detect the EOL character for string input. Returns null if no newline.
Parameters
content
string
The string content to detect the EOL from.
Returns
"\n" | "\r\n"
Example
import { detect } from "@visulima/fs/eol";
detect("Hello\r\nWorld"); // "\r\n"
detect("Hello\nWorld"); // "\n"
detect("HelloWorld"); // null
format()
function format(content, eol): string;
Defined in: packages/fs/src/eol.ts:54
Format the file to the targeted EOL.
Parameters
content
string
The string content to format.
eol
The target EOL character.
"\n" | "\r\n"
Returns
string
Example
import { format, LF, CRLF } from "@visulima/fs/eol";
format("Hello\r\nWorld\nUnix", LF); // "Hello\nWorld\nUnix"
format("Hello\nWorld\r\nWindows", CRLF); // "Hello\r\nWorld\r\nWindows"
Variables
CRLF
const CRLF: "\r\n";
Defined in: packages/fs/src/eol.ts:9
End-of-line character for Windows platforms.
EOL
const EOL: "\n" | "\r\n";
Defined in: packages/fs/src/eol.ts:14
End-of-line character evaluated for the current platform.
LF
const LF: "\n";
Defined in: packages/fs/src/eol.ts:6
End-of-line character for POSIX platforms such as macOS and Linux.
error
Classes
AlreadyExistsError
Defined in: packages/fs/src/error/already-exists-error.ts:28
Error thrown when a file or directory already exists at a specified path, and an operation was expecting it not to.
Example
import { AlreadyExistsError } from "@visulima/fs/error"; // Assuming it's exported from an index or directly
import { ensureSymlinkSync } from "@visulima/fs"; // Or any function that might throw this
import { join } from "node:path";
try {
// Example: ensureSymlinkSync might throw this if a file (not a symlink) already exists at linkName
// For demonstration, let's assume someFunction internally throws it:
const someFunctionThatMightThrow = (path) => {
if (path === "/tmp/existing-file.txt") { // Simulate a check
throw new AlreadyExistsError(`file already exists at '/tmp/existing-file.txt'`);
}
}
someFunctionThatMightThrow("/tmp/existing-file.txt");
} catch (error) {
if (error instanceof AlreadyExistsError) {
console.error(`Operation failed because path exists: ${error.message}`);
console.error(`Error code: ${error.code}`); // EEXIST
} else {
console.error("An unexpected error occurred:", error);
}
}
Extends
Error
Constructors
Constructor
new AlreadyExistsError(message): AlreadyExistsError;
Defined in: packages/fs/src/error/already-exists-error.ts:33
Creates a new instance.
Parameters
message
string
The error message.
Returns
Overrides
Error.constructor
Accessors
code
Get Signature
get code(): string;
Defined in: packages/fs/src/error/already-exists-error.ts:38
Returns
string
Set Signature
set code(_name): void;
Defined in: packages/fs/src/error/already-exists-error.ts:43
Parameters
_name
string
Returns
void
name
Get Signature
get name(): string;
Defined in: packages/fs/src/error/already-exists-error.ts:48
Returns
string
Set Signature
set name(_name): void;
Defined in: packages/fs/src/error/already-exists-error.ts:53
Parameters
_name
string
Returns
void
Overrides
Error.name
Methods
captureStackTrace()
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
Parameters
targetObject
object
constructorOpt?
Function
Returns
void
Inherited from
Error.captureStackTrace
Properties
cause?
optional cause: unknown;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
Inherited from
Error.cause
message
message: string;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es5.d.ts:1077
Inherited from
Error.message
stack?
optional stack: string;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es5.d.ts:1078
Inherited from
Error.stack
prepareStackTrace()?
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
Parameters
err
Error
stackTraces
CallSite[]
Returns
any
See
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
Inherited from
Error.prepareStackTrace
stackTraceLimit
static stackTraceLimit: number;
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:100
Inherited from
Error.stackTraceLimit
DirectoryError
Defined in: packages/fs/src/error/directory-error.ts:36
Error thrown when an operation that is not allowed on a directory is attempted. This typically occurs when a file-specific operation is used on a directory path.
Example
import { DirectoryError } from "@visulima/fs/error";
import { readFile } from "@visulima/fs"; // Or any function that might throw this
import { join } from "node:path";
const attemptToReadFileFromDir = async () => {
try {
// Attempting to read a directory as if it were a file
// This is a conceptual example; readFile might throw a different error first
// depending on its internal checks, but EISDIR is the underlying system error.
// Forcing the scenario:
const pretendReadFileOnDir = (path) => {
if (path === "/tmp/my-directory") { // Simulate a directory path
throw new DirectoryError(`read '/tmp/my-directory'`);
}
}
pretendReadFileOnDir("/tmp/my-directory");
// await readFile(join("/tmp", "my-directory"));
} catch (error) {
if (error instanceof DirectoryError) {
console.error(`Operation failed, path is a directory: ${error.message}`);
console.error(`Error code: ${error.code}`); // EISDIR
} else {
console.error("An unexpected error occurred:", error);
}
}
};
attemptToReadFileFromDir();
Extends
Error
Constructors
Constructor
new DirectoryError(message): DirectoryError;
Defined in: packages/fs/src/error/directory-error.ts:41
Creates a new instance.
Parameters
message
string
The error message.
Returns
Overrides
Error.constructor
Accessors
code
Get Signature
get code(): string;
Defined in: packages/fs/src/error/directory-error.ts:46
Returns
string
Set Signature
set code(_name): void;
Defined in: packages/fs/src/error/directory-error.ts:51
Parameters
_name
string
Returns
void
name
Get Signature
get name(): string;
Defined in: packages/fs/src/error/directory-error.ts:56
Returns
string
Set Signature
set name(_name): void;
Defined in: packages/fs/src/error/directory-error.ts:61
Parameters
_name
string
Returns
void
Overrides
Error.name
Methods
captureStackTrace()
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
Parameters
targetObject
object
constructorOpt?
Function
Returns
void
Inherited from
Error.captureStackTrace
Properties
cause?
optional cause: unknown;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
Inherited from
Error.cause
message
message: string;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es5.d.ts:1077
Inherited from
Error.message
stack?
optional stack: string;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es5.d.ts:1078
Inherited from
Error.stack
prepareStackTrace()?
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
Parameters
err
Error
stackTraces
CallSite[]
Returns
any
See
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
Inherited from
Error.prepareStackTrace
stackTraceLimit
static stackTraceLimit: number;
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:100
Inherited from
Error.stackTraceLimit
NotEmptyError
Defined in: packages/fs/src/error/not-empty-error.ts:40
Error thrown when a directory is not empty.
Example
import { NotEmptyError } from "@visulima/fs/error";
import { rmdir } from "node:fs/promises"; // Or any fs function that might throw this system error
import { join } from "node:path";
const attemptToRemoveNonEmptyDir = async () => {
const dirPath = join("/tmp", "my-non-empty-dir"); // Assume this directory exists and has files
try {
// Forcing the scenario for demonstration, as rmdir might throw its own specific error.
// Node.js fs operations that encounter a non-empty directory when expecting an empty one
// typically throw an error with code ENOTEMPTY.
const simulateNotEmpty = (path) => {
if (path === dirPath) { // Simulate check for non-empty
throw new NotEmptyError(`rmdir '${dirPath}'`);
}
}
simulateNotEmpty(dirPath);
// await rmdir(dirPath); // This would likely throw an error with code ENOTEMPTY
} catch (error) {
if (error instanceof NotEmptyError) {
console.error(`Operation failed, directory is not empty: ${error.message}`);
console.error(`Error code: ${error.code}`); // ENOTEMPTY
} else {
console.error("An unexpected error occurred:", error);
}
}
};
// You would need to set up a non-empty directory at /tmp/my-non-empty-dir for a real test
// import { ensureDirSync, writeFileSync } from "@visulima/fs";
// ensureDirSync(dirPath);
// writeFileSync(join(dirPath, "somefile.txt"), "content");
attemptToRemoveNonEmptyDir();
Extends
Error
Constructors
Constructor
new NotEmptyError(message): NotEmptyError;
Defined in: packages/fs/src/error/not-empty-error.ts:45
Creates a new instance.
Parameters
message
string
The error message.
Returns
Overrides
Error.constructor
Accessors
code
Get Signature
get code(): string;
Defined in: packages/fs/src/error/not-empty-error.ts:50
Returns
string
Set Signature
set code(_name): void;
Defined in: packages/fs/src/error/not-empty-error.ts:55
Parameters
_name
string
Returns
void
name
Get Signature
get name(): string;
Defined in: packages/fs/src/error/not-empty-error.ts:60
Returns
string
Set Signature
set name(_name): void;
Defined in: packages/fs/src/error/not-empty-error.ts:65
Parameters
_name
string
Returns
void
Overrides
Error.name
Methods
captureStackTrace()
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
Parameters
targetObject
object
constructorOpt?
Function
Returns
void
Inherited from
Error.captureStackTrace
Properties
cause?
optional cause: unknown;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
Inherited from
Error.cause
message
message: string;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es5.d.ts:1077
Inherited from
Error.message
stack?
optional stack: string;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es5.d.ts:1078
Inherited from
Error.stack
prepareStackTrace()?
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
Parameters
err
Error
stackTraces
CallSite[]
Returns
any
See
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
Inherited from
Error.prepareStackTrace
stackTraceLimit
static stackTraceLimit: number;
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:100
Inherited from
Error.stackTraceLimit
NotFoundError
Defined in: packages/fs/src/error/not-found-error.ts:33
Error thrown when a file or directory is not found at a specified path.
Example
import { NotFoundError } from "@visulima/fs/error";
import { readFile } from "@visulima/fs"; // Or any function that might throw this
import { join } from "node:path";
const tryReadingNonExistentFile = async () => {
const filePath = join("/tmp", "this-file-does-not-exist.txt");
try {
// Forcing the scenario for demonstration, as readFile itself would throw this.
const simulateNotFound = (path) => {
if (path === filePath) {
throw new NotFoundError(`no such file or directory, open '${filePath}'`);
}
}
simulateNotFound(filePath);
// await readFile(filePath);
} catch (error) {
if (error instanceof NotFoundError) {
console.error(`Operation failed, path not found: ${error.message}`);
console.error(`Error code: ${error.code}`); // ENOENT
} else {
console.error("An unexpected error occurred:", error);
}
}
};
tryReadingNonExistentFile();
Extends
Error
Constructors
Constructor
new NotFoundError(message): NotFoundError;
Defined in: packages/fs/src/error/not-found-error.ts:38
Creates a new instance.
Parameters
message
string
The error message.
Returns
Overrides
Error.constructor
Accessors
code
Get Signature
get code(): string;
Defined in: packages/fs/src/error/not-found-error.ts:43
Returns
string
Set Signature
set code(_name): void;
Defined in: packages/fs/src/error/not-found-error.ts:48
Parameters
_name
string
Returns
void
name
Get Signature
get name(): string;
Defined in: packages/fs/src/error/not-found-error.ts:53
Returns
string
Set Signature
set name(_name): void;
Defined in: packages/fs/src/error/not-found-error.ts:58
Parameters
_name
string
Returns
void
Overrides
Error.name
Methods
captureStackTrace()
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
Parameters
targetObject
object
constructorOpt?
Function
Returns
void
Inherited from
Error.captureStackTrace
Properties
cause?
optional cause: unknown;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
Inherited from
Error.cause
message
message: string;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es5.d.ts:1077
Inherited from
Error.message
stack?
optional stack: string;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es5.d.ts:1078
Inherited from
Error.stack
prepareStackTrace()?
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
Parameters
err
Error
stackTraces
CallSite[]
Returns
any
See
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
Inherited from
Error.prepareStackTrace
stackTraceLimit
static stackTraceLimit: number;
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:100
Inherited from
Error.stackTraceLimit
PermissionError
Defined in: packages/fs/src/error/permission-error.ts:34
Error thrown when an operation is not permitted due to insufficient privileges or other access control restrictions.
Example
import { PermissionError } from "@visulima/fs/error";
import { writeFile } from "@visulima/fs"; // Or any function that might throw this
import { join } from "node:path";
const tryWritingToProtectedFile = async () => {
const filePath = join("/root", "protected-file.txt"); // A path that typically requires root privileges
try {
// Forcing the scenario for demonstration, as writeFile itself would throw this.
const simulatePermissionError = (path) => {
if (path === filePath) {
throw new PermissionError(`open '${filePath}'`);
}
}
simulatePermissionError(filePath);
// await writeFile(filePath, "test content");
} catch (error) {
if (error instanceof PermissionError) {
console.error(`Operation not permitted: ${error.message}`);
console.error(`Error code: ${error.code}`); // EPERM
} else {
console.error("An unexpected error occurred:", error);
}
}
};
tryWritingToProtectedFile();
Extends
Error
Constructors
Constructor
new PermissionError(message): PermissionError;
Defined in: packages/fs/src/error/permission-error.ts:39
Creates a new instance.
Parameters
message
string
The error message.
Returns
Overrides
Error.constructor
Accessors
code
Get Signature
get code(): string;
Defined in: packages/fs/src/error/permission-error.ts:44
Returns
string
Set Signature
set code(_name): void;
Defined in: packages/fs/src/error/permission-error.ts:49
Parameters
_name
string
Returns
void
name
Get Signature
get name(): string;
Defined in: packages/fs/src/error/permission-error.ts:54
Returns
string
Set Signature
set name(_name): void;
Defined in: packages/fs/src/error/permission-error.ts:59
Parameters
_name
string
Returns
void
Overrides
Error.name
Methods
captureStackTrace()
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
Parameters
targetObject
object
constructorOpt?
Function
Returns
void
Inherited from
Error.captureStackTrace
Properties
cause?
optional cause: unknown;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
Inherited from
Error.cause
message
message: string;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es5.d.ts:1077
Inherited from
Error.message
stack?
optional stack: string;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es5.d.ts:1078
Inherited from
Error.stack
prepareStackTrace()?
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
Parameters
err
Error
stackTraces
CallSite[]
Returns
any
See
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
Inherited from
Error.prepareStackTrace
stackTraceLimit
static stackTraceLimit: number;
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:100
Inherited from
Error.stackTraceLimit
WalkError
Defined in: packages/fs/src/error/walk-error.ts:43
Error thrown in walk or walkSync during iteration.
Example
import { WalkError } from "@visulima/fs/error";
import { walk } from "@visulima/fs";
import { join } from "node:path";
const processDirectory = async () => {
const dirToWalk = join("/tmp", "non-existent-or-permission-denied-dir");
try {
// Forcing the scenario: walk might throw a WalkError if it encounters an issue
// like a directory it cannot read during the walk process.
const simulateWalkError = async (rootDir) => {
// Let's say readdir inside walk fails for a subdirectory.
const underlyingError = new Error("Permission denied reading subdirectory");
throw new WalkError(underlyingError, rootDir);
}
// This is conceptual. In a real scenario, 'walk' itself would throw.
// for await (const entry of walk(dirToWalk)) {
// console.log(entry.path);
// }
await simulateWalkError(dirToWalk);
} catch (error) {
if (error instanceof WalkError) {
console.error(`Error during directory walk of "${error.root}": ${error.message}`);
if (error.cause) {
console.error(`Underlying cause: ${error.cause}`);
}
} else {
console.error("An unexpected error occurred:", error);
}
}
};
processDirectory();
Extends
Error
Constructors
Constructor
new WalkError(cause, root): WalkError;
Defined in: packages/fs/src/error/walk-error.ts:52
Constructs a new instance.
Parameters
cause
unknown
The underlying error or reason for the walk failure.
root
string
The root directory path where the walk operation started or encountered the error.
Returns
Overrides
Error.constructor
Accessors
name
Get Signature
get name(): string;
Defined in: packages/fs/src/error/walk-error.ts:61
Returns
string
Set Signature
set name(_name): void;
Defined in: packages/fs/src/error/walk-error.ts:66
Parameters
_name
string
Returns
void
Overrides
Error.name
Methods
captureStackTrace()
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
Parameters
targetObject
object
constructorOpt?
Function
Returns
void
Inherited from
Error.captureStackTrace
Properties
cause?
optional cause: unknown;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
Inherited from
Error.cause
message
message: string;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es5.d.ts:1077
Inherited from
Error.message
root
root: string;
Defined in: packages/fs/src/error/walk-error.ts:45
File path of the root that's being walked.
stack?
optional stack: string;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es5.d.ts:1078
Inherited from
Error.stack
prepareStackTrace()?
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
Parameters
err
Error
stackTraces
CallSite[]
Returns
any
See
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
Inherited from
Error.prepareStackTrace
stackTraceLimit
static stackTraceLimit: number;
Defined in: node_modules/.pnpm/@types+node@18.19.71/node_modules/@types/node/globals.d.ts:100
Inherited from
Error.stackTraceLimit
References
JSONError
Re-exports JSONError
index
Functions
collect()
function collect(directory, options): Promise<string[]>;
Defined in: packages/fs/src/find/collect.ts:37
Asynchronously collects all file paths within a directory that match the specified criteria. By default, it searches for JavaScript and TypeScript file extensions.
Parameters
directory
string
The root directory to start collecting files from.
options
WalkOptions = {}
Optional configuration to control the collection process. See WalkOptions.
Returns
Promise\<string[]>
A promise that resolves to an array of absolute file paths.
Example
import { collect } from "@visulima/fs";
import { join } from "node:path";
const collectFiles = async () => {
// Collect all .txt and .md files in /tmp/docs, up to 2 levels deep
const files = await collect(join("/tmp", "docs"), {
extensions: ["txt", "md"],
maxDepth: 2,
includeDirs: false, // Only collect files
});
console.log(files);
// Example output: ['/tmp/docs/file1.txt', '/tmp/docs/subdir/report.md']
// Collect all .js files, excluding anything in node_modules
const jsFiles = await collect(join("/tmp", "project"), {
extensions: ["js"],
skip: [/node_modules/],
});
console.log(jsFiles);
};
collectFiles();
collectSync()
function collectSync(directory, options): string[];
Defined in: packages/fs/src/find/collect-sync.ts:33
Synchronously collects all file paths within a directory that match the specified criteria. By default, it searches for JavaScript and TypeScript file extensions.
Parameters
directory
string
The root directory to start collecting files from.
options
WalkOptions = {}
Optional configuration to control the collection process. See WalkOptions.
Returns
string[]
An array of absolute file paths.
Example
import { collectSync } from "@visulima/fs";
import { join } from "node:path";
// Collect all .txt and .md files in /tmp/docs, up to 2 levels deep
const files = collectSync(join("/tmp", "docs"), {
extensions: ["txt", "md"],
maxDepth: 2,
includeDirs: false, // Only collect files
});
console.log(files);
// Example output: ['/tmp/docs/file1.txt', '/tmp/docs/subdir/report.md']
// Collect all .js files, excluding anything in node_modules
const jsFiles = collectSync(join("/tmp", "project"), {
extensions: ["js"],
skip: [/node_modules/],
});
console.log(jsFiles);
emptyDir()
function emptyDir(dir, options?): Promise<void>;
Defined in: packages/fs/src/remove/empty-dir.ts:38
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.
Parameters
dir
The path to the directory to empty.
string | URL
options?
RetryOptions
Optional configuration for the operation. See RetryOptions.
Returns
Promise\<void>
A promise that resolves when the directory is empty.
Example
import { emptyDir } from "@visulima/fs";
import { join } from "node:path";
const clearTempDir = async () => {
try {
await emptyDir(join("/tmp", "my-app-temp"));
console.log("Temporary directory emptied or created.");
} catch (error) {
console.error("Failed to empty directory:", error);
}
};
clearTempDir();
emptyDirSync()
function emptyDirSync(dir, options?): void;
Defined in: packages/fs/src/remove/empty-dir-sync.ts:33
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.
Parameters
dir
The path to the directory to empty.
string | URL
options?
RetryOptions
Optional configuration for the operation. See RetryOptions.
Returns
void
void
Example
import { emptyDirSync } from "@visulima/fs";
import { join } from "node:path";
try {
emptyDirSync(join("/tmp", "my-app-temp"));
console.log("Temporary directory emptied or created.");
} catch (error) {
console.error("Failed to empty directory:", error);
}
ensureDir()
function ensureDir(directory): Promise<void>;
Defined in: packages/fs/src/ensure/ensure-dir.ts:20
Ensures that the directory exists. If the directory structure does not exist, it is created. Like mkdir -p.
Parameters
directory
The path to the directory to ensure exists.
string | URL
Returns
Promise\<void>
Example
import ensureDir from "@visulima/fs/ensure/ensure-dir";
await ensureDir("/tmp/foo/bar/baz");
// Creates the directory structure /tmp/foo/bar/baz if it doesn't exist
ensureDirSync()
function ensureDirSync(directory): void;
Defined in: packages/fs/src/ensure/ensure-dir-sync.ts:20
Ensures that the directory exists. If the directory structure does not exist, it is created. Like mkdir -p.
Parameters
directory
The path to the directory to ensure exists.
string | URL
Returns
void
Example
import ensureDirSync from "@visulima/fs/ensure/ensure-dir-sync";
ensureDirSync("/tmp/foo/bar/baz");
// Creates the directory structure /tmp/foo/bar/baz if it doesn't exist
ensureFile()
function ensureFile(filePath): Promise<void>;
Defined in: packages/fs/src/ensure/ensure-file.ts:37
Asynchronously ensures that a file exists. If the directory structure for the file does not exist, it is created. If the file already exists, it is not modified.
Parameters
filePath
The path to the file. Can be a string or a URL object.
string | URL
Returns
Promise\<void>
A Promise that resolves when the file has been created or confirmed to exist.
Throws
Will throw an error if the path exists and is not a file.
Throws
Will throw an error if directory or file creation fails for reasons other than the path not existing initially.
Example
import { ensureFile } from "@visulima/fs";
(async () => {
try {
await ensureFile("path/to/my/file.txt");
console.log("File ensured!");
await ensureFile(new URL("file:///path/to/another/file.log"));
console.log("Another file ensured!");
} catch (error) {
console.error("Failed to ensure file:", error);
}
})();
ensureFileSync()
function ensureFileSync(filePath): void;
Defined in: packages/fs/src/ensure/ensure-file-sync.ts:24
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 NOT MODIFIED.
Parameters
filePath
The path to the file to ensure exists.
string | URL
Returns
void
Example
import { ensureFileSync } from "@visulima/fs";
ensureFileSync("/tmp/foo/bar/baz.txt");
// Creates the file /tmp/foo/bar/baz.txt and any missing parent directories if they don't exist
ensureLink()
function ensureLink(source, destination): Promise<void>;
Defined in: packages/fs/src/ensure/ensure-link.ts:25
Ensures that the hard link exists. If the directory structure does not exist, it is created.
Parameters
source
The path to the source file or directory.
string | URL
destination
The path to the destination link.
string | URL
Returns
Promise\<void>
Example
import { ensureLink } from "@visulima/fs";
import { join } from "node:path";
// ensure the link /tmp/foo/bar-link.txt points to /tmp/foo/bar.txt
await ensureLink(join("/tmp", "foo", "bar.txt"), join("/tmp", "foo", "bar-link.txt"));
ensureLinkSync()
function ensureLinkSync(source, destination): void;
Defined in: packages/fs/src/ensure/ensure-link-sync.ts:25
Ensures that the hard link exists. If the directory structure does not exist, it is created.
Parameters
source
The path to the source file or directory.
string | URL
destination
The path to the destination link.
string | URL
Returns
void
Example
import { ensureLinkSync } from "@visulima/fs";
import { join } from "node:path";
// ensure the link /tmp/foo/bar-link.txt points to /tmp/foo/bar.txt
ensureLinkSync(join("/tmp", "foo", "bar.txt"), join("/tmp", "foo", "bar-link.txt"));
ensureSymlink()
function ensureSymlink(
target,
linkName,
type?): Promise<void>;
Defined in: packages/fs/src/ensure/ensure-symlink.ts:39
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.
Parameters
target
the source file path
string | URL
linkName
the destination link path
string | URL
type?
Type
the type of the symlink, or null to use automatic detection
Returns
Promise\<void>
A void promise that resolves once the link exists.
Example
import { ensureSymlink } from "@visulima/fs";
import { join } from "node:path";
// Ensure a symlink /tmp/foo/link-to-bar.txt points to /tmp/foo/bar.txt
await ensureSymlink(join("/tmp", "foo", "bar.txt"), join("/tmp", "foo", "link-to-bar.txt"));
// Ensure a directory symlink /tmp/foo/link-to-baz-dir points to /tmp/foo/baz-dir
await ensureSymlink(join("/tmp", "foo", "baz-dir"), join("/tmp", "foo", "link-to-baz-dir"), "dir");
ensureSymlinkSync()
function ensureSymlinkSync(
target,
linkName,
type?): void;
Defined in: packages/fs/src/ensure/ensure-symlink-sync.ts:39
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.
Parameters
target
the source file path
string | URL
linkName
the destination link path
string | URL
type?
Type
the type of the symlink, or null to use automatic detection
Returns
void
A void.
Example
import { ensureSymlinkSync } from "@visulima/fs";
import { join } from "node:path";
// Ensure a symlink /tmp/foo/link-to-bar.txt points to /tmp/foo/bar.txt
ensureSymlinkSync(join("/tmp", "foo", "bar.txt"), join("/tmp", "foo", "link-to-bar.txt"));
// Ensure a directory symlink /tmp/foo/link-to-baz-dir points to /tmp/foo/baz-dir
ensureSymlinkSync(join("/tmp", "foo", "baz-dir"), join("/tmp", "foo", "link-to-baz-dir"), "dir");
findUp()
function findUp(name, options): Promise<string>;
Defined in: packages/fs/src/find/find-up.ts:55
Asynchronously finds a file or directory by walking up parent directories.
Parameters
name
The name(s) of the file or directory to find. Can be a string, an array of strings, or a function that returns a name or FIND_UP_STOP.
options
FindUpOptions = {}
Optional configuration for the search. See FindUpOptions.
Returns
Promise\<string>
A promise that resolves to the absolute path of the first found file/directory, or undefined if not found.
Example
import { findUp } from "@visulima/fs";
import { join } from "node:path";
const findProjectRoot = async () => {
// Find the closest package.json, starting from /tmp/foo/bar/baz
const projectRoot = await findUp("package.json", {
cwd: join("/tmp", "foo", "bar", "baz"),
type: "file",
});
console.log(projectRoot); // e.g., /tmp/foo/package.json or undefined
// Find the closest .git directory or a README.md file
const gitDirOrReadme = await findUp([".git", "README.md"], {
cwd: join("/tmp", "foo", "bar"),
});
console.log(gitDirOrReadme);
// Find using a custom function, stopping at /tmp
const customFound = await findUp(
(directory) => {
if (directory === join("/tmp", "foo")) {
return "found-it-here.txt"; // Pretend this file exists in /tmp/foo
}
return undefined;
},
{
cwd: join("/tmp", "foo", "bar", "baz"),
stopAt: join("/tmp"),
}
);
console.log(customFound);
};
findProjectRoot();
findUpSync()
function findUpSync(name, options): string;
Defined in: packages/fs/src/find/find-up-sync.ts:51
Synchronously finds a file or directory by walking up parent directories.
Parameters
name
The name(s) of the file or directory to find. Can be a string, an array of strings, or a function that returns a name or FIND_UP_STOP.
options
FindUpOptions = {}
Optional configuration for the search. See FindUpOptions.
Returns
string
The absolute path of the first found file/directory, or undefined if not found.
Example
import { findUpSync } from "@visulima/fs";
import { join } from "node:path";
// Find the closest package.json, starting from /tmp/foo/bar/baz
const projectRoot = findUpSync("package.json", {
cwd: join("/tmp", "foo", "bar", "baz"),
type: "file",
});
console.log(projectRoot); // e.g., /tmp/foo/package.json or undefined
// Find the closest .git directory or a README.md file
const gitDirOrReadme = findUpSync([".git", "README.md"], {
cwd: join("/tmp", "foo", "bar"),
});
console.log(gitDirOrReadme);
// Find using a custom function, stopping at /tmp
const customFound = findUpSync(
(directory) => {
if (directory === join("/tmp", "foo")) {
return "found-it-here.txt"; // Pretend this file exists in /tmp/foo
}
return undefined;
},
{
cwd: join("/tmp", "foo", "bar", "baz"),
stopAt: join("/tmp"),
}
);
console.log(customFound);
isAccessible()
function isAccessible(path, mode?): Promise<boolean>;
Defined in: packages/fs/src/is-accessible.ts:36
Asynchronously tests a user's permissions for the file or directory specified by path.
Returns a Promise that resolves to true if the accessibility check is successful, false otherwise.
Parameters
path
The path to the file or directory. Can be a string or a URL object.
string | URL
mode?
number
The accessibility checks to perform. Defaults to F_OK (check for existence).
Other possible values include R_OK (check for read access), W_OK (check for write access),
and X_OK (check for execute/search access). Multiple modes can be combined using bitwise OR.
Returns
Promise\<boolean>
A Promise that resolves to a boolean indicating if the path is accessible with the specified mode.
Example
import { isAccessible, F_OK, R_OK } from "@visulima/fs";
(async () => {
if (await isAccessible("myFile.txt")) {
console.log("myFile.txt exists");
}
if (await isAccessible("myFile.txt", R_OK)) {
console.log("myFile.txt is readable");
}
if (await isAccessible("myDirectory", F_OK | R_OK | W_OK)) {
console.log("myDirectory exists, is readable and writable");
}
})();
isAccessibleSync()
function isAccessibleSync(path, mode?): boolean;
Defined in: packages/fs/src/is-accessible-sync.ts:9
Synchronously tests a user's permissions for the file or directory specified by path.
If the accessibility check is successful, true is returned. Otherwise, false is returned.
Parameters
path
string | URL
mode?
number
Returns
boolean
true if the accessibility check is successful, false otherwise.
Param
A path to a file or directory. If a URL is provided, it must use the file: protocol.
Param
The accessibility checks to perform. Default: F_OK (tests for existence of the file).
Other possible values are R_OK (tests for read permission), W_OK (tests for write permission),
and X_OK (tests for execute permissions). Multiple modes can be combined using bitwise OR.
Example
import { isAccessibleSync, F_OK, R_OK, W_OK } from "@visulima/fs";
import { writeFileSync, unlinkSync, chmodSync } from "node:fs";
import { join } from "node:path";
const filePath = join("temp-access-test.txt");
// Test for existence (default mode)
writeFileSync(filePath, "content");
console.log(`File exists: ${isAccessibleSync(filePath)}`); // true
unlinkSync(filePath);
console.log(`File exists after delete: ${isAccessibleSync(filePath)}`); // false
// Test for read and write permissions
writeFileSync(filePath, "content");
chmodSync(filePath, 0o600); // Read/Write for owner
console.log(`Readable: ${isAccessibleSync(filePath, R_OK)}`); // true
console.log(`Writable: ${isAccessibleSync(filePath, W_OK)}`); // true
console.log(`Readable & Writable: ${isAccessibleSync(filePath, R_OK | W_OK)}`); // true
chmodSync(filePath, 0o400); // Read-only for owner
console.log(`Readable (after chmod): ${isAccessibleSync(filePath, R_OK)}`); // true
console.log(`Writable (after chmod): ${isAccessibleSync(filePath, W_OK)}`); // false
unlinkSync(filePath); // Clean up
// Example with URL
writeFileSync(filePath, "content for URL test");
const fileUrl = new URL(`file://${join(process.cwd(), filePath)}`);
console.log(`URL exists: ${isAccessibleSync(fileUrl)}`); // true
unlinkSync(filePath);
move()
function move(
sourcePath,
destinationPath,
options): Promise<void>;
Defined in: packages/fs/src/move/index.ts:35
Move a file asynchronously.
Parameters
sourcePath
string
The file you want to move.
destinationPath
string
Where you want the file moved.
options
MoveOptions = {}
Configuration options.
Returns
Promise\<void>
A Promise that resolves when the file has been moved.
Example
import { move } from '@visulima/fs';
await move('source/test.png', 'destination/test.png');
console.log('The file has been moved');
moveSync()
function moveSync(
sourcePath,
destinationPath,
options?): void;
Defined in: packages/fs/src/move/index.ts:61
Move a file synchronously.
Parameters
sourcePath
string
The file you want to move.
destinationPath
string
Where you want the file moved.
options?
Configuration options.
Returns
void
Nothing is returned.
Example
import { moveSync } from '@visulima/fs';
moveSync('source/test.png', 'destination/test.png');
console.log('The file has been moved');
readFile()
function readFile<O>(path, options?): Promise<ContentType<O>>;
Defined in: packages/fs/src/read/read-file.ts:57
Asynchronously reads the entire contents of a file.
It can also decompress the file content if a compression option is provided.
Type Parameters
O
O extends ReadFileOptions\<"brotli" | "gzip" | "none"> = undefined
The type of the options object, extending ReadFileOptions.
Parameters
path
The path to the file to read. Can be a file URL or a string path.
string | URL
options?
O
Optional configuration for reading the file. See ReadFileOptions.
Available compression methods: "brotli", "gzip", "none" (default).
Returns
Promise\<ContentType\<O>>
A promise that resolves with the file content. The type of the content (string or Buffer)
depends on the buffer option (defaults to string if buffer is false or not set).
Example
import { readFile } from "@visulima/fs";
import { join } from "node:path";
const readMyFile = async () => {
try {
// Read a regular text file
const content = await readFile(join("path", "to", "my-file.txt"));
console.log("File content:", content);
// Read a file as a Buffer
const bufferContent = await readFile(join("path", "to", "another-file.bin"), { buffer: true });
console.log("Buffer length:", bufferContent.length);
// Read and decompress a gzipped file
// Assume my-archive.txt.gz exists
// const decompressedContent = await readFile(join("path", "to", "my-archive.txt.gz"), { compression: "gzip", encoding: "utf8" });
// console.log("Decompressed content:", decompressedContent);
} catch (error) {
console.error("Failed to read file:", error);
}
};
readMyFile();
readFileSync()
function readFileSync<O>(path, options?): ContentType<O>;
Defined in: packages/fs/src/read/read-file-sync.ts:51
Synchronously reads the entire contents of a file.
It can also decompress the file content if a compression option is provided.
Type Parameters
O
O extends ReadFileOptions\<"brotli" | "gzip" | "none"> = undefined
The type of the options object, extending ReadFileOptions.
Parameters
path
The path to the file to read. Can be a file URL or a string path.
string | URL
options?
O
Optional configuration for reading the file. See ReadFileOptions.
Available compression methods: "brotli", "gzip", "none" (default).
Returns
ContentType\<O>
The file content. The type of the content (string or Buffer)
depends on the buffer option (defaults to string if buffer is false or not set).
Example
import { readFileSync } from "@visulima/fs";
import { join } from "node:path";
try {
// Read a regular text file
const content = readFileSync(join("path", "to", "my-file.txt"));
console.log("File content:", content);
// Read a file as a Buffer
const bufferContent = readFileSync(join("path", "to", "another-file.bin"), { buffer: true });
console.log("Buffer length:", bufferContent.length);
// Read and decompress a gzipped file
// Assume my-archive.txt.gz exists
// const decompressedContent = readFileSync(join("path", "to", "my-archive.txt.gz"), { compression: "gzip", encoding: "utf8" });
// console.log("Decompressed content:", decompressedContent);
} catch (error) {
console.error("Failed to read file:", error);
}
readJson()
Asynchronously reads a JSON file and then parses it into an object.
Template
The expected type of the parsed JSON object.
Param
The path to the JSON file to read. Can be a file URL or a string path.
Param
A function to transform the results. This function is called for each member of the object.
Alternatively, this can be the options object if no reviver function is provided.
Param
Optional configuration for reading and parsing the JSON file. See ReadJsonOptions.
If reviver is an object, this argument is ignored.
Example
```javascript import { readJson } from "@visulima/fs"; import { join } from "node:path";
const readMyJson = async () => { try { const data = await readJson(join("path", "to", "my-config.json")); console.log("Config data:", data);
// With a reviver function
const dataWithReviver = await readJson(join("path", "to", "another.json"), (key, value) => {
if (key === "date") return new Da