dree.euber.dev
Open in
urlscan Pro
76.76.21.123
Public Scan
URL:
https://dree.euber.dev/
Submission: On July 21 via automatic, source certstream-suspicious — Scanned from DE
Submission: On July 21 via automatic, source certstream-suspicious — Scanned from DE
Form analysis 1 forms found in the DOM
<form>
<ul id="tsd-filter-options">
<li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked="" data-has-instance="true"><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true">
<rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect>
<path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path>
</svg><span>Inherited</span></label></li>
</ul>
</form>Text Content
Github
* Preparing search index...
* The search index is not available
dree - v5.0.4
DREE - V5.0.4
DREE
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.
THE NAME
A little explaination of the name dree:
I chose it because it comes from the union of Directory Tree.
INSTALL
To install dree as a local module:
$ npm install dree
Copy
To install dree as a global module:
$ npm install -g dree
Copy
USAGE (LOCAL MODULE)
GET AN OBJECT
Simple:
const dree = require('dree');
const tree = dree.scan('./folder');
Copy
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);
Copy
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);
Copy
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);
});
Copy
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);
Copy
GET A STRING
Simple:
const dree = require('dree');
const string = dree.parse('./folder');
Copy
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);
Copy
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);
Copy
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);
});
Copy
USAGE (GLOBAL MODULE)
GET AN OBJECT AND PRINT ON STDOUT
$ dree scan <source>
Copy
This way the result will be printed on stdout
GET AN OBJECT AND SAVE IN A FILE
$ dree scan <source> --dest ./output/result.json
Copy
This way the result will be saved in ./output/result.json
GET A STRING AND PRINT ON STDOUT
$ dree parse <source>
Copy
This way the result will be printed on stdout
GET A STRING AND SAVE IN A FILE
$ dree parse <source> --dest ./output/result.txt
Copy
This way the result will be saved in ./output/result.txt
LOG THE RESULT AND SAVE IN A FILE
$ dree parse <source> --dest ./output/result.txt --show
Copy
With --show option, the result will also be printed with on stdout even if also
saved in a file
SEE ALL OPTIONS
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
Copy
CODE COMPLETION
In case you wanted to add the code completion for cli commands, you can use the
following command:
$ dree completion
Copy
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
Copy
RESULT
Given a directory structured like this:
sample
├── backend
│ └── firebase.json
│ └── notes.txt
│ └── server
│ └── server.ts
└── .gitignore
Copy
With this configurations:
const options = {
stat: false,
hash: false,
sizeInBytes: false,
size: true,
normalize: true,
extensions: [ 'ts', 'json' ]
};
Copy
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"
}
]
}
]
}
]
}
Copy
With similar configurations, parse will return:
sample
└─> backend
├── firebase.json
├── hello.txt
└─> server
└── server.ts
Copy
ACTION
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.
API
ONLINE DOCUMENTATION
The documentation generated with TypeDoc is available in this site. There is
also a more specific version for development in this site.
SCAN
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:
* path: Is of type string, and is the relative or absolute path the file or
directory that you want to scan
* options: Optional. Is of type object and allows you to customize the function
behaviour.
* fileCallback: Optional. Called each time a file is added to the tree. It
provides you the node, which reflects the given options, and its status
returned by fs.stat (fs.lstat if 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.
* dirCallback: Optional. Called each time a directory is added to the tree. It
provides you the node, which reflects the given options, and its status
returned by fs.lstat (fs.stat if 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:
* stat: Default value: false. If true every node of the result will contain
stat property, provided by fs.lstat or fs.stat.
* normalize: Default value: false. If true, on windows, normalize each path
replacing each backslash \\ with a slash /.
* symbolicLinks: Default value: true. If true, all symbolic links found will be
included in the result. Could not work on Windows.
* followLinks: Default value: false. If true, all symbolic links will be
followed, including even their content if they link to a folder. Could not
work on Windows.
* sizeInBytes: Default value: 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.
* size: Default value: 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.
* hash: Default value: 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.
* hashAlgorithm: Values: md5(default) and sha1. Hash algorithm used by cryptojs
to return the hash.
* hashEncoding: Values: hex(default), binary, base64url and base64. Hash
encoding used by cryptojs to return the hash.
* showHidden: Default value: 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.
* depth: Default value: 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.
* exclude: Default value: undefined. It is a regex, string (glob patterns) or
array of them and all the matched paths will not be considered by the
algorithm.
* matches: Default value: 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.
* extensions: Default value: 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.
* emptyDirectory: Default value: 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.
* excludeEmptyDirectories: Default value: 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.
* descendants: Default value false. If true, also the number of descendants of
each node will be added to the result.
* descendantsIgnoreDirectories: Default value false. If true, only files will
be count as descendants of a node. It does not have effect if descendants
option is not true.
* sorted: Default value: 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.
* postSorted: Default value: 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.
* homeShortcut: Default value: false. If true, the unix homedir shortcut ~ will
be expanded to the user home directory.
* skipErrors: Default value: 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.
* ALPHABETICAL: Alphabetical order.
* ALPHABETICAL_REVERSE: Alphabetical order, reversed.
* ALPHABETICAL_INSENSITIVE: Alphabetical order, case insensitive.
* ALPHABETICAL_INSENSITIVE_REVERSE: Alphabetical order, reversed, case
insensitive.
Result object parameters:
* name: Always returned. The name of the node as a string.
* path: Always returned. The absolute path of the node.
* relativePath: Always returned. The relative path from the root of the node.
* type: Always returned. Values: file or directory.
* isSymbolicLink: Always returned. A boolean with true value if the node is a
symbolic link.
* sizeInBytes: The size in bytes of the node, returned as a number.
* size: The size of the node, returned as a string rounded to two decimals and
appropriate unit.
* hash: The hash of the node.
* extension: The extension (without dot) of the node. Returned only if the node
is a file.
* isEmpty: A boolean with true value if the node is a directory containig no
files and no directories.
* descendants: The number of descendants of the node. Returned only if the node
is a directory and descendants option is specified.
* stat: The fs.lstat or fs.fstat of the node.
* children: An array of object structured like this one, containing all the
children of the node.
This is also the structure of the callbacks' first parameter.
SCANASYNC
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:
* path: Is of type string, and is the relative or absolute path the file or
directory that you want to scan
* options: Optional. Is of type object and allows you to customize the function
behaviour.
* fileCallback: Optional. Called each time a file is added to the tree. It
provides you the node, which reflects the given options, and its status
returned by fs.stat (fs.lstat if 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.
* dirCallback: Optional. Called each time a directory is added to the tree. It
provides you the node, which reflects the given options, and its status
returned by fs.lstat (fs.stat if 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:
* name: Always returned. The name of the node as a string.
* path: Always returned. The absolute path of the node.
* relativePath: Always returned. The relative path from the root of the node.
* type: Always returned. Values: file or directory.
* isSymbolicLink: Always returned. A boolean with true value if the node is a
symbolic link.
* sizeInBytes: The size in bytes of the node, returned as a number.
* size: The size of the node, returned as a string rounded to two decimals and
appropriate unit.
* hash: The hash of the node.
* extension: The extension (without dot) of the node. Returned only if the node
is a file.
* isEmpty: A boolean with true value if the node is a directory containig no
files and no directories.
* descendants: The number of descendants of the node. Returned only if the node
is a directory and descendants option is specified.
* stat: The fs.lstat or fs.fstat of the node.
* children: An array of object structured like this one, containing all the
children of the node.
This is also the structure of the callbacks' first parameter.
PARSE
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:
* path: Is of type string, and is the relative or absolute path the file or
directory that you want to parse
* options: Optional. Is of type object and allows you to customize the function
behaviour.
Options parameters:
* symbolicLinks: Default value: true. If true, all symbolic links found will be
included in the result. Could not work on Windows.
* followLinks: Default value: false. If true, all symbolic links will be
followed, including even their content if they link to a folder. Could not
work on Windows.
* showHidden: Default value: 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.
* depth: Default value: 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.
* exclude: Default value: undefined. It is a regex, string (glob patterns) or
array of them and all the matched paths will not be considered by the
algorithm.
* extensions: Default value: 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.
* sorted: Default value: 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.
* homeShortcut: Default value: false. If true, the unix homedir shortcut ~ will
be expanded to the user home directory.
* skipErrors: Default value: 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:
* path: Is of type string, and is the relative or absolute path the file or
directory that you want to parse
* options: Optional. Is of type object 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 >>.
PARSETREE
Syntax:
dree.parseTree(dirTree, options)
Description:
The same as parse, but the first parameter is an object returned by scan
function. Executed synchronously.
Parameters:
* dirTree: Is of type object, and is the object representing a Directory Tree
that you want to parse into a string.
* options: Optional. Is of type 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 >>.
PARSETREEASYNC
Syntax:
dree.parseTreeAsync(dirTree, options)
Description:
The same as parseAsync, but the first parameter is an object returned by scan
function. Executed asynchronously.
Parameters:
* dirTree: Is of type object, and is the object representing a Directory Tree
that you want to parse into a string.
* options: Optional. Is of type 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 >>.
NOTE
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.
PROJECT STRUCTURE
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
Copy
DEVELOPMENT
Make sure that you have all the dependencies installed
TRANSPILE
To transpile the typescript code
$ npm run transpile
Copy
The transpiled code will be in the dist folder.
BUNDLE
To bundle the library with esbuild:
$ npm run bundle
Copy
The bundled code will be in the bundled folder.
TEST
After having transpiled the code:
$ npm test
Copy
The tests with mocha will be run.
SETTINGS
MEMBER VISIBILITY
* Inherited
THEME
OSLightDark
ON THIS PAGE
dree
* The name
* Install
* Usage (local module)
* * Get an object
* Get a string
* Usage (global module)
* * Get an object and print on stdout
* Get an object and save in a file
* Get a string and print on stdout
* Get a string and save in a file
* Log the result and save in a file
* See all options
* Code completion
* Result
* Action
* API
* * Online documentation
* scan
* scanAsync
* parse
* parseTree
* parseTreeAsync
* Note
* Project structure
* Development
* * Transpile
* Bundle
* Test
DEV docs
dree - v5.0.4
* PostSortMethodPredefined
* SortMethodPredefined
* Type
* Dree
* ParseOptions
* ScanOptions
* Callback
* CallbackAsync
* PostSortDiscriminator
* SortDiscriminator
* parse
* parseAsync
* parseTree
* parseTreeAsync
* scan
* scanAsync
Generated using TypeDoc