{"id":13204,"library":"fs-tree-structure","title":"Filesystem Tree Structure Builder","description":"fs-tree-structure is a lightweight JavaScript/TypeScript utility designed to transform a flat list of file paths into a nested JavaScript object representing a directory tree structure. As of its current stable version, 0.0.5, it provides a single, focused function `makeTreeStructure` to perform this transformation. Due to its specific utility and low version number, its release cadence is likely stable but infrequent, implying minimal updates once its core functionality is mature. Key differentiators include its simplicity and direct focus on in-memory tree generation from string-based path arrays, rather than actual file system interaction. It includes TypeScript type definitions, ensuring type safety for TypeScript projects. The output is a plain JavaScript object, making it easily consumable by other parts of an application for purposes like documentation generation, build process analysis, or mock file system creation, providing a programmatic representation of a hierarchical file structure from flat input.","status":"active","version":"0.0.5","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","tree","nodejs","filesystem","module","dependencies","typescript"],"install":[{"cmd":"npm install fs-tree-structure","lang":"bash","label":"npm"},{"cmd":"yarn add fs-tree-structure","lang":"bash","label":"yarn"},{"cmd":"pnpm add fs-tree-structure","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily exports a named function. CommonJS 'require' syntax will not work with ESM-only setups.","wrong":"const makeTreeStructure = require('fs-tree-structure');","symbol":"makeTreeStructure","correct":"import { makeTreeStructure } from 'fs-tree-structure';"},{"note":"Import the `TreeStructure` type using `import type` for type-only imports in TypeScript, to avoid runtime overhead.","wrong":"import { TreeStructure } from 'fs-tree-structure';","symbol":"TreeStructure","correct":"import type { TreeStructure } from 'fs-tree-structure';"},{"note":"While a direct default import is not the primary pattern, if forced to use a default import (e.g., in some bundler configurations or older environments), you might need to target the CommonJS build specifically. The primary intended usage is named export.","wrong":"import makeTreeStructure from 'fs-tree-structure';","symbol":"default import","correct":"import makeTreeStructure from 'fs-tree-structure/dist/cjs/index.js';"}],"quickstart":{"code":"import { makeTreeStructure, type TreeStructure } from 'fs-tree-structure';\nimport assert from 'assert';\n\n// Example 1: Basic file paths\nconst filePaths1: string[] = [\n  \"src/components/Button.ts\",\n  \"src/components/Input.ts\",\n  \"src/utils/helpers.ts\",\n  \"src/index.ts\",\n  \"public/index.html\",\n  \"public/styles/main.css\"\n];\n\nconst treeStructure1: TreeStructure = makeTreeStructure(filePaths1);\n\nconsole.log('Tree Structure 1:', JSON.stringify(treeStructure1, null, 2));\nassert.deepStrictEqual(treeStructure1, {\n  src: {\n    components: {\n      \"Button.ts\": {},\n      \"Input.ts\": {}\n    },\n    utils: {\n      \"helpers.ts\": {}\n    },\n    \"index.ts\": {}\n  },\n  public: {\n    styles: {\n      \"main.css\": {}\n    },\n    \"index.html\": {}\n  }\n});\n\n// Example 2: Paths with different delimiters (library handles '/' internally)\nconst filePaths2: string[] = [\n  \"docs\\/guide\\/index.md\",\n  \"docs\\/api\\/index.md\"\n];\n\nconst treeStructure2: TreeStructure = makeTreeStructure(filePaths2);\nassert.deepStrictEqual(treeStructure2, {\n  docs: {\n    guide: {\n      \"index.md\": {}\n    },\n    api: {\n      \"index.md\": {}\n    }\n  }\n});\n\nconsole.log('Tree Structure 2:', JSON.stringify(treeStructure2, null, 2));\nconsole.log('All assertions passed!');","lang":"typescript","description":"This quickstart demonstrates how to use `makeTreeStructure` with various file path inputs, including paths with different separators, and verifies the resulting nested object structure with `assert.deepStrictEqual`."},"warnings":[{"fix":"Ensure all elements in the input array `filePaths` are valid strings representing file paths.","message":"The library expects file paths to be strings. Providing non-string or malformed path elements in the input array may lead to unexpected results or runtime errors, as it doesn't perform strict validation on individual path segment types.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"After generating the tree, iterate through it or use a separate mapping to add custom metadata to file nodes.","message":"The output tree structure represents files as empty objects (`{}`). There is no mechanism to attach additional metadata (like file content, size, or modification time) directly through the `makeTreeStructure` function. You must augment the resulting tree manually if such data is needed.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Pre-process file paths using Node.js `path` module utilities (e.g., `path.normalize()`, `path.posix.normalize()`) to ensure consistent path separators and simplified paths before passing them to `makeTreeStructure`.","message":"The library assumes a conventional file system hierarchy. Paths containing unusual characters, Windows-style backslashes mixed with forward slashes in inconsistent ways, or complex relative path navigations (e.g., `../`) might not resolve into the expected tree structure without prior normalization.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Filter or validate your input `filePaths` array to ensure all elements are valid string paths: `filePaths.filter(p => typeof p === 'string')`.","cause":"An element in the input `filePaths` array was not a string, or was `null` or `undefined`.","error":"TypeError: Cannot read properties of undefined (reading 'split')"},{"fix":"Review the input `filePaths` for conflicting entries (e.g., `a/b` and `a/b/c`). Ensure no path segment is both a file and a directory at the same level of the hierarchy. The library’s simple object merging will typically resolve 'file wins' or 'last write wins' for direct conflicts.","cause":"This specific error string is hypothetical but represents a common logic error in tree builders: attempting to create a directory where a file of the same name already exists at that level, or vice-versa. While `fs-tree-structure` generally overwrites, malformed inputs might lead to unexpected flattening if a path segment is ambiguous.","error":"Path segment 'foo' already exists as a file, cannot add directory 'foo'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}