fs-hierarchy

Create a hierarchy map of a filesystem using node's built-in fs.

You can use the CLI or include it directly in your project. It returns a structure that can be used in different contexts like for d3-hierarchy.

Additionally it is possible:

• to include extra informations like the file extension, the absolute path, the type and stats
• filter paths and names
• follow symbolic links
• in CLI: output in json, yaml or in a tree to stdout or file

• fs-hierarchy
• CLI
• Programmatic use

CLI

Using the CLI, fs-hierarchy supports different output formats and options.

Commands

• fs-hierarchy [DIR] [OUTPUT]

fs-hierarchy [DIR] [OUTPUT]

Create a hierarchy map of a filesystem using node's built-in fs.

USAGE
  $ fs-hierarchy  [DIR] [OUTPUT] [-e] [--flat] [-f tree|yaml|json] [-h] [-i ext|path|stats|type] [-m
    <value>] [-M all|none|some] [--minify] [-r <value>] [-s] [-v]

ARGUMENTS
  DIR     [default: .] path to create a hierarchy from
  OUTPUT  output filename

FLAGS
  -M, --match-rule=<option>  [default: some] rule for matching paths
                             <options: all|none|some>
  -e, --empty                include child nodes that have no children
  -f, --format=<option>      [default: json] the used output format
                             <options: tree|yaml|json>
  -h, --help                 show this help
  -i, --include=<option>...  the included informations in return object
                             <options: ext|path|stats|type>
  -m, --match=<value>...     filter matching paths
  -r, --root=<value>         the used name for the root-folder
  -s, --symlinks             follow symbolic links
  -v, --version              show the version
      --flat                 flatten the output
      --minify               minify the output

DESCRIPTION
  Create a hierarchy map of a filesystem using node's built-in *fs*.

FLAG DESCRIPTIONS
  -M, --match-rule=all|none|some  rule for matching paths

    when set to "all" all filters must resolve successfully,
    when set to "some" at least one filter must resolve successfully,
    when set to "none" no filter must resolve successfully

  -m, --match=<value>...  filter matching paths

    use glob pattern for matching
    negate by leading '!'
    e.g. -m '**/*.ts' '!**/node_modules/**'

  --flat  flatten the output

    if true the full path will be included by default. using tree format the full path will be used instead of the
    filenames

  --minify  minify the output

    only for json format

JSON

$ fs-hierarchy ./src -m 'index.ts'

{
  "name": "./src",
  "children": [
    {
      "name": "commands",
      "children": [
        {
          "name": "index.ts"
        }
      ]
    },
    {
      "name": "index.ts"
    },
    {
      "name": "lib",
      "children": [
        {
          "name": "index.ts"
        }
      ]
    }
  ]
}

Tree

$ fs-hierarchy ./src -f tree -m '*.ts'

./src
 ├─ commands
 │  ╰─ index.ts
 ├─ index.ts
 ╰─ lib
    ├─ format
    │  ├─ json.ts
    │  ├─ tree.ts
    │  ╰─ yaml.ts
    ├─ hierarchy.ts
    ├─ index.ts
    ├─ types.ts
    ├─ utils
    │  ├─ factories.ts
    │  ├─ flatten.ts
    │  ├─ leaf.ts
    │  ├─ read-dir.ts
    │  ├─ type.ts
    │  ╰─ typeguards.ts
    ╰─ write
       ├─ file.ts
       ╰─ stdout.ts

More Examples

• Formatting
• Filter

Programmatic use

$ npm install fs-hierarchy

const { hierarchy } = require('fs-hirarchy');

const root = path.resolve(__dirname, 'files');
const options = {
  filter: { match: '*.json' },
  include: { path: true },
  rootName: 'HomeSweetHome'
};

const matches = hierarchy(root, options);

hierarchy

function

Creates a hierarchy tree structure based on the given root path and options.

defined in fs-hierarchy/src/lib/hierarchy.ts

parameters

Name	Type	Description
root*	string	The root path of the hierarchy.
options*	Options	The options for configuring the hierarchy.
returns	Leaf | Node	The hierarchy tree structure.

Type

union

Types of a Leaf or Node entry

defined in fs-hierarchy/src/lib/types.ts

values

"block-device" | "char-device" | "dir" | "file" | "pipe" | "socket" | "symlink"

Leaf

type

a Leaf of the hierarchy

defined in fs-hierarchy/src/lib/types.ts

properties

Name	Type	Description
extension	string	optionally included extension (only for Leaf s)
name*	string	the name of the entry (without the base path)
path	string	optionally included absolute path
stats	Stats	A fs.Stats object provides information about a file. Objects returned from [{@link lstat} and {@link fstat](stat},) and their synchronous counterparts are of this type. If bigint in the options passed to those methods is true, the numeric values will be bigint instead of number , and the object will contain additional nanosecond-precision properties suffixed with Ns . console Stats { dev: 2114, ino: 48064969, mode: 33188, nlink: 1, uid: 85, gid: 100, rdev: 0, size: 527, blksize: 4096, blocks: 8, atimeMs: 1318289051000.1, mtimeMs: 1318289051000.1, ctimeMs: 1318289051000.1, birthtimeMs: 1318289051000.1, atime: Mon, 10 Oct 2011 23:24:11 GMT, mtime: Mon, 10 Oct 2011 23:24:11 GMT, ctime: Mon, 10 Oct 2011 23:24:11 GMT, birthtime: Mon, 10 Oct 2011 23:24:11 GMT } bigint version: console BigIntStats { dev: 2114n, ino: 48064969n, mode: 33188n, nlink: 1n, uid: 85n, gid: 100n, rdev: 0n, size: 527n, blksize: 4096n, blocks: 8n, atimeMs: 1318289051000n, mtimeMs: 1318289051000n, ctimeMs: 1318289051000n, birthtimeMs: 1318289051000n, atimeNs: 1318289051000000000n, mtimeNs: 1318289051000000000n, ctimeNs: 1318289051000000000n, birthtimeNs: 1318289051000000000n, atime: Mon, 10 Oct 2011 23:24:11 GMT, mtime: Mon, 10 Oct 2011 23:24:11 GMT, ctime: Mon, 10 Oct 2011 23:24:11 GMT, birthtime: Mon, 10 Oct 2011 23:24:11 GMT }
type	Type	Types of a Leaf or Node entry

Node

type

a Node of the hierarchy

defined in fs-hierarchy/src/lib/types.ts

properties

Name	Type	Parent	Description
children*	((Leaf, Node))[]		children of the Node
stats	Stats	Leaf	A fs.Stats object provides information about a file. Objects returned from [{@link lstat} and {@link fstat](stat},) and their synchronous counterparts are of this type. If bigint in the options passed to those methods is true, the numeric values will be bigint instead of number , and the object will contain additional nanosecond-precision properties suffixed with Ns . console Stats { dev: 2114, ino: 48064969, mode: 33188, nlink: 1, uid: 85, gid: 100, rdev: 0, size: 527, blksize: 4096, blocks: 8, atimeMs: 1318289051000.1, mtimeMs: 1318289051000.1, ctimeMs: 1318289051000.1, birthtimeMs: 1318289051000.1, atime: Mon, 10 Oct 2011 23:24:11 GMT, mtime: Mon, 10 Oct 2011 23:24:11 GMT, ctime: Mon, 10 Oct 2011 23:24:11 GMT, birthtime: Mon, 10 Oct 2011 23:24:11 GMT } bigint version: console BigIntStats { dev: 2114n, ino: 48064969n, mode: 33188n, nlink: 1n, uid: 85n, gid: 100n, rdev: 0n, size: 527n, blksize: 4096n, blocks: 8n, atimeMs: 1318289051000n, mtimeMs: 1318289051000n, ctimeMs: 1318289051000n, birthtimeMs: 1318289051000n, atimeNs: 1318289051000000000n, mtimeNs: 1318289051000000000n, ctimeNs: 1318289051000000000n, birthtimeNs: 1318289051000000000n, atime: Mon, 10 Oct 2011 23:24:11 GMT, mtime: Mon, 10 Oct 2011 23:24:11 GMT, ctime: Mon, 10 Oct 2011 23:24:11 GMT, birthtime: Mon, 10 Oct 2011 23:24:11 GMT }
type	Type	Leaf	Types of a Leaf or Node entry
name*	string	Leaf	the name of the entry (without the base path)
path	string	Leaf	optionally included absolute path

Hierarchy

union

defined in fs-hierarchy/src/lib/types.ts

values

Leaf | Node

MatchOptions

type

`minimatch` options for filtering (https://github.com/isaacs/minimatch#options)

defined in fs-hierarchy/src/lib/types.ts

properties

Name	Type	Parent
dot	boolean
matchBase	boolean
nobrace	boolean	MinimatchOptions
nocomment	boolean	MinimatchOptions
nonegate	boolean	MinimatchOptions
debug	boolean	MinimatchOptions
noglobstar	boolean	MinimatchOptions
noext	boolean	MinimatchOptions
nonull	boolean	MinimatchOptions
windowsPathsNoEscape	boolean	MinimatchOptions
allowWindowsEscape	boolean	MinimatchOptions
partial	boolean	MinimatchOptions
nocase	boolean	MinimatchOptions
nocaseMagicOnly	boolean	MinimatchOptions
magicalBraces	boolean	MinimatchOptions
flipNegate	boolean	MinimatchOptions
preserveMultipleSlashes	boolean	MinimatchOptions
optimizationLevel	number	MinimatchOptions
platform	"aix" | "android" | "darwin" | "freebsd" | "haiku" | "linux" | "openbsd" | "sunos" | "win32" | "cygwin" | "netbsd"	MinimatchOptions
windowsNoMagicRoot	boolean	MinimatchOptions

MatchRule

union

The logical rule how filter patterns should be applied when set to `all` all filters must resolve successfully, when set to `some` at least one filter must resolve successfully, when set to `none` no filter must resolve successfully

defined in fs-hierarchy/src/lib/types.ts

values

"all" | "none" | "some"

Options

type

Use the options when you want to filter the resulting Hierarchy object or want to include extra informations.

defined in fs-hierarchy/src/lib/types.ts

properties

Name	Type	Description
filter	type empty: boolean match: string | string[] options: MatchOptions rule: MatchRule	filter options the resulting Hierarchy object
flatten	boolean	when true , the hierarchy will be flattened.
include	type extension: boolean pathname: boolean stats: boolean type: boolean	included in the return object
rootName	string	the used text of the root node
symlinks	boolean	when true , symlinks are followed