npm

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

To install dree as a global module:

$ npm install -g dree

Usage (local module)

Get an object

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);

Get a string

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' ],
  symbols: dree.ASCII_SYMBOLS
};

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);
  });

Usage (global module)

Get an object and print on stdout

$ dree scan <source>

This way the result will be printed on stdout

Get an object and save in a file

$ dree scan <source> --dest ./output/result.json

This way the result will be saved in ./output/result.json

Get a string and print on stdout

$ dree parse <source>

This way the result will be printed on stdout

Get a string and save in a file

$ dree parse <source> --dest ./output/result.txt

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

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

Code completion

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

Result

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

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 en

Dree

Install / Use

README