@rickferrdev/bea-logger

v1.0.0

Published

3 months ago

Bea Logger is a Node.js logging library that provides colorful and highly customizable log outputs.

0High
0Medium
0Low

rickferrdev

Bea Logger 🌸

Introduction

Bea Logger is a Node.js logging library that provides colorful and highly customizable log outputs.
Developed with TypeScript, it offers strong typing and an intuitive API for event logging in applications.

Development Note: This project was created primarily for educational and study purposes, but it's publicly available on npm for community use.
Portuguese Documentation: For Brazilian Portuguese documentation, see docs/README.pt-BR.md.

Features

Colored outputs with ANSI color support
Highly customizable — colors, formats, and styles
Multiple log levels (Error, Success, Info, Trace, Debug, Fatal)
Optional timestamps with ISO formatting
Complete TypeScript typings
Customizable output streams
Simple and intuitive API

Installation

npm install bea-logger

Quick Start

Import and Initialization

import Logger from 'bea-logger';

// Logger with default configuration
const logger = new Logger();

// Usage examples
logger.info('Informational message');
logger.success('Operation completed successfully');
logger.error('Execution error');
logger.debug('Debug information');
logger.trace('Detailed tracing');
logger.fatal('Critical unrecoverable error');

Expected Output

[INFO] (2023-10-05T14:30:00.000Z) Informational message
[SUCCESS] (2023-10-05T14:30:00.001Z) Operation completed successfully
[ERROR] (2023-10-05T14:30:00.002Z) Execution error
[DEBUG] (2023-10-05T14:30:00.003Z) Debug information
[TRACE] (2023-10-05T14:30:00.004Z) Detailed tracing
[FATAL] (2023-10-05T14:30:00.005Z) Critical unrecoverable error

Configuration

Configuration Options

const config = {
  colors: true,      // Enable/disable colors
  level: true,       // Show/hide log level
  timestamp: true,   // Enable/disable timestamp
  custom: 'CUSTOM'   // Custom text for level
};

const logger = new Logger(config);

Custom Configuration Example

// Logger without colors and timestamp
const simpleLogger = new Logger({
  colors: false,
  timestamp: false
});

simpleLogger.info('Simplified log'); // Output: [INFO] Simplified log

Log Methods

| Method | Description | Display Level | Default Color | |-------------|------------------|----------------|---------------------------| | error() | Error log | ERROR | Bright red | | success() | Success log | SUCCESS | Bright green | | info() | Informational log | INFO | Bright blue | | trace() | Trace log | TRACE | Cyan | | debug() | Debug log | DEBUG | Magenta | | fatal() | Fatal log | FATAL | Black with red background |

Customization

Available Colors

Text Colors (Foreground)

| Color | Description | Bright Variant | |--------|--------------|----------------| | black | Black | blackBright | | red | Red | redBright | | green | Green | greenBright | | yellow | Yellow | yellowBright | | blue | Blue | blueBright | | magenta | Magenta | magentaBright | | cyan | Cyan | cyanBright | | white | White | whiteBright | | gray / grey | Gray | - |

Background Colors

| Color | Description | Bright Variant | | --------------- | ------------------ | --------------- | | bgBlack | Black background | bgBlackBright | | bgRed | Red background | bgRedBright | | bgGreen | Green background | bgGreenBright | | bgYellow | Yellow background | bgYellowBright | | bgBlue | Blue background | bgBlueBright | | bgMagenta | Magenta background | bgMagentaBright | | bgCyan | Cyan background | bgCyanBright | | bgWhite | White background | bgWhiteBright | | bgGray / bgGrey | Gray background | - |

Text Modifiers

| Modifier | Description | |-----------|--------------| | bold | Bold text | | dim | Reduced brightness text | | italic | Italic text | | underline | Underlined text | | blink | Blinking text | | inverse | Inverted text and background colors | | hidden | Invisible text | | strikethrough | Strikethrough text | | doubleunderline | Double underlined text | | framed | Framed text | | overlined | Overlined text | | none | No modification |

Defining Custom Styles

import { defaultStylish } from 'bea-logger';

const customStylish = {
  levels: {
    ...defaultStylish.levels,
    Info: {
      name: "INFORMATION",
      level: {
        color: "yellowBright",
        background: "bgBlue",
        effect: "bold"
      },
      timestamp: {
        color: "white",
        background: "none",
        effect: "italic"
      },
      message: {
        color: "cyan",
        background: "none",
        effect: "none"
      }
    }
  }
};

const customLogger = new Logger({}, customStylish);

Output Customization

File Output

import { createWriteStream } from 'fs';

// Logger that writes to file
const fileLogger = new Logger(
  { colors: false }, // No colors for file
  defaultStylish,
  createWriteStream('app.log')
);

Multiple Outputs

// Logger for console with colors
const consoleLogger = new Logger();

// Logger for file without colors
const fileLogger = new Logger(
  { colors: false, timestamp: true },
  defaultStylish,
  createWriteStream('logs.txt')
);

// Using both
function logEverywhere(level: string, message: string) {
  consoleLogger[level](message);
  fileLogger[level](message);
}

API Reference

Constructor

new Logger(config?: Config, stylish?: Main, output?: stream.Writable)

TypeScript Types

| Type | Description | Properties | | ---------- | -------------------- | -------------------------------- | | Config | Logger configuration | colors, custom, level, timestamp | | Style | Style for components | color, background, effect | | Foreground | Text colors | See table above | | Background | Background colors | See table above | | Modifiers | Text modifiers | See table above |

Integration Examples

Express.js

import express from 'express';
import Logger from 'bea-logger';

const app = express();
const logger = new Logger();

app.use((req, res, next) => {
  logger.info(`${req.method} ${req.url}`);
  next();
});

app.listen(3000, () => {
  logger.success('Server started on port 3000');
});

Node.js Application

import Logger from 'bea-logger';

const logger = new Logger();

function processData(data: any) {
  logger.info('Starting data processing');
  
  try {
    // Processing here
    logger.success('Data processed successfully');
  } catch (error) {
    logger.error('Processing error:', error.message);
  }
}

FAQ

Troubleshooting Table

| Problem | Possible Cause | Solution | |----------|----------------|-----------| | Colors not showing | Terminal doesn't support ANSI | Use colors: false or change terminal | | Incorrect timestamp | UTC timezone | Customize style to use local time | | Output not appearing | Stream blocked | Check permissions and stream state | | TypeScript errors | Incorrect import | Use import Logger from 'bea-logger' |

How to completely disable colors

const logger = new Logger({ colors: false });

Can I use in production?

Yes, the logger is stable for production use, but remember it was also developed for educational purposes.

License

This project is licensed under the MIT License.