json-toonify

Convert JSON/objects/arrays into a cleaner, more human-friendly toon-style formatted output with beautiful box-drawing characters and colorized terminal output.

Installation

npm install json-toonify

Quick Start

import { toonify, toonTable, toonDiff, toonLog } from 'json-toonify';

// Basic usage
const data = {
  name: 'John',
  age: 30,
  hobbies: ['reading', 'coding'],
  address: {
    city: 'New York',
    zip: '10001'
  }
};

console.log(toonify(data));

Features

• 🎨 Beautiful formatting with box-drawing characters
• 🌈 Colorized output for terminals (ANSI colors)
• 📊 Table formatting for arrays of objects
• 🔍 Diff comparison between objects
• 📝 Logging utility with automatic formatting
• ⚙️ Highly configurable with TypeScript types
• 🚀 Zero dependencies (except TypeScript for development)

API Reference

toonify(data, options?)

Main function to convert data into toon-style formatted string.

Parameters:

• data (unknown): The data to format (object, array, or primitive)
• options (ToonifyOptions, optional): Configuration options

Options:

interface ToonifyOptions {
  indent?: number;           // Indentation spaces (default: 2)
  colors?: boolean;          // Enable colorized output (default: true)
  maxDepth?: number;         // Maximum nesting depth (default: Infinity)
  maxStringLength?: number;  // Max string length before truncation (default: Infinity)
  showIndices?: boolean;     // Show array indices (default: true)
  showTypes?: boolean;       // Show type information (default: false)
}

Example:

const obj = {
  name: 'Alice',
  scores: [95, 87, 92],
  metadata: {
    created: '2024-01-01',
    tags: ['important', 'feature']
  }
};

console.log(toonify(obj));
// Output:
// ├─ name: "Alice"
// ├─ scores:
// │  ├─ [0]: 95
// │  ├─ [1]: 87
// │  └─ [2]: 92
// └─ metadata:
//    ├─ created: "2024-01-01"
//    └─ tags:
//       ├─ [0]: "important"
//       └─ [1]: "feature"

toonTable(data, options?)

Convert an array of objects into a formatted table.

Parameters:

• data (unknown[]): Array of objects to display as a table
• options (ToonTableOptions, optional): Configuration options

Options:

interface ToonTableOptions {
  headers?: string[];        // Column headers (auto-detected if not provided)
  colors?: boolean;          // Enable colorized output (default: true)
  align?: 'left' | 'right' | 'center';  // Column alignment (default: 'left')
  padding?: number;          // Cell padding (default: 1)
  maxColumnWidth?: number;   // Maximum column width (default: Infinity)
}

Example:

const users = [
  { name: 'Alice', age: 30, city: 'New York' },
  { name: 'Bob', age: 25, city: 'London' },
  { name: 'Charlie', age: 35, city: 'Tokyo' }
];

console.log(toonTable(users));
// Output:
// ┌──────────┬─────┬──────────┐
// │ name     │ age │ city     │
// ├──────────┼─────┼──────────┤
// │ Alice    │ 30  │ New York │
// │ Bob      │ 25  │ London   │
// │ Charlie  │ 35  │ Tokyo    │
// └──────────┴─────┴──────────┘

toonDiff(obj1, obj2, options?)

Compare two objects and display differences in a formatted way.

Parameters:

• obj1 (unknown): First object to compare
• obj2 (unknown): Second object to compare
• options (ToonDiffOptions, optional): Configuration options

Options:

interface ToonDiffOptions {
  showAdded?: boolean;       // Show added properties (default: true)
  showRemoved?: boolean;      // Show removed properties (default: true)
  showChanged?: boolean;      // Show changed properties (default: true)
  colors?: boolean;          // Enable colorized output (default: true)
  mode?: 'unified' | 'side-by-side';  // Display mode (default: 'unified')
  indent?: number;           // Indentation level (default: 2)
}

Example:

const obj1 = { name: 'Alice', age: 30, city: 'NYC' };
const obj2 = { name: 'Alice', age: 31, country: 'USA' };

console.log(toonDiff(obj1, obj2));
// Output:
// ├─ age:
// │  - 30
// │  + 31
// ├─ - city: "NYC"
// └─ + country: "USA"

toonLog(...args)

Logging utility that automatically formats data with toonify.

Parameters:

• ...args (unknown[]): Arguments to log (same as console.log)

Example:

const user = { name: 'Bob', age: 25 };
const scores = [95, 87, 92];

toonLog(user, scores);
// Automatically formats and logs both values

Advanced Usage

Custom Formatting

// Disable colors
console.log(toonify(data, { colors: false }));

// Limit depth
console.log(toonify(data, { maxDepth: 2 }));

// Show types
console.log(toonify(data, { showTypes: true }));

// Custom indentation
console.log(toonify(data, { indent: 4 }));

Table with Custom Headers

const data = [
  { a: 1, b: 2, c: 3 },
  { a: 4, b: 5, c: 6 }
];

console.log(toonTable(data, {
  headers: ['a', 'b', 'c'],
  align: 'center',
  padding: 2
}));

Diff Options

// Only show changes
console.log(toonDiff(obj1, obj2, {
  showAdded: false,
  showRemoved: false,
  showChanged: true
}));

TypeScript Support

Full TypeScript support with exported types:

import type {
  ToonifyOptions,
  ToonTableOptions,
  ToonDiffOptions
} from 'json-toonify';

Browser Support

This package uses ANSI color codes for terminal output. In browser environments, colors will be displayed as escape sequences unless you use a library that supports ANSI colors in the browser.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Changelog

1.0.0

• Initial release
• Core functions: toonify, toonTable, toonDiff, toonLog
• TypeScript support
• Colorized terminal output
• Box-drawing character formatting