npm package: @nhogs/table-logger
Description: A lightweight, zero-dependency, and state-aware Unicode table logger for Node.js.
Author: nhogs
Latest version: 0.0.2

# @nhogs/table-logger

> A lightweight, zero-dependency, and state-aware Unicode table logger for Node.js CLI applications.

![License](https://img.shields.io/npm/l/@nhogs/table-logger)
![Version](https://img.shields.io/npm/v/@nhogs/table-logger)

**Table Logger** is designed to create structured, readable logs in your terminal. Unlike standard `console.log` or complex table libraries, `table-logger` focuses on **streaming logs**. It maintains the visual structure of a table (headers, borders, footers) even as you log events line by line over time.

## ✨ Features

- **State-Aware**: Automatically handles transitions between headers, body lines, and footers.
- **Unicode Drawing**: Clean box-drawing characters for a professional look.
- **Streaming Friendly**: Designed to log processes as they happen (e.g., file processing, migrations).
- **Built-in Status Helpers**: Ready-to-use methods for `Success`, `Error`, `Warning`, `Info`, `Created`, etc.
- **TypeScript Support**: Written in TypeScript with full type definitions included.
- **Lightweight**: Minimal footprint, powered by `picocolors` for styling.

## 📦 Installation

```bash
npm install @nhogs/table-logger
```

## 🚀 Usage

### Basic Example

```typescript
import TableLogger from "@nhogs/table-logger";

// Initialize with default column widths
const logger = new TableLogger();

logger.logHeader("System Synchronization");

// Log standard lines: (Symbol, Status, Message)
logger.logLine("1", "INIT", "Connecting to database...");
logger.logLine("2", "AUTH", "Verifying credentials...");

// Use built-in helpers for colorful status
logger.logSuccess("Database connected successfully");
logger.logInfo("Fetching 500 records");
logger.logWarning("Response time > 200ms");
logger.logError("Failed to parse record #42");

logger.logFooter("Sync Completed");
logger.logEnd(); // Closes the table
```

### Visual Output Preview

```text
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃  System Synchronization                                                   ┃
┡━━━┯━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 1 │   INIT   │ Connecting to database...                                  │
│ 2 │   AUTH   │ Verifying credentials...                                   │
│ ✔ │ success  │ Database connected successfully                            │
│ » │   info   │ Fetching 500 records                                       │
│ ¡ │ warning  │ Response time > 200ms                                      │
│ ¿ │  error   │ Failed to parse record #42                                 │
┗━━━┷━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
    ┊  Sync Completed                                                       ┊
    ╰╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╯
```

## 📖 API Reference

### Constructor

```typescript
const logger = new TableLogger();
```

- `columnLength` (default: 10): Width of the "Status" column.
- `totalLength` (default: 224): Total width of the table.

### Core Methods

- **`logHeader(message: string)`**: Starts a new section with a double-border header.
- **`logLine(char: string, status: string, message: string)`**: Logs a standard row.
- `char`: Short symbol (1-3 chars) centered in the first column.
- `status`: Status text centered in the second column.
- `message`: Main content aligned left.

- **`logFooter(message: string)`**: Adds a footer section (useful for summaries).
- **`logEnd()`**: Closes the table bottom border. **Important:** Call this when your process is done.

### Helper Methods (Colorized)

These methods act as shortcuts for `logLine` with predefined symbols and colors:

| Method            | Symbol | Color       | Usage                 |
| ----------------- | ------ | ----------- | --------------------- |
| `logSuccess(msg)` | ✔      | Green       | Successful operations |
| `logError(msg)`   | ¿      | Red         | Critical failures     |
| `logWarning(msg)` | ¡      | Yellow      | Alerts                |
| `logInfo(msg)`    | »      | Cyan        | General information   |
| `logCreated(msg)` | +      | Green (Bg)  | Resource creation     |
| `logDeleted(msg)` | ✘      | Yellow (Bg) | Resource deletion     |
| `logUpdated(msg)` | ↯      | Blue (Bg)   | Resource updates      |
| `logExists(msg)`  | ◌      | Cyan (Bg)   | Skipped resources     |

### Summary System

You can push messages to a summary stack and flush them later (e.g., at the end of a script).

```typescript
logger.logSummary("Processed 50 files");
logger.logSummary("Skipped 2 files");

// ... later ...

TableLogger.flushSummary(); // Prints all summaries in a dedicated table
```

## 🎨 Customization

You can inject a custom "dyer" (coloring function) in the constructor if you want to override default styles or strip colors.

```typescript
import pc from "picocolors";

// Example: Force all borders to be magenta
const logger = new TableLogger(10, 100, pc.magenta);
```

## 📜 License

MIT © [NHOGS Interactive](https://github.com/nhogs)