logger-chroma 1.0.0

package/.github/workflows/npmpublish.yml

@@ -0,0 +1,48 @@
+# This workflow will run tests using node and then publish a package to npm using Trusted Publishing (OIDC)
+# For more information see: https://docs.npmjs.com/using-private-packages-in-a-ci-cd-workflow
+
+name: logger-chroma NPM Package
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    # Skip Dependabot PRs for CI/CD
+    if: ${{ github.actor != 'dependabot[bot]' }}
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: lts/krypton
+
+      - run: npm install
+      - run: npm test
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+
+    # Skip Dependabot PRs
+    if: ${{ github.actor != 'dependabot[bot]' }}
+
+    # Required for OIDC Trusted Publishing
+    permissions:
+      contents: read
+      id-token: write # 👈 REQUIRED for Trusted Publishing
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: lts/krypton
+          registry-url: https://registry.npmjs.org/
+
+      - run: npm install
+      - run: npm publish

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex
+
+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,111 @@
+# logger-chroma
+
+<p align="center"><a href="https://nodei.co/npm/logger-chroma/"><img src="https://nodei.co/npm/logger-chroma.png"></a></a></p>
+<p align="center">
+  <img src="https://img.shields.io/badge/License-MIT-yellow.svg">
+</p>
+
+<p align="center">
+  <img src="terminal.png" alt="Terminal output image">
+</p>
+
+* 🎨 A lightweight, high-performance Node.js logging utility designed for developers who need to visualize complex, nested operations. `logger-chroma` transforms flat, messy console outputs into a beautiful, structured tree that makes debugging logical flows intuitive.
+* 👨‍💻 Optimized for modern terminals like `Windows Terminal`, `VS Code Integrated Terminal`, and `iTerm2`, `Windows Git Bash Terminal` where box-drawing characters are rendered natively.
+* ♻️ Works seamlessly with `CommonJS`, `ESM` and `TypeScript`
+
+# 📦 Install via [NPM](https://www.npmjs.com/package/logger-chroma)
+
+```bash
+$ npm i logger-chroma
+```
+
+# 💻 Usage
+
+- See examples below
+
+## CommonJS
+```javascript
+const loggerChroma = require('logger-chroma');
+
+// --| Same code as below in ESM and TypeScript
+```
+
+## ESM or TypeScript
+```javascript
+import loggerChroma from 'logger-chroma';
+
+// --| Server start
+loggerChroma.info("Server starting on port", 3000, "🚀");
+
+// --| Environment info
+loggerChroma.debug({ env: process.env.NODE_ENV || "development", version: "1.0.0" }, "💡", "Current environment");
+
+// --| Full HTTP request handling example
+loggerChroma.group("HTTP GET /users", () => {
+    loggerChroma.info("Request received", "📥");
+
+    // --| Authentication
+    loggerChroma.group("Auth check", () => {
+        const user = { id: 1, role: "admin", permissions: ["read", "write"] };
+        loggerChroma.debug(user, "🕵️", "User payload");
+
+        loggerChroma.group("Token validation", () => {
+            const token = { valid: true, expires: "2026-03-05T18:00:00Z" };
+            loggerChroma.debug(token, "🔑", "Token info");
+            loggerChroma.info("Token is valid", "✅");
+        });
+
+        loggerChroma.info("Authentication passed", "✅");
+    });
+
+    // --| Database query
+    loggerChroma.group("DB query", () => {
+        const users = [
+            { id: 1, name: "Alice", active: true },
+            { id: 2, name: "Bob", active: false },
+            { id: 3, name: "Charlie", active: true },
+        ];
+        loggerChroma.debug(users, "🗄️", "Fetched users");
+
+        loggerChroma.group("Filter active users", () => {
+            const activeUsers = users.filter(u => u.active);
+            loggerChroma.info(activeUsers, "🌟", "Active users list");
+        });
+    });
+
+    loggerChroma.info("Request completed", "🎯");
+});
+
+// --| Another route example
+loggerChroma.group("HTTP POST /orders", () => {
+    loggerChroma.info("Request received", "📥");
+
+    loggerChroma.group("Auth check", () => {
+        const user = { id: 2, role: "customer" };
+        loggerChroma.debug(user, "🕵️", "User payload");
+        loggerChroma.info("Authentication passed", "✅");
+    });
+
+    loggerChroma.group("DB insert order", () => {
+        const order = { id: 101, items: ["apple", "banana"], total: 12.5 };
+        loggerChroma.debug(order, "🛒", "Order object");
+
+        loggerChroma.group("Send notification", () => {
+            const notification = { to: "user@example.com", status: "sent" };
+            loggerChroma.info(notification, "📧", "Notification sent");
+        });
+    });
+
+    loggerChroma.info("Order processed successfully", "🎯");
+});
+
+// --| Error example
+try {
+    throw new Error("Something went horribly wrong!");
+} catch (err) {
+    loggerChroma.error(err, "🦄", "Critical error during request handling");
+}
+
+// --| Final server ready message
+loggerChroma.info("Server ready to accept requests", "✨");
+```

package/index.cjs

@@ -0,0 +1,19 @@
+/**
+ *  logger-chroma - 🦄 A colorful, developer-friendly Node.js logger with timestamps, emojis, pretty-printed objects, and grouped logs for clear, readable output.
+ *  @version: v1.0.0
+ *  @link: https://github.com/tutyamxx/logger-chroma
+ *  @license: MIT
+ **/
+
+
+// --| CommonJS wrapper for loggerChroma
+const esmLogger = require('./index.js');
+
+// --| Export default for require('logger-chroma')
+const loggerChroma = esmLogger.default ?? esmLogger;
+
+module.exports = loggerChroma;
+
+// --| Named and default properties for better interop
+module.exports.loggerChroma = loggerChroma;
+module.exports.default = loggerChroma;

package/index.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Configuration options for LoggerChroma.
+ */
+export interface LoggerConfig {
+    /**
+     * Show timestamps in the log output.
+     * @default true
+     * Note: timestamps are always enabled in the current version.
+     */
+    timestampEnabled?: boolean;
+
+    /**
+     * Number of spaces used for indenting grouped logs.
+     * @default 2
+     */
+    groupIndentSize?: number;
+
+    /**
+     * Custom color and label configuration per log level.
+     * Key is the log level name (`info`, `warn`, `error`, `debug`, etc.).
+     */
+    levelColors?: Record<string, LevelConfig>;
+}
+
+/**
+ * Configuration for a single log level.
+ */
+export interface LevelConfig {
+    /**
+     * Function to colorize the log text. Defaults to identity function.
+     */
+    color?: (text: string) => string;
+
+    /**
+     * Label displayed in square brackets in the log prefix.
+     */
+    label: string;
+}
+
+/**
+ * Type definition for a single logging function.
+ *
+ * Accepts any number of arguments of any type: strings, numbers, objects, arrays, or emojis.
+ */
+export type LogFunction = (...args: any[]) => void;
+
+/**
+ * The LoggerChroma interface.
+ */
+export interface LoggerChroma {
+    /**
+     * Logs an info-level message.
+     */
+    info: LogFunction;
+
+    /**
+     * Logs a warning-level message.
+     */
+    warn: LogFunction;
+
+    /**
+     * Logs an error-level message.
+     */
+    error: LogFunction;
+
+    /**
+     * Logs a debug-level message.
+     */
+    debug: LogFunction;
+
+    /**
+     * Creates a grouped log section.
+     *
+     * Inner log lines are automatically prefixed with `| ` and indented according to `config.groupIndentSize`.
+     * Nested groups are fully supported; each level increases indentation.
+     *
+     * @param title - The title of the log group.
+     * @param callback - Function that contains logs to be grouped.
+     */
+    group: (title: string, callback?: () => void) => void;
+
+    /**
+     * Current logger configuration.
+     */
+    config: LoggerConfig;
+}
+
+declare const loggerChroma: LoggerChroma;
+export default loggerChroma;

package/index.js

@@ -0,0 +1,85 @@
+/**
+ *  logger-chroma - 🦄 A colorful, developer-friendly Node.js logger with timestamps, emojis, pretty-printed objects, and grouped logs for clear, readable output.
+ *  @version: v1.0.0
+ *  @link: https://github.com/tutyamxx/logger-chroma
+ *  @license: MIT
+ **/
+
+
+import util from 'util';
+import chalk from 'chalk';
+
+const logLevels = {
+    info: { color: chalk.green, label: 'INFO ' },
+    warn: { color: chalk.yellow, label: 'WARN ' },
+    error: { color: chalk.red, label: 'ERROR' },
+    debug: { color: chalk.blue, label: 'DEBUG' },
+};
+
+const defaultLoggerConfig = {
+    timestampEnabled: true,
+    groupIndentSize: 2,
+    levelColors: logLevels,
+};
+
+const getFormattedTimestamp = () => new Date().toISOString().replace('T', ' ').split('.')[0];
+const prettyPrintObject = (obj) => util.inspect(obj, { colors: true, depth: null });
+
+const generateLogPrefix = (level, customEmoji, config, depth) => {
+    const levelConfig = config.levelColors?.[level] ?? { color: (text) => text, label: level.toUpperCase() };
+    const timestampPart = config.timestampEnabled ? `[${getFormattedTimestamp()}] ` : '';
+
+    let indent = '';
+    for (let i = 0; i < depth; i++) {
+        indent += '│ ';
+    }
+
+    const emojiPart = customEmoji ? `${customEmoji} ` : '   ';
+
+    return `${timestampPart}${indent}${emojiPart}${levelConfig.color(`[${levelConfig.label}]`)}`;
+};
+
+const createLoggerFunction = (level) => (message, customEmoji, ...additionalArgs) => {
+    const config = createLoggerFunction.config ?? defaultLoggerConfig;
+    const depth = createLoggerFunction.currentDepth ?? 0;
+    const prefix = generateLogPrefix(level, customEmoji, config, depth);
+
+    const formattedMessage = [message, ...additionalArgs]
+        ?.map(arg => typeof arg === 'object' ? prettyPrintObject(arg) : arg)
+        ?.join(' ')
+        ?.split('\n')
+        ?.map(line => `${prefix} ${line}`)
+        ?.join('\n');
+
+    console.log(formattedMessage);
+};
+
+const createLogGroup = (groupTitle, groupCallback) => {
+    const config = createLoggerFunction.config ?? defaultLoggerConfig;
+    const depth = createLoggerFunction.currentDepth ?? 0;
+    const timestamp = config.timestampEnabled ? `[${getFormattedTimestamp()}] ` : '';
+
+    let parentPipes = '';
+    for (let i = 0; i < depth; i++) {
+        parentPipes += '│ ';
+    }
+
+    console.log(`${timestamp}${parentPipes}┌─ ${groupTitle}`);
+
+    createLoggerFunction.currentDepth = depth + 1;
+
+    if (typeof groupCallback === 'function') {
+        groupCallback();
+    }
+    createLoggerFunction.currentDepth = depth;
+
+    console.log(`${timestamp}${parentPipes}└─ End ${groupTitle}`);
+};
+
+const loggerChroma = {};
+Object.keys(logLevels).forEach(level => loggerChroma[level] = createLoggerFunction(level));
+
+loggerChroma.group = createLogGroup;
+loggerChroma.config = defaultLoggerConfig;
+
+export default loggerChroma;

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "logger-chroma",
+  "version": "1.0.0",
+  "description": "🦄 A colorful, developer-friendly Node.js logger with timestamps, emojis, pretty-printed objects, and grouped logs for clear, readable output.",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "require": "./index.cjs",
+      "types": "./index.d.ts"
+    }
+  },
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tutyamxx/logger-chroma.git"
+  },
+  "keywords": [
+    "logger",
+    "logging",
+    "colorful",
+    "pretty",
+    "emoji",
+    "nodejs",
+    "debug",
+    "grouped-logs",
+    "structured-logs",
+    "console",
+    "dev-tools",
+    "readable-logs",
+    "cli",
+    "developer-friendly",
+    "timed-logs"
+  ],
+  "author": "tuty",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/tutyamxx/logger-chroma/issues"
+  },
+  "homepage": "https://github.com/tutyamxx/logger-chroma#readme",
+  "dependencies": {
+    "chalk": "^5.6.2"
+  },
+  "devDependencies": {
+    "jest": "^30.2.0"
+  }
+}

package/test/index.test.js

@@ -0,0 +1,115 @@
+import loggerChroma from '../index.js';
+import { jest } from '@jest/globals';
+
+const stripAnsi = (str) => str.replace(/\u001b\[[0-9;]*m/g, '');
+
+describe('Logger Chroma Unit Tests', () => {
+    let logSpy;
+
+    beforeEach(() => {
+        logSpy = jest.spyOn(console, 'log').mockImplementation(() => {});
+
+        const infoFn = loggerChroma.info;
+        if (infoFn) {
+            Object.getPrototypeOf(infoFn).constructor.currentDepth = 0;
+        }
+    });
+
+    afterEach(() => logSpy.mockRestore());
+
+    describe('Basic Logging', () => {
+        test('Should log a simple info message with the correct label', () => {
+            loggerChroma.info('Hello World');
+            const output = stripAnsi(logSpy.mock.calls[0][0]);
+
+            expect(output).toContain('[INFO ]');
+            expect(output).toContain('Hello World');
+        });
+
+        test('Should include custom emojis and maintain alignment', () => {
+            loggerChroma.info('Message A', '🚀');
+            loggerChroma.info('Message B', '🔥');
+
+            const outA = stripAnsi(logSpy.mock.calls[0][0]);
+            const outB = stripAnsi(logSpy.mock.calls[1][0]);
+
+            expect(outA.indexOf('[INFO ]')).toBe(outB.indexOf('[INFO ]'));
+        });
+    });
+
+    describe('Grouping & Hierarchy', () => {
+        test('Should render group brackets and nested pipes correctly', () => {
+            loggerChroma.group('My Group', () => {
+                loggerChroma.info('Inside Log');
+            });
+
+            const header = stripAnsi(logSpy.mock.calls[0][0]);
+            const body = stripAnsi(logSpy.mock.calls[1][0]);
+            const footer = stripAnsi(logSpy.mock.calls[2][0]);
+
+            expect(header).toContain('┌─ My Group');
+            expect(body).toContain('│');
+            expect(body).toContain('Inside Log');
+            expect(footer).toContain('└─ End My Group');
+
+            expect(header.indexOf('┌')).toBe(body.indexOf('│'));
+        });
+
+        test('Should support deep nesting with multiple pipes', () => {
+            loggerChroma.group('L1', () => {
+                loggerChroma.group('L2', () => {
+                    loggerChroma.info('Deep');
+                });
+            });
+
+            const deepLog = stripAnsi(logSpy.mock.calls[2][0]);
+            const pipeCount = (deepLog.match(/│/g) || []).length;
+
+            expect(pipeCount).toBe(2);
+            expect(deepLog).toContain('Deep');
+        });
+    });
+
+    describe('Data Formatting', () => {
+        test('Should pretty print objects using util.inspect', () => {
+            const data = { id: 123, status: 'ok' };
+            loggerChroma.info('Data:', null, data);
+
+            const output = stripAnsi(logSpy.mock.calls[0][0]);
+            expect(output).toContain('id: 123');
+            expect(output).toContain("status: 'ok'");
+        });
+
+        test('Should handle multi-line strings by adding pipes to every line', () => {
+            loggerChroma.group('MultiLine', () => {
+                loggerChroma.info('Line 1\nLine 2');
+            });
+
+            const output = stripAnsi(logSpy.mock.calls[1][0]);
+            const lines = output.split('\n');
+
+            expect(lines[0]).toContain('│');
+            expect(lines[0]).toContain('Line 1');
+            expect(lines[1]).toContain('│');
+            expect(lines[1]).toContain('Line 2');
+        });
+    });
+
+    describe('Edge Cases', () => {
+        test('Should not throw if groupCallback is not a function', () => {
+            expect(() => loggerChroma.group('Empty Group', null)).not.toThrow();
+            expect(logSpy).toHaveBeenCalledTimes(2);
+        });
+
+        test('Should respect timestampEnabled being disabled', () => {
+            const original = loggerChroma.config.timestampEnabled;
+            loggerChroma.config.timestampEnabled = false;
+
+            loggerChroma.info('No timestamp');
+            const output = stripAnsi(logSpy.mock.calls[0][0]);
+
+            expect(output).not.toMatch(/^\[\d{4}-\d{2}-\d{2}/);
+            loggerChroma.config.timestampEnabled = original;
+        });
+    });
+});