🌲 termtree

Ultra-fast, zero-dependency console object tree inspector and interactive CLI logger for Node.js and TypeScript.

termtree is a modern developer experience (DX) tool that transforms complex, nested JavaScript objects and primitives into highly readable, color-coded trees directly in your terminal. It automatically prints clickable source code links mapping exactly to where the logger was called, letting you cmd+click straight to your files from VS Code, iTerm, or other terminals.

[APP INITIALIZATION] ↳ Call Trace: bootstrap (file:///Users/dev/project/src/index.js:12:3)
{
├── service: "outreach-campaign"
├── status: "active"
└── metrics:
    ├── durationMs: 1420
    ├── successRate: 0.98
    └── activeConnections: 12
}

Key Features

• ⚡ Zero-Dependency & Fast: Sub-10KB install size. Designed for edge runtimes (Cloudflare Workers, Vercel Edge, Bun) where external dependency size and startup latency are critical.
• 🔍 Clickable Stack Trace Mapping: Automatically captures the file path, line, and column that invoked the log. Renders a clickable file:// link directly in the terminal console.
• 🎨 Vibrant Color Schemes: Comes prepackaged with high-contrast, premium color palettes (ocean, forest, candy, sunset).
• 🛡️ Circular Reference Guard: Safely intercepts self-referencing loops and cyclical structures, preventing stack overflows.
• 📦 Native TypeScript Support: Prepackaged with type definitions (index.d.ts) for clean autocompletion.
• ⚙️ Custom Color Themes: Design your own theme configuration keys using plain functions or customized color mappings.

Installation

Install via your preferred package manager:

npm install termtree-logger
# or
yarn add termtree-logger
# or
pnpm add termtree-logger
# or
bun add termtree-logger

Quick Start

1. Simple Shorthand Logging

Use the shorthand functions for instantaneous debugging with predefined styles:

const { termtree } = require('termtree-logger');

// Default Ocean Theme
termtree({ name: 'Ezekiel', active: true }, 'User status');

// Sunset Orange/Red Theme (Perfect for warnings)
termtree.sunset({ error: 'TOKEN_EXPIRED', status: 401 }, 'Auth error');

// Candy Pink/Purple Theme (Great for visual separation)
termtree.candy({ items: [1, 2, 3] }, 'Cart details');

// Forest Green Theme (Perfect for DB sync actions)
termtree.forest(new Set(['sql', 'redis']), 'Data stores');

// Plain Text Theme (Strips color formatting)
termtree.plain({ debug: true }, 'Raw logs');

2. Custom Logger Instance

Create custom instances with strict constraints, custom themes, or toggled trace flags:

const { TermTree } = require('termtree-logger');

const logger = new TermTree({
  theme: 'forest',     // ocean | forest | candy | sunset | plain
  showTrace: true,     // Toggle caller stack trace mapping
  showTypes: true,     // Include Map/Set/Array prefixes
  maxDepth: 3,         // Safeguard nesting depth
});

logger.log({
  config: {
    db: {
      url: 'localhost:5432',
      pool: 10
    }
  }
}, 'Database Initialization');

3. Custom Themes

Build your own customized color palettes mapping key console types:

const logger = new TermTree({
  theme: {
    key: (text) => `\x1b[33m${text}\x1b[0m`,    // Yellow keys
    string: (text) => `\x1b[32m${text}\x1b[0m`, // Green strings
    number: (text) => `\x1b[36m${text}\x1b[0m`, // Cyan numbers
  }
});

Contrast Matrix

| Theme | Key Color | String Color | Number Color | Border | Recommended Use Cases | | :--- | :--- | :--- | :--- | :--- | :--- | | Ocean | Cyan | Green | Yellow | Gray | General logging, app lifecycle states | | Forest | Green | Yellow | Cyan | Gray | Database ops, caching, file sync | | Candy | Magenta | Cyan | Yellow | Gray | User actions, auth events, requests | | Sunset | Red | Yellow | Magenta | Gray | Error stacks, warnings, socket issues | | Plain | Raw | Raw | Raw | Raw | File logs, production pipelines, CI |

Technical Details & Architecture

Clickable Call Traces

termtree inspects the calling frame using V8's native stack traces (Error.prepareStackTrace) when a logging method is triggered. It bypasses internal package calls and node core stack frames to output the precise file, line, and column that invoked the log. The resulting string is rendered using the file:// protocol, which modern terminals like VS Code and iTerm2 parse natively as a clickable hyperlink.

Circular Reference Checking

A dynamic Set monitors active reference depths during recursion. When a child property points to a parent reference already tracked within the set, termtree prints [Circular Reference] instead of triggering an infinite rendering loop.

Contributing

We welcome community contributions! To set up termtree locally:

1. Clone the repository: git clone https://github.com/Ezeko/termtree.git
2. Run automated tests: npm test
3. Test terminal coloring locally: node scratch_run.js

Please read our Contributing Guide to understand linting rules, formatting guidelines, and PR procedures.

License

MIT © Ezekiel Adejobi