try fix for windows, change how logging works allows much more flexibility
All checks were successful
Code quality checks / biome (push) Successful in 9s

This commit is contained in:
creations 2025-06-11 18:24:48 -04:00
parent 15d4978ac5
commit f313a8a329
Signed by: creations
GPG key ID: 8F553AA4320FC711
6 changed files with 297 additions and 51 deletions

180
README.md
View file

@ -1,24 +1,18 @@
# @atums/echo
A minimal, flexible logger for Node with:
- Colored console output
- Daily `.jsonl` file logging
- Configurable output patterns and file naming
- Structured logs with caller metadata
- Fully typed config with environment/file/constructor override
---
A minimal, flexible logger for Node
## Features
- Console and file logging with level-based filtering
- Multiple arguments per log call with automatic formatting
- Colored output with ANSI formatting
- Daily rotated `.jsonl` files with custom naming patterns
- Supports runtime configuration merging
- Auto-formatted output using custom patterns
- Includes caller file, line, and column
- Pretty-prints structured objects if enabled
- Safe handling of circular references and complex objects
- Flushes open file streams on exit
- Uses Biome and EditorConfig for formatting and linting
@ -34,19 +28,74 @@ bun add @atums/echo
## Usage
### Basic Logging
```ts
import { echo } from "@atums/echo";
// Single arguments
echo.info("App started");
echo.debug({ state: "init", ok: true });
// Multiple arguments - all joined with spaces in console
echo.info("User login:", { userId: 123, ip: "192.168.1.1" });
echo.warn("Rate limit exceeded:", 429, { endpoint: "/api/users" });
echo.error("Database error:", error, { query: "SELECT * FROM users" });
```
### Error Handling
```ts
try {
throw new Error("Something failed");
} catch (err) {
// Single error
echo.error(err);
// Error with context
echo.error("Operation failed:", err, { userId: 123, operation: "login" });
// Multiple context items
echo.fatal("Critical error:", err, "System shutting down", { timestamp: Date.now() });
}
```
### Multiple Data Types
```ts
// Mix any data types
echo.info("Processing:", 42, true, { batch: "A1" }, ["item1", "item2"]);
echo.debug("State:", "active", { connections: 5 }, null, undefined);
echo.warn("Alert:", "High CPU usage:", 95.2, "%", { threshold: 80 });
```
### API Request Logging
```ts
// Custom tagged logs for HTTP requests
echo.custom("GET", "/api/users", { status: 200, duration: "15ms" });
echo.custom("POST", "/api/auth", { status: 401, error: "Invalid token" });
// Standard logs with request context
echo.info("API Request:", "GET /health", { status: 200, responseTime: "5ms" });
echo.error("API Error:", "POST /users", 500, { error: "Database timeout" });
```
---
## Log Levels
All log levels support multiple arguments:
```ts
echo.trace("Trace message:", data1, data2);
echo.debug("Debug info:", object, array, "string");
echo.info("Information:", value1, value2, value3);
echo.warn("Warning:", message, errorCode, context);
echo.error("Error occurred:", error, additionalData);
echo.fatal("Fatal error:", error, "system", "shutdown");
```
---
## Configuration
@ -159,10 +208,10 @@ These tokens are replaced in the log pattern:
| `{file-name}` | Source filename |
| `{line}` | Line number in source |
| `{column}` | Column number in source |
| `{data}` | Formatted log data (message/object) |
| `{data}` | Formatted log data |
| `{id}` | Unique short ID for the log |
| `{tag}` | Custom tag used in `echo.custom()` |
| `{context}` | Custom context in `echo.custom()` |
| `{context}` | Custom context in `echo.custom()` |
| `{color:*}` | ANSI color start (e.g. `{color:red}`) |
| `{color:levelColor}` | Dynamic color based on log level |
| `{color:tagColor}` | Color for custom tag |
@ -177,6 +226,8 @@ You can log arbitrary tagged messages with `echo.custom(tag, context, message)`:
```ts
echo.custom("GET", "/health", { status: 200 });
echo.custom("WEBHOOK", "payment_received", { amount: 99.99, userId: "abc123" });
echo.custom("CRON", "daily_backup", { files: 1420, duration: "2m 15s" });
```
The output format is controlled by:
@ -188,22 +239,39 @@ The output format is controlled by:
```
2025-05-24 16:22:00.123 [GET] (/health) { status: 200 }
2025-05-24 16:22:01.456 [WEBHOOK] (payment_received) { amount: 99.99, userId: "abc123" }
```
---
## Output Examples
### Console
### Console Output
**Single argument:**
```
2025-05-24 16:15:00.000 [INFO] (index.ts:3:6) Server started
```
### File (`logs/2025-05-24.jsonl`)
**Multiple arguments:**
```
2025-05-24 16:15:01.123 [ERROR] (index.ts:8:6) Database error: Error: Connection timeout {
query: 'SELECT * FROM users',
duration: '5s'
}
```
Each line is structured JSON:
**Mixed data types:**
```
2025-05-24 16:15:02.456 [WARN] (index.ts:12:6) Rate limit: 429 exceeded for /api/users {
ip: '192.168.1.1',
attempts: 15
}
```
### File Output (`logs/2025-05-24.jsonl`)
**Single argument JSON:**
```json
{
"timestamp": 1748115300000,
@ -212,30 +280,96 @@ Each line is structured JSON:
"file": "index.ts",
"line": "3",
"column": "6",
"data": "Server started"
"data": ["Server started"]
}
```
If an error is logged:
**Multiple arguments JSON:**
```json
{
"timestamp": 1748115301000,
"timestamp": 1748115301123,
"level": "error",
"id": "qW3eR7tU",
"file": "index.ts",
"line": "10",
"column": "12",
"line": "8",
"column": "6",
"data": [
"Database error:",
{
"name": "Error",
"message": "Connection timeout",
"stack": "Error: Connection timeout\n at index.ts:8:6"
},
{
"query": "SELECT * FROM users",
"duration": "5s"
}
]
}
```
**Custom log JSON:**
```json
{
"timestamp": 1748115302456,
"level": "GET",
"id": "mN8oP2qR",
"file": "index.ts",
"line": "15",
"column": "6",
"data": {
"name": "Error",
"message": "Something failed",
"stack": "Error: Something failed\n at index.ts:10:12"
"context": "/health",
"data": { "status": 200 }
}
}
```
---
## Advanced Features
### Circular Reference Handling
The logger safely handles circular references without crashing:
```ts
const obj = { name: "test" };
obj.self = obj; // Creates circular reference
echo.info("Circular object:", obj); // Works safely
// Console: Shows <ref *1> { name: 'test', self: [Circular *1] }
// File: Stores { "name": "test", "self": "[Circular Reference]" }
```
### Error Object Serialization
Error objects are automatically converted to structured data:
```ts
const error = new Error("Something failed");
echo.error("Operation failed:", error, { userId: 123 });
// File output includes:
// {
// "name": "Error",
// "message": "Something failed",
// "stack": "Error: Something failed\n at ..."
// }
```
### Performance Considerations
The logger handles rapid logging efficiently:
```ts
for (let i = 0; i < 1000; i++) {
echo.debug("Processing item:", i, { batch: "A1", progress: i/1000 });
}
// All logs are processed without blocking
```
---
## Development
This project uses: