npm package: @rickferrdev/bea-logger
Description: Bea Logger is a Node.js logging library that provides colorful and highly customizable log outputs.
Author: Henr. Ferr
Latest version: 1.0.0

# Bea Logger 🌸

## Table of Contents

- [Introduction](#introduction)
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Log Methods](#log-methods)
- [Customization](#customization)
- [Output Customization](#output-customization)
- [API Reference](#api-reference)
- [Integration Examples](#integration-examples)
- [FAQ](#faq)
- [Troubleshooting](#troubleshooting)
- [Development](#development)
- [License](#license)
- [Links](#links)

---

## 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

```bash
npm install bea-logger
```

## Quick Start

### Import and Initialization

```js
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

```js
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

```js
// 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

```js
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

```js
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

```ts
// 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
```ts
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

```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

```ts
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

```js
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.

## Links

- npm: https://www.npmjs.com/package/bea-logger
- GitHub: https://github.com/rickferrdev/bea-logger
- Portuguese Documentation: docs/README.pt-BR.md

---

> Note: Developed with an educational focus, but fully functional for production use.