@visulima/fs
v2.0.8
Published
Human friendly file system utilities for Node.js
Downloads
1,176
Maintainers
Keywords
Readme
Install
npm install @visulima/fs
yarn add @visulima/fs
pnpm add @visulima/fs
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[] | (dir: string) => string | symbole | undefined
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.
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.
Supported Node.js Versions
Libraries in this ecosystem make the best effort to track Node.js’ release schedule. Here’s a post on why we think this is important.
Contributing
If you would like to help take a look at the list of issues and check our Contributing guild.
Note: please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
Credits
About
Related Projects
- strip-json-comments - Strip comments from JSON. Lets you use comments in your JSON files!
- parse-json - Parse JSON with more helpful errors.
- find-up - Find a file or directory by walking up parent directories.
- walk - Walk a directory recursively and yield all files and directories.
License
The visulima fs is open-sourced software licensed under the MIT