# @atums/echo

A minimal, flexible logger for Node with:

- Colored console output
- Daily `.jsonl` file logging
- Configurable output patterns
- Structured logs with caller metadata
- Fully typed config with environment/file/constructor override

---

## Features

- Console and file logging with level-based filtering
- Colored output with ANSI formatting
- Daily rotated `.jsonl` files
- Supports runtime configuration merging
- Auto-formatted output using custom patterns
- Includes caller file, line, and column
- Pretty-prints structured objects if enabled
- Flushes open file streams on exit
- Uses Biome and EditorConfig for formatting and linting

---

## Installation

```bash
bun add @atums/echo
```

---

## Usage

```ts
import { echo } from "@atums/echo";

echo.info("App started");
echo.debug({ state: "init", ok: true });

try {
	throw new Error("Something failed");
} catch (err) {
	echo.error(err);
}
```

---

## Configuration

Logger config can be defined in three ways:

1. JSON file (e.g. `logger.json`)
2. Environment variables
3. Constructor override

Priority (highest to lowest):

```
constructor > environment > logger.json > defaults
```

---

### logger.json example

```json
{
  "directory": "logs",
  "level": "debug",
  "console": true,
  "consoleColor": true,
  "rotate": true,
  "maxFiles": 3,
  "prettyPrint": true,
  "pattern": "{color:gray}{timestamp}{reset} {color:levelColor}[{level-name}]{reset} ({file-name}:{line}:{column}) {data}"
}
```

---

### Supported Environment Variables

| Variable              | Description                              |
|------------------------|------------------------------------------|
| `LOG_LEVEL`            | Log level (`debug`, `info`, etc.)        |
| `LOG_DIRECTORY`        | Log directory path (default: `logs`)     |
| `LOG_DISABLE_FILE`     | Disable file output (`true` or `false`)  |
| `LOG_ROTATE`           | Enable daily rotation                    |
| `LOG_MAX_FILES`        | Max rotated files to keep                |
| `LOG_CONSOLE`          | Enable console output                    |
| `LOG_CONSOLE_COLOR`    | Enable ANSI color in console output      |
| `LOG_DATE_FORMAT`      | Date format for display timestamp        |
| `LOG_TIMEZONE`         | Timezone (`local` or IANA string)        |
| `LOG_SILENT`           | Completely disable output                |
| `LOG_PATTERN`          | Custom log format for console            |
| `LOG_PRETTY_PRINT`     | Pretty-print objects in console output   |

---

## Pattern Tokens

These tokens are replaced in the log pattern:

| Token         | Description                             |
|---------------|-----------------------------------------|
| `{timestamp}` | Formatted display timestamp             |
| `{level-name}`| Uppercase log level (e.g. DEBUG)        |
| `{level}`     | Numeric log level                       |
| `{file-name}` | Source filename                         |
| `{line}`      | Line number in source                   |
| `{column}`    | Column number in source                 |
| `{data}`      | Formatted log data (message/object)     |
| `{id}`        | Unique short ID for the log             |
| `{color:*}`   | ANSI color start (e.g. `{color:red}`)   |
| `{reset}`     | Resets console color                    |

---

## Output Examples

### Console (with colors)

```
2025-05-24 16:15:00.000 [INFO] (index.ts:3:6) Server started
```

### File (`logs/2025-05-24.jsonl`)

Each line is structured JSON:

```json
{
  "timestamp": 1748115300000,
  "level": "info",
  "id": "aB4cD9xZ",
  "file": "index.ts",
  "line": "3",
  "column": "6",
  "data": "Server started"
}
```

If an error is logged:

```json
{
  "timestamp": 1748115301000,
  "level": "error",
  "id": "qW3eR7tU",
  "file": "index.ts",
  "line": "10",
  "column": "12",
  "data": {
    "name": "Error",
    "message": "Something failed",
    "stack": "Error: Something failed\n  at index.ts:10:12"
  }
}
```

---

## Development

This project uses:

- TypeScript
- Bun runtime
- Biome for formatting/linting
- JSONL for structured file output
- `date-fns-tz` for timezone support

---

## License

BSD 3-Clause [License](License)