Registry / serialization / fs-tree-structure

fs-tree-structure

library0.0.5jsnpmunverified

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.

serialization data

npm install fs-tree-structure

package ↗

INSTALL

IMPORT

SIG · FS-TREE-STRUCTURE

fs-tree-structure

serializationjavascriptv0.0.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

makeTreeStructure

✓ import { makeTreeStructure } from 'fs-tree-structure';

✗ const makeTreeStructure = require('fs-tree-structure');

The library primarily exports a named function. CommonJS 'require' syntax will not work with ESM-only setups.

TreeStructure

✓ import type { TreeStructure } from 'fs-tree-structure';

✗ import { TreeStructure } from 'fs-tree-structure';

Import the `TreeStructure` type using `import type` for type-only imports in TypeScript, to avoid runtime overhead.

default import

✓ import makeTreeStructure from 'fs-tree-structure/dist/cjs/index.js';

✗ import makeTreeStructure from 'fs-tree-structure';

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.

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`.

import { makeTreeStructure, type TreeStructure } from 'fs-tree-structure'; import assert from 'assert'; // Example 1: Basic file paths const filePaths1: string[] = [ "src/components/Button.ts", "src/components/Input.ts", "src/utils/helpers.ts", "src/index.ts", "public/index.html", "public/styles/main.css" ]; const treeStructure1: TreeStructure = makeTreeStructure(filePaths1); console.log('Tree Structure 1:', JSON.stringify(treeStructure1, null, 2)); assert.deepStrictEqual(treeStructure1, { src: { components: { "Button.ts": {}, "Input.ts": {} }, utils: { "helpers.ts": {} }, "index.ts": {} }, public: { styles: { "main.css": {} }, "index.html": {} } }); // Example 2: Paths with different delimiters (library handles '/' internally) const filePaths2: string[] = [ "docs\/guide\/index.md", "docs\/api\/index.md" ]; const treeStructure2: TreeStructure = makeTreeStructure(filePaths2); assert.deepStrictEqual(treeStructure2, { docs: { guide: { "index.md": {} }, api: { "index.md": {} } } }); console.log('Tree Structure 2:', JSON.stringify(treeStructure2, null, 2)); console.log('All assertions passed!');

Debug

Known issues

gotchaThe 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.

fix

Ensure all elements in the input array `filePaths` are valid strings representing file paths.

affects: >=0.0.1

gotchaThe 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.

fix

After generating the tree, iterate through it or use a separate mapping to add custom metadata to file nodes.

affects: >=0.0.1

gotchaThe 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.

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`.

affects: >=0.0.1

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'split')

An element in the input `filePaths` array was not a string, or was `null` or `undefined`.

fix

Filter or validate your input `filePaths` array to ensure all elements are valid string paths: `filePaths.filter(p => typeof p === 'string')`.

Path segment 'foo' already exists as a file, cannot add directory 'foo'

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.

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.

Upgrade

Version history

0.0.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/fs-tree-structure ↗