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 | typeempty: booleanmatch: string | string[]options: MatchOptionsrule: MatchRule | filter options the resulting Hierarchy object | | flatten | boolean | when true , the hierarchy will be flattened. | | include | typeextension: booleanpathname: booleanstats: booleantype: boolean | included in the return object | | rootName | string | the used text of the root node | | symlinks | boolean | when true , symlinks are followed |