@node-cli/logger

@node-cli/logger

A powerful, flexible console logger for Node.js command-line applications with rich formatting options and in-memory logging capabilities.

Installation

npm install --save-dev @node-cli/logger

Overview

@node-cli/logger provides two main classes:

• Logger: A versatile console logger with enhanced formatting, colors, and utility methods
• Spinner: An elegant terminal spinner for displaying progress, based on ora

Basic Usage

Logger

import { Logger } from "@node-cli/logger";

// Create a new logger instance
const log = new Logger();

// Basic logging methods
log.info("This is an informational message");
log.warn("This is a warning message");
log.error("This is an error message");
log.debug("This is a debug message");
log.log("This is a standard log message");

Spinner

import { Spinner } from "@node-cli/logger";

// Create a new spinner with initial text
const spinner = new Spinner("Processing files...");

// Start the spinner
spinner.start();

// Update the spinner text during a long-running process
spinner.text = "Analyzing data...";

// Complete the spinner with different statuses
spinner.stop("Process completed successfully!"); // Success (default)
// or
spinner.stop("Process failed!", Spinner.ERROR); // Error
// or
spinner.stop("Process needs attention", Spinner.WARNING); // Warning
// or
spinner.stop("Process information", Spinner.INFO); // Info

Advanced Logger Examples

Customizing Logger Output

// Initialize with options
const log = new Logger({
  boring: false, // Enable colors (default)
  silent: false, // Enable logging (default)
  prefix: "MyApp:", // Add a prefix to all logs
  timestamp: true, // Add timestamps to logs
  inMemory: false // Log to console (default)
});

// Log with different levels
log.info("Starting application...");
log.debug("Debug information");
log.warn("Warning: configuration file not found");
log.error("Error: failed to connect to database");

// Output:
// MyApp: [ Tue Mar 18 2025 10:30:00 AM ] Starting application...
// MyApp: [ Tue Mar 18 2025 10:30:01 AM ] Debug information
// MyApp: [ Tue Mar 18 2025 10:30:02 AM ] Warning: configuration file not found
// MyApp: [ Tue Mar 18 2025 10:30:03 AM ] Error: failed to connect to database

Dynamic Configuration

const log = new Logger();

// Change configuration at runtime
log.info("Normal colored output");

// Disable colors for test environments
log.boring = process.env.NODE_ENV === "test";
log.info("No colors in test environment");

// Add a prefix for specific sections
log.prefix = "[CONFIG]";
log.info("Loading configuration..."); // Output: [CONFIG] Loading configuration...

// Add timestamps for debugging
log.timestamp = true;
log.debug("Detailed timing information"); // Output: [CONFIG] [ Tue Mar 18 2025 10:30:00 AM ] Detailed timing information

// Silence logs temporarily
log.silent = true;
log.info("This won't be displayed");

// Re-enable logs
log.silent = false;
log.info("Logging resumed");

Printing Messages in a Box

// Simple box with default options
log.printBox("Important Message");
/*
┌─────────────────────┐
│                     │
│  Important Message  │
│                     │
└─────────────────────┘
*/

// Multiple messages in a box
log.printBox(["Welcome to MyApp v1.2.3", "Copyright © 2025"]);
/*
┌──────────────────────────┐
│                          │
│  Welcome to MyApp v1.2.3 │
│    Copyright © 2025      │
│                          │
└──────────────────────────┘
*/

// Customized box
log.printBox("WARNING: Disk space low", {
  borderColor: "red",
  padding: 2,
  textAlignment: "center",
  title: "System Alert",
  newLineAfter: true,
  newLineBefore: true
});
/*
┌─ System Alert ───────────────┐
│                              │
│                              │
│    WARNING: Disk space low   │
│                              │
│                              │
└──────────────────────────────┘
*/

Error Handling and Process Exit

// Display multiple errors and exit the process
const errors = [
  "Failed to connect to database",
  "Configuration file is invalid",
  "Required environment variables missing"
];

// Display errors and exit with code 1
log.printErrorsAndExit(errors, 1);

// Or just display errors without exiting
log.printErrorsAndExit(errors);

In-Memory Logging

// Create a logger that stores logs in memory instead of console
const memoryLogger = new Logger({ inMemory: true });

// Log messages that are stored in memory
memoryLogger.info("Starting process");
memoryLogger.warn("Resource usage high");
memoryLogger.error("Process failed");

// Retrieve all logs as a string
const logs = memoryLogger.getMemoryLogs();
console.log(logs);
// Output:
// Starting process
// Resource usage high
// Process failed

// Clear memory logs when no longer needed
memoryLogger.clearMemoryLogs();

// Toggle between console and memory logging
const log = new Logger();
log.info("This goes to console");

log.inMemory = true;
log.info("This goes to memory only");

// Get only the in-memory logs
const memLogs = log.getMemoryLogs(); // Contains only "This goes to memory only"

log.inMemory = false;
log.info("Back to console logging");

Advanced Spinner Examples

Spinner with Custom Options

// Create a spinner with custom options
const spinner = new Spinner({
  text: "Processing...",
  color: "blue",
  spinner: "dots" // Use the 'dots' spinner pattern
});

spinner.start();

Spinner in Async Functions

import { Spinner } from "@node-cli/logger";

async function deployApplication() {
  const spinner = new Spinner("Preparing deployment...");
  spinner.start();

  try {
    // Building phase
    spinner.text = "Building application...";
    await buildApp();

    // Testing phase
    spinner.text = "Running tests...";
    await runTests();

    // Deployment phase
    spinner.text = "Deploying to production...";
    await deploy();

    // Success
    spinner.stop("Deployment completed successfully!");
    return true;
  } catch (error) {
    // Handle failure
    spinner.stop(`Deployment failed: ${error.message}`, Spinner.ERROR);
    return false;
  }
}

Chaining Multiple Spinners

import { Spinner } from "@node-cli/logger";

async function processWorkflow() {
  // Step 1
  const step1 = new Spinner("Step 1: Data validation");
  step1.start();
  await validateData();
  step1.stop("Data validation complete", Spinner.SUCCESS);

  // Step 2
  const step2 = new Spinner("Step 2: Processing records");
  step2.start();
  await processRecords();
  step2.stop("Records processed", Spinner.SUCCESS);

  // Step 3
  const step3 = new Spinner("Step 3: Generating report");
  step3.start();
  await generateReport();
  step3.stop("Report generated", Spinner.SUCCESS);

  console.log("Workflow completed successfully!");
}

API Reference

Logger Class

Constructor Options

Option	Type	Default	Description
boring	boolean	false	Disable colors in output
silent	boolean	false	Disable all logging
prefix	string	""	Add a prefix to all log messages
timestamp	boolean	false	Add timestamps to all log messages
inMemory	boolean	false	Store logs in memory instead of console

Methods

Method	Arguments	Description
log	...args	Standard log output (white)
info	...args	Informational log output (blue)
debug	...args	Debug log output (grey)
warn	...args	Warning log output (yellow)
error	...args	Error log output (red)
printBox	messages: string | string[], options?: PrintBoxOptions	Display message(s) in a formatted box
printErrorsAndExit	errorMessages: string[], exitStatus?: number	Display error messages and optionally exit the process
getMemoryLogs	none	Get all logs stored in memory as a string
clearMemoryLogs	none	Clear all logs stored in memory

Properties (Setters)

Property	Type	Description
silent	boolean	Enable/disable logging
boring	boolean	Enable/disable colors
prefix	string	Set prefix for log messages
timestamp	boolean	Enable/disable timestamps
inMemory	boolean	Enable/disable in-memory logging

PrintBox Options

Option	Type	Default	Description
newLineAfter	boolean	true	Print a new line after the box
newLineBefore	boolean	true	Print a new line before the box
borderColor	string	"yellow"	Color of the box border
padding	number	1	Padding inside the box
textAlignment	string	"center"	Text alignment ("left", "center", "right")
title	string	undefined	Optional title for the box

Plus all options from Boxen.

Spinner Class

Constructor Options

Accepts all options from ora.

Option	Type	Description
text	string	Text to display after the spinner
color	string	Color of the spinner
spinner	string | object	Spinner pattern to use
...	...	All other ora options

Methods

Method	Arguments	Description
start	text?: string	Start the spinner with optional text
stop	text?: string, status?: string	Stop the spinner with optional text and status

Properties

Property	Type	Description
text	string	Set the spinner text

Status Constants

Constant	Value	Description
Spinner.SUCCESS	"success"	Success status (green checkmark)
Spinner.ERROR	"fail"	Error status (red X)
Spinner.WARNING	"warn"	Warning status (yellow exclamation)
Spinner.INFO	"info"	Info status (blue i)

Environment Compatibility

• Works with Node.js >=16
• ESM module format
• TypeScript definitions included

License

MIT Arno Versini