@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.
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.
string
The string content to detect the EOL from.
"\n" | "\r\n"
import { detect } from "@visulima/fs/eol";
detect("Hello\r\nWorld"); // "\r\n"
detect("Hello\nWorld"); // "\n"
detect("HelloWorld"); // null
function format(content, eol): string;
Defined in: packages/fs/src/eol.ts:54
Format the file to the targeted EOL.
string
The string content to format.
The target EOL character.
"\n" | "\r\n"
string
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"
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 LF: "\n";
Defined in: packages/fs/src/eol.ts:6
End-of-line character for POSIX platforms such as macOS and Linux.
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.
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);
}
}
Errornew AlreadyExistsError(message): AlreadyExistsError;
Defined in: packages/fs/src/error/already-exists-error.ts:33
Creates a new instance.
string
The error message.
Error.constructor;
get code(): string;
Defined in: packages/fs/src/error/already-exists-error.ts:38
string
set code(_name): void;
Defined in: packages/fs/src/error/already-exists-error.ts:43
string
void
get name(): string;
Defined in: packages/fs/src/error/already-exists-error.ts:48
string
set name(_name): void;
Defined in: packages/fs/src/error/already-exists-error.ts:53
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.8.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
Error.cause;
message: string;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es5.d.ts:1077
Error.message;
optional stack: string;
Defined in: node_modules/.pnpm/typescript@5.8.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: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.
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();
Errornew DirectoryError(message): DirectoryError;
Defined in: packages/fs/src/error/directory-error.ts:41
Creates a new instance.
string
The error message.
Error.constructor;
get code(): string;
Defined in: packages/fs/src/error/directory-error.ts:46
string
set code(_name): void;
Defined in: packages/fs/src/error/directory-error.ts:51
string
void
get name(): string;
Defined in: packages/fs/src/error/directory-error.ts:56
string
set name(_name): void;
Defined in: packages/fs/src/error/directory-error.ts:61
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.8.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
Error.cause;
message: string;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es5.d.ts:1077
Error.message;
optional stack: string;
Defined in: node_modules/.pnpm/typescript@5.8.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:40
Error thrown when a directory is not empty.
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();
Errornew NotEmptyError(message): NotEmptyError;
Defined in: packages/fs/src/error/not-empty-error.ts:45
Creates a new instance.
string
The error message.
Error.constructor;
get code(): string;
Defined in: packages/fs/src/error/not-empty-error.ts:50
string
set code(_name): void;
Defined in: packages/fs/src/error/not-empty-error.ts:55
string
void
get name(): string;
Defined in: packages/fs/src/error/not-empty-error.ts:60
string
set name(_name): void;
Defined in: packages/fs/src/error/not-empty-error.ts:65
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.8.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
Error.cause;
message: string;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es5.d.ts:1077
Error.message;
optional stack: string;
Defined in: node_modules/.pnpm/typescript@5.8.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:33
Error thrown when a file or directory is not found at a specified path.
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();
Errornew NotFoundError(message): NotFoundError;
Defined in: packages/fs/src/error/not-found-error.ts:38
Creates a new instance.
string
The error message.
Error.constructor;
get code(): string;
Defined in: packages/fs/src/error/not-found-error.ts:43
string
set code(_name): void;
Defined in: packages/fs/src/error/not-found-error.ts:48
string
void
get name(): string;
Defined in: packages/fs/src/error/not-found-error.ts:53
string
set name(_name): void;
Defined in: packages/fs/src/error/not-found-error.ts:58
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.8.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
Error.cause;
message: string;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es5.d.ts:1077
Error.message;
optional stack: string;
Defined in: node_modules/.pnpm/typescript@5.8.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:34
Error thrown when an operation is not permitted due to insufficient privileges or other access control restrictions.
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();
Errornew PermissionError(message): PermissionError;
Defined in: packages/fs/src/error/permission-error.ts:39
Creates a new instance.
string
The error message.
Error.constructor;
get code(): string;
Defined in: packages/fs/src/error/permission-error.ts:44
string
set code(_name): void;
Defined in: packages/fs/src/error/permission-error.ts:49
string
void
get name(): string;
Defined in: packages/fs/src/error/permission-error.ts:54
string
set name(_name): void;
Defined in: packages/fs/src/error/permission-error.ts:59
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.8.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
Error.cause;
message: string;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es5.d.ts:1077
Error.message;
optional stack: string;
Defined in: node_modules/.pnpm/typescript@5.8.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:43
Error thrown in walk or walkSync during iteration.
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();
Errornew WalkError(cause, root): WalkError;
Defined in: packages/fs/src/error/walk-error.ts:52
Constructs a new instance.
unknown
The underlying error or reason for the walk failure.
string
The root directory path where the walk operation started or encountered the error.
Error.constructor;
get name(): string;
Defined in: packages/fs/src/error/walk-error.ts:61
string
set name(_name): void;
Defined in: packages/fs/src/error/walk-error.ts:66
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.8.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
Error.cause;
message: string;
Defined in: node_modules/.pnpm/typescript@5.8.3/node_modules/typescript/lib/lib.es5.d.ts:1077
Error.message;
root: string;
Defined in: packages/fs/src/error/walk-error.ts:45
File path of the root that's being walked.
optional stack: string;
Defined in: node_modules/.pnpm/typescript@5.8.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:37
Asynchronously collects all file paths within a directory that match the specified criteria. By default, it searches for JavaScript and TypeScript file extensions.
string
The root directory to start collecting files from.
WalkOptions = {}
Optional configuration to control the collection process. See WalkOptions.
Promise<string[]>
A promise that resolves to an array of absolute file paths.
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();
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.
string
The root directory to start collecting files from.
WalkOptions = {}
Optional configuration to control the collection process. See WalkOptions.
string[]
An array of absolute file paths.
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);
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.
The path to the directory to empty.
string | URL
RetryOptions
Optional configuration for the operation. See RetryOptions.
Promise<void>
A promise that resolves when the directory is empty.
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();
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.
The path to the directory to empty.
string | URL
RetryOptions
Optional configuration for the operation. See RetryOptions.
void
void
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);
}
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.
The path to the directory to ensure exists.
string | URL
Promise<void>
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
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.
The path to the directory to ensure exists.
string | URL
void
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
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.
The path to the file. Can be a string or a URL object.
string | URL
Promise<void>
A Promise that resolves when the file has been created or confirmed to exist.
Will throw an error if the path exists and is not a file.
Will throw an error if directory or file creation fails for reasons other than the path not existing initially.
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);
}
})();
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.
The path to the file to ensure exists.
string | URL
void
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
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.
The path to the source file or directory.
string | URL
The path to the destination link.
string | URL
Promise<void>
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"));
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.
The path to the source file or directory.
string | URL
The path to the destination link.
string | URL
void
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"));
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.
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.
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");
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.
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.
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");
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.
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.
FindUpOptions = {}
Optional configuration for the search. See FindUpOptions.
Promise<string>
A promise that resolves to the absolute path of the first found file/directory, or undefined if not found.
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();
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.
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.
FindUpOptions = {}
Optional configuration for the search. See FindUpOptions.
string
The absolute path of the first found file/directory, or undefined if not found.
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);
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.
The path to the file or directory. Can be a string or a URL object.
string | URL
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.
Promise<boolean>
A Promise that resolves to a boolean indicating if the path is accessible with the specified mode.
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");
}
})();
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.
string | URL
number
boolean
true if the accessibility check is successful, false otherwise.
A path to a file or directory. If a URL is provided, it must use the file: protocol.
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.
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);
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 { move } from '@visulima/fs';
await move('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 { moveSync } from '@visulima/fs';
moveSync('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:57
Asynchronously reads the entire contents of a file.
It can also decompress the file content if a compression option is provided.
O extends ReadFileOptions<"brotli" | "gzip" | "none"> = undefined
The type of the options object, extending ReadFileOptions.
The path to the file to read. Can be a file URL or a string path.
string | URL
O
Optional configuration for reading the file. See ReadFileOptions.
Available compression methods: "brotli", "gzip", "none" (default).
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).
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();
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.
O extends ReadFileOptions<"brotli" | "gzip" | "none"> = undefined
The type of the options object, extending ReadFileOptions.
The path to the file to read. Can be a file URL or a string path.
string | URL
O
Optional configuration for reading the file. See ReadFileOptions.
Available compression methods: "brotli", "gzip", "none" (default).
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).
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);
}
Asynchronously reads a JSON file and then parses it into an object.
The expected type of the parsed JSON object.
The path to the JSON file to read. Can be a file URL or a string path.
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.
Optional configuration for reading and parsing the JSON file. See ReadJsonOptions.
If reviver is an object, this argument is ignored.
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 Date(value);
return value;
});
console.log("Date field is now a Date object:", dataWithReviver.date);
// With options (e.g., for custom error reporting)
const dataWithOptions = await readJson(join("path", "to", "options.json"), { color: { message: (str) => `\x1b[31m${str}\x1b[0m` } });
console.log(dataWithOptions);
} catch (error) {
console.error("Failed to read or parse JSON file:", error);
}
};
readMyJson();
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>
Synchronously reads a JSON file and then parses it into an object.
The expected type of the parsed JSON object.
The path to the JSON file to read. Can be a file URL or a string path.
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.
Optional configuration for reading and parsing the JSON file. See ReadJsonOptions.
If reviver is an object, this argument is ignored.
import { readJsonSync } from "@visulima/fs";
import { join } from "node:path";
try {
const data = readJsonSync(join("path", "to", "my-config.json"));
console.log("Config data:", data);
// With a reviver function
const dataWithReviver = readJsonSync(join("path", "to", "another.json"), (key, value) => {
if (key === "date") return new Date(value);
return value;
});
console.log("Date field is now a Date object:", dataWithReviver.date);
// With options (e.g., for custom error reporting)
const dataWithOptions = readJsonSync(join("path", "to", "options.json"), { color: { message: (str) => `\x1b[31m${str}\x1b[0m` } });
console.log(dataWithOptions);
} catch (error) {
console.error("Failed to read or parse JSON file:", error);
}
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:36
Asynchronously removes a file or directory (recursively). If the path does not exist, it does nothing.
The path to the file or directory to remove.
string | URL
RetryOptions = {}
Optional configuration for the operation. See RetryOptions.
Promise<void>
A promise that resolves when the path has been removed.
import { remove } from "@visulima/fs";
import { join } from "node:path";
const deleteFileOrDir = async () => {
try {
await remove(join("/tmp", "my-file.txt"));
console.log("File /tmp/my-file.txt removed.");
await remove(join("/tmp", "my-empty-dir"));
console.log("Directory /tmp/my-empty-dir removed.");
await remove(join("/tmp", "my-dir-with-contents"));
console.log("Directory /tmp/my-dir-with-contents and its contents removed.");
} catch (error) {
console.error("Failed to remove path:", error);
}
};
deleteFileOrDir();
function removeSync(path, options): void;
Defined in: packages/fs/src/remove/remove-sync.ts:32
Synchronously removes a file or directory (recursively). If the path does not exist, it does nothing.
The path to the file or directory to remove.
string | URL
RetryOptions = {}
Optional configuration for the operation. See RetryOptions.
void
void
import { removeSync } from "@visulima/fs";
import { join } from "node:path";
try {
removeSync(join("/tmp", "my-file.txt"));
console.log("File /tmp/my-file.txt removed.");
removeSync(join("/tmp", "my-empty-dir"));
console.log("Directory /tmp/my-empty-dir removed.");
removeSync(join("/tmp", "my-dir-with-contents"));
console.log("Directory /tmp/my-dir-with-contents and its contents removed.");
} catch (error) {
console.error("Failed to remove path:", error);
}
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 { rename } from '@visulima/fs';
await rename('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 { renameSync } from '@visulima/fs';
renameSync('test.png', 'tests.png', {cwd: 'source'});
console.log('The file has been renamed');
function walk(directory, options): AsyncIterableIterator<WalkEntry>;
Defined in: packages/fs/src/find/walk.ts:64
Asynchronously walks the file tree rooted at directory, yielding each file or directory that matches the criteria specified in options.
The root directory to start walking from.
string | URL
WalkOptions = {}
Optional configuration to control the walking process. See WalkOptions.
AsyncIterableIterator<WalkEntry>
An async iterable iterator yielding WalkEntry objects for each matching file or directory.
import { walk } from "@visulima/fs";
import { join } from "node:path";
const printEntries = async () => {
// Walk through /tmp/my-project, looking for .ts files, max depth 2
for await (const entry of walk(join("/tmp", "my-project"), { extensions: ["ts"], maxDepth: 2 })) {
console.log(`Found: ${entry.path} (Type: ${entry.isFile() ? "file" : "directory"})`);
}
// Walk, including only directories, and skip any node_modules folders
for await (const entry of walk(join("/tmp", "another-project"), { includeFiles: false, skip: [/node_modules/] })) {
if (entry.isDirectory()) {
console.log(`Directory: ${entry.path}`);
}
}
};
printEntries();
function walkSync(directory, options): IterableIterator<WalkEntry>;
Defined in: packages/fs/src/find/walk-sync.ts:64
Synchronously walks the file tree rooted at directory, yielding each file or directory that matches the criteria specified in options.
This is the synchronous version of the walk function.
The root directory to start walking from.
string | URL
WalkOptions = {}
Optional configuration to control the walking process. See WalkOptions.
IterableIterator<WalkEntry>
An iterable iterator yielding WalkEntry objects for each matching file or directory.
import { walkSync } from "@visulima/fs";
import { join } from "node:path";
// Walk through /tmp/my-project, looking for .ts files, max depth 2
for (const entry of walkSync(join("/tmp", "my-project"), { extensions: ["ts"], maxDepth: 2 })) {
console.log(`Found: ${entry.path} (Type: ${entry.isFile() ? "file" : "directory"})`);
}
// Walk, including only directories, and skip any node_modules folders
for (const entry of walkSync(join("/tmp", "another-project"), { includeFiles: false, skip: [/node_modules/] })) {
if (entry.isDirectory()) {
console.log(`Directory: ${entry.path}`);
}
}
function writeFile(path, content, options?): Promise<void>;
Defined in: packages/fs/src/write/write-file.ts:43
Asynchronously writes data to a file, replacing the file if it already exists. This function includes safeguards like writing to a temporary file first and then renaming, and handling permissions.
The path to the file to write. Can be a file URL or a string path.
string | URL
The data to write. Can be a string, Buffer, ArrayBuffer, or ArrayBufferView.
string | ArrayBuffer | ArrayBufferView<ArrayBufferLike>
Optional configuration for writing the file. See WriteFileOptions.
Promise<void>
A promise that resolves when the file has been written.
import { writeFile } from "@visulima/fs";
import { join } from "node:path";
const writeMyFile = async () => {
try {
await writeFile(join("/tmp", "my-new-file.txt"), "Hello World!");
console.log("File written successfully.");
await writeFile(join("/tmp", "another-file.txt"), "Some other content", { encoding: "utf16le", mode: 0o600 });
console.log("Another file written with specific options.");
} catch (error) {
console.error("Failed to write file:", error);
}
};
writeMyFile();
function writeFileSync(path, content, options?): void;
Defined in: packages/fs/src/write/write-file-sync.ts:43
Synchronously writes data to a file, replacing the file if it already exists. This function includes safeguards like writing to a temporary file first and then renaming, and handling permissions.
The path to the file to write. Can be a file URL or a string path.
string | URL
The data to write. Can be a string, Buffer, ArrayBuffer, or ArrayBufferView.
string | ArrayBuffer | ArrayBufferView<ArrayBufferLike>
Optional configuration for writing the file. See WriteFileOptions.
void
void
import { writeFileSync } from "@visulima/fs";
import { join } from "node:path";
const writeMyFileSync = () => {
try {
writeFileSync(join("/tmp", "my-new-file-sync.txt"), "Hello World Synchronously!");
console.log("File written successfully (sync).");
writeFileSync(join("/tmp", "another-file-sync.txt"), "Some other sync content", { encoding: "utf16le", mode: 0o600 });
console.log("Another file written with specific options (sync).");
} catch (error) {
console.error("Failed to write file (sync):", error);
}
};
writeMyFileSync();
function writeJson(path, data, options): Promise<void>;
Defined in: packages/fs/src/write/write-json.ts:39
Asynchronously writes an object to a JSON file. Handles indentation detection, custom stringifiers, and gracefully manages existing files.
The path to the JSON file to write. Can be a file URL or a string path.
string | URL
unknown
The data to serialize and write. Can be any JavaScript value that can be stringified by JSON.stringify or a custom stringifier.
WriteJsonOptions = {}
Optional configuration for writing the JSON file. See WriteJsonOptions.
Promise<void>
A promise that resolves when the JSON file has been written.
import { writeJson } from "@visulima/fs";
import { join } from "node:path";
const writeMyJson = async () => {
try {
await writeJson(join("/tmp", "my-config.json"), { setting: "enabled", value: 123 });
console.log("JSON file written successfully.");
await writeJson(join("/tmp", "another-config.json"), { user: "test", id: "abc" }, { indent: 2, replacer: ["user"] });
console.log("Another JSON file written with specific options (indent 2, only 'user' key).");
} catch (error) {
console.error("Failed to write JSON file:", error);
}
};
writeMyJson();
function writeJsonSync(path, data, options): void;
Defined in: packages/fs/src/write/write-json-sync.ts:39
Synchronously writes an object to a JSON file. Handles indentation detection, custom stringifiers, and gracefully manages existing files.
The path to the JSON file to write. Can be a file URL or a string path.
string | URL
unknown
The data to serialize and write. Can be any JavaScript value that can be stringified by JSON.stringify or a custom stringifier.
WriteJsonOptions = {}
Optional configuration for writing the JSON file. See WriteJsonOptions.
void
void
import { writeJsonSync } from "@visulima/fs";
import { join } from "node:path";
const writeMyJsonSync = () => {
try {
writeJsonSync(join("/tmp", "my-config-sync.json"), { setting: "enabled", value: 456 });
console.log("JSON file written successfully (sync).");
writeJsonSync(join("/tmp", "another-config-sync.json"), { user: "testSync", id: "def" }, { indent: 4, replacer: ["id"] });
console.log("Another JSON file written with specific options (sync, indent 4, only 'id' key).");
} catch (error) {
console.error("Failed to write JSON file (sync):", error);
}
};
writeMyJsonSync();
const F_OK: 0 = 0;
Defined in: packages/fs/src/constants.ts:5
Constant to check if the path is visible to the calling process.
Corresponds to node:fs.constants.F_OK.
const FIND_UP_STOP: typeof FIND_UP_STOP;
Defined in: packages/fs/src/constants.ts:29
A special symbol that can be returned by the matcher function in findUp or findUpSync
to stop the search process prematurely.
const R_OK: 4 = 4;
Defined in: packages/fs/src/constants.ts:11
Constant to check if the path is readable to the calling process.
Corresponds to node:fs.constants.R_OK.
const W_OK: 2 = 2;
Defined in: packages/fs/src/constants.ts:17
Constant to check if the path is writable to the calling process.
Corresponds to node:fs.constants.W_OK.
const X_OK: 1 = 1;
Defined in: packages/fs/src/constants.ts:23
Constant to check if the path is executable by the calling process.
Corresponds to node:fs.constants.X_OK.
Defined in: packages/fs/src/types.ts:62
Represents an entry found by walk or walkSync.
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:64
The full path to the entry.
Defined in: packages/fs/src/types.ts:12
Options for the walk and walkSync functions.
optional extensions: string[];
Defined in: packages/fs/src/types.ts:18
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:23
Indicates whether symlinks should be resolved or not.
{
false;
}
optional includeDirs: boolean;
Defined in: packages/fs/src/types.ts:28
Indicates whether directory entries should be included or not.
{
true;
}
optional includeFiles: boolean;
Defined in: packages/fs/src/types.ts:33
Indicates whether file entries should be included or not.
{
true;
}
optional includeSymlinks: boolean;
Defined in: packages/fs/src/types.ts:39
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:45
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:50
The maximum depth of the file tree to be walked recursively.
{
Infinity;
}
optional skip: (string | RegExp)[];
Defined in: packages/fs/src/types.ts:56
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:117
Specifies a location (line and column) in a file for code frame generation.
optional column: number;
Defined in: packages/fs/src/types.ts:119
The column number.
line: number;
Defined in: packages/fs/src/types.ts:121
The line number.
type CodeFrameOptions = object;
Defined in: packages/fs/src/types.ts:127
Options for customizing the appearance of code frames.
optional color: object;
Defined in: packages/fs/src/types.ts:129
Colorization methods for different parts of the code frame.
optional gutter: ColorizeMethod;
Color for the gutter (line numbers).
optional marker: ColorizeMethod;
Color for the marker (pointing to the error).
optional message: ColorizeMethod;
Color for the message.
type ContentType<O> = O extends object ? Buffer : string;
Defined in: packages/fs/src/types.ts:104
Represents the content type of a read file, which can be a Buffer or a string based on options.
O = undefined
The ReadFileOptions type.
type FindUpName =
| string[]
| string
| (directory) => FindUpNameFnResult;
Defined in: packages/fs/src/types.ts:270
Specifies the name(s) of the file or directory to search for in findUp.
Can be a single name, an array of names, or a function that returns a name or FIND_UP_STOP.
type FindUpNameFnResult = PathLike | Promise<PathLike | typeof FIND_UP_STOP> | typeof FIND_UP_STOP | undefined;
Defined in: packages/fs/src/types.ts:264
The result type for the name matcher function used in findUp.
It can be a PathLike (string, Buffer, or URL), a Promise resolving to PathLike or FIND_UP_STOP,
FIND_UP_STOP to stop the search, or undefined to continue.
type FindUpNameSync =
| string[]
| string
| (directory) => FindUpNameSyncFnResult;
Defined in: packages/fs/src/types.ts:284
Specifies the name(s) of the file or directory to search for in findUpSync.
Can be a single name, an array of names, or a function that returns a name or FIND_UP_STOP.
type FindUpNameSyncFnResult = PathLike | typeof FIND_UP_STOP | undefined;
Defined in: packages/fs/src/types.ts:278
The result type for the name matcher function used in findUpSync.
It can be a PathLike (string, Buffer, or URL), FIND_UP_STOP to stop the search,
or undefined to continue.
type FindUpOptions = object;
Defined in: packages/fs/src/types.ts:235
Options for the findUp and findUpSync functions.
optional allowSymlinks: boolean;
Defined in: packages/fs/src/types.ts:240
Whether to follow symbolic links.
undefined (behaves like true for findUp, false for findUpSync due to fs.stat vs fs.lstat)
optional cwd: URL | string;
Defined in: packages/fs/src/types.ts:245
The current working directory.
process.cwd();
optional stopAt: URL | string;
Defined in: packages/fs/src/types.ts:250
The directory to stop searching at.
path.parse(cwd).root;
optional type: "directory" | "file";
Defined in: packages/fs/src/types.ts:255
The type of path to find.
"file";
type JsonReplacer = (number | string)[] | (this, key, value) => unknown | null;
Defined in: packages/fs/src/types.ts:197
Type for the replacer parameter of JSON.stringify().
Can be a function that alters the behavior of the stringification process,
or an array of strings and numbers that acts as a whitelist for selecting
the properties of the value object to be included in the JSON string.
If this value is null or not provided, all properties of the object are included in the resulting JSON string.
type JsonReviver = Parameters<(typeof JSON)["parse"]>["1"];
Defined in: packages/fs/src/types.ts:112
Type for the reviver parameter of JSON.parse().
A function that transforms the results. This function is called for each member of the object.
If a member contains nested objects, the nested objects are transformed before the parent object is.
type MoveOptions = object;
Defined in: packages/fs/src/move/types.ts:3
optional cwd: URL | string;
Defined in: packages/fs/src/move/types.ts:10
The working directory to find source files. The source and destination path are relative to this.
process.cwd();
readonly optional directoryMode: FilePermissions;
Defined in: packages/fs/src/move/types.ts:19
Permissions for created directories.
It has no effect on Windows.
0o777;
readonly optional overwrite: boolean;
Defined in: packages/fs/src/move/types.ts:26
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:71
Supported file encodings for reading files.
type ReadFileOptions<C> = object;
Defined in: packages/fs/src/types.ts:77
Options for reading files.
C
The type of compression used.
optional buffer: boolean;
Defined in: packages/fs/src/types.ts:81
Return content as a Buffer. Default: false
optional compression: C;
Defined in: packages/fs/src/types.ts:86
Compression method to decompress the file against. Default: none
optional encoding: ReadFileEncoding;
Defined in: packages/fs/src/types.ts:92
The encoding to use. Default: utf8
https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings
optional flag: number | string;
Defined in: packages/fs/src/types.ts:97
The flag used to open the file. Default: r
type ReadJsonOptions = CodeFrameOptions & object;
Defined in: packages/fs/src/types.ts:143
Options for reading and parsing JSON files. Extends CodeFrameOptions.
optional beforeParse: (source) => string;
A function to transform the string content before parsing.
string
The raw string content of the file.
string
The transformed string content.
type WriteFileOptions = object;
Defined in: packages/fs/src/types.ts:155
Options for writing files.
optional chown: object;
Defined in: packages/fs/src/types.ts:159
The group and user ID used to set the file ownership. Default: undefined
gid: number;
uid: number;
optional encoding: BufferEncoding | null;
Defined in: packages/fs/src/types.ts:167
The encoding to use. Default: utf8
optional flag: string;
Defined in: packages/fs/src/types.ts:172
The flag used to write the file. Default: w
optional mode: number;
Defined in: packages/fs/src/types.ts:177
The file mode (permission and sticky bits). Default: 0o666
optional overwrite: boolean;
Defined in: packages/fs/src/types.ts:182
Indicates whether the file should be overwritten if it already exists. Default: false
optional recursive: boolean;
Defined in: packages/fs/src/types.ts:187
Recursively create parent directories if needed. Default: true
type WriteJsonOptions = WriteFileOptions & object;
Defined in: packages/fs/src/types.ts:208
Options for writing JSON files. Extends WriteFileOptions.
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
Re-exports CRLF
Re-exports detect
Re-exports EOL
Re-exports format
Re-exports LF
function brotliSize(input, options?): Promise<number>;
Defined in: packages/fs/src/size.ts:222
Asynchronously calculates the Brotli compressed size of the given input. The input can be a Buffer, a Readable stream, a URL object pointing to a file, or a string (file path or content). Uses memory-efficient streaming for files and streams to avoid loading entire contents into memory.
The input data to compress with Brotli and measure.
string | URL | Buffer<ArrayBufferLike> | Readable
BrotliOptions
Optional Zlib options for Brotli compression.
Promise<number>
A promise that resolves with the Brotli compressed size in bytes.
import { brotliSize } from "@visulima/fs";
import { Readable } from "node:stream";
import { writeFile, unlink } from "node:fs/promises";
import { join } from "node:path";
const text = "This is a test string for Brotli compression efficiency.";
const filePath = join("temp-brotli-file.txt");
async function main() {
// From Buffer
const buffer = Buffer.from(text);
console.log(`Brotli size of buffer: ${await brotliSize(buffer)} bytes`);
// From string (content)
console.log(`Brotli size of string content: ${await brotliSize(text)} bytes`);
// From file path
await writeFile(filePath, text);
console.log(`Brotli size of file: ${await brotliSize(filePath)} bytes`);
// From URL
const fileUrl = new URL(`file://${filePath}`);
console.log(`Brotli size of URL: ${await brotliSize(fileUrl)} bytes`);
// From Readable stream
const stream = Readable.from(text);
console.log(`Brotli size of stream: ${await brotliSize(stream)} bytes`);
await unlink(filePath); // Clean up temp file
}
main().catch(console.error);
function brotliSizeSync(input, options?): number;
Defined in: packages/fs/src/size.ts:370
Synchronously calculates the Brotli compressed size of the given input.
The input can be a Buffer, a URL object pointing to a file, or a string (file path or content).
Note: For Readable streams or very large files, consider using the asynchronous brotliSize function for better performance and to avoid blocking.
The input data to compress with Brotli and measure.
string | URL | Buffer<ArrayBufferLike>
BrotliOptions
Optional Zlib options for Brotli compression.
number
The Brotli compressed size in bytes.
import { brotliSizeSync } from "@visulima/fs";
import { writeFileSync, unlinkSync } from "node:fs";
import { join } from "node:path";
const text = "This is a test string for Brotli compression efficiency, synchronously.";
const filePath = join("temp-brotli-sync-file.txt");
// From Buffer
const buffer = Buffer.from(text);
console.log(`Sync Brotli size of buffer: ${brotliSizeSync(buffer)} bytes`);
// From string (content)
console.log(`Sync Brotli size of string content: ${brotliSizeSync(text)} bytes`);
// From file path
try {
writeFileSync(filePath, text);
console.log(`Sync Brotli size of file: ${brotliSizeSync(filePath)} bytes`);
// From URL
const fileUrl = new URL(`file://${filePath}`);
console.log(`Sync Brotli size of URL: ${brotliSizeSync(fileUrl)} bytes`);
} finally {
try {
unlinkSync(filePath);
} catch {} // Clean up temp file
}
function gzipSize(input, options?): Promise<number>;
Defined in: packages/fs/src/size.ts:171
Asynchronously calculates the gzipped size of the given input. The input can be a Buffer, a Readable stream, a URL object pointing to a file, or a string (file path or content). Uses memory-efficient streaming for files and streams to avoid loading entire contents into memory.
The input data to gzip and measure.
string | URL | Buffer<ArrayBufferLike> | Readable
ZlibOptions
Optional Zlib options for gzip compression.
Promise<number>
A promise that resolves with the gzipped size in bytes.
import { gzipSize } from "@visulima/fs";
import { Readable } from "node:stream";
import { writeFile, unlink } from "node:fs/promises";
import { join } from "node:path";
const text = "Lorem ipsum dolor sit amet, consectetur adipiscing elit.";
const filePath = join("temp-file.txt");
async function main() {
// From Buffer
const buffer = Buffer.from(text);
console.log(`Gzip size of buffer: ${await gzipSize(buffer)} bytes`);
// From string (content)
console.log(`Gzip size of string content: ${await gzipSize(text)} bytes`);
// From file path
await writeFile(filePath, text);
console.log(`Gzip size of file: ${await gzipSize(filePath)} bytes`);
// From URL
const fileUrl = new URL(`file://${filePath}`);
console.log(`Gzip size of URL: ${await gzipSize(fileUrl)} bytes`);
// From Readable stream
const stream = Readable.from(text);
console.log(`Gzip size of stream: ${await gzipSize(stream)} bytes`);
await unlink(filePath); // Clean up temp file
}
main().catch(console.error);
function gzipSizeSync(input, options?): number;
Defined in: packages/fs/src/size.ts:316
Synchronously calculates the gzipped size of the given input.
The input can be a Buffer, a URL object pointing to a file, or a string (file path or content).
Note: For Readable streams or very large files, consider using the asynchronous gzipSize function for better performance and to avoid blocking.
The input data to gzip and measure.
string | URL | Buffer<ArrayBufferLike>
ZlibOptions
Optional Zlib options for gzip compression.
number
The gzipped size in bytes.
import { gzipSizeSync } from "@visulima/fs";
import { writeFileSync, unlinkSync } from "node:fs";
import { join } from "node:path";
const text = "Lorem ipsum dolor sit amet, consectetur adipiscing elit.";
const filePath = join("temp-sync-file.txt");
// From Buffer
const buffer = Buffer.from(text);
console.log(`Sync Gzip size of buffer: ${gzipSizeSync(buffer)} bytes`);
// From string (content)
console.log(`Sync Gzip size of string content: ${gzipSizeSync(text)} bytes`);
// From file path
try {
writeFileSync(filePath, text);
console.log(`Sync Gzip size of file: ${gzipSizeSync(filePath)} bytes`);
// From URL
const fileUrl = new URL(`file://${filePath}`);
console.log(`Sync Gzip size of URL: ${gzipSizeSync(fileUrl)} bytes`);
} finally {
try {
unlinkSync(filePath);
} catch {} // Clean up temp file
}
function rawSize(input): Promise<number>;
Defined in: packages/fs/src/size.ts:272
Asynchronously calculates the raw (uncompressed) size of the given input. The input can be a Buffer, a Readable stream, a URL object pointing to a file, or a string (file path or content). Uses memory-efficient streaming for files and streams to avoid loading entire contents into memory.
The input data to measure.
string | URL | Buffer<ArrayBufferLike> | Readable
Promise<number>
A promise that resolves with the raw size in bytes.
import { rawSize } from "@visulima/fs";
import { Readable } from "node:stream";
import { writeFile, unlink } from "node:fs/promises";
import { join } from "node:path";
const text = "Hello, World!";
const filePath = join("temp-raw-file.txt");
async function main() {
// From Buffer
const buffer = Buffer.from(text);
console.log(`Raw size of buffer: ${await rawSize(buffer)} bytes`);
// From string (content)
console.log(`Raw size of string content: ${await rawSize(text)} bytes`);
// From file path
await writeFile(filePath, text);
console.log(`Raw size of file: ${await rawSize(filePath)} bytes`);
// From URL
const fileUrl = new URL(`file://${filePath}`);
console.log(`Raw size of URL: ${await rawSize(fileUrl)} bytes`);
// From Readable stream
const stream = Readable.from(text);
console.log(`Raw size of stream: ${await rawSize(stream)} bytes`);
await unlink(filePath); // Clean up temp file
}
main().catch(console.error);
function rawSizeSync(input): number;
Defined in: packages/fs/src/size.ts:424
Synchronously calculates the raw (uncompressed) size of the given input.
The input can be a Buffer, a URL object pointing to a file, or a string (file path or content).
For file paths, it uses statSync to get the file size.
Note: For Readable streams or very large files, consider using the asynchronous rawSize function for better performance and to avoid blocking.
The input data to measure.
string | URL | Buffer<ArrayBufferLike>
number
The raw size in bytes.
import { rawSizeSync } from "@visulima/fs";
import { writeFileSync, unlinkSync } from "node:fs";
import { join } from "node:path";
const text = "Hello, Synchronous World!";
const filePath = join("temp-raw-sync-file.txt");
// From Buffer
const buffer = Buffer.from(text);
console.log(`Sync Raw size of buffer: ${rawSizeSync(buffer)} bytes`);
// From string (content)
console.log(`Sync Raw size of string content: ${rawSizeSync(text)} bytes`);
// From file path
try {
writeFileSync(filePath, text);
console.log(`Sync Raw size of file: ${rawSizeSync(filePath)} bytes`);
// From URL
const fileUrl = new URL(`file://${filePath}`);
console.log(`Sync Raw size of URL: ${rawSizeSync(fileUrl)} bytes`);
} finally {
try {
unlinkSync(filePath);
} catch {} // Clean up temp file
}
Defined in: packages/fs/src/error/json-error.ts:39
Custom error class for handling JSON parsing or related errors. It can optionally include a file name and a code frame for better debugging.
import { JSONError } from "@visulima/fs/error";
import { readJsonSync } from "@visulima/fs"; // Or any function that might throw this
import { join } from "node:path";
try {
// Imagine readJsonSync encounters a malformed JSON file and throws JSONError
// Forcing the scenario for demonstration:
const simulateJsonError = (filePath, content) => {
const err = new JSONError(`Unexpected token '}' at position 15`);
err.fileName = filePath;
// A real implementation might generate a code frame using a library
err.codeFrame = ` 13 | "key": "value",
> 14 | "anotherKey": "anotherValue",}
| ^
15 | "lastKey": "end"
`;
throw err;
};
simulateJsonError(join("path", "to", "corrupted.json"), '{ "key": "value", "anotherKey": "anotherValue",} ');
// const jsonData = readJsonSync(join("path", "to", "corrupted.json"));
} catch (error) {
if (error instanceof JSONError) {
console.error(`JSON Error: ${error.message}`);
// message property will include fileName and codeFrame if they were set.
// console.error(`File: ${error.fileName}`);
// console.error(`Code Frame:\n${error.codeFrame}`);
} else {
console.error("An unexpected error occurred:", error);
}
}
Errornew JSONError(message): JSONError;
Defined in: packages/fs/src/error/json-error.ts:53
Creates a new JSONError instance.
string
The primary error message.
Error.constructor;
get message(): string;
Defined in: packages/fs/src/error/json-error.ts:63
string
set message(message): void;
Defined in: packages/fs/src/error/json-error.ts:67
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.8.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
Error.cause;
codeFrame: string;
Defined in: packages/fs/src/error/json-error.ts:42
fileName: string;
Defined in: packages/fs/src/error/json-error.ts:40
readonly name: "JSONError" = "JSONError";
Defined in: packages/fs/src/error/json-error.ts:45
Error.name;
optional stack: string;
Defined in: node_modules/.pnpm/typescript@5.8.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:28
Asserts that the provided contents are valid for writing to a file. Valid contents can be a string, an ArrayBuffer, or an ArrayBuffer view (e.g., Uint8Array).
any
The file contents to validate.
void
If the contents are not a string, ArrayBuffer, or ArrayBuffer view.
import { assertValidFileContents } from "@visulima/fs"; // Assuming this util is exported
try {
assertValidFileContents("Hello, world!");
assertValidFileContents(new Uint8Array([72, 101, 108, 108, 111])); // "Hello"
assertValidFileContents(new ArrayBuffer(8));
console.log("File contents are valid.");
} catch (error) {
console.error(error.message); // File contents must be a string, ArrayBuffer, or ArrayBuffer view.
}
try {
assertValidFileContents(123); // Invalid content type
} catch (error) {
console.error(error.message); // File contents must be a string, ArrayBuffer, or ArrayBuffer view.
}
function assertValidFileOrDirectoryPath(fileOrDirectoryPath): void;
Defined in: packages/fs/src/utils/assert-valid-file-or-directory-path.ts:27
Asserts that the provided path is a valid file or directory path. A valid path must be a non-empty string or a URL instance.
any
The path to validate.
void
If the path is not a non-empty string or a URL.
import { assertValidFileOrDirectoryPath } from "@visulima/fs"; // Assuming this util is exported
try {
assertValidFileOrDirectoryPath("/path/to/file.txt");
assertValidFileOrDirectoryPath(new URL("file:///path/to/file.txt"));
console.log("Path is valid.");
} catch (error) {
console.error(error.message); // Path must be a non-empty string or URL.
}
try {
assertValidFileOrDirectoryPath(""); // Invalid path
} catch (error) {
console.error(error.message); // Path must be a non-empty string or URL.
}
Parses a JSON string, constructing the JavaScript value or object described by the string.
This is a modified version of parse-json from https://github.com/sindresorhus/parse-json/blob/main/index.js.
It provides more detailed error messages including code frames.
The type of the parsed JSON value.
The JSON string to parse.
An optional reviver function that can transform the results, or a filename string if no reviver is used.
An optional filename string (if reviver is provided), or CodeFrameOptions (if reviver is not provided and this is the third argument).
Optional options for generating the code frame on error.
If the string to parse is not valid JSON, or if any other parsing error occurs.
import { parseJson } from "@visulima/fs"; // Assuming this util is exported or re-exported
const jsonString = '{"name": "John Doe", "age": 30, "city": "New York"}';
const malformedJson = '{"name": "Jane Doe", "age": "thirty}'; // Missing quote
try {
const data = parseJson(jsonString);
console.log(data.name); // Output: John Doe
const dataWithReviver = parseJson(jsonString, (key, value) => {
if (key === "age") {
return value + 5;
}
return value;
});
console.log(dataWithReviver.age); // Output: 35
// With filename for better error reporting
const user = parseJson(malformedJson, "user-data.json");
} catch (error) {
// error will be an instance of JsonError
console.error(error.message);
// Example error message:
// Unexpected token } in JSON at position 37 in user-data.json
//
// 35 | "name": "Jane Doe",
// > 36 | "age": "thirty}
// | ^
// 37 |
if (error.fileName) {
console.error(`Error in file: ${error.fileName}`);
}
if (error.codeFrame) {
console.error(error.codeFrame);
}
}
function parseJson<T>(string, filename?, options?): T;
Defined in: packages/fs/src/utils/parse-json.ts:60
T = JsonValue
string
string
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
T
function stripJsonComments(jsonString, options?): string;
Defined in: packages/fs/src/utils/strip-json-comments.ts:46
Strips comments from a JSON string. Handles both single-line (//) and multi-line (/_ ... _/) comments.
string
The JSON string possibly containing comments.
Optional configuration for stripping comments.
boolean = true
If true (default), comments are replaced with whitespace to preserve line numbers and character positions. If false, comments are removed entirely.
string
The JSON string with comments stripped.
import { stripJsonComments } from "@visulima/fs"; // Assuming this util is exported
const jsonWithComments = `{
// This is a single-line comment
"name": "John Doe",
"age": 30, /* This is a
multi-line comment */
"city": "New York"
}`;
const stripped = stripJsonComments(jsonWithComments);
console.log(stripped);
// Output (with whitespace=true):
// {
//
// "name": "John Doe",
// "age": 30, /*
//
// "city": "New York"
// }
const strippedWithoutWhitespace = stripJsonComments(jsonWithComments, { whitespace: false });
console.log(strippedWithoutWhitespace);
// Output (with whitespace=false):
// {
// "name": "John Doe",
// "age": 30,
// "city": "New York"
// }
const toPath: (urlOrPath) => string;
Defined in: node_modules/.pnpm/@visulima+path@1.3.6/node_modules/@visulima/path/dist/utils.d.mts:7
URL | string
string
Asynchronously reads a YAML file and then parses it into an object.
The expected type of the parsed YAML object. Defaults to Record<string, unknown>.
The path to the YAML file to read. Can be a file URL or a string path.
An optional reviver function (similar to JSON.parse reviver) or the options object.
Optional configuration for reading and parsing the YAML file. See ReadYamlOptions.
If reviver is an object, this argument is ignored.
import { readYaml } from "@visulima/fs";
import { join } from "node:path";
const readMyYaml = async () => {
try {
const data = await readYaml(join("path", "to", "my-config.yaml"));
console.log("Config data:", data);
// With a reviver function
const dataWithReviver = await readYaml(join("path", "to", "another.yaml"), (key, value) => {
if (key === "date") return new Date(value);
return value;
});
console.log("Date field is now a Date object:", dataWithReviver.date);
// With options (e.g., for schema validation - assuming yaml options are passed correctly)
// const dataWithOptions = await readYaml(join("path", "to", "options.yaml"), { schema: 'failsafe' });
// console.log(dataWithOptions);
} catch (error) {
console.error("Failed to read or parse YAML file:", error);
}
};
readMyYaml();
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>
Synchronously reads a YAML file and then parses it into an object.
The expected type of the parsed YAML object. Defaults to Record<string, unknown>.
The path to the YAML file to read. Can be a file URL or a string path.
An optional reviver function (similar to JSON.parse reviver) or the options object.
Optional configuration for reading and parsing the YAML file. See ReadYamlOptions.
If reviver is an object, this argument is ignored.
import { readYamlSync } from "@visulima/fs";
import { join } from "node:path";
try {
const data = readYamlSync(join("path", "to", "my-config.yaml"));
console.log("Config data:", data);
// With a reviver function
const dataWithReviver = readYamlSync(join("path", "to", "another.yaml"), (key, value) => {
if (key === "date") return new Date(value);
return value;
});
console.log("Date field is now a Date object:", dataWithReviver.date);
// With options (e.g., for schema validation - assuming yaml options are passed correctly)
// const dataWithOptions = readYamlSync(join("path", "to", "options.yaml"), { schema: 'failsafe' });
// console.log(dataWithOptions);
} catch (error) {
console.error("Failed to read or parse YAML file:", error);
}
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
Asynchronously writes an object to a YAML file.
The path to the YAML file to write. Can be a file URL or a string path.
The data to serialize and write. Can be any JavaScript value that can be stringified by yaml.stringify.
Optional. A replacer function or an array of keys to include, or the options object itself.
See yaml.stringify documentation for more details.
Optional. Configuration for writing and stringifying the YAML file. See WriteYamlOptions.
If replacer is an object and not a function/array, it's treated as options.
The space property within options can be a number for spaces or a string for tabs/etc.
import { writeYaml } from "@visulima/fs";
import { join } from "node:path";
const writeMyYaml = async () => {
try {
await writeYaml(join("/tmp", "my-data.yaml"), { name: "John Doe", age: 30, city: "New York" });
console.log("YAML file written successfully.");
await writeYaml(join("/tmp", "another-data.yaml"), { user: "jane", details: { id: 1, status: "active" } }, null, 2);
console.log("Another YAML file written with 2 spaces indentation.");
const customReplacer = (key, value) => (key === "age" ? undefined : value);
await writeYaml(join("/tmp", "filtered-data.yaml"), { name: "Smith", age: 45, occupation: "Engineer" }, customReplacer, { space: "\t" });
console.log("Filtered YAML file written with tab indentation.");
} catch (error) {
console.error("Failed to write YAML file:", error);
}
};
writeMyYaml();
function writeYaml(path, data, options?): Promise<void>;
Defined in: packages/fs/src/write/write-yaml.ts:6
string | URL
any
WriteYamlOptions
Promise<void>
function writeYaml(path, data, replacer?, options?): Promise<void>;
Defined in: packages/fs/src/write/write-yaml.ts:12
string | URL
any
string | number | WriteYamlOptions
Promise<void>
Synchronously writes an object to a YAML file.
The path to the YAML file to write. Can be a file URL or a string path.
The data to serialize and write. Can be any JavaScript value that can be stringified by yaml.stringify.
Optional. A replacer function or an array of keys to include, or the options object itself.
See yaml.stringify documentation for more details.
Optional. Configuration for writing and stringifying the YAML file. See WriteYamlOptions.
If replacer is an object and not a function/array, it's treated as options.
The space property within options can be a number for spaces or a string for tabs/etc.
import { writeYamlSync } from "@visulima/fs";
import { join } from "node:path";
const writeMyYamlSync = () => {
try {
writeYamlSync(join("/tmp", "my-data-sync.yaml"), { name: "Jane Doe", age: 28, city: "London" });
console.log("YAML file written successfully (sync).");
writeYamlSync(join("/tmp", "another-data-sync.yaml"), { user: "john_sync", details: { id: 2, status: "inactive" } }, null, 4);
console.log("Another YAML file written with 4 spaces indentation (sync).");
const customReplacer = (key, value) => (key === "city" ? "REDACTED" : value);
writeYamlSync(join("/tmp", "filtered-data-sync.yaml"), { name: "Peter", age: 50, city: "Paris" }, customReplacer, { space: 2 });
console.log("Filtered YAML file written with 2 spaces indentation (sync).");
} catch (error) {
console.error("Failed to write YAML file (sync):", error);
}
};
writeMyYamlSync();
function writeYamlSync(path, data, options?): void;
Defined in: packages/fs/src/write/write-yaml-sync.ts:6
string | URL
any
WriteYamlOptions
void
function writeYamlSync(path, data, replacer?, options?): void;
Defined in: packages/fs/src/write/write-yaml-sync.ts:12
string | URL
any
string | number | WriteYamlOptions
void
type YamlReplacer = JsonReplacer;
Defined in: packages/fs/src/types.ts:202
Type for the replacer parameter used in YAML serialization, similar to JSON.stringify's replacer.
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.
Research
Five malicious NuGet packages impersonate Chinese .NET libraries to deploy a stealer targeting browser credentials, crypto wallets, SSH keys, and local files.
Security News
pnpm 11 turns on a 1-day Minimum Release Age and blocks exotic subdeps by default, adding safeguards against fast-moving supply chain attacks.
Security News
The remediated findings include organization permission bugs, stale project access after transfers, OIDC replay edge cases, audit logging gaps, and an IDOR in API token deletion.
