files-to-tree
Version:
Convert file path objects to hierarchical tree structures
197 lines (144 loc) • 4.74 kB
Markdown
[](https://badge.fury.io/js/files-to-tree)
[](https://www.typescriptlang.org)
A lightweight TypeScript library that converts flat file path objects into hierarchical tree structures. Perfect for representing file systems, directory structures, or any hierarchical data in a clean, tree-like format.
```bash
npm install files-to-tree
```
```bash
yarn add files-to-tree
```
```bash
pnpm add files-to-tree
```
```typescript
import { convertFilesToTreeItems } from 'files-to-tree';
const files = {
'src/index.ts': 'export * from "./utils"',
'src/utils/helpers.ts': 'export function help() {}',
'src/components/Button.tsx': 'export const Button = () => {}',
'package.json': '{"name": "my-app"}',
'README.md': '# My App',
};
const tree = convertFilesToTreeItems(files);
console.log(tree);
// Output:
// [
// 'README.md',
// 'package.json',
// [
// 'src',
// ['components', 'Button.tsx'],
// 'index.ts',
// ['utils', 'helpers.ts']
// ]
// ]
```
Converts a flat object of file paths to a hierarchical tree structure.
**Parameters:**
- `files` (FilesObject): An object where keys are file paths and values are file contents (contents are used for sorting but not included in output)
**Returns:**
- `TreeItem[]`: An array representing the tree structure
### Types
```typescript
// A tree item can be either a string (file/empty dir) or a tuple (directory with children)
type TreeItem = string | [string, ...TreeItem[]];
// Input object type
interface FilesObject {
[]: string;
}
```
```typescript
import { convertFilesToTreeItems } from 'files-to-tree';
const files = {
'index.html': '<html>...</html>',
'styles.css': 'body { margin: 0; }',
'script.js': 'console.log("Hello");',
};
const tree = convertFilesToTreeItems(files);
// Result: ['index.html', 'script.js', 'styles.css']
```
```typescript
const files = {
'src/components/Header/index.ts': 'export',
'src/components/Header/Header.tsx': 'component',
'src/components/Footer/Footer.tsx': 'component',
'src/utils/api.ts': 'api functions',
'public/favicon.ico': 'icon',
'package.json': 'manifest',
};
const tree = convertFilesToTreeItems(files);
// Result:
// [
// 'package.json',
// ['public', 'favicon.ico'],
// [
// 'src',
// [
// 'components',
// ['Footer', 'Footer.tsx'],
// ['Header', 'Header.tsx', 'index.ts']
// ],
// ['utils', 'api.ts']
// ]
// ]
```
```typescript
// Named import
import { convertFilesToTreeItems } from 'files-to-tree';
// Default import
import convertFilesToTreeItems from 'files-to-tree';
// CommonJS
const { convertFilesToTreeItems } = require('files-to-tree');
```
- **🚀 Lightweight**: Zero dependencies, minimal footprint
- **📦 TypeScript First**: Full TypeScript support with detailed type definitions
- **🔧 Multiple Formats**: Supports CommonJS, ESM, and TypeScript
- **📊 Sorted Output**: Files and directories are automatically sorted alphabetically
- **🎯 Simple API**: Single function with intuitive input/output
- **✅ Well Tested**: Comprehensive test coverage
- **📱 Universal**: Works in Node.js, browsers, and edge environments
- **File System Representation**: Display directory structures in UI components
- **Documentation**: Generate file tree views for project documentation
- **Code Analysis**: Analyze project structure and dependencies
- **Build Tools**: Process file hierarchies in build pipelines
- **API Responses**: Structure file listings in REST APIs
```bash
npm install
npm test
npm run test:coverage
npm run build
npm run dev
```
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
MIT © [KlyneChrysler]
- **BREAKING**: Fixed TypeScript compilation issues with strict mode
- Improved error handling and type safety
- Better handling of edge cases (empty paths, undefined values)
- Enhanced sorting algorithm for consistent output
- Full TypeScript declaration file generation
### 1.0.0
- Initial release
- Basic file-to-tree conversion functionality
- TypeScript support
- Comprehensive test coverage