Skip to content

A modern TypeScript library for building organized, dynamic terminal interfaces with zone-based layouts

License

Notifications You must be signed in to change notification settings

itsJess1ca/Zonr-Core

Repository files navigation

Zonr Logo

A modern TypeScript library for building organized, dynamic terminal interfaces with zone-based layouts

npm version License: MIT Node.js Version


Hero Demo GIF

Zonr transforms terminal output from chaotic text streams into organized, responsive interfaces. Create dashboards, build tools, monitoring systems, and interactive applications with intuitive zone-based layouts that adapt to your terminal size.


✨ Key Features

  • 🎯 Zone-Based Architecture: Organize output into distinct, configurable areas
  • 📐 Dynamic Layout System: Automatic row grouping with intelligent space distribution
  • 📱 Responsive Design: Zones adapt automatically to terminal size changes
  • ⚡ Real-Time Updates: Event-driven messaging for instant UI updates
  • 🎨 Customizable Styling: Configurable borders, colors, headers, and dimensions
  • 🔧 Perfect Alignment: Custom ANSI renderer ensures pixel-perfect borders
  • 🌍 Wide Character Support: Proper handling of emoji and Unicode characters
  • 🚀 High Performance: Differential rendering updates only changed content
  • 🪟 Cross-Platform: Full Windows support with resize detection workarounds
  • 📁 File Transport: High-performance logging with sonic-boom and automatic cleanup
  • 🛡️ Signal Handling: Automatic graceful shutdown with transport flushing on SIGINT/SIGTERM

📦 Installation

npm install @zonr-logs/core # or pnpm add @zonr-logs/core # or yarn add @zonr-logs/core

Requirements: Node.js ≥16


🎮 Quick Start

import Zonr, { FileTransport } from '@zonr-logs/core'; // Create a new terminal UI with automatic signal handling const zonr = new Zonr({ autoCleanup: true }); // Add zones with different layouts and file logging const logs = zonr.addZone({ name: "Application Logs", width: "70%", height: "auto", borderColor: "blue", additionalTransports: [ new FileTransport({ filePath: "./app.log", highVolume: true // Optimized for high-throughput logging }) ] }); const status = zonr.addZone({ name: "System Status", width: "30%", height: "auto", borderColor: "green" }); // Start logging - automatically flushes to file on exit logs.info('🚀 Application started'); logs.warn('⚠️ High memory usage detected'); logs.error('❌ Database connection failed'); status.info('✅ Server: Online'); status.info('📊 CPU: 45%'); status.info('💾 Memory: 2.1GB');

🎬 Demo Gallery

🚀 Playground Demo - Basic file processing with progress tracking

The main playground demonstration showing file processing with real-time progress bars, metadata tracking, and logging.

pnpm run playground

Features: Progress bars, batch processing, real-time metrics, file logging

Hero Demo GIF

📊 Minimal Dashboard - Simple two-zone layout

Clean, minimal interface demonstrating basic zone creation with application logs and system status.

pnpm run demo:minimal

Features: Basic layouts, log levels, system metrics, auto-updating status

Demo Minimal GIF

🎮 Gaming Interface Demo - Multi-zone gaming server monitor

Comprehensive gaming server monitoring interface with player activity, server stats, game events, and match results.

pnpm run demo:gaming

Features: Multi-zone layout, real-time stats, emoji rendering, leaderboards

Gaming Demo GIF

🔧 Build System Monitor - Complex build pipeline visualization

Advanced build pipeline demonstration with progress tracking, build logs, test results, and deployment status.

pnpm run demo:build

Features: Build stages, progress indicators, test results, deployment tracking

Build Demo GIF

📈 Data Processing Dashboard - Real-time data pipeline

Real-time data processing pipeline with input queues, processing steps, output results, and performance metrics.

pnpm run demo:data

Features: Queue management, processing analytics, throughput metrics, auto-height zones

Data Demo GIF

🖥️ Full Development Dashboard - Complete monitoring interface

Comprehensive developer monitoring interface with system metrics, application logs, alerts, and status indicators.

pnpm run demo:dashboard

Features: System monitoring, log aggregation, alert management, comprehensive layouts

Dashboard Demo GIF


📚 API Reference

Creating a Zonr Instance

import Zonr from '@zonr-logs/core'; const zonr = new Zonr();

Adding Zones

const zone = zonr.addZone({ name: string, // Zone header text width: string | number, // "50%", "auto", or pixel value height: string | number,// "auto", "50%", or pixel value  borderColor?: string, // "red", "blue", "green", etc. showHeader?: boolean, // Show/hide zone header showBorder?: boolean // Show/hide zone borders });

Zone Methods

// Logging methods zone.info(message: string) // Blue info message zone.warn(message: string) // Yellow warning message  zone.error(message: string) // Red error message zone.debug(message: string) // Gray debug message zone.log(message: string) // Default log message // Zone management zone.clear() // Clear all messages zone.getName() // Get zone name zone.getConfig() // Get zone configuration

Zone Management

// Zone management methods zonr.addZone(config) // Add a new zone zonr.getZone(name) // Find zone by name zonr.hasZone(name) // Check if zone exists zonr.getAllZones() // Get all zones array zonr.removeZone(nameOrZone) // Remove specific zone by name or reference zonr.clearZones() // Remove all zones // Legacy API still available zonr.zones.add(config) // Same as zonr.addZone() zonr.zones.get(name) // Same as zonr.getZone() zonr.zones.list() // Same as zonr.getAllZones()

Layout Configuration

// Width options width: "50%" // Percentage of terminal width width: "auto" // Automatic width distribution width: 80 // Fixed pixel width // Height options  height: "auto" // Adapts to terminal size and content height: "30%" // Percentage of terminal height height: 20 // Fixed row height // Color options borderColor: "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white" | "gray"

🎯 Use Cases

Development Tools

  • Build Monitors: Track compilation, testing, and deployment stages
  • Log Aggregation: Organize application logs by service or severity
  • Development Servers: Show multiple service statuses simultaneously

System Monitoring

  • Server Dashboards: Display metrics, alerts, and system health
  • Process Monitoring: Track multiple running processes and their output
  • Network Tools: Monitor connections, throughput, and diagnostics

Interactive Applications

  • Gaming Interfaces: Leaderboards, chat, game state visualization
  • CLI Tools: Multi-step workflows with progress tracking
  • Data Processing: Real-time pipeline monitoring and statistics

🔧 Advanced Usage

File Transport

import { FileTransport } from '@zonr-logs/core'; // High-performance file logging with automatic cleanup const fileTransport = new FileTransport({ filePath: './logs/app.log', // Direct file path highVolume: true, // Optimize for high-throughput logging maxFiles: 5, // File rotation (placeholder) maxSize: '100MB' // Size rotation (placeholder) }); // Alternative: path + filename pattern const altTransport = new FileTransport({ path: './logs', // Directory path filename: 'application.log', // Filename sync: true, // Synchronous writes for reliability minLength: 8192 // Buffer size for performance }); const zone = zonr.addZone({ name: "Persistent Logs", width: "100%", height: "auto", additionalTransports: [fileTransport] // Updated property name }); // Automatic transport cleanup on SIGINT/SIGTERM // Files are properly flushed and closed when process exits

Event-Driven Updates

// Zones automatically emit events for real-time updates zone.info('Processing started...'); // Updates are immediately reflected in the terminal setTimeout(() => { zone.info('Processing completed ✅'); }, 2000);

Automatic Signal Handling

// Create Zonr instance with automatic cleanup (default: true) const zonr = new Zonr({ autoCleanup: true }); // Add zones with file transports const logger = zonr.addZone({ name: "Application", additionalTransports: [ new FileTransport({ filePath: './app.log' }) ] }); logger.info('Application started'); // When user presses Ctrl+C or process receives SIGTERM: // 1. All transports are automatically flushed // 2. All transports are properly closed  // 3. Process exits gracefully // 4. No data is lost! // Disable automatic cleanup if needed const manualZonr = new Zonr({ autoCleanup: false }); // You would need to manually call: // await manualZonr.flushAllTransports(); // await manualZonr.closeAllTransports();

Dynamic Layout Changes

// Zones automatically reflow when terminal is resized // No additional code needed - Zonr handles it automatically! // Works perfectly on Windows with built-in resize detection

🏗️ Architecture

Zonr uses a custom ANSI-based rendering system that provides:

  • Direct Terminal Control: Precise cursor positioning and screen management
  • Differential Updates: Only redraws changed content to eliminate flicker
  • Layout Engine: Sophisticated algorithm for space distribution and row grouping
  • Event System: Real-time communication between zones and renderer
  • Windows Compatibility: Specialized handling for Windows terminal limitations

Key Components

  • Zonr Class: Main facade providing the public API
  • Zone Manager: Handles zone lifecycle and organization
  • Layout Calculator: Dynamic space allocation and row grouping
  • Custom Renderer: ANSI-based rendering with perfect border alignment
  • Transport System: Pluggable output destinations (terminal, file, etc.)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository  git clone https://github.com/itsJess1ca/Zonr-Core.git cd zonr # Install dependencies pnpm install # Run tests pnpm test # Build the project pnpm build # Try the demos pnpm run demo:minimal pnpm run demo:gaming

Conventional Commits

This project uses Conventional Commits with automated semantic versioning:

# Interactive commit prompts (recommended) pnpm run commit # Manual conventional format git commit -m "feat: add new zone layout algorithm" git commit -m "fix: resolve border alignment issue" git commit -m "docs: update API documentation" # Test what would be released pnpm run release:dry

Commit Types:

  • feat: - New features (minor version bump)
  • fix: - Bug fixes (patch version bump)
  • docs: - Documentation changes
  • style: - Code style changes
  • refactor: - Code refactoring
  • test: - Adding or updating tests
  • chore: - Maintenance tasks
  • ci: - CI/CD changes
  • perf: - Performance improvements
  • build: - Build system changes

Breaking Changes: Add BREAKING CHANGE: in commit footer for major version bumps.

Automated Releases: Semantic releases are automatically created when conventional commits are pushed to the main branch.

Running Tests

pnpm test # Run tests in watch mode pnpm test:run # Run tests once pnpm test:ui # Run tests with UI

📄 License

This project is licensed under the MIT License - see the LICENSE.md file for details


🙏 Acknowledgments

  • Built with TypeScript for excellent developer experience
  • Inspired by modern terminal UI libraries but designed for simplicity
  • Special thanks to the Node.js community for terminal handling insights

📞 Support


⭐ Give us a star on GitHub!

Made with ❤️ for the terminal-loving community