{"id":18440562,"url":"https://github.com/fooloomanzoo/fs-hierarchy","last_synced_at":"2025-04-07T22:31:37.407Z","repository":{"id":57242265,"uuid":"267537608","full_name":"fooloomanzoo/fs-hierarchy","owner":"fooloomanzoo","description":"build hierarchy maps of files and folders using nodejs in json, yaml or in tree view","archived":false,"fork":false,"pushed_at":"2024-05-06T06:39:27.000Z","size":1227,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-23T01:12:30.598Z","etag":null,"topics":["cli","d3","fs","hierachy","nodejs","tree","tree-structure","treemap"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fooloomanzoo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-28T08:39:55.000Z","updated_at":"2024-05-06T06:39:30.000Z","dependencies_parsed_at":"2024-11-06T06:33:45.479Z","dependency_job_id":"1674a52d-c9b0-4969-83cf-9d445b4c53bf","html_url":"https://github.com/fooloomanzoo/fs-hierarchy","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fooloomanzoo%2Ffs-hierarchy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fooloomanzoo%2Ffs-hierarchy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fooloomanzoo%2Ffs-hierarchy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fooloomanzoo%2Ffs-hierarchy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fooloomanzoo","download_url":"https://codeload.github.com/fooloomanzoo/fs-hierarchy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247740871,"owners_count":20988283,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","d3","fs","hierachy","nodejs","tree","tree-structure","treemap"],"created_at":"2024-11-06T06:31:11.224Z","updated_at":"2025-04-07T22:31:35.643Z","avatar_url":"https://github.com/fooloomanzoo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fs-hierarchy\n\nCreate a hierarchy map of a filesystem using node's built-in **fs**. \n\nYou can use the CLI or include it directly in your project.\nIt returns a structure that can be used in different contexts like for [d3-hierarchy](https://observablehq.com/@d3/d3-hierarchy). \n\nAdditionally it is possible:\n\n- to include extra informations like the file extension, the absolute path, the type and [stats](https://nodejs.org/api/fs.html#fs_class_fs_stats)\n- filter paths and names\n- follow symbolic links\n- in CLI: output in json, yaml or in a tree to stdout or file\n\n[![Version](https://img.shields.io/npm/v/fs-hierarchy.svg?style=for-the-badge)](https://npmjs.org/package/fs-hierarchy)\n[![Downloads/week](https://img.shields.io/npm/dw/fs-hierarchy.svg?style=for-the-badge)](https://npmjs.org/package/fs-hierarchy)\n[![License](https://img.shields.io/npm/l/fs-hierarchy.svg?style=for-the-badge)](https://github.com/fooloomanzoo/fs-hierarchy/blob/master/package.json)\n\n\u003c!-- toc --\u003e\n\n- [fs-hierarchy](#fs-hierarchy)\n- [CLI](#cli)\n- [Programmatic use](#programmatic-use)\n \u003c!-- tocstop --\u003e\n\n# CLI\n\nUsing the CLI, `fs-hierarchy` supports different output formats and options.\n\n## Commands\n\n\u003c!-- commands --\u003e\n\n- [`fs-hierarchy [DIR] [OUTPUT]`](#fs-hierarchy-dir-output)\n\n## `fs-hierarchy [DIR] [OUTPUT]`\n\nCreate a hierarchy map of a filesystem using node's built-in _fs_.\n\n USAGE\n $ fs-hierarchy [DIR] [OUTPUT] [-e] [--flat] [-f tree|yaml|json] [-h] [-i ext|path|stats|type] [-m\n \u003cvalue\u003e] [-M all|none|some] [--minify] [-r \u003cvalue\u003e] [-s] [-v]\n\n ARGUMENTS\n DIR [default: .] path to create a hierarchy from\n OUTPUT output filename\n\n FLAGS\n -M, --match-rule=\u003coption\u003e [default: some] rule for matching paths\n \u003coptions: all|none|some\u003e\n -e, --empty include child nodes that have no children\n -f, --format=\u003coption\u003e [default: json] the used output format\n \u003coptions: tree|yaml|json\u003e\n -h, --help show this help\n -i, --include=\u003coption\u003e... the included informations in return object\n \u003coptions: ext|path|stats|type\u003e\n -m, --match=\u003cvalue\u003e... filter matching paths\n -r, --root=\u003cvalue\u003e the used name for the root-folder\n -s, --symlinks follow symbolic links\n -v, --version show the version\n --flat flatten the output\n --minify minify the output\n\n DESCRIPTION\n Create a hierarchy map of a filesystem using node's built-in *fs*.\n\n FLAG DESCRIPTIONS\n -M, --match-rule=all|none|some rule for matching paths\n\n when set to \"all\" all filters must resolve successfully,\n when set to \"some\" at least one filter must resolve successfully,\n when set to \"none\" no filter must resolve successfully\n\n -m, --match=\u003cvalue\u003e... filter matching paths\n\n use glob pattern for matching\n negate by leading '!'\n e.g. -m '**/*.ts' '!**/node_modules/**'\n\n --flat flatten the output\n\n if true the full path will be included by default. using tree format the full path will be used instead of the\n filenames\n\n --minify minify the output\n\n only for json format\n\n\u003c!-- commandsstop --\u003e\n\n\u003c!-- output --\u003e\n## JSON\n \n```shell-script\n$ fs-hierarchy ./src -m 'index.ts'\n```\n\n\n```json\n{\n \"name\": \"./src\",\n \"children\": [\n {\n \"name\": \"commands\",\n \"children\": [\n {\n \"name\": \"index.ts\"\n }\n ]\n },\n {\n \"name\": \"index.ts\"\n },\n {\n \"name\": \"lib\",\n \"children\": [\n {\n \"name\": \"index.ts\"\n }\n ]\n }\n ]\n}\n\n```\n\n\n## Tree\n \n```shell-script\n$ fs-hierarchy ./src -f tree -m '*.ts'\n```\n\n\n```\n./src\n ├─ commands\n │ ╰─ index.ts\n ├─ index.ts\n ╰─ lib\n ├─ format\n │ ├─ json.ts\n │ ├─ tree.ts\n │ ╰─ yaml.ts\n ├─ hierarchy.ts\n ├─ index.ts\n ├─ types.ts\n ├─ utils\n │ ├─ factories.ts\n │ ├─ flatten.ts\n │ ├─ leaf.ts\n │ ├─ read-dir.ts\n │ ├─ type.ts\n │ ╰─ typeguards.ts\n ╰─ write\n ├─ file.ts\n ╰─ stdout.ts\n\n\n```\n\n\n\u003c!-- outputstop --\u003e\n\n## More Examples\n\n- [Formatting](docs/format.md)\n- [Filter](docs/filter.md)\n\n# Programmatic use\n\n```sh-session\n$ npm install fs-hierarchy\n```\n\n```javascript\nconst { hierarchy } = require('fs-hirarchy');\n\nconst root = path.resolve(__dirname, 'files');\nconst options = {\n filter: { match: '*.json' },\n include: { path: true },\n rootName: 'HomeSweetHome'\n};\n\nconst matches = hierarchy(root, options);\n```\n\n\u003capi-readme files=\"./src/lib/index.ts\" /\u003e\n\n\u003c!-- START-API-README --\u003e\n\n## hierarchy\n\n**`function`**\n\nCreates a hierarchy tree structure based on the given root path and options.\n\n_defined in [fs-hierarchy/src/lib/hierarchy.ts](https://github.com/fooloomanzoo/fs-hierarchy/tree/master/src/lib/hierarchy.ts#L20)_\n\n**parameters**\n\n| Name | Type | Description |\n| ---------- | ---------------------------------- | ------------------------------------------ |\n| `root*` | `string` | The root path of the hierarchy. |\n| `options*` | [`Options`](#options) | The options for configuring the hierarchy. |\n| `returns` | [`Leaf`](#leaf) \\| [`Node`](#node) | The hierarchy tree structure. |\n\n## Type\n\n**`union`**\n\nTypes of a Leaf or Node entry\n\n_defined in [fs-hierarchy/src/lib/types.ts](https://github.com/fooloomanzoo/fs-hierarchy/tree/master/src/lib/types.ts#L7)_\n\n**values**\n\n`\"block-device\"` \\| `\"char-device\"` \\| `\"dir\"` \\| `\"file\"` \\| `\"pipe\"` \\| `\"socket\"` \\| `\"symlink\"`\n\n## Leaf\n\n**`type`**\n\na Leaf of the hierarchy\n\n_defined in [fs-hierarchy/src/lib/types.ts](https://github.com/fooloomanzoo/fs-hierarchy/tree/master/src/lib/types.ts#L19)_\n\n**properties**\n\n| Name | Type | Description |\n| ----------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `extension` | `string` | optionally included extension (only for `Leaf` s) |\n| `name*` | `string` | the name of the entry (without the base path) |\n| `path` | `string` | optionally included absolute path |\n| `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 } ` |\n| `type` | [`Type`](#type) | Types of a Leaf or Node entry |\n\n## Node\n\n**`type`**\n\na Node of the hierarchy\n\n_defined in [fs-hierarchy/src/lib/types.ts](https://github.com/fooloomanzoo/fs-hierarchy/tree/master/src/lib/types.ts#L45)_\n\n**properties**\n\n| Name | Type | Parent | Description |\n| ----------- | --------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `children*` | (([`Leaf`](#leaf), [`Node`](#node)))\\[] | | children of the `Node` |\n| `stats` | Stats | [`Leaf`](#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 } ` |\n| `type` | [`Type`](#type) | [`Leaf`](#leaf) | Types of a Leaf or Node entry |\n| `name*` | `string` | [`Leaf`](#leaf) | the name of the entry (without the base path) |\n| `path` | `string` | [`Leaf`](#leaf) | optionally included absolute path |\n\n## Hierarchy\n\n**`union`**\n\n_defined in [fs-hierarchy/src/lib/types.ts](https://github.com/fooloomanzoo/fs-hierarchy/tree/master/src/lib/types.ts#L53)_\n\n**values**\n\n[`Leaf`](#leaf) \\| [`Node`](#node)\n\n## MatchOptions\n\n**`type`**\n\n\\`minimatch\\` options for filtering (https\u0026#x3A;//github.com/isaacs/minimatch#options)\n\n_defined in [fs-hierarchy/src/lib/types.ts](https://github.com/fooloomanzoo/fs-hierarchy/tree/master/src/lib/types.ts#L58)_\n\n**properties**\n\n| Name | Type | Parent |\n| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |\n| `dot` | `boolean` | |\n| `matchBase` | `boolean` | |\n| `nobrace` | `boolean` | `MinimatchOptions` |\n| `nocomment` | `boolean` | `MinimatchOptions` |\n| `nonegate` | `boolean` | `MinimatchOptions` |\n| `debug` | `boolean` | `MinimatchOptions` |\n| `noglobstar` | `boolean` | `MinimatchOptions` |\n| `noext` | `boolean` | `MinimatchOptions` |\n| `nonull` | `boolean` | `MinimatchOptions` |\n| `windowsPathsNoEscape` | `boolean` | `MinimatchOptions` |\n| `allowWindowsEscape` | `boolean` | `MinimatchOptions` |\n| `partial` | `boolean` | `MinimatchOptions` |\n| `nocase` | `boolean` | `MinimatchOptions` |\n| `nocaseMagicOnly` | `boolean` | `MinimatchOptions` |\n| `magicalBraces` | `boolean` | `MinimatchOptions` |\n| `flipNegate` | `boolean` | `MinimatchOptions` |\n| `preserveMultipleSlashes` | `boolean` | `MinimatchOptions` |\n| `optimizationLevel` | `number` | `MinimatchOptions` |\n| `platform` | `\"aix\"` \\| `\"android\"` \\| `\"darwin\"` \\| `\"freebsd\"` \\| `\"haiku\"` \\| `\"linux\"` \\| `\"openbsd\"` \\| `\"sunos\"` \\| `\"win32\"` \\| `\"cygwin\"` \\| `\"netbsd\"` | `MinimatchOptions` |\n| `windowsNoMagicRoot` | `boolean` | `MinimatchOptions` |\n\n## MatchRule\n\n**`union`**\n\nThe 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\n\n_defined in [fs-hierarchy/src/lib/types.ts](https://github.com/fooloomanzoo/fs-hierarchy/tree/master/src/lib/types.ts#L72)_\n\n**values**\n\n`\"all\"` \\| `\"none\"` \\| `\"some\"`\n\n## Options\n\n**`type`**\n\nUse the options when you want to filter the resulting Hierarchy object or want to include extra informations.\n\n_defined in [fs-hierarchy/src/lib/types.ts](https://github.com/fooloomanzoo/fs-hierarchy/tree/master/src/lib/types.ts#L77)_\n\n**properties**\n\n| Name | Type | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |\n| `filter` | \u003cdetails\u003e\u003csummary\u003e`type`\u003c/summary\u003e\u003cblockquote\u003e`empty`: `boolean`\u003cbr /\u003e`match`: `string` \\| `string`\\[]\u003cbr /\u003e`options`: [`MatchOptions`](#matchoptions)\u003cbr /\u003e`rule`: [`MatchRule`](#matchrule)\u003c/blockquote\u003e\u003c/details\u003e | filter options the resulting Hierarchy object |\n| `flatten` | `boolean` | when `true` , the hierarchy will be flattened. |\n| `include` | \u003cdetails\u003e\u003csummary\u003e`type`\u003c/summary\u003e\u003cblockquote\u003e`extension`: `boolean`\u003cbr /\u003e`pathname`: `boolean`\u003cbr /\u003e`stats`: `boolean`\u003cbr /\u003e`type`: `boolean`\u003c/blockquote\u003e\u003c/details\u003e | included in the return object |\n| `rootName` | `string` | the used text of the root node |\n| `symlinks` | `boolean` | when `true` , symlinks are followed |\n\n\u003c!-- END-API-README --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffooloomanzoo%2Ffs-hierarchy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffooloomanzoo%2Ffs-hierarchy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffooloomanzoo%2Ffs-hierarchy/lists"}