@visulima/fs v3.1.2

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

error

Classes

AlreadyExistsError

Defined in: packages/fs/src/error/already-exists-error.ts:4

Error thrown when file already exists.

Extends

• Error

Constructors

new AlreadyExistsError()

new AlreadyExistsError(message): AlreadyExistsError

Defined in: packages/fs/src/error/already-exists-error.ts:9

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:14

Returns

string

Set Signature

set code(_name): void

Defined in: packages/fs/src/error/already-exists-error.ts:19

Parameters

_name

string

Returns

void

name

Get Signature

get name(): string

Defined in: packages/fs/src/error/already-exists-error.ts:24

Returns

string

Set Signature

set name(_name): void

Defined in: packages/fs/src/error/already-exists-error.ts:29

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.2/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.2/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.2/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:4

Error thrown when an operation is not allowed on a directory.

Extends

• Error

Constructors

new DirectoryError()

new DirectoryError(message): DirectoryError

Defined in: packages/fs/src/error/directory-error.ts:9

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:14

Returns

string

Set Signature

set code(_name): void

Defined in: packages/fs/src/error/directory-error.ts:19

Parameters

_name

string

Returns

void

name

Get Signature

get name(): string

Defined in: packages/fs/src/error/directory-error.ts:24

Returns

string

Set Signature

set name(_name): void

Defined in: packages/fs/src/error/directory-error.ts:29

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.2/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.2/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.2/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:4

Error thrown when a directory is not empty.

Extends

• Error

Constructors

new NotEmptyError()

new NotEmptyError(message): NotEmptyError

Defined in: packages/fs/src/error/not-empty-error.ts:9

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:14

Returns

string

Set Signature

set code(_name): void

Defined in: packages/fs/src/error/not-empty-error.ts:19

Parameters

_name

string

Returns

void

name

Get Signature

get name(): string

Defined in: packages/fs/src/error/not-empty-error.ts:24

Returns

string

Set Signature

set name(_name): void

Defined in: packages/fs/src/error/not-empty-error.ts:29

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.2/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.2/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.2/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:4

Error thrown when a file or directory is not found.

Extends

• Error

Constructors

new NotFoundError()

new NotFoundError(message): NotFoundError

Defined in: packages/fs/src/error/not-found-error.ts:9

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:14

Returns

string

Set Signature

set code(_name): void

Defined in: packages/fs/src/error/not-found-error.ts:19

Parameters

_name

string

Returns

void

name

Get Signature

get name(): string

Defined in: packages/fs/src/error/not-found-error.ts:24

Returns

string

Set Signature

set name(_name): void

Defined in: packages/fs/src/error/not-found-error.ts:29

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.2/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.2/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.2/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:4

Error thrown when an operation is not permitted.

Extends

• Error

Constructors

new PermissionError()

new PermissionError(message): PermissionError

Defined in: packages/fs/src/error/permission-error.ts:9

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:14

Returns

string

Set Signature

set code(_name): void

Defined in: packages/fs/src/error/permission-error.ts:19

Parameters

_name

string

Returns

void

name

Get Signature

get name(): string

Defined in: packages/fs/src/error/permission-error.ts:24

Returns

string

Set Signature

set name(_name): void

Defined in: packages/fs/src/error/permission-error.ts:29

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.2/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.2/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.2/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:7

Error thrown in walk or walkSync during iteration.

Extends

• Error

Constructors

new WalkError()

new WalkError(cause, root): WalkError

Defined in: packages/fs/src/error/walk-error.ts:12

Constructs a new instance.

Parameters

cause

unknown

root

string

Returns

WalkError

Overrides

Error.constructor

Accessors

name

Get Signature

get name(): string

Defined in: packages/fs/src/error/walk-error.ts:21

Returns

string

Set Signature

set name(_name): void

Defined in: packages/fs/src/error/walk-error.ts:26

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.2/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.2/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:9

File path of the root that's being walked.

stack?

optional stack: string;

Defined in: node_modules/.pnpm/typescript@5.8.2/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:4

Parameters

directory

string

options

WalkOptions = {}

Returns

Promise\<string[]>

collectSync()

function collectSync(directory, options): string[]

Defined in: packages/fs/src/find/collect-sync.ts:4

Parameters

directory

string

options

WalkOptions = {}

Returns

string[]

detect()

function detect(content): "\n" | "\r\n"

Defined in: packages/fs/src/eol.ts:20

Detect the EOL character for string input. Returns null if no newline.

Parameters

content

string

Returns

"\n" | "\r\n"

emptyDir()

function emptyDir(dir, options?): Promise<void>

Defined in: packages/fs/src/remove/empty-dir.ts:19

Ensures that a directory is empty. Deletes directory contents if the directory is not empty. If the directory does not exist, it is created. The directory itself is not deleted.

Parameters

dir

string | URL

options?

EmptyDirOptions

Returns

Promise\<void>

emptyDirSync()

function emptyDirSync(dir, options?): void

Defined in: packages/fs/src/remove/empty-dir-sync.ts:18

Ensures that a directory is empty. Deletes directory contents if the directory is not empty. If the directory does not exist, it is created. The directory itself is not deleted.

Parameters

dir

string | URL

options?

EmptyDirOptions

Returns

void

ensureDir()

function ensureDir(directory): Promise<void>

Defined in: packages/fs/src/ensure/ensure-dir.ts:12

Ensures that the directory exists. If the directory structure does not exist, it is created. Like mkdir -p.

Parameters

directory

string | URL

Returns

Promise\<void>

ensureDirSync()

function ensureDirSync(directory): void

Defined in: packages/fs/src/ensure/ensure-dir-sync.ts:12

Ensures that the directory exists. If the directory structure does not exist, it is created. Like mkdir -p.

Parameters

directory

string | URL

Returns

void

ensureFile()

function ensureFile(filePath): Promise<void>

Defined in: packages/fs/src/ensure/ensure-file.ts:16

Ensures that the file exists. If the file that is requested to be created is in directories that do not exist, these directories are created. If the file already exists, it is NOTMODIFIED.

Parameters

filePath

string | URL

Returns

Promise\<void>

ensureFileSync()

function ensureFileSync(filePath): void

Defined in: packages/fs/src/ensure/ensure-file-sync.ts:16

Ensures that the file exists. If the file that is requested to be created is in directories that do not exist, these directories are created. If the file already exists, it is NOTMODIFIED.

Parameters

filePath

string | URL

Returns

void

ensureLink()

function ensureLink(source, destination): Promise<void>

Defined in: packages/fs/src/ensure/ensure-link.ts:15

Ensures that the hard link exists. If the directory structure does not exist, it is created.

Parameters

source

string | URL

destination

string | URL

Returns

Promise\<void>

ensureLinkSync()

function ensureLinkSync(source, destination): void

Defined in: packages/fs/src/ensure/ensure-link-sync.ts:15

Ensures that the hard link exists. If the directory structure does not exist, it is created.

Parameters

source

string | URL

destination

string | URL

Returns

void

ensureSymlink()

function ensureSymlink(
   target, 
   linkName, 
type?): Promise<void>

Defined in: packages/fs/src/ensure/ensure-symlink.ts:28

Ensures that the link exists, and points to a valid file. If the directory structure does not exist, it is created. If the link already exists, it is not modified but error is thrown if it is not point to the given target.

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.

ensureSymlinkSync()

function ensureSymlinkSync(
   target, 
   linkName, 
   type?): void

Defined in: packages/fs/src/ensure/ensure-symlink-sync.ts:28

Ensures that the link exists, and points to a valid file. If the directory structure does not exist, it is created. If the link already exists, it is not modified but error is thrown if it is not point to the given target.

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.

findUp()

function findUp(name, options): Promise<string>

Defined in: packages/fs/src/find/find-up.ts:11

Parameters

name

FindUpName

options

FindUpOptions = {}

Returns

Promise\<string>

findUpSync()

function findUpSync(name, options): string

Defined in: packages/fs/src/find/find-up-sync.ts:11

Parameters

name

FindUpNameSync

options

FindUpOptions = {}

Returns

string

format()

function format(content, eol): string

Defined in: packages/fs/src/eol.ts:36

Format the file to the targeted EOL.

Parameters

content

string

eol

"\n" | "\r\n"

Returns

string

isAccessible()

function isAccessible(path, mode?): Promise<boolean>

Defined in: packages/fs/src/is-accessible.ts:9

Returns a Promise that resolves to a boolean indicating if the path is accessible or not.

Parameters

path

string | URL

mode?

number

Returns

Promise\<boolean>

isAccessibleSync()

function isAccessibleSync(path, mode?): boolean

Defined in: packages/fs/src/is-accessible-sync.ts:9

Returns a boolean indicating if the path is accessible or not.

Parameters

path

string | URL

mode?

number

Returns

boolean

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 { moveFile } from '@visulima/fs';

await moveFile('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 { moveFileSync } from '@visulima/fs';

moveFileSync('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:20

Type Parameters

• O extends ReadFileOptions\<"brotli" | "gzip" | "none"> = undefined

Parameters

path

string | URL

options?

O

Returns

Promise\<ContentType\<O>>

readFileSync()

function readFileSync<O>(path, options?): ContentType<O>

Defined in: packages/fs/src/read/read-file-sync.ts:18

Type Parameters

• O extends ReadFileOptions\<"brotli" | "gzip" | "none"> = undefined

Parameters

path

string | URL

options?

O

Returns

ContentType\<O>

readJson()

Call Signature

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

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

Type Parameters

• 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 extends JsonValue

Parameters

path

string | URL

reviver

(this, key, value) => any

options?

ReadJsonOptions

Returns

Promise\<T>

readJsonSync()

Call Signature

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

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

Type Parameters

• 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 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:5

Parameters

path

string | URL

options

maxRetries?

number

If an EBUSY, EMFILE, ENFILE, ENOTEMPTY, or EPERM error is encountered, Node.js will retry the operation with a linear backoff wait of retryDelay ms longer on each try. This option represents the number of retries. This option is ignored if the recursive option is not true.

Default

0

retryDelay?

number

The amount of time in milliseconds to wait between retries. This option is ignored if the recursive option is not true.

Default

100

Returns

Promise\<void>

removeSync()

function removeSync(path, options): void

Defined in: packages/fs/src/remove/remove-sync.ts:5

Parameters

path

string | URL

options

maxRetries?

number

If an EBUSY, EMFILE, ENFILE, ENOTEMPTY, or EPERM error is encountered, Node.js will retry the operation with a linear backoff wait of retryDelay ms longer on each try. This option represents the number of retries. This option is ignored if the recursive option is not true.

Default

0

retryDelay?

number

The amount of time in milliseconds to wait between retries. This option is ignored if the recursive option is not true.

Default

100

Returns

void

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 { renameFile } from '@visulima/fs';

await renameFile('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 {renameFileSync} from '@visulima/fs';

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

walk()

function walk(directory, __namedParameters): AsyncIterableIterator<WalkEntry>

Defined in: packages/fs/src/find/walk.ts:49

Walks the file tree rooted at root, yielding each file or directory in the tree filtered according to the given options. Options:

• maxDepth?: number = Infinity;
• includeFiles?: boolean = true;
• includeDirs?: boolean = true;
• includeSymlinks?: boolean = true;
• followSymlinks?: boolean = false;
• extensions?: string[];
• match?: string | ReadonlyArray;
• skip?: string | ReadonlyArray;

Parameters

directory

string | URL

__namedParameters

WalkOptions = {}

Returns

AsyncIterableIterator\<WalkEntry>

walkSync()

function walkSync(directory, __namedParameters): IterableIterator<WalkEntry>

Defined in: packages/fs/src/find/walk-sync.ts:40

Same as walk but uses synchronous ops

Parameters

directory

string | URL

__namedParameters

WalkOptions = {}

Returns

IterableIterator\<WalkEntry>

writeFile()

function writeFile(
   path, 
   content, 
options?): Promise<void>

Defined in: packages/fs/src/write/write-file.ts:15

Parameters

path

string | URL

content

string | ArrayBuffer | ArrayBufferView\<ArrayBufferLike>

options?

WriteFileOptions

Returns

Promise\<void>

writeFileSync()

function writeFileSync(
   path, 
   content, 
   options?): void

Defined in: packages/fs/src/write/write-file-sync.ts:15

Parameters

path

string | URL

content

string | ArrayBuffer | ArrayBufferView\<ArrayBufferLike>

options?

WriteFileOptions

Returns

void

writeJson()

function writeJson(
   path, 
   data, 
options): Promise<void>

Defined in: packages/fs/src/write/write-json.ts:11

Parameters

path

string | URL

data

unknown

options

WriteJsonOptions = {}

Returns

Promise\<void>

writeJsonSync()

function writeJsonSync(
   path, 
   data, 
   options): void

Defined in: packages/fs/src/write/write-json-sync.ts:11

Parameters

path

string | URL

data

unknown

options

WriteJsonOptions = {}

Returns

void

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.

F_OK

const F_OK: 0 = 0;

Defined in: packages/fs/src/constants.ts:2

Is the path visible to the calling process?

FIND_UP_STOP

const FIND_UP_STOP: typeof FIND_UP_STOP;

Defined in: packages/fs/src/constants.ts:13

LF

const LF: "\n";

Defined in: packages/fs/src/eol.ts:6

End-of-line character for POSIX platforms such as macOS and Linux.

R_OK

const R_OK: 4 = 4;

Defined in: packages/fs/src/constants.ts:5

Is the path readable to the calling process?

W_OK

const W_OK: 2 = 2;

Defined in: packages/fs/src/constants.ts:8

Is the path writable to the calling process?

X_OK

const X_OK: 1 = 1;

Defined in: packages/fs/src/constants.ts:11

Is the path executable to the calling process?

Interfaces

WalkEntry

Defined in: packages/fs/src/types.ts:56

Extends

• Pick\<Dirent, "isDirectory" | "isFile" | "isSymbolicLink" | "name">

Methods

isDirectory()

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.

Returns

boolean

Since

v10.10.0

Inherited from

Pick.isDirectory

isFile()

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.

Returns

boolean

Since

v10.10.0

Inherited from

Pick.isFile

isSymbolicLink()

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.

Returns

boolean

Since

v10.10.0

Inherited from

Pick.isSymbolicLink

Properties

name

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.

Since

v10.10.0

Inherited from

Pick.name

path

path: string;

Defined in: packages/fs/src/types.ts:57

WalkOptions

Defined in: packages/fs/src/types.ts:9

Properties

extensions?

optional extensions: string[];

Defined in: packages/fs/src/types.ts:15

List of file extensions used to filter entries. If specified, entries without the file extension specified by this option are excluded.

Default

{undefined}

followSymlinks?

optional followSymlinks: boolean;

Defined in: packages/fs/src/types.ts:20

Indicates whether symlinks should be resolved or not.

Default

{false}

includeDirs?

optional includeDirs: boolean;

Defined in: packages/fs/src/types.ts:25

Indicates whether directory entries should be included or not.

Default

{true}

includeFiles?

optional includeFiles: boolean;

Defined in: packages/fs/src/types.ts:30

Indicates whether file entries should be included or not.

Default

{true}

includeSymlinks?

optional includeSymlinks: boolean;

Defined in: packages/fs/src/types.ts:36

Indicates whether symlink entries should be included or not. This option is meaningful only if followSymlinks is set to false.

Default

{true}

match?

optional match: (string | RegExp)[];

Defined in: packages/fs/src/types.ts:42

List of regular expression or glob patterns used to filter entries. If specified, entries that do not match the patterns specified by this option are excluded.

Default

{undefined}

maxDepth?

optional maxDepth: number;

Defined in: packages/fs/src/types.ts:47

The maximum depth of the file tree to be walked recursively.

Default

{Infinity}

skip?

optional skip: (string | RegExp)[];

Defined in: packages/fs/src/types.ts:53

List of regular expression or glob patterns used to filter entries. If specified, entries matching the patterns specified by this option are excluded.

Default

{undefined}

Type Aliases

CodeFrameLocation

type CodeFrameLocation = object;

Defined in: packages/fs/src/types.ts:91

Type declaration

column?

optional column: number;

line

line: number;

EmptyDirOptions

type EmptyDirOptions = object;

Defined in: packages/fs/src/types.ts:188

Type declaration

maxRetries?

optional maxRetries: number;

If an EBUSY, EMFILE, ENFILE, ENOTEMPTY, or EPERM error is encountered, Node.js will retry the operation with a linear backoff wait of retryDelay ms longer on each try. This option represents the number of retries. This option is ignored if the recursive option is not true.

Default

0

retryDelay?

optional retryDelay: number;

The amount of time in milliseconds to wait between retries. This option is ignored if the recursive option is not true.

Default

100

FindUpName

type FindUpName = 
  | string[]
  | string
  | (directory) => FindUpNameFnResult;

Defined in: packages/fs/src/types.ts:180

FindUpNameFnResult

type FindUpNameFnResult = 
  | PathLike
  | Promise<PathLike | typeof FIND_UP_STOP>
  | typeof FIND_UP_STOP
  | undefined;

Defined in: packages/fs/src/types.ts:178

FindUpNameSync

type FindUpNameSync = 
  | string[]
  | string
  | (directory) => FindUpNameSyncFnResult;

Defined in: packages/fs/src/types.ts:185

FindUpNameSyncFnResult

type FindUpNameSyncFnResult = PathLike | typeof FIND_UP_STOP | undefined;

Defined in: packages/fs/src/types.ts:183

FindUpOptions

type FindUpOptions = object;

Defined in: packages/fs/src/types.ts:170

Type declaration

allowSymlinks?

optional allowSymlinks: boolean;

cwd?

optional cwd: URL | string;

stopAt?

optional stopAt: URL | string;

type?

optional type: "directory" | "file";

JsonReplacer

type JsonReplacer = (number | string)[] | (this, key, value) => unknown | null;

Defined in: packages/fs/src/types.ts:143

JsonReviver

type JsonReviver = Parameters<typeof JSON["parse"]>["1"];

Defined in: packages/fs/src/types.ts:89

MoveOptions

type MoveOptions = object;

Defined in: packages/fs/src/move/types.ts:3

Type declaration

cwd?

optional cwd: URL | string;

The working directory to find source files. The source and destination path are relative to this.

Default

process.cwd()

directoryMode?

readonly optional directoryMode: FilePermissions;

Permissions for created directories.

It has no effect on Windows.

Default

0o777

overwrite?

readonly optional overwrite: boolean;

Overwrite existing destination file.

Default

true

ReadFileEncoding

type ReadFileEncoding = 
  | "ascii"
  | "base64"
  | "base64url"
  | "hex"
  | "latin1"
  | "ucs-2"
  | "ucs2"
  | "utf-8"
  | "utf-16le"
  | "utf8"
  | "utf16le";

Defined in: packages/fs/src/types.ts:61

ReadFileOptions\<C>

type ReadFileOptions<C> = object;

Defined in: packages/fs/src/types.ts:63

Type Parameters

• C

Type declaration

buffer?

optional buffer: boolean;

Return content as a Buffer. Default: false

compression?

optional compression: C;

Compression method to decompress the file against. Default: none

encoding?

optional encoding: ReadFileEncoding;

The encoding to use. Default: utf8

See

https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings

flag?

optional flag: number | string;

The flag used to open the file. Default: r

ReadJsonOptions

type ReadJsonOptions = CodeFrameOptions & object;

Defined in: packages/fs/src/types.ts:104

Type declaration

beforeParse()?

optional beforeParse: (source) => string;

Parameters

source

string

Returns

string

WriteFileOptions

type WriteFileOptions = object;

Defined in: packages/fs/src/types.ts:108

Type declaration

chown?

optional chown: object;

The group and user ID used to set the file ownership. Default: undefined

chown.gid

gid: number;

chown.uid

uid: number;

encoding?

optional encoding: BufferEncoding | null;

The encoding to use. Default: utf8

flag?

optional flag: string;

The flag used to write the file. Default: w

mode?

optional mode: number;

The file mode (permission and sticky bits). Default: 0o666

overwrite?

optional overwrite: boolean;

Indicates whether the file should be overwritten if it already exists. Default: false

recursive?

optional recursive: boolean;

Recursively create parent directories if needed. Default: true

WriteJsonOptions

type WriteJsonOptions = WriteFileOptions & object;

Defined in: packages/fs/src/types.ts:146

Type declaration

detectIndent?

optional detectIndent: boolean;

Detect indentation automatically if the file exists. Default: false

indent?

optional indent: number | string;

The space used for pretty-printing.

Pass in undefined for no formatting.

replacer?

optional replacer: JsonReplacer;

Passed into JSON.stringify.

stringify()?

optional stringify: (data, replacer, space) => string;

Override the default JSON.stringify method.

Parameters

data

unknown

replacer

JsonReplacer

space

number | string | undefined

Returns

string

size

Functions

brotliSize()

function brotliSize(input, options?): Promise<number>

Defined in: packages/fs/src/size.ts:109

Asynchronously calculates the Brotli compressed size of the input. Uses memory-efficient streaming for large inputs.

Parameters

input

string | URL | Buffer\<ArrayBufferLike> | Readable

options?

BrotliOptions

Returns

Promise\<number>

brotliSizeSync()

function brotliSizeSync(input, options?): numbe