@reliverse/relinka 1.6.1 → 2.2.7

package/README.md

@@ -1,407 +1,260 @@
-# Relinka: Logging that Actually Feels Good
+# @reliverse/relinka
 
-[sponsor](https://github.com/sponsors/blefnk) — [discord](https://discord.gg/Pb8uKbwpsJ) — [repo](https://github.com/reliverse/relinka) — [npm](https://npmjs.com/@reliverse/relinka)
+A modern, lightweight logging library for TypeScript/JavaScript with both synchronous and asynchronous logging capabilities. Perfect for CLI tools, build systems, and concurrent applications.
 
-> **@reliverse/relinka** is a modern logging library that actually *feels* right. It's not just pretty output — it's a system: smart formatting, file-safe logging, runtime config support, and a `fatal` mode built for developers who care about correctness. Whether you're building CLI tools, SDKs, or full-stack apps — Relinka helps you log with intention.
+## Features
 
-## Why Relinka
+- 🚀 **Dual Mode**: Synchronous (`logger`) and asynchronous (`relinka`) logging
+- 🎨 **Colored Output**: Beautiful, color-coded log levels using [@reliverse/relico](https://github.com/reliverse/relico)
+- 📦 **Zero Dependencies**: Only depends on `@reliverse/relico` for colors
+- 🔒 **Thread-Safe**: Async logger uses write queuing to prevent interleaving
+- 🎯 **Type-Safe**: Full TypeScript support with proper type inference
+- 📝 **Multiple Log Levels**: `log`, `error`, `fatal`, `warn`, `info`, `success`, `debug`, `box`, `raw`
+- 🎭 **Callable Interface**: Use as a function or with method calls
+- ⚡ **Non-Blocking**: Async logger queues writes but returns immediately
 
-- 🧙 **Drop-in replacement** for `node:console`, `consola`, or your internal logger
-- 💬 **12 log levels**: `info`, `warn`, `success`, `error`, `verbose`, `fatal`, `log`, `step`, `box`, `message`, `internal`, `null`
-- 🎨 **Beautiful terminal output** with automatic color handling and Unicode support
-- 📁 **Smart file logging** with buffering, rotation, cleanup, and date-based naming
-- 🧠 **Structured formatting** for objects, errors, and stack traces
-- ⚙️ **Runtime configuration** via `.config/relinka.ts` or `relinka.config.ts`
-- 🚨 **Fatal logging** that halts execution and triggers debugger in development
-- 🧩 **Dual syntax support** - both function calls (`relinka("info", "Hello world")`) and method chaining (`relinka.info("Hello world")`)
-- ⚡ **Performance optimized** with intelligent buffering and async support
-- 🛎️ **Dler-ready** - if you use `dler build`, all `internal`-level logs will be removed from the built dist
-
-## Quick Start
-
-### 1. Install
+## Installation
 
 ```bash
 bun add @reliverse/relinka
+# or
+npm install @reliverse/relinka
+# or
+pnpm add @reliverse/relinka
 ```
 
-### 2. Basic Usage
+## Quick Start
 
-```ts
-import { relinka, relinkaConfig, relinkaShutdown } from "@reliverse/relinka";
+```typescript
+import { logger, relinka } from "@reliverse/relinka";
 
-async function main() {
-  // Load configuration (required at start)
-  await relinkaConfig();
-  
-  // Log with different levels
-  relinka("info", "Application started");
-  relinka("success", "Configuration loaded successfully");
-  relinka("warn", "This is a warning");
-  relinka("error", "Something went wrong");
-  
-  // Use method syntax (also supported)
-  relinka.info("Another info message");
-  relinka.success("Another success message");
-  
-  // Clean shutdown (required at end)
-  await relinkaShutdown();
-}
+// Synchronous logging (blocks until write completes)
+logger.info("Application started");
+logger.success("Build completed successfully");
+logger.error("Failed to load configuration");
 
-main();
+// Asynchronous logging (queues writes, returns immediately)
+await relinka.info("Processing files...");
+await relinka.success("All files processed");
+await relinka.error("File processing failed");
 ```
 
-## Log Levels
-
-Relinka supports 12 different log levels, each with customizable symbols and colors:
-
-| Level | Symbol | Description |
-|-------|--------|-------------|
-| `info` | ◈ | General information |
-| `success` | ✓ | Success messages |
-| `warn` | ⚠ | Warnings |
-| `error` | ✖ | Non-fatal errors |
-| `fatal` | ‼ | Fatal errors + error throwing |
-| `verbose` | ✱ | Debug information |
-| `log` | │ | General logging |
-| `step` | → | Progress steps |
-| `box` | ■ | Boxed messages |
-| `message` | 🞠 | General messages |
-| `internal` | ⚙ | Internal system logs |
-| `null` | (none) | No symbol or spacing |
-
-## API Reference
-
-### Core Functions
-
-#### `relinka(level, message, ...args)`
-
-Main logging function with dual syntax support.
-
-```ts
-// Function syntax
-relinka("info", "Hello world");
-relinka("error", "Something broke", { error: "details" });
-
-// Method syntax
-relinka.info("Hello world");
-relinka.error("Something broke", { error: "details" });
+## When to Use Sync vs Async
+
+### Use `logger` (Synchronous) when:
+- ✅ Sequential logging (like CLI tools with ordered output)
+- ✅ Small, frequent console writes
+- ✅ Error reporting that needs to maintain order
+- ✅ When you need guaranteed write completion before continuing
+- ✅ CLI tools where output order is critical
+
+### Use `relinka` (Asynchronous) when:
+- ✅ Logging from multiple concurrent async operations
+- ✅ High-frequency logging where you don't want to block
+- ✅ Large log outputs that could slow down execution
+- ✅ Fire-and-forget logging (writes are queued and happen in background)
+- ✅ When order matters but you don't want to wait for each write
+
+**Note**: `relinka` queues writes in order but returns immediately without waiting for completion. This prevents blocking while maintaining write order.
+
+## API
+
+### Log Levels
+
+Both `logger` and `relinka` support the following log levels:
+
+| Level | Symbol | Color | Description |
+|-------|--------|-------|-------------|
+| `log` | `│  ` | White | General logging |
+| `error` | `✖  ` | Red | Error messages |
+| `fatal` | `☠  ` | Red | Fatal errors |
+| `warn` | `⚠  ` | Yellow | Warning messages |
+| `info` | `■  ` | Blue | Informational messages |
+| `success` | `✓  ` | Green | Success messages |
+| `debug` | `✱  ` | Gray | Debug messages |
+| `box` | - | White | Box-formatted messages |
+| `raw` | - | - | Raw output (no formatting) |
+
+### Usage Patterns
+
+#### Method Calls
+
+```typescript
+import { logger, relinka } from "@reliverse/relinka";
+
+// Synchronous
+logger.log("General message");
+logger.info("Information");
+logger.success("Operation succeeded");
+logger.warn("Warning message");
+logger.error("Error occurred");
+logger.fatal("Fatal error");
+logger.debug("Debug information");
+logger.box("Boxed message");
+logger.raw("Raw output without formatting");
+
+// Asynchronous (returns Promise<void>)
+await relinka.log("General message");
+await relinka.info("Information");
+await relinka.success("Operation succeeded");
+await relinka.warn("Warning message");
+await relinka.error("Error occurred");
+await relinka.fatal("Fatal error");
+await relinka.debug("Debug information");
+await relinka.box("Boxed message");
+await relinka.raw("Raw output without formatting");
 ```
 
-#### `relinkaAsync(level, message, ...args)`
-
-Async version that waits for configuration to load.
+#### Callable Function
 
-```ts
-await relinkaAsync("info", "Async message");
-await relinkaAsync("success", "Operation completed");
-```
+Both loggers can be called as functions with the log level as the first argument:
 
-#### `relinkaConfig(options?)`
+```typescript
+import { logger, relinka } from "@reliverse/relinka";
 
-Load configuration with optional fresh log file support.
+// Synchronous
+logger("info", "Application started");
+logger("success", "Build completed");
+logger("error", "Build failed");
 
-```ts
-// Basic config loading
-await relinkaConfig();
-
-// With fresh log file (clears existing log file)
-await relinkaConfig({ supportFreshLogFile: true });
+// Asynchronous
+await relinka("info", "Processing started");
+await relinka("success", "Processing completed");
+await relinka("error", "Processing failed");
 ```
 
-#### `relinkaShutdown()`
+#### Multiple Arguments
 
-Flush all buffers and clean up resources. **Always call this at the end of your program.**
+All log methods accept multiple arguments, which are automatically joined:
 
-```ts
-await relinkaShutdown();
-```
+```typescript
+logger.info("User", username, "logged in");
+// Output: ■  User john_doe logged in
 
-### Utility Functions
-
-#### `log`, `logger`
-
-Aliases for the main `relinka` function.
-
-```ts
-import { log, logger } from "@reliverse/relinka";
-
-log("info", "Using alias");
-logger.success("Another alias");
-```
-
-#### `message(msg, ...args)`
-
-Convenience function for general messages.
-
-```ts
-import { message } from "@reliverse/relinka";
-message("This is a general message");
+logger.error("Failed to connect to", host, "on port", port);
+// Output: ✖  Failed to connect to localhost on port 3000
 ```
 
-#### `step(msg, ...args)`
+## Examples
 
-Convenience function for progress steps.
+### CLI Tool (Synchronous)
 
-```ts
-import { step } from "@reliverse/relinka";
-step("Step 1: Initialize");
-step("Step 2: Load config");
-```
+```typescript
+import { logger } from "@reliverse/relinka";
 
-## Configuration
-
-Create a configuration file to customize Relinka's behavior:
-
-### File Locations (in order of priority)
-
-1. `relinka.config.ts` (project root) - **highest priority**
-2. `.config/relinka.ts` - **lower priority**
-
-### Configuration Example
-
-```ts
-import { defineConfig } from "@reliverse/relinka";
-
-export default defineConfig({
-  // Enable verbose logging
-  verbose: false,
-
-  // Timestamp configuration
-  timestamp: {
-    enabled: true,
-    format: "YYYY-MM-DD HH:mm:ss.SSS",
-  },
-
-  // File logging
-  saveLogsToFile: true,
-  logFile: {
-    outputPath: "logs/app.log",
-    nameWithDate: "append-before", // "disable" | "append-before" | "append-after"
-    freshLogFile: true, // Clear log file on each run
-  },
-
-  // Log rotation
-  dirs: {
-    maxLogFiles: 10, // Keep only the 10 most recent log files
-  },
-
-  // Performance tuning
-  bufferSize: 4096, // 4KB buffer before flushing
-  maxBufferAge: 5000, // 5 seconds max buffer age
-  cleanupInterval: 10000, // 10 seconds between cleanups
-
-  // Customize log levels
-  levels: {
-    success: {
-      symbol: "✓",
-      fallbackSymbol: "[OK]",
-      color: "greenBright",
-      spacing: 3,
-    },
-    info: {
-      symbol: "◈",
-      fallbackSymbol: "[i]",
-      color: "cyanBright",
-      spacing: 3,
-    },
-    // ... customize other levels
-  },
-});
+async function buildProject() {
+  logger.info("Starting build process...");
+  
+  try {
+    // Build steps
+    logger.success("Build completed successfully");
+  } catch (error) {
+    logger.error("Build failed:", error);
+    process.exit(1);
+  }
+}
 ```
 
-### Configuration Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `verbose` | `boolean` | `false` | Enable verbose logging |
-| `saveLogsToFile` | `boolean` | `false` | Save logs to file |
-| `disableColors` | `boolean` | `false` | Disable color output |
-| `timestamp.enabled` | `boolean` | `false` | Add timestamps to logs |
-| `timestamp.format` | `string` | `"YYYY-MM-DD HH:mm:ss.SSS"` | Timestamp format |
-| `logFile.outputPath` | `string` | `"logs.log"` | Log file path |
-| `logFile.nameWithDate` | `string` | `"disable"` | Date handling in filename |
-| `logFile.freshLogFile` | `boolean` | `true` | Clear log file on startup |
-| `dirs.maxLogFiles` | `number` | `0` | Maximum log files to keep |
-| `bufferSize` | `number` | `4096` | Buffer size in bytes |
-| `maxBufferAge` | `number` | `5000` | Max buffer age in ms |
-| `cleanupInterval` | `number` | `10000` | Cleanup interval in ms |
-
-## File Logging
-
-### File Naming Patterns
-
-- **Default**: `logs.log`
-- **With subdirectory**: `logs/app.log`
-- **With date prefix**: `2025-01-15-logs.log`
-- **With date suffix**: `logs-2025-01-15.log`
-- **Combined**: `logs/2025-01-15-app.log`
-
-### Automatic Cleanup
-
-When `maxLogFiles` is set, Relinka automatically:
-
-- Keeps only the N most recent log files
-- Deletes older files during cleanup
-- Runs cleanup periodically and on shutdown
-
-## Advanced Usage
+### Concurrent Operations (Asynchronous)
 
-### Fatal Logging
+```typescript
+import { relinka } from "@reliverse/relinka";
 
-Fatal logs throw errors and halt execution:
-
-```ts
-// This will throw an error and trigger debugger in development
-relinka("fatal", "Critical system failure");
-// or
-relinka.fatal("Critical system failure");
+async function processFiles(files: string[]) {
+  // All logs are queued and won't block execution
+  await Promise.all(
+    files.map(async (file) => {
+      await relinka.info(`Processing ${file}...`);
+      // Process file...
+      await relinka.success(`Completed ${file}`);
+    })
+  );
+  
+  // Writes happen in background, maintaining order
+  await relinka.info("All files processed");
+}
 ```
 
 ### Box Formatting
 
-Create visually appealing boxed messages:
-
-```ts
-relinka("box", "This message will be displayed in a box");
-relinka.box("This also works with method syntax");
-```
-
-### Async Context
-
-Use `relinkaAsync` when you need to ensure configuration is loaded:
-
-```ts
-await relinkaAsync("info", "This waits for config to load");
+```typescript
+import { logger } from "@reliverse/relinka";
+
+logger.box(`
+  Welcome to My Application
+  Version 1.0.0
+  Ready to serve requests
+`);
+
+// Output:
+// ┌──────────────────────────────┐
+// │  Welcome to My Application   │
+// │  Version 1.0.0                │
+// │  Ready to serve requests      │
+// └──────────────────────────────┘
 ```
 
-### Clear Terminal
-
-Clear the terminal output:
-
-```ts
-relinka("clear", "");
-// or
-relinka.clear();
+### Error Handling
+
+```typescript
+import { logger } from "@reliverse/relinka";
+
+try {
+  await riskyOperation();
+  logger.success("Operation completed");
+} catch (error) {
+  logger.error("Operation failed");
+  logger.fatal("Application cannot continue");
+  if (error instanceof Error) {
+    logger.raw(error.stack);
+  }
+  process.exit(1);
+}
 ```
 
-### Empty Lines
-
-Add blank lines to output:
+### Conditional Logging
 
-```ts
-relinka("info", "");
-```
+```typescript
+import { logger } from "@reliverse/relinka";
 
-## Best Practices
+const DEBUG = process.env.DEBUG === "true";
 
-### 1. Always Initialize and Shutdown
-
-```ts
-async function main() {
-  await relinkaConfig(); // At the start
-  
-  // Your application logic
-  relinka("info", "App running");
-  
-  await relinkaShutdown(); // At the end
+if (DEBUG) {
+  logger.debug("Debug mode enabled");
+  logger.debug("Configuration:", config);
 }
 ```
 
-### 2. Use Appropriate Log Levels
+## TypeScript Support
 
-```ts
-relinka("info", "User logged in"); // General info
-relinka("success", "Payment processed"); // Success events
-relinka("warn", "High memory usage"); // Warnings
-relinka("error", "Database connection failed"); // Recoverable errors
-relinka("fatal", "Critical system failure"); // Unrecoverable errors
-```
+Full TypeScript support with proper type inference:
 
-### 3. Leverage Verbose Logging
+```typescript
+import type { Logger, LoggerAsync } from "@reliverse/relinka";
+import { logger, relinka } from "@reliverse/relinka";
 
-```ts
-relinka("verbose", "Debug information"); // Only shown when verbose=true
-```
+// Type-safe log level
+type LogLevel = "log" | "error" | "fatal" | "warn" | "info" | "success" | "debug" | "box" | "raw";
 
-### 4. Structure Complex Data
+// Logger types
+const syncLogger: Logger = logger;
+const asyncLogger: LoggerAsync = relinka;
 
-```ts
-relinka("error", "API request failed", {
-  endpoint: "/api/users",
-  statusCode: 500,
-  error: error.message
-});
+// Function call with type safety
+logger("info", "Message"); // ✅ Valid
+relinka("info", "Message"); // ✅ Valid, returns Promise<void>
 ```
 
-## Performance Features
-
-- **Intelligent Buffering**: Logs are buffered and flushed efficiently
-- **Async File Operations**: Non-blocking file writes
-- **Memory Management**: Automatic cleanup of old log files
-- **Unicode Detection**: Automatic fallback for non-Unicode terminals
-
-## FAQ
-
-### Why does my terminal hang after logging?
-
-→ You forgot to call `await relinkaShutdown()` at the end of your program. This is required to flush buffers.
-
-### Why isn't my configuration loading?
-
-→ Make sure you call `await relinkaConfig()` at the start of your application.
-
-### Does `fatal` always throw?
-
-→ Yes, `fatal` logs always throw errors and halt execution. In development mode, they also trigger the debugger.
-
-### How do I disable colors?
-
-→ Set `disableColors: true` in your configuration or use `NO_COLOR=1` environment variable.
-
-### Can I use Relinka in both sync and async contexts?
-
-→ Yes! Use `relinka()` for sync operations and `relinkaAsync()` when you need to use some advanced features (like typing text streaming animation).
-
-### What's the difference between `log` and `message` levels?
-
-→ `log` uses a pipe symbol (│) and is for general logging, while `message` uses a different symbol (🞠) and is for general messages.
-
-## Ecosystem
-
-Relinka works great with other Reliverse tools:
-
-- **CLI Development**: [`@reliverse/prompts`](https://npmjs.com/@reliverse/prompts)
-- **Bundling**: [`@reliverse/dler`](https://npmjs.com/@reliverse/dler)
-
-## Roadmap
-
-- [x] File logging with rotation
-- [x] Timestamp support
-- [x] Date-based file naming
-- [x] Automatic cleanup
-- [x] Fatal logging with debugger
-- [x] Runtime configuration
-- [x] Dual syntax support
-- [ ] Plugin system
-- [ ] Custom formatters
-- [ ] CLI interface for log management
-- [ ] WebSocket streaming
-- [ ] Structured logging (JSON)
-
-## Contributing
+## Requirements
 
-We welcome contributions! Please see our [contributing guide](CONTRIBUTING.md) for details.
+- **Runtime**: Bun (uses `Bun.write` for async operations)
+- **TypeScript**: 5.0+ (for best experience)
 
 ## License
 
-💖 MIT © 2025 [blefnk Nazar Kornienko](https://github.com/blefnk)
+MIT
 
-## Acknowledgments
+## Related Packages
 
-Relinka is inspired by these excellent logging libraries:
+- [@reliverse/relico](https://github.com/reliverse/relico) - Color utilities used by relinka
 
-- [unjs/consola](https://github.com/unjs/consola) - Console logging for Node.js
-- [winston](https://github.com/winstonjs/winston) - Multi-transport logging
-- [pino](https://github.com/pinojs/pino) - Fast Node.js logger
-- [node-bunyan](https://github.com/trentm/node-bunyan) - JSON logging

package/dist/mod.d.ts

@@ -0,0 +1,49 @@
+declare const LOG_COLORS: {
+    readonly log: any;
+    readonly error: any;
+    readonly fatal: any;
+    readonly warn: any;
+    readonly info: any;
+    readonly success: any;
+    readonly debug: any;
+    readonly box: any;
+};
+type LogLevel = keyof typeof LOG_COLORS;
+interface LoggerBase {
+    log: (...args: unknown[]) => void | Promise<void>;
+    error: (...args: unknown[]) => void | Promise<void>;
+    fatal: (...args: unknown[]) => void | Promise<void>;
+    warn: (...args: unknown[]) => void | Promise<void>;
+    info: (...args: unknown[]) => void | Promise<void>;
+    success: (...args: unknown[]) => void | Promise<void>;
+    debug: (...args: unknown[]) => void | Promise<void>;
+    box: (...args: unknown[]) => void | Promise<void>;
+    raw: (...args: unknown[]) => void | Promise<void>;
+}
+interface LoggerAsync extends LoggerBase {
+    (level: LogLevel, ...args: unknown[]): Promise<void>;
+    log: (...args: unknown[]) => Promise<void>;
+    error: (...args: unknown[]) => Promise<void>;
+    fatal: (...args: unknown[]) => Promise<void>;
+    warn: (...args: unknown[]) => Promise<void>;
+    info: (...args: unknown[]) => Promise<void>;
+    success: (...args: unknown[]) => Promise<void>;
+    debug: (...args: unknown[]) => Promise<void>;
+    box: (...args: unknown[]) => Promise<void>;
+    raw: (...args: unknown[]) => Promise<void>;
+}
+interface Logger extends LoggerBase {
+    (level: LogLevel, ...args: unknown[]): void;
+    log: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    fatal: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    success: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+    box: (...args: unknown[]) => void;
+    raw: (...args: unknown[]) => void;
+}
+export declare const logger: Logger;
+export declare const relinka: LoggerAsync;
+export {};