fs-tree-utils
Work with filesystem tree with ease
Features
- Traverse a folder structure.
- Read a folder structure into a JSON object.
- Write a JSON object into a folder structure.
Requirements
- Node.js ≥ 8.9.0
APIs
NOTE:
fsTreeUtils
is an alias of modulefs-tree-utils
.fsExtra
is an alias of modulefs-extra
.fs
is an alias of modulefs
.- All example code snippets are in async context.
fsTreeUtils.traverse
declare
Parameters:
dirname
: Directory that contains all items need to be iterated over.options.deep
(optional): Decides whether or not to dive deeper, default to "always".options.level
(optional): Initial level of depth, default to0
.options.stat
(optional): Return filesystem item's stats (fs.Stats
), default tofs.stat
.
Returns:
- A promise of
DeepFuncParam[]
Other types:
DeepFuncParam::container
: Path to directory that contains each item.DeepFuncParam::item
: Name (basename) of each item (including extension).DeepFuncParam::path
: Full path to each item.DeepFuncParam::stats
: Returned value ofoptions.stat
upon each item.DeepFuncParam::level
: Level of depth, minimum depth is customizable viaoptions.level
.
Examples
Simplest form
const res = await consoleconsoleconsole
Get all symbolic links
This example requires fsExtra.lstat
/fs.lstatSync
in order to detect symbolic links. This is also safer methods when there're recursive links.
const res = await const links = resconsole
deep
With specified Don't traverse .git
's/node_modules
's children.
const deep = item !== '.git' && item !== 'node_modules'const res = await console
fsTreeUtils.read.nested
declare // See https://git.io/vhar7 for more types
Parameters:
name
: Path to the top directory of a tree.options.stat
(optional): Stat function to use (returns eitherfs.Stats
orPromise<fs.Stats>
), default tofsExtra.stat
.options.filter
(optional): Function that filter subtrees.options.onerror
(optional): Function that transforms an error into a value, these errors will be thrown instead if the function is not provided.options.onunknown
(optional): Function that creates a value when encounter unknown filesystem entity, errors would be thrown instead if the function is not provided.
Examples
Simplest form
const tree = await readconsole
options.stat
With specified Use fsExtra.lstat
as options.stat
.
const tree = await readconsole
fsTreeUtils.read.flat
declare // See https://git.io/vhar7 for more types
This function uses traverse
under the hook.
Parameters:
name
: Path to the top directory.options
(optional): Options to pass totraverse
.
Returns:
FlatReadResultValue::fileContents
: A dict (Object
) with keys being files' paths (string
) and values being files' content (Buffer | string
).FlatReadResultValue::directories
: A list (Array
) of directories' paths (string
).FlatReadResultValue::files
: A list (Array
) of files' paths (string
).FlatReadResultValue::all
: A list (Array
) of every item's path (string
).
fsTreeUtils.create
declare // `Tree.Write` is basically tree-like dictionary, see https://git.io/vhar7 for its definition
Parameters:
tree
: Intended tree structure representation.container
: Intended top-level directory.
Returns:
- A promise that resolves when tree creation is finishes successfully and rejects when tree creation fails.
Effects:
- Populate directory of
container
with filesystem entities that as represented intree
.
Examples
Tree Creation
const tree = // top-level `tree` object corresponds to top-level directory of `container` (directory) files: // corresponding path: {container}/files/ (directory) 'string.txt': 'A string' // corresponding path: {container}/files/string.txt (file) 'buffer.txt': Buffer // corresponding path: {container}/files/buffer.txt (file) 'class.txt': 'File class' // corresponding path: {container}/files/class.txt (file) // corresponding path: {container}/files/function.async.txt // corresponding path: {container}/files/function.sync.txt symlinks: // corresponding path: {container}/symlinks 'to-files-container': '../files' // points to {container}/files/ 'to-nowhere': '/this/is/nowhere' // points to /this/is/nowhere 'a-windows-junction': 'C:\\Windows' type: 'junction' // this is a junction (in Windows) clones: // corresponding path: {container}/clones 'my-copy': '/source/for/copying' // uses `fsExtra.copy` under the hook await
fsTreeUtils.FileSystemRepresentation
// See https://git.io/vhar7 for more types
This is an abstract class upon which fsTreeUtils.FileSystemRepresentation.*
was built.
fsTreeUtils.FileSystemRepresentation::write
This is an abstract method.
This method is used by fsTreeUtils.create
.
Parameters:
target
: Name of represented entity.param.create
: It isfsTreeUtils.create
.
Returns:
- Synchronous version returns nothing (i.e.
void
a.k.a.undefined
). - Asynchronous version returns a promise that resolves
undefined
.
fsTreeUtils.FileSystemRepresentation.File
declare
fsTreeUtils.FileSystemRepresentation.File::constructor
Parameters:
content
: Intended file's content (string | Buffer
).
fsTreeUtils.FileSystemRepresentation.File::write
Parameters:
filename
: Intended file's name (string
).
Returns:
- A promise that resolves when content is written into file successfully.
Effects:
- Write
content
into file with namefilename
.
Examples
const File = FileSystemRepresentation await Promiseall
fsTreeUtils.FileSystemRepresentation.Directory
declare // See https://git.io/vhar7 for more types
fsTreeUtils.FileSystemRepresentation.Directory::constructor
Parameters:
content
(optional): A dictionary of tree representation (Tree.Writable.Object
).
fsTreeUtils.FileSystemRepresentation.Directory::write
Parameters:
dirname
: Intended directory's name.param.create
: It isfsTreeUtils.create
.
Returns:
- A promise that resolves when tree creation inside directory is completed.
Effects:
- Create a filesystem tree inside directory.
fsTreeUtils.FileSystemRepresentation.Symlink
declare // See https://git.io/vhar7 for more types
fsTreeUtils.FileSystemRepresentation.Symlink::constructor
Parameters:
linkTarget
: Intended symlink's target (string
).options.type
(optional): Either"dir"
,"file"
or"junction"
. Windows only.
fsTreeUtils.FileSystemRepresentation.Symlink::write
Parameters:
linkName
: Path to intended symlink (string
).
Returns:
- A promise that resolves when symlink creation succeeds.
Effects:
- Create a symlink at
linkName
that points tolinkTarget
.
Examples
const Symlink = FileSystemRepresentation await
fsTreeUtils.FileSystemRepresentation.Clone
declare
fsTreeUtils.FileSystemRepresentation.Clone::constructor
Parameters:
source
: Path to existing source (string
).options
(optional): Options to pass tofsExtra.copy
(fsExtra.CopyOptions
).
fsTreeUtils.FileSystemRepresentation.Clone::write
This method uses fsExtra.copy
under the hook.
Parameters:
destination
: Path to destination (string
).
Returns:
- A promise that resolves when cloning is completed.
Effects:
- Create a copy of
source
atdestination
.
Other types and classes
See module fs-tree-utils/lib/.types
.