181 lines
4.1 KiB
Markdown
181 lines
4.1 KiB
Markdown
# @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)
|