🌈 SpectraLog

Lightweight, colorful, and expressive terminal logging

SpectraLog transforms boring console logs into vibrant, stylish output that improves readability and makes your application logs more expressive. With customizable log levels, smooth printing animation, and rich text formatting, SpectraLog brings your terminal to life.

📋 Table of Contents

• Installation
• Quick Start
• Style and Color Syntax
• Log Levels
• Log Method Parameters
• HTTP Status Code Support
• Configuration
• Queue Management
• Standby Indicator
• Complete Example
• License

📦 Installation

npm install spectra-log

You must use ESM to use this package.

✨ Quick Start

import log from "spectra-log";
// if you're using CJS, then use:
// const log = require("spectra-log");

// Simple log message
log("This is a standard log message");

// Styled log message with inline formatting
log("This is a {{ bold : blue : styled }} message");

// Error message with color
log("Error occurred: {{ red : Something went wrong! }}", 500, "ERROR");

Whitespace between colons is optional. For example: {{bold:green:text}} or {{ bold : green : text }} are both valid.

📝 Style and Color Syntax

SpectraLog provides a powerful and intuitive syntax for styling your logs:

log("Text {{ style : color : content }} more text");

Style Options

• bold - Make text bold
• italic - Make text italic
• underline - Add underline to text

Color Options

• red, brightRed, orange, yellow, brightYellow, green, brightGreen, lime,
• blue, brightBlue, cyan, brightCyan, muteCyan, teal,
• magenta, pink, purple, violet,
• brown, gold, maroon,
• white, silver, gray, dim

Examples

// Highlight important information
log("User {{ bold : green : successfully }} logged in");

// Emphasize warnings
log("Please note: {{ italic : yellow : This feature is experimental }}");

// Mark important segments
log("Critical config: {{ underline : cyan : database.json }}");

// Multiple styles in one message
log(
  "Status: {{ bold : green : ONLINE }} - {{ italic : yellow : 3 pending tasks }}"
);

🔄 Log Levels

SpectraLog uses familiar log levels with appropriate colors:

// Set minimum display level
log.setDebugLevel("DEBUG"); // Only shows DEBUG and higher priority

// Full log with level
log("Server started on port 3000", 600, "INFO");
log("Connection failed", 500, "ERROR");

📤 Log Method Parameters

log(message, type, level, options);

HTTP Status Code Support

SpectraLog includes built-in support for HTTP status codes with appropriate colors and labels for each code. This feature makes it easy to log HTTP-related events with consistent formatting.

Usage

When logging, you can pass an HTTP status code as the second parameter:

import log from "spectra-log";

// Log with HTTP status codes
log("User authentication successful", 200); // Green "OK" tag
log("Redirect to login page", 302); // Yellow "FOUND" tag
log("Resource not found", 404, "ERROR"); // Red "NOT-FOUND" tag
log("Internal server error", 500, "FATAL"); // Red "SERVER-ERROR" tag

Supported HTTP Status Codes

1xx Informational

2xx Success

3xx Redirection

4xx Client Errors

5xx Server Errors

Custom Codes

Default

If an unrecognized status code is provided, the logger will use: | Label | Color | Description | |---------|-------|--------------------------| | UNKNOWN | Dim | Unknown status code |

🛠️ Configuration

Set Debug Level

Control which log levels are displayed:

// Only show ERROR and FATAL logs
log.setDebugLevel("ERROR");

// Silently update level (no confirmation message)
log.setDebugLevel("MUTE", { silent: true });

Smooth Printing

Enable typewriter-like animation for logs:

// Enable smooth printing animation
log.setSmoothPrint(true);

// Set animation speed (ms per character)
log.setPrintSpeed(10);

Urgent and Force Options

You can override the default log queue behavior with urgent and force options.

• urgent: Marks the log as urgent, which means it will bypass the default queue and print immediately. However, it will still be subject to the current debug level. If the debug level is set to a level that doesn't show the log, the urgent log may still be suppressed. also When smooth printing is enabled, the effect of an urgent log is even more pronounced, as it will immediately be displayed without the animation delay.

• force: Forces the log to be displayed regardless of the debug level. Even if the debug level is set to MUTE or a level that would normally suppress the log, it will always be printed.

// Urgent log that jumps the queue
log("This prints immediately!", 500, "ERROR", { urgent: true });

// Force log that bypasses queue
log("This is always displayed!", 200, "INFO", { force: true });

Example Usage of urgent and force

import log from "spectra-log";

// Set debug level to ERROR (only ERROR and FATAL logs will show)
log.setDebugLevel("ERROR");

// Urgent log (will print immediately but may still be suppressed by debug level)
log("This is an urgent log!", 200, "INFO", { urgent: true });

// Force log (will always print, even if debug level is set to MUTE)
log("This log will always print!", 200, "INFO", { force: true });

// Normal log (will be suppressed because the level is set to ERROR)
log("This is a normal log", 200, "INFO");

The urgent and force options give you more flexibility in controlling log behavior while respecting the debug level configurations.

🌙 Standby Mode

Enable a standby indicator that remains active until the program is manually terminated.

log.setDisplayStandBy(true);

This will show a live standby line in the terminal until the process is aborted.

🔁 Queue Management

Logs are processed in order by default, unless marked urgent:

// Normal queued log
log("This will print in queue order", 200, "INFO");

// Urgent log that jumps the queue
log("This prints immediately!", 500, "ERROR", { urgent: true });

🌙 Standby Indicator

When idle, SpectraLog displays a standby indicator that updates every second:

[ STBY   | -            | 21:00:00 ]

🧩 Complete Example

import log from "spectra-log";

// Configure logger
log.setDebugLevel("DEBUG");
log.setSmoothPrint(true);
log.setPrintSpeed(5);

// Information with styled content
log("Welcome to {{ bold : green : SpectraLog }}!");

// Error with status code
log("{{ bold : red : Not Found }}", 404, "ERROR");

// Debug message with custom type
log("This is a {{ italic : cyan : debug }} message", 103, "DEBUG");

// Urgent fatal error that bypasses queue
log("🚨 {{ bold : magenta : Critical system failure }}", 500, "FATAL", {
  urgent: true,
});

📜 License

MIT License
2025 Copyright © acorn497