A nodejs module wich helps you handle a directory tree providing you its abstraction through tested functions and a custom configuration.
A nodejs module which helps you handle a directory tree. It provides you an object of a directory tree with custom configuration and optional callback method when a file or dir is scanned. You will also be able to turn the tree into a string representation. With Typescript support and both sync and async support.
A little explaination of the name dree:
I chose it because it comes from the union of Directory Tree.
To install dree as a local module:
$ npm install dree
To install dree as a global module:
$ npm install -g dree
Simple:
const dree = require('dree');
const tree = dree.scan('./folder');
With custom configuration:
const dree = require('dree');
const options = {
stat: false,
normalize: true,
followLinks: true,
size: true,
hash: true,
depth: 5,
exclude: /dir_to_exclude/,
extensions: [ 'txt', 'jpg' ]
};
const tree = dree.scan('./folder', options);
With file and dir callbacks:
const dree = require('dree');
const options = {
stat: false
};
const fileCallback = function (element, stat) {
console.log('Found file named ' + element.name + ' created on ' + stat.ctime);
};
const dirCallback = function (element, stat) {
console.log('Found file named ' + element.name + ' created on ' + stat.ctime);
};
const tree = dree.scan('./folder', options, fileCallback, dirCallback);
With the asynchronous version:
const dree = require('dree');
const options = {
stat: false,
normalize: true,
followLinks: true,
size: true,
hash: true,
depth: 5,
exclude: /dir_to_exclude/,
extensions: [ 'txt', 'jpg' ]
};
dree.scanAsync('./folder', options)
.then(function (tree) {
console.log(tree);
});
With typescript and by changing the objects onDir and onFile:
import * as dree from 'dree';
interface CustomResult extends dree.Dree {
description: string;
}
const options: dree.Options = {
stat: false
};
const fileCallback: dree.Callback<CustomResult> = function (node, stat) {
node.description = `${node.name} (${node.size})`;
};
const dirCallback: dree.Callback<CustomResult> = function (node, stat) {
node.description = `${node.name} (${node.size})`;
};
const tree: CustomResult = dree.scan<CustomResult>('./folder', options, fileCallback, dirCallback);
Simple:
const dree = require('dree');
const string = dree.parse('./folder');
With custom configuration:
const dree = require('dree');
const options = {
followLinks: true,
depth: 5,
exclude: /dir_to_exclude/,
extensions: [ 'txt', 'jpg' ]
};
const string = dree.parse('./folder', options);
Get a string from an object:
const dree = require('dree');
const tree = dree.scan('./folder');
const options = {
followLinks: true,
depth: 5,
exclude: /dir_to_exclude/,
extensions: [ 'txt', 'jpg' ]
};
const string = dree.parseTree(tree, options);
With the asynchronous version:
const dree = require('dree');
const options = {
followLinks: true,
depth: 5,
exclude: /dir_to_exclude/,
extensions: [ 'txt', 'jpg' ]
};
dree.parseAsync('./folder', options)
.then(function (string) {
console.log(string);
});
$ dree scan <source>
This way the result will be printed on stdout
$ dree scan <source> --dest ./output/result.json
This way the result will be saved in ./output/result.json
$ dree parse <source>
This way the result will be printed on stdout
$ dree parse <source> --dest ./output/result.txt
This way the result will be saved in ./output/result.txt
$ dree parse <source> --dest ./output/result.txt --show
With --show option, the result will also be printed with on stdout even if also saved in a file
scan and parse accept the same options of their analog local functions. The options can be specified both as command arguments and json file.
$ dree --help --all-options
In case you wanted to add the code completion for cli commands, you can use the following command:
$ dree completion
It will output the code completion for your shell. You can then add it to your .bashrc or .zshrc file.
For instance, if you want to add it to your .bashrc file, you can do it like this:
$ dree completion >> ~/.bashrc
Given a directory structured like this:
sample
├── backend
│ └── firebase.json
│ └── notes.txt
│ └── server
│ └── server.ts
└── .gitignore
With this configurations:
const options = {
stat: false,
hash: false,
sizeInBytes: false,
size: true,
normalize: true,
extensions: [ 'ts', 'json' ]
};
The object returned from scan will be:
{
"name": "sample",
"path": "D:/Github/dree/test/sample",
"relativePath": ".",
"type": "directory",
"isSymbolicLink": false,
"size": "1.79 MB",
"children": [
{
"name": "backend",
"path": "D:/Github/dree/test/sample/backend",
"relativePath": "backend",
"type": "directory",
"isSymbolicLink": false,
"size": "1.79 MB",
"children": [
{
"name": "firebase.json",
"path": "D:/Github/dree/test/sample/backend/firebase.json",
"relativePath": "backend/firebase.json",
"type": "file",
"isSymbolicLink": false,
"extension": "json",
"size": "29 B"
},
{
"name": "server",
"path": "D:/Github/dree/test/sample/backend/server",
"relativePath": "backend/server",
"type": "directory",
"isSymbolicLink": false,
"size": "1.79 MB",
"children": [
{
"name": "server.ts",
"path": "D:/Github/dree/test/sample/backend/server/server.ts",
"relativePath": "backend/server/server.ts",
"type": "file",
"isSymbolicLink": false,
"extension": "ts",
"size": "1.79 MB"
}
]
}
]
}
]
}
With similar configurations, parse will return:
sample
└─> backend
├── firebase.json
├── hello.txt
└─> server
└── server.ts
Based on this module the is the github action ga-dree, that allows you to keep a markdown representation of your directory tree updated in your repository's README.md file.
The documentation generated with TypeDoc is available in this site. There is also a more specific version for development in this site.
Syntax:
dree.scan(path, options, fileCallback, dirCallback)
Description:
Given a path, returns an object representing its directory tree. The result could be customized with options and a callback for either each file and each directory is provided. Executed synchronously. See Usage to have an example.
Parameters:
string, and is the relative or absolute path the file or directory that you want to scanobject and allows you to customize the function behaviour.followLinks option is enabled). Note that it can be used also to modify the node (only by extending it) and that there are generics typings for it.followLinks option is enabled). Note that it can be used also to modify the node (only by extending it) and that there are generics typings for it.Options parameters:
false. If true every node of the result will contain stat property, provided by fs.lstat or fs.stat.false. If true, on windows, normalize each path replacing each backslash \\ with a slash /.true. If true, all symbolic links found will be included in the result. Could not work on Windows.false. If true, all symbolic links will be followed, including even their content if they link to a folder. Could not work on Windows.true. If true, every node in the result will contain sizeInBytes property as the number of bytes of the content. If a node is a folder, only its considered inner files will be computed to have this size.true. If true, every node in the result will contain size property. Same as sizeInBytes, but it is a string rounded to the second decimal digit and with an appropriate unit.true. If true, every node in the result will contain hash property, computed by taking in consideration the name and the content of the node. If the node is a folder, all his considered inner files will be used by the algorithm.md5(default) and sha1. Hash algorithm used by cryptojs to return the hash.hex(default), binary, base64url and base64. Hash encoding used by cryptojs to return the hash.true. If true, all hidden files and dirs will be included in the result. A hidden file or a directory has a name which starts with a dot and in some systems like Linux are hidden.undefined. It is a number which says the max depth the algorithm can reach scanning the given path. All files and dirs which are beyound the max depth will not be considered by the algorithm.undefined. It is a regex, string (glob patterns) or array of them and all the matched paths will not be considered by the algorithm.undefined. It is a regex, string (glob patterns) or array of them and all the non-matching paths will not be considered by the algorithm. Note: All the ancestors of a matching node will be added.undefined. It is an array of strings and all the files whose extension is not included in that array will be skipped by the algorithm. If value is undefined, all file extensions will be considered, if it is [], no files will be included.false. If value is true, the isEmpty property will be added in all the directory nodes in the result. Its value will be true if the directory contains no files and no directories, false otherwise.false. If value is true, all empty directories will be excluded from the result. Even directories which are not empty but all their children are excluded are excluded from the result because of other options will be considered empty.false. If true, also the number of descendants of each node will be added to the result.false. If true, only files will be count as descendants of a node. It does not have effect if descendants option is not true.false. If true, directories and files will be scanned ordered by path. The value can be both boolean for default alpha order, a custom sorting function or a predefined sorting method in SortMethodPredefined.false. If true, the child nodes of a node will be ordered. The value can be both boolean for default alpha order, a custom sorting function or a predefined sorting method in PostSortMethodPredefined.false. If true, the unix homedir shortcut ~ will be expanded to the user home directory.true. If true, folders whose user has not permissions will be skipped. An error will be thrown otherwise. Note: in fact every error thrown by fs calls will be ignored.SortMethodPredefined enum:
In Javascript it is an object, in Typescript an enum, whose values are used to determine how the paths should be sorted.
Result object parameters:
file or directory.fs.lstat or fs.fstat of the node.This is also the structure of the callbacks' first parameter.
Syntax:
dree.scanAsync(path, options, fileCallback, dirCallback)
Description:
Given a path, returns a promise to an object representing its directory tree. The result could be customized with options and a callback for either each file and each directory is provided. Executed asynchronously, it is the asynchronous analog of the scan function. See Usage to have an example.
Parameters:
string, and is the relative or absolute path the file or directory that you want to scanobject and allows you to customize the function behaviour.followLinks option is enabled). The callback can be an async function. Note that it can be used also to modify the node (only by extending it) and that there are generics typings for it.followLinks option is enabled). The callback can be an async function. Note that it can be used also to modify the node (only by extending it) and that there are generics typings for it.Options parameters:
They are exactly the same of the scan's function option parameters.
Result object parameters:
file or directory.fs.lstat or fs.fstat of the node.This is also the structure of the callbacks' first parameter.
Syntax:
dree.parse(path, options)
Description:
Given a path, returns a string representing its directory tree. The result could be customized with options. Executed synchronously. See Usage to have an example.
Parameters:
string, and is the relative or absolute path the file or directory that you want to parseobject and allows you to customize the function behaviour.Options parameters:
true. If true, all symbolic links found will be included in the result. Could not work on Windows.false. If true, all symbolic links will be followed, including even their content if they link to a folder. Could not work on Windows.true. If true, all hidden files and dirs will be included in the result. A hidden file or a directory has a name which starts with a dot and in some systems like Linux are hidden.undefined. It is a number which says the max depth the algorithm can reach scanning the given path. All files and dirs which are beyound the max depth will not be considered by the algorithm.undefined. It is a regex, string (glob patterns) or array of them and all the matched paths will not be considered by the algorithm.undefined. It is an array of strings and all the files whose extension is not included in that array will be skipped by the algorithm. If value is undefined, all file extensions will be considered, if it is [], no files will be included.undefined. If true, directories and files will be scanned ordered by path. The value can be both boolean for default alpha order, a custom sorting function or a predefined sorting method in SortMethodPredefined.false. If true, the unix homedir shortcut ~ will be expanded to the user home directory.true. If true, folders whose user has not permissions will be skipped. An error will be thrown otherwise. Note: in fact every error thrown by fs calls will be ignored.Result string:
The result will be a string representing the Directory Tree of the path given as first parameter. Folders will be preceded by > and symbolic links by >>.
Syntax:
dree.parseAsync(path, options)
Description:
Given a path, returns a promise to a string representing its directory tree. The result could be customized with options. Executed asynchronously. See Usage to have an example.
Parameters:
string, and is the relative or absolute path the file or directory that you want to parseobject and allows you to customize the function behaviour.Options parameters:
They are exactly the same of the parse's function options parameters.
Result string:
The result will be a promise to string representing the Directory Tree of the path given as first parameter. Folders will be preceded by > and symbolic links by >>.
Syntax:
dree.parseTree(dirTree, options)
Description:
The same as parse, but the first parameter is an object returned by scan function. Executed synchronously.
Parameters:
object, and is the object representing a Directory Tree that you want to parse into a string.object and allows you to customize the function behaviour.Options parameters:
Same parameters of parse, with one more parameter, skipErrors: is the same parameter in scan options.
Result string:
The result will be a string representing the Directory Tree of the object given as first parameter. Folders will be preceded by > and symbolic links by >>.
Syntax:
dree.parseTreeAsync(dirTree, options)
Description:
The same as parseAsync, but the first parameter is an object returned by scan function. Executed asynchronously.
Parameters:
object, and is the object representing a Directory Tree that you want to parse into a string.object and allows you to customize the function behaviour.Options parameters:
Same parameters of parse, with one more parameter, skipErrors: is the same parameter in scan options.
Result string:
The result will be a promise to string representing the Directory Tree of the object given as first parameter. Folders will be preceded by > and symbolic links by >>.
On Windows it could be possible that symbolic links are not detected, due to a problem with node fs module. If symbolicLinks is set to true, then isSymbolicLink could result false for al the tree nodes. In addition, if followLinks is set to true, it could be possible that links will not be followed instead.
The callbacks have a tree representation of the node and its stat as parameters. The tree parameter reflects the options given to scan. For example, if you set hash to false, then the tree parameter of a callback will not have the hash value. The stat parameter depends on the followLinks option. If it is true it will be the result of fs.stat, otherwise it will be the result of fs.lstat.
The callbacks for scanAsync can return a promise, hence async callbacks are supported.
Properties as hash or size are computed considering only the not filtered nodes. For instance, the result size of a folder could be different from its actual size, if some of its inner files have not been considered due to filters as exclude.
The hash of two nodes with the same content could be different, because also the name is take in consideration.
In the global usage, if an option is given both in the command args and in the options json file, the args one is considered.
Executing the asynchronous version of scan could return a different object to the one returned by the synchronous one. This is why the asynchronous and synchronous versions read the directory in a different order.
Made with dree
dree
├── .env.example
├── .release-it.json
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── build.mjs
├── build.test.mjs
├─> docs
│ └─> tree
│ └── dree.config.json
├── package.json
├── pnpm-lock.yaml
├─> scripts
│ └── generate-expected-tests-results.js
├─> source
│ ├─> bin
│ │ ├── index.ts
│ │ └── shims.d.ts
│ ├─> lib
│ │ └── index.ts
│ └── tsconfig.json
├─> test
│ ├── .gitignore
│ ├─> parse
│ ├─> parseTree
│ ├─> sample
│ ├─> scan
│ └── test.js
├── typedoc.cjs
└── typedoc.dev.cjs
Make sure that you have all the dependencies installed
To transpile the typescript code
$ npm run transpile
The transpiled code will be in the dist folder.
To bundle the library with esbuild:
$ npm run bundle
The bundled code will be in the bundled folder.
After having transpiled the code:
$ npm test
The tests with mocha will be run.
FAQs
A nodejs module wich helps you handle a directory tree providing you its abstraction through tested functions and a custom configuration.
The npm package dree receives a total of 4,969 weekly downloads. As such, dree popularity was classified as popular.
We found that dree demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
At its inaugural meeting, the JSR Working Group outlined plans for an open governance model and a roadmap to enhance JavaScript package management.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.