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 yaml as well.

npm install yaml

yarn add yaml

pnpm add yaml

After installing yaml, you can use the readYaml, readYamlSync and writeYaml, writeYamlSync functions 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

AlreadyExistsError

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

DirectoryError

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

NotEmptyError

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

NotFoundError

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

PermissionError

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

WalkError

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

FindUpName

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

FindUpNameSync

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?

MoveOptions

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

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();

Call Signature

function readJson<T>(path, options?): Promise<T>;

Defined in: packages/fs/src/read/read-json.ts:8

Type Parameters

T

T extends JsonValue

Parameters

path

string | URL

options?

ReadJsonOptions

Returns

Promise<T>

Call Signature

function readJson<T>(path, reviver, options?): Promise<T>;

Defined in: packages/fs/src/read/read-json.ts:10

Type Parameters

T

T extends JsonValue

Parameters

path

string | URL

reviver

(this, key, value) => any

options?

ReadJsonOptions

Returns

Promise<T>

readJsonSync()

Synchronously 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

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);
}

Call Signature

function readJsonSync<T>(path, options?): T;

Defined in: packages/fs/src/read/read-json-sync.ts:8

Type Parameters

T

T extends JsonValue

Parameters

path

string | URL

options?

ReadJsonOptions

Returns

T

Call Signature

function readJsonSync<T>(path, reviver, options?): T;

Defined in: packages/fs/src/read/read-json-sync.ts:10

Type Parameters

T

T extends JsonValue

Parameters

path

string | URL

reviver

(this, key, value) => any

options?

ReadJsonOptions

Returns

T

remove()

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.

Parameters

path

The path to the file or directory to remove.

string | URL

options

RetryOptions = {}

Optional configuration for the operation. See RetryOptions.

Returns

Promise<void>

A promise that resolves when the path has been removed.

Example

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();

removeSync()

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.

Parameters

path

The path to the file or directory to remove.

string | URL

options

RetryOptions = {}

Optional configuration for the operation. See RetryOptions.

Returns

void

void

Example

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);
}

rename()

function rename(source, destination, options?): Promise<void>;

Defined in: packages/fs/src/move/index.ts:85

Rename a file asynchronously.

Parameters

source

string

The file you want to rename.

destination

string

The name of the renamed file.

options?

MoveOptions

Configuration options.

Returns

Promise<void>

A Promise that resolves when the file has been renamed.

Example

import { rename } from '@visulima/fs';

await rename('test.png', 'tests.png', {cwd: 'source'});
console.log('The file has been renamed');

renameSync()

function renameSync(source, destination, options?): void;

Defined in: packages/fs/src/move/index.ts:109

Rename a file synchronously.

Parameters

source

string

The file you want to rename.

destination

string

The name of the renamed file.

options?

MoveOptions

Configuration options.

Returns

void

A Promise that resolves when the file has been renamed.

Example

import { renameSync } from '@visulima/fs';

renameSync('test.png', 'tests.png', {cwd: 'source'});
console.log('The file has been renamed');

walk()

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.

Parameters

directory

The root directory to start walking from.

string | URL

options

WalkOptions = {}

Optional configuration to control the walking process. See WalkOptions.

Returns

AsyncIterableIterator<WalkEntry>

An async iterable iterator yielding WalkEntry objects for each matching file or directory.

Example

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();

walkSync()

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.

Parameters

directory

The root directory to start walking from.

string | URL

options

WalkOptions = {}

Optional configuration to control the walking process. See WalkOptions.

Returns

IterableIterator<WalkEntry>

An iterable iterator yielding WalkEntry objects for each matching file or directory.

Example

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}`);
    }
}

writeFile()

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.

Parameters

path

The path to the file to write. Can be a file URL or a string path.

string | URL

content

The data to write. Can be a string, Buffer, ArrayBuffer, or ArrayBufferView.

string | ArrayBuffer | ArrayBufferView<ArrayBufferLike>

options?

WriteFileOptions

Optional configuration for writing the file. See WriteFileOptions.

Returns

Promise<void>

A promise that resolves when the file has been written.

Example

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();