directory-tree

What is directory-tree?

The directory-tree npm package is a utility for generating a nested directory structure in JSON format. It is useful for visualizing and working with file system hierarchies in a programmatic way.

What are directory-tree's main functionalities?

Generate Directory Tree

This feature allows you to generate a JSON representation of a directory structure starting from a specified path. The code sample demonstrates how to use the package to create a directory tree and print it in a readable JSON format.

const dirTree = require('directory-tree');
const tree = dirTree('/some/path');
console.log(JSON.stringify(tree, null, 2));

Filter by File Extensions

This feature allows you to filter the files included in the directory tree by their extensions. The code sample shows how to generate a directory tree that only includes Markdown and JavaScript files.

const dirTree = require('directory-tree');
const tree = dirTree('/some/path', { extensions: /\.(md|js)$/ });
console.log(JSON.stringify(tree, null, 2));

Exclude Specific Paths

This feature allows you to exclude specific paths from the directory tree. The code sample demonstrates how to exclude the 'node_modules' directory from the generated tree.

const dirTree = require('directory-tree');
const tree = dirTree('/some/path', { exclude: /node_modules/ });
console.log(JSON.stringify(tree, null, 2));

Other packages similar to directory-tree

readdirp

Readdirp is a recursive version of fs.readdir with additional features like filtering and streaming. It provides more control over the file reading process compared to directory-tree, which is more focused on generating a static JSON structure.

klaw

Klaw is a file system walker that streams file paths as it traverses directories. It offers more flexibility and streaming capabilities compared to directory-tree, which is primarily used for generating a complete directory snapshot in JSON format.

fs-extra

Fs-extra extends the native Node.js fs module with additional methods, including recursive directory operations. While it doesn't directly generate directory trees, it provides utilities that can be used to build similar functionality with more manual control.

README

directory-tree

Creates a JavaScript object representing a directory tree.

Install

$ npm install directory-tree

Usage

const dirTree = require("directory-tree");
const tree = dirTree("/some/path");

And you can also filter by an extensions regex: This is useful for including only certain types of files.

const dirTree = require("directory-tree");
const filteredTree = dirTree("/some/path", { extensions: /\.txt/ });

Example for filtering multiple extensions with Regex.

const dirTree = require("directory-tree");
const filteredTree = dirTree("/some/path", {
  extensions: /\.(md|js|html|java|py|rb)$/
});

You can also exclude paths from the tree using a regex:

const dirTree = require("directory-tree");
const filteredTree = dirTree("/some/path", { exclude: /some_path_to_exclude/ });

You can also specify which additional attributes you would like to be included about each file/directory:

const dirTree = require('directory-tree');
const filteredTree = dirTree('/some/path', {attributes:['mode', 'mtime']});

The default attributes are [name, path] for Files and [name, path, children] for Directories

A callback function can be executed with each file that matches the extensions provided:

const PATH = require('path');
const dirTree = require('directory-tree');

const tree = dirTree('./test/test_data', {extensions:/\.txt$/}, (item, PATH, stats) => {
  console.log(item);
});

The callback function takes the directory item (has path, name, size, and extension) and an instance of node path and an instance of node FS.stats.

You can also pass a callback function for directories:

const PATH = require('path');
const dirTree = require('directory-tree');

const tree = dirTree('./test/test_data', {extensions:/\.txt$/}, null, (item, PATH, stats) => {
  console.log(item);
});

Options

exclude : RegExp|RegExp[] - A RegExp or an array of RegExp to test for exclusion of directories.

extensions : RegExp - A RegExp to test for exclusion of files with the matching extension.

attributes : string[] - Array of FS.stats attributes.

normalizePath : Boolean - If true, windows style paths will be normalized to unix style pathes (/ instead of \).

depth : number - If presented, reads so many nested dirs as specified in argument. Usage of size attribute with depth option is prohibited.

Result

Given a directory structured like this:

photos
├── summer
│   └── june
│       └── windsurf.jpg
└── winter
    └── january
        ├── ski.png
        └── snowboard.jpg

directory-tree with attributes: ["size", "type", "extension"] will return this JS object:

{
  "path": "photos",
  "name": "photos",
  "size": 600,
  "type": "directory",
  "children": [
    {
      "path": "photos/summer",
      "name": "summer",
      "size": 400,
      "type": "directory",
      "children": [
        {
          "path": "photos/summer/june",
          "name": "june",
          "size": 400,
          "type": "directory",
          "children": [
            {
              "path": "photos/summer/june/windsurf.jpg",
              "name": "windsurf.jpg",
              "size": 400,
              "type": "file",
              "extension": ".jpg"
            }
          ]
        }
      ]
    },
    {
      "path": "photos/winter",
      "name": "winter",
      "size": 200,
      "type": "directory",
      "children": [
        {
          "path": "photos/winter/january",
          "name": "january",
          "size": 200,
          "type": "directory",
          "children": [
            {
              "path": "photos/winter/january/ski.png",
              "name": "ski.png",
              "size": 100,
              "type": "file",
              "extension": ".png"
            },
            {
              "path": "photos/winter/january/snowboard.jpg",
              "name": "snowboard.jpg",
              "size": 100,
              "type": "file",
              "extension": ".jpg"
            }
          ]
        }
      ]
    }
  ]
}

Adding custom fields

You can easily extend a DirectoryTree object with custom fields by adding them to the custom field. For example add an id based on the path of a DirectoryTree object for each directory and file like so:

import { createHash } from 'crypto';
import * as directoryTree from 'directory-tree';
import { DirectoryTree, DirectoryTreeOptions, DirectoryTreeCallback } from 'directory-tree';

const callback: DirectoryTreeCallback = (
            item: DirectoryTree,
            path: string
        ) => {
            item.custom.id = createHash('sha1').update(path).digest('base64');
        };

const dirTree: DirectoryTree & { id?: string } = directoryTree(
    "<your-directory-path>",
    {},
    callback,
    callback
);

// to explore the object with the new custom fields
console.log(JSON.stringify(dirTree, null, 2));

Note

Device, FIFO and socket files are ignored.

Files to which the user does not have permissions are included in the directory tree, however, directories to which the user does not have permissions, along with all of its contained files, are completely ignored.

Dev

To run tests go the package root in your CLI and run,

$ npm test

Make sure you have the dev dependencies installed (e.g. npm install .)

Node version

This project requires at least Node v4.2. Check out version 0.1.1 if you need support for older versions of Node.

CLI usage

You can use script directly from command line for generating json data.

$ npx directory-tree --help

$ npx directory-tree --path /Users/user/target --attributes type,extension --pretty -o ./xz.json --depth 1 

Available options

-p, --path string 🗂 The input folder to process. Required.
-e, --exclude string 🐒 Exclude some folders from processing by regexp string. Ex -e "test_data/some_dir$|js|.DS_Store"
-o, --output string 📝 Put result into file provided by this options. Overwrites if exists.
-d, --depth number ☞ Reads dirs in deep as specified. Usage of size attribute with depth option is prohibited.
--attributes string ℹ️ Grab file attributes. Example: --attributes size,type,extension. Usage of size attribute with depth option is prohibited
--pretty 💎 Json pretty print