@youbamj/tree 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 youbamj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,222 @@
+# @youbamj/tree
+
+<p>
+  <a href="https://www.npmjs.com/package/@youbamj/tree">
+    <img src="https://img.shields.io/npm/v/@youbamj/tree" alt="NPM Version" />
+  </a>
+  <a href="https://www.npmjs.com/package/@youbamj/tree">
+    <img src="https://img.shields.io/npm/l/@youbamj/tree" alt="License" />
+  </a>
+</p>
+
+`@youbamj/tree` is a modern TypeScript + Bun package to render directory trees and custom object trees.
+
+- CLI command: `ytree`
+- Library functions: `getFileTree()` and `getStringTree()`
+
+## Install
+
+### Install CLI globally
+
+Using npm:
+
+```bash
+npm install -g @youbamj/tree
+```
+
+Using bun:
+
+```bash
+bun add -g @youbamj/tree
+```
+
+### Install in your project
+
+Using npm:
+
+```bash
+npm install @youbamj/tree
+```
+
+Using bun:
+
+```bash
+bun add @youbamj/tree
+```
+
+## Use in terminal
+
+You can run `ytree` in the shell:
+
+```bash
+ytree -d ./src --ignore node_modules,.git --depth 3
+```
+
+Example output:
+
+```text
+·
+└── src
+    ├── cli.ts
+    ├── fs-tree.ts
+    ├── index.ts
+    ├── renderer.ts
+    └── types.ts
+```
+
+## Options
+
+```text
+Usage: ytree [options] [directory]
+
+Arguments:
+  directory               Directory to render (default: ".")
+
+Options:
+  -v, --version           Show version
+  -d, --dir <path>        Directory to render (overrides positional arg)
+  -o, --out <file>        Write output to a file
+  -i, --ignore <pattern>  Ignore basename or relative path (repeatable and comma-separated)
+  -l, --depth <n>         Max depth (root is level 1)
+  --no-hidden             Exclude hidden files/folders
+  --follow-symlinks       Traverse symbolic links
+  --no-gitignore          Do not respect .gitignore rules
+  --sort <mode>           Sorting mode: asc | desc | none
+  --max-nodes <n>         Maximum number of nodes to include (default: 10000, use -1 for no cap)
+  --json                  Print JSON tree
+  -c, --color [name]      Output color (default: "white")
+  --no-color              Disable color output
+  -h, --help              Display help
+```
+
+## Use in your project
+
+`getFileTree()` uses a default safety cap of `10000` nodes.
+Set `maxNodes: -1` to disable the cap.
+
+### 1) Render a directory tree to string
+
+```ts
+import { getFileTree, getStringTree } from "@youbamj/tree";
+
+const treeData = await getFileTree({
+  dir: "./",
+  ignore: ["node_modules", ".git"],
+  level: 3,
+  includeHidden: false,
+  gitignore: true,
+  sort: "asc"
+});
+
+console.log(getStringTree(treeData));
+```
+
+Example output:
+
+```text
+·
+└── my-project
+    ├── package.json
+    ├── src
+    │   ├── cli.ts
+    │   └── index.ts
+    └── tsconfig.json
+```
+
+Bun ESM script example:
+
+```ts
+// scripts/show-tree.ts
+import { getFileTree, getStringTree } from "@youbamj/tree";
+
+const data = await getFileTree({ dir: ".", level: 2 });
+console.log(getStringTree(data));
+```
+
+Run it with:
+
+```bash
+bun run scripts/show-tree.ts
+```
+
+### 2) Get raw `getFileTree()` JSON result
+
+```ts
+import { getFileTree } from "@youbamj/tree";
+
+const treeData = await getFileTree({
+  dir: "./src",
+  level: 2
+});
+
+console.log(JSON.stringify(treeData, null, 2));
+```
+
+Example result:
+
+```json
+[
+  {
+    "name": "src",
+    "path": "/absolute/path/to/src",
+    "type": "directory",
+    "children": [
+      {
+        "name": "cli.ts",
+        "path": "/absolute/path/to/src/cli.ts",
+        "type": "file"
+      },
+      {
+        "name": "index.ts",
+        "path": "/absolute/path/to/src/index.ts",
+        "type": "file"
+      }
+    ]
+  }
+]
+```
+
+### 3) Render custom object trees to string
+
+```ts
+import { getStringTree } from "@youbamj/tree";
+
+const output = getStringTree(
+  [
+    {
+      title: "done",
+      items: [{ title: "hiking" }, { title: "camping" }]
+    }
+  ],
+  {
+    labelKey: "title",
+    childrenKey: "items",
+    sanitizeLabels: true
+  }
+);
+
+console.log(output);
+```
+
+Example output:
+
+```text
+·
+└── done
+    ├── hiking
+    └── camping
+```
+
+## Why @youbamj/tree?
+
+- 🌲 Render directory content in a clean tree structure
+- 📝 Optionally write output to a file (`--out`)
+- 🎨 Colorized CLI output
+- 🧩 Convert custom arrays/objects to tree strings
+- 🙈 `.gitignore` support by default
+- 🔒 Terminal-safe label sanitization by default
+- ⚡ TypeScript + Bun friendly
+
+## License
+
+[MIT](./LICENSE)

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { Command, InvalidOptionArgumentError } from "commander";
+import { getFileTree, getStringTree } from "./index.js";
+const COLOR_CODES = {
+    white: "\u001b[37m",
+    red: "\u001b[31m",
+    green: "\u001b[32m",
+    yellow: "\u001b[33m",
+    blue: "\u001b[34m",
+    magenta: "\u001b[35m",
+    cyan: "\u001b[36m",
+    gray: "\u001b[90m",
+};
+const RESET = "\u001b[0m";
+const VERSION = "0.1.0";
+function applyColor(text, color, enabled) {
+    if (!enabled)
+        return text;
+    const normalized = (color || "white");
+    const code = COLOR_CODES[normalized] ?? COLOR_CODES.white;
+    return `${code}${text}${RESET}`;
+}
+function parseDepth(value) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new InvalidOptionArgumentError("depth must be a positive integer");
+    }
+    return parsed;
+}
+function parseSort(value) {
+    if (value === "asc" || value === "desc" || value === "none") {
+        return value;
+    }
+    throw new InvalidOptionArgumentError("sort must be one of: asc, desc, none");
+}
+function parseMaxNodes(value) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || (parsed < 1 && parsed !== -1)) {
+        throw new InvalidOptionArgumentError("max-nodes must be a positive integer or -1");
+    }
+    return parsed;
+}
+function collectIgnore(value, previous) {
+    const parsed = value
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    return [...previous, ...parsed];
+}
+function normalizeOutput(content, filename) {
+    const ext = path.extname(filename).toLowerCase();
+    if (ext === ".md") {
+        return `\
+\`\`\`text
+${content}
+\`\`\`
+`;
+    }
+    return content;
+}
+const program = new Command();
+program
+    .name("ytree")
+    .description("Render directory trees from the terminal")
+    .version(VERSION, "-v, --version", "Show version")
+    .argument("[directory]", "Directory to render", ".")
+    .option("-d, --dir <path>", "Directory to render (overrides positional arg)")
+    .option("-o, --out <file>", "Write output to a file")
+    .option("-i, --ignore <pattern>", "Ignore basename or relative path (repeatable and comma-separated)", collectIgnore, [])
+    .option("-l, --depth <n>", "Max depth (root is level 1)", parseDepth)
+    .option("--no-hidden", "Exclude hidden files/folders")
+    .option("--follow-symlinks", "Traverse symbolic links", false)
+    .option("--no-gitignore", "Do not respect .gitignore rules")
+    .option("--sort <mode>", "Sorting mode", parseSort, "asc")
+    .option("--max-nodes <n>", "Maximum number of nodes to include", parseMaxNodes)
+    .option("--json", "Print JSON tree", false)
+    .option("-c, --color [name]", "Output color", "white")
+    .option("--no-color", "Disable color output")
+    .action(async (directory, options) => {
+    const dir = options.dir ?? directory;
+    const treeData = await getFileTree({
+        dir,
+        ignore: options.ignore,
+        level: options.depth,
+        includeHidden: options.hidden,
+        followSymlinks: options.followSymlinks,
+        gitignore: options.gitignore,
+        sort: options.sort,
+        maxNodes: options.maxNodes,
+    });
+    const rendered = options.json ? JSON.stringify(treeData, null, 2) : getStringTree(treeData);
+    const colorEnabled = Boolean(options.color) && !options.json;
+    const colorName = typeof options.color === "string" ? options.color : "white";
+    const output = applyColor(rendered, colorName, colorEnabled);
+    console.log(output);
+    if (options.out) {
+        const fileContent = normalizeOutput(rendered, options.out);
+        await writeFile(options.out, fileContent, "utf8");
+    }
+});
+program.parseAsync(process.argv).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`[ERR] ${message}\n`);
+    process.exit(1);
+});

package/dist/fs-tree.d.ts

@@ -0,0 +1,2 @@
+import type { GetFileTreeOptions, TreeNode } from "./types.js";
+export declare function getFileTree({ dir, ignore, level, includeHidden, followSymlinks, sort, gitignore, maxNodes, }: GetFileTreeOptions): Promise<TreeNode[]>;

package/dist/fs-tree.js

@@ -0,0 +1,167 @@
+import { lstat, readFile, readdir, realpath } from "node:fs/promises";
+import path from "node:path";
+import createIgnore from "ignore";
+const DEFAULT_MAX_NODES = 10_000;
+function normalizeSlashes(input) {
+    return input.replace(/\\/g, "/");
+}
+function parseIgnore(ignore) {
+    if (!ignore)
+        return [];
+    const list = Array.isArray(ignore) ? ignore : ignore.split(",");
+    return list
+        .map((item) => item.trim())
+        .filter(Boolean)
+        .map((item) => normalizeSlashes(item.replace(/\/$/, "")));
+}
+function normalizeMaxNodes(maxNodes) {
+    if (maxNodes === -1)
+        return undefined;
+    if (!Number.isInteger(maxNodes) || maxNodes < 1) {
+        throw new Error("maxNodes must be a positive integer or -1 to disable the cap");
+    }
+    return maxNodes;
+}
+function shouldIgnoreByPatterns(relativePath, baseName, ignorePatterns) {
+    if (ignorePatterns.length === 0)
+        return false;
+    const rel = normalizeSlashes(relativePath);
+    for (const pattern of ignorePatterns) {
+        if (pattern.includes("/")) {
+            if (rel === pattern || rel.startsWith(`${pattern}/`)) {
+                return true;
+            }
+            continue;
+        }
+        if (baseName === pattern) {
+            return true;
+        }
+    }
+    return false;
+}
+function shouldIgnoreByGitignore(relativePath, isDirectory, gitignoreMatcher) {
+    if (!gitignoreMatcher || relativePath === "") {
+        return false;
+    }
+    if (gitignoreMatcher.ignores(relativePath)) {
+        return true;
+    }
+    if (isDirectory && gitignoreMatcher.ignores(`${relativePath}/`)) {
+        return true;
+    }
+    return false;
+}
+async function loadGitignore(rootDir, enabled) {
+    if (!enabled) {
+        return undefined;
+    }
+    try {
+        const gitignorePath = path.join(rootDir, ".gitignore");
+        const content = await readFile(gitignorePath, "utf8");
+        const gitignoreMatcher = createIgnore();
+        gitignoreMatcher.add(content);
+        return gitignoreMatcher;
+    }
+    catch {
+        return undefined;
+    }
+}
+function compareNames(a, b, sort) {
+    if (sort === "none")
+        return 0;
+    const result = a.localeCompare(b);
+    return sort === "desc" ? -result : result;
+}
+async function buildNode(absolutePath, depth, options) {
+    let stats;
+    try {
+        stats = await lstat(absolutePath);
+    }
+    catch (error) {
+        if (depth === 1) {
+            throw error;
+        }
+        return null;
+    }
+    const relativePath = normalizeSlashes(path.relative(options.rootDir, absolutePath));
+    const name = path.basename(absolutePath);
+    const isDirectory = stats.isDirectory();
+    if (!options.includeHidden && name.startsWith(".")) {
+        return null;
+    }
+    if (shouldIgnoreByPatterns(relativePath, name, options.ignorePatterns)) {
+        return null;
+    }
+    if (shouldIgnoreByGitignore(relativePath, isDirectory, options.gitignoreMatcher)) {
+        return null;
+    }
+    if (options.maxNodes !== undefined && options.nodeCount >= options.maxNodes) {
+        return null;
+    }
+    const node = {
+        name,
+        path: absolutePath,
+        type: isDirectory ? "directory" : stats.isSymbolicLink() ? "symlink" : "file",
+    };
+    options.nodeCount += 1;
+    if (options.maxDepth !== undefined && depth >= options.maxDepth) {
+        return node;
+    }
+    const shouldTraverseDirectory = isDirectory;
+    const shouldTraverseSymlink = stats.isSymbolicLink() && options.followSymlinks;
+    if (!shouldTraverseDirectory && !shouldTraverseSymlink) {
+        return node;
+    }
+    let targetPath = absolutePath;
+    if (shouldTraverseSymlink) {
+        try {
+            targetPath = await realpath(absolutePath);
+        }
+        catch {
+            return node;
+        }
+        if (options.visited.has(targetPath)) {
+            return node;
+        }
+        options.visited.add(targetPath);
+    }
+    let entries;
+    try {
+        entries = await readdir(targetPath);
+    }
+    catch {
+        return node;
+    }
+    entries = [...entries].sort((a, b) => compareNames(a, b, options.sort));
+    const children = [];
+    for (const entry of entries) {
+        const childPath = path.join(targetPath, entry);
+        const child = await buildNode(childPath, depth + 1, options);
+        if (child) {
+            children.push(child);
+        }
+    }
+    if (children.length > 0) {
+        node.children = children;
+    }
+    return node;
+}
+export async function getFileTree({ dir, ignore, level, includeHidden = true, followSymlinks = false, sort = "asc", gitignore = true, maxNodes = DEFAULT_MAX_NODES, }) {
+    const rootDir = path.resolve(process.cwd(), dir);
+    const ignorePatterns = parseIgnore(ignore);
+    const gitignoreMatcher = await loadGitignore(rootDir, gitignore);
+    const options = {
+        rootDir,
+        maxDepth: level,
+        includeHidden,
+        followSymlinks,
+        sort,
+        ignorePatterns,
+        gitignoreMatcher,
+        maxNodes: normalizeMaxNodes(maxNodes),
+        nodeCount: 0,
+        visited: new Set(),
+    };
+    const rootNode = await buildNode(rootDir, 1, options);
+    return rootNode ? [rootNode] : [];
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { getStringTree, getTreeLines } from "./renderer.js";
+export { getFileTree } from "./fs-tree.js";
+export type { GetFileTreeOptions, NodeType, RenderTreeOptions, SortOrder, TreeNode, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { getStringTree, getTreeLines } from "./renderer.js";
+export { getFileTree } from "./fs-tree.js";

package/dist/renderer.d.ts

@@ -0,0 +1,4 @@
+import type { RenderTreeOptions, TreeNode } from "./types.js";
+export declare function getTreeLines<T extends object>(data?: T[], renderOptions?: RenderTreeOptions): string[];
+export declare function getStringTree<T extends object>(data?: T[], renderOptions?: RenderTreeOptions): string;
+export type { TreeNode };

package/dist/renderer.js

@@ -0,0 +1,84 @@
+const DEFAULT_RENDER_OPTIONS = {
+    labelKey: "name",
+    childrenKey: "children",
+    rootMarker: "·",
+    indent: "    ",
+    branch: "├── ",
+    lastBranch: "└── ",
+    vertical: "│   ",
+    sanitizeLabels: true,
+};
+function asRecord(value) {
+    return value;
+}
+function stripAnsiSequences(value) {
+    let output = "";
+    for (let i = 0; i < value.length; i += 1) {
+        const code = value.charCodeAt(i);
+        // CSI escape sequence: ESC [ ... final-byte
+        if (code === 0x1b && value.charCodeAt(i + 1) === 0x5b) {
+            i += 2;
+            while (i < value.length) {
+                const next = value.charCodeAt(i);
+                if (next >= 0x40 && next <= 0x7e) {
+                    break;
+                }
+                i += 1;
+            }
+            continue;
+        }
+        output += value[i] ?? "";
+    }
+    return output;
+}
+function sanitizeControlCharacters(value) {
+    let output = "";
+    for (const char of value) {
+        const code = char.charCodeAt(0);
+        if (code < 32 || code === 127) {
+            output += `\\x${code.toString(16).padStart(2, "0")}`;
+            continue;
+        }
+        output += char;
+    }
+    return output;
+}
+function sanitizeLabel(label) {
+    return sanitizeControlCharacters(stripAnsiSequences(label));
+}
+function readChildren(node, childrenKey) {
+    const value = asRecord(node)[childrenKey];
+    return Array.isArray(value) ? value : [];
+}
+function readLabel(node, labelKey, sanitize) {
+    const value = asRecord(node)[labelKey];
+    const label = value == null ? "" : String(value);
+    return sanitize ? sanitizeLabel(label) : label;
+}
+function walk(nodes, options, parentLastFlags, out) {
+    for (const [i, node] of nodes.entries()) {
+        const isLast = i === nodes.length - 1;
+        let row = "";
+        for (const parentIsLast of parentLastFlags) {
+            row += parentIsLast ? options.indent : options.vertical;
+        }
+        row += isLast ? options.lastBranch : options.branch;
+        row += readLabel(node, options.labelKey, options.sanitizeLabels);
+        out.push(row);
+        const children = readChildren(node, options.childrenKey);
+        if (children.length > 0) {
+            walk(children, options, [...parentLastFlags, isLast], out);
+        }
+    }
+}
+export function getTreeLines(data = [], renderOptions = {}) {
+    const options = { ...DEFAULT_RENDER_OPTIONS, ...renderOptions };
+    if (data.length === 0)
+        return [];
+    const lines = [options.rootMarker];
+    walk(data, options, [], lines);
+    return lines;
+}
+export function getStringTree(data = [], renderOptions = {}) {
+    return getTreeLines(data, renderOptions).join("\n");
+}

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+export type NodeType = "file" | "directory" | "symlink";
+export interface TreeNode {
+    name: string;
+    path?: string;
+    type?: NodeType;
+    children?: TreeNode[];
+}
+export interface RenderTreeOptions {
+    labelKey?: string;
+    childrenKey?: string;
+    rootMarker?: string;
+    indent?: string;
+    branch?: string;
+    lastBranch?: string;
+    vertical?: string;
+    sanitizeLabels?: boolean;
+}
+export type SortOrder = "asc" | "desc" | "none";
+export interface GetFileTreeOptions {
+    dir: string;
+    ignore?: string | string[];
+    level?: number;
+    includeHidden?: boolean;
+    followSymlinks?: boolean;
+    sort?: SortOrder;
+    gitignore?: boolean;
+    maxNodes?: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@youbamj/tree",
+  "version": "0.1.0",
+  "description": "Render directory and object trees in a clean, modern TypeScript package with CLI support.",
+  "type": "module",
+  "license": "MIT",
+  "author": "youbamj",
+  "homepage": "https://github.com/youbamj/tree#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/youbamj/tree.git"
+  },
+  "bugs": {
+    "url": "https://github.com/youbamj/tree/issues"
+  },
+  "keywords": ["tree", "cli", "directory", "typescript", "bun"],
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "ytree": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "bun run src/cli.ts",
+    "test": "bun test",
+    "check:types": "tsc --noEmit",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "check": "bun run check:types && bun run lint",
+    "precommit": "lint-staged && bun run check:types",
+    "prepare": "husky",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "npm publish --provenance"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx,json,md}": ["biome check --write"]
+  },
+  "dependencies": {
+    "commander": "^14.0.1",
+    "ignore": "^7.0.5"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@changesets/cli": "^2.29.7",
+    "@types/bun": "latest",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.0",
+    "typescript": "^5.6.3"
+  }
+}