@reliverse/relinka 1.5.2 → 1.5.3

package/README.md

@@ -1,23 +1,23 @@
 # Relinka: Logging that Actually Feels Good
 
-> **@reliverse/relinka** is a modern, minimal 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.
-
 [sponsor](https://github.com/sponsors/blefnk) — [discord](https://discord.gg/Pb8uKbwpsJ) — [repo](https://github.com/reliverse/relinka) — [npm](https://npmjs.com/@reliverse/relinka)
 
-## Why Relinka
+> **@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.
 
-- 🧙 Drop-in replacement for `node:console`, `consola`, or your internal logger
-- 💬 Supports: `info`, `warn`, `success`, `error`, `verbose`, `fatal`, `clear`
-- 🎨 Terminal output that *pops*, with automatic color handling
-- 📁 Save logs to file (with daily rotation, cleanup, and max-file limits)
-- 🧠 Structured message formatting (objects, errors, stacks — handled!)
-- ⚙️ Runtime config via `relinka.config.ts` (powered by `reconf`)
-- 🚨 `fatal` logs halt execution and trigger `debugger` in dev
-- 🧩 Sync-first, async, & CLI-friendly thanks to buffer flushing
+## Why Relinka
 
-## Getting Started
+- 🧙 **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
 
-Make sure you have git, node.js, and bun/pnpm/yarn/npm installed.
+## Quick Start
 
 ### 1. Install
 
@@ -25,158 +25,173 @@ Make sure you have git, node.js, and bun/pnpm/yarn/npm installed.
 bun add @reliverse/relinka
 ```
 
-**Coming soon**:
+### 2. Basic Usage
 
-```bash
-bun i -g @reliverse/dler
-dler relinka --console-to-relinka
+```ts
+import { relinka, relinkaConfig, relinkaShutdown } 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();
+}
+
+main();
 ```
 
-### 2. Use It
+## 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 |
 
-#### Direct Method (Recommended)
+## API Reference
 
-- Place this **at the START** of your app's main function:
+### Core Functions
+
+#### `relinka(level, message, ...args)`
+
+Main logging function with dual syntax support.
 
 ```ts
-await relinkaConfig;
+// Function syntax
+relinka("info", "Hello world");
+relinka("error", "Something broke", { error: "details" });
+
+// Method syntax
+relinka.info("Hello world");
+relinka.error("Something broke", { error: "details" });
 ```
 
-- Place this **at the END** of your app's main function:
+#### `relinkaAsync(level, message, ...args)`
+
+Async version that waits for configuration to load.
 
 ```ts
-await relinkaShutdown();
+await relinkaAsync("info", "Async message");
+await relinkaAsync("success", "Operation completed");
 ```
 
-**Usage example**:
+#### `relinkaConfig(options?)`
+
+Load configuration with optional fresh log file support.
 
 ```ts
-import {
-  relinka,
-  relinkaAsync,
-  relinkaConfig,
-  relinkaShutdown,
-} from "@reliverse/relinka";
-
-export async function main() {
-  await relinkaAsync(
-    // this automatically loads the config
-    "verbose",
-    "This ASYNC verbose message can be seen only if verbose=true (in user config)",
-  );
-  await relinkaConfig; // place this at your main function or just at the top of your entry file
-  relinka(
-    "verbose",
-    "This SYNC verbose message can be seen only if verbose=true (in user config) AND config was loaded ",
-  );
-
-  // --- BOX LEVEL EXAMPLES ---
-  relinka("box", "This is a boxed message using direct syntax!");
-  relinka.box("This is a boxed message using method syntax!");
-
-  // --- MESSAGE LEVEL EXAMPLES ---
-  relinka("message", "This is a message using direct syntax!");
-  relinka.message("This is a message using method syntax!");
-
-  // --- STEP LEVEL EXAMPLES ---
-  relinka("step", "Step 1: Initialize application");
-  relinka.step("Step 2: Load configuration");
-  relinka.step("Step 3: Start services");
-
-  // --- LOG LEVEL EXAMPLES ---
-  relinka("log", "Hello! 👋");
-  relinka("log", "Great to see you here!");
-  relinka("info", "Everything is running smoothly");
-  relinka("warn", "This might be a problem");
-  relinka(
-    "error", // non-fatal issue level can be recovered
-    "Uh oh, something broke",
-  );
-
-  relinka(
-    "null",
-    "'null' level has a special handling case: no symbol or spacing",
-  );
-
-  // relinka(
-  //   "fatal",
-  //   "We should never reach this code! This should never happen! (see <anonymous> line)",
-  // ); // fatal level throws error and halts execution
-  relinka("success", "Thanks for using Relinka!");
-
-  // Make sure to shut down the logger at the end of your program
-  // This is important to flush all buffers and close file handles
-  await relinkaShutdown();
+// Basic config loading
+await relinkaConfig();
 
-  // Make sure to exit the program after your CLI is done
-  // It's not required for Bun-only apps, but recommended
-  // for other terminal runtimes like Node.js (incl. `tsx`)
-  // It's also not required for @reliverse/rempts `runMain()`
-  process.exit(0);
-}
+// With fresh log file (clears existing log file)
+await relinkaConfig({ supportFreshLogFile: true });
+```
+
+#### `relinkaShutdown()`
 
-await main();
+Flush all buffers and clean up resources. **Always call this at the end of your program.**
+
+```ts
+await relinkaShutdown();
 ```
 
-#### [🔜 Soon] Singleton Method
+### Utility Functions
+
+#### `log`, `logger`
+
+Aliases for the main `relinka` function.
 
 ```ts
-const logger = initRelinkaInstance({/* per-project config */}); 
-logger("info", "Looks great!");
+import { log, logger } from "@reliverse/relinka";
+
+log("info", "Using alias");
+logger.success("Another alias");
 ```
 
-#### [🔜 Soon] Object Method
+#### `message(msg, ...args)`
+
+Convenience function for general messages.
 
 ```ts
-await relinkaConfig;
-relinka.info("Looks great!");
+import { message } from "@reliverse/relinka";
+message("This is a general message");
 ```
 
-## Advanced Usage
+#### `step(msg, ...args)`
+
+Convenience function for progress steps.
 
 ```ts
-// Clear terminal:
-relinka("clear", "");
-// Blank line:
-relinka("info", "");
-// Async variant:
-import { relinkaAsync } from "@reliverse/relinka";
-await relinkaAsync("info", "Logged from async context");
-// Coming soon:
-await relinkaAsync("info", "Something happened", { animate: true });
+import { step } from "@reliverse/relinka";
+step("Step 1: Initialize");
+step("Step 2: Load config");
 ```
 
-## Config
+## Configuration
+
+Create a configuration file to customize Relinka's behavior:
+
+### File Locations (in order of priority)
 
-Create `relinka.config.ts`:
+1. `relinka.config.ts` (project root) - **highest priority**
+2. `.config/relinka.ts` - **lower priority**
+
+### Configuration Example
 
 ```ts
 import { defineConfig } from "@reliverse/relinka";
-/**
- * RELINKA CONFIGURATION FILE
- * - Hover over a field to see the information
- * - Use intellisense to see available options
- * @see https://github.com/reliverse/relinka
- */
+
 export default defineConfig({
-  // Enable to see verbose logs
+  // Enable verbose logging
   verbose: false,
 
   // Timestamp configuration
   timestamp: {
-    enabled: false,
-    format: "HH:mm:ss",
+    enabled: true,
+    format: "YYYY-MM-DD HH:mm:ss.SSS",
   },
 
-  // Control whether logs are saved to a file
+  // 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
+  },
 
-  // Disable colors in the console
-  disableColors: false,
+  // Log rotation
+  dirs: {
+    maxLogFiles: 10, // Keep only the 10 most recent log files
+  },
 
-  // Log file path
-  logFilePath: "relinka.log",
+  // 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: "✓",
@@ -185,138 +200,208 @@ export default defineConfig({
       spacing: 3,
     },
     info: {
-      symbol: "i",
+      symbol: "◈",
       fallbackSymbol: "[i]",
       color: "cyanBright",
       spacing: 3,
     },
-    error: {
-      symbol: "✖",
-      fallbackSymbol: "[ERR]",
-      color: "redBright",
-      spacing: 3,
-    },
-    warn: {
-      symbol: "⚠",
-      fallbackSymbol: "[WARN]",
-      color: "yellowBright",
-      spacing: 3,
-    },
-    fatal: {
-      symbol: "‼",
-      fallbackSymbol: "[FATAL]",
-      color: "redBright",
-      spacing: 3,
-    },
-    verbose: {
-      symbol: "✧",
-      fallbackSymbol: "[VERBOSE]",
-      color: "gray",
-      spacing: 3,
-    },
-    log: { symbol: "│", fallbackSymbol: "|", color: "dim", spacing: 3 },
-  },
-
-  // Directory settings
-  dirs: {
-    dailyLogs: true,
-    logDir: "logs", // store logs in a custom folder
-    maxLogFiles: 5, // keep only the 5 most recent log files
-    specialDirs: {
-      distDirNames: [],
-      useParentConfigInDist: true,
-    },
+    // ... customize other levels
   },
 });
 ```
 
-Supported files:
+### 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 |
 
-- `relinka.config.ts`
-- 🔜 other formats, supported by `reconf`, are coming soon
+## File Logging
 
-## Log Files
+### File Naming Patterns
 
-- Default: `logs/relinka.log`
-- Daily mode: `2025-04-11-relinka.log`
-- Auto-cleanup: keep latest N logs
+- **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`
 
-## API Summary
+### 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
+
+### Fatal Logging
+
+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");
+```
+
+### 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");
+```
+
+### Clear Terminal
+
+Clear the terminal output:
+
+```ts
+relinka("clear", "");
+// or
+relinka.clear();
+```
+
+### Empty Lines
+
+Add blank lines to output:
 
 ```ts
-relinka("info", "message", optionalDetails);
-relinka("fatal", "something broke"); // throws
-relinka("clear", ""); // clears terminal
+relinka("info", "");
+```
 
-await relinkaAsync("warn", "something async");
+## Best Practices
+
+### 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
+}
 ```
 
+### 2. Use Appropriate Log Levels
+
 ```ts
-defineConfig({ ... }) // helper for relinka.config.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
 ```
 
-## Built-in Utilities
+### 3. Leverage Verbose Logging
+
+```ts
+relinka("verbose", "Debug information"); // Only shown when verbose=true
+```
 
-- ✅ Timestamping
-- ✅ File-safe formatting
-- ✅ Log rotation
-- ✅ Fatal logging (with debugger)
-- ✅ Colorized terminal output
+### 4. Structure Complex Data
+
+```ts
+relinka("error", "API request failed", {
+  endpoint: "/api/users",
+  statusCode: 500,
+  error: error.message
+});
+```
+
+## 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 `relinka.config.ts` doesn't works for me?
+### Why does my terminal hang after logging?
 
-→ You forget to load user's config by using `await relinkaConfig;` **at the START** of your app's main function.
+→ You forgot to call `await relinkaShutdown()` at the end of your program. This is required to flush buffers.
 
-### Why my terminal stucks after last relinka() usage?
+### Why isn't my configuration loading?
 
-→ You forget to flush the buffer. Place `await relinkaShutdown();` **at the END** of your app's main function.
+→ Make sure you call `await relinkaConfig()` at the start of your application.
 
-### Why does TS linter tells that something wrong with `relinka("info", args)`?
+### Does `fatal` always throw?
 
-→ Add empty string: `relinka("info", "", args)`
+→ Yes, `fatal` logs always throw errors and halt execution. In development mode, they also trigger the debugger.
 
-### Does `fatal` throw?
+### How do I disable colors?
 
-→ Yes, always. It will halt execution and trigger `debugger` in dev mode.
+→ Set `disableColors: true` in your configuration or use `NO_COLOR=1` environment variable.
 
-### What's coming next?
+### Can I use Relinka in both sync and async contexts?
 
-- Relinka is designed to be used in the different ways:
-- Use `relinka(level, message, ...args)` (recommended).
-- 🔜 Or, just `relinka.level(message, ...args)`
-- 🔜 Both designed to work with both sync (default) and async/await.
-- 🔜 Both designed to work with both direct and wrapper methods.
-- 🔜 Use the async logger if you want some advanced features (like typing text streaming animation).
+→ Yes! Use `relinka()` for sync operations and `relinkaAsync()` when you need to use some advanced features (like typing text streaming animation).
 
-## Tips
+### What's the difference between `log` and `message` levels?
 
-- Building CLIs? Use with [`@reliverse/prompts`](https://npmjs.com/@reliverse/prompts)
-- Want type-safe injections? Try [`@reliverse/reinject`](https://npmjs.com/@reliverse/reinject)
-- For advanced bundling? Pair with [`@reliverse/dler`](https://npmjs.com/@reliverse/dler)
+→ `log` uses a pipe symbol (│) and is for general logging, while `message` uses a different symbol (🞠) and is for general messages.
 
-## Roadmap
+## Ecosystem
 
-- [x] File logging
-- [x] Timestamps
-- [x] Daily logs
-- [x] Log rotation
-- [x] `fatal` type
-- [x] Runtime config
-- [ ] Implement per-project config redefinition
-- [ ] Plugin support (custom formatters, hooks)
-- [ ] CLI interface (to manage logs, config, etc)
+Relinka works great with other Reliverse tools:
 
-## Shoutouts
+- **CLI Development**: [`@reliverse/prompts`](https://npmjs.com/@reliverse/prompts)
+- **Bundling**: [`@reliverse/dler`](https://npmjs.com/@reliverse/dler)
 
-Relinka wouldn't exist without these gems:
+## 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
 
-- [unjs/consola](https://github.com/unjs/consola#readme)  
-- [winston](https://github.com/winstonjs/winston#readme)  
-- [pino](https://github.com/pinojs/pino#readme)  
-- [node-bunyan](https://github.com/trentm/node-bunyan#readme)
+We welcome contributions! Please see our [contributing guide](CONTRIBUTING.md) for details.
 
 ## License
 
 💖 MIT © 2025 [blefnk Nazar Kornienko](https://github.com/blefnk)
+
+## Acknowledgments
+
+Relinka is inspired by these excellent logging libraries:
+
+- [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/bin/impl.d.ts

@@ -1,15 +1,7 @@
 import type { DefaultColorKeys } from "@reliverse/relico";
-/** Configuration for special directory handling. */
-export type RelinkaSpecialDirsConfig = {
-    distDirNames?: string[];
-    useParentConfigInDist?: boolean;
-};
 /** Configuration for directory-related settings. */
 export type RelinkaDirsConfig = {
-    dailyLogs?: boolean;
-    logDir?: string;
     maxLogFiles?: number;
-    specialDirs?: RelinkaSpecialDirsConfig;
 };
 /** Configuration for a single log level. */
 export type LogLevelConfig = {
@@ -50,12 +42,7 @@ export type RelinkaConfig = {
     verbose?: boolean;
     /**
      * Configuration for directory-related settings.
-     * - `dailyLogs`: If true, logs will be stored in a daily subdirectory.
-     * - `logDir`: The base directory for logs.
      * - `maxLogFiles`: The maximum number of log files to keep before cleanup.
-     * - `specialDirs`: Configuration for special directory handling.
-     *   - `distDirNames`: An array of directory names to check for special handling.
-     *   - `useParentConfigInDist`: If true, use the parent config in dist directories.
      */
     dirs?: RelinkaDirsConfig;
     /**
@@ -63,9 +50,26 @@ export type RelinkaConfig = {
      */
     disableColors?: boolean;
     /**
-     * Path to the log file.
+     * Configuration for log file output.
      */
-    logFilePath?: string;
+    logFile?: {
+        /**
+         * Path to the log file.
+         */
+        outputPath?: string;
+        /**
+         * How to handle date in the filename.
+         * - `disable`: No date prefix/suffix
+         * - `append-before`: Add date before the filename (e.g., "2024-01-15-log.txt")
+         * - `append-after`: Add date after the filename (e.g., "log-2024-01-15.txt")
+         */
+        nameWithDate?: "disable" | "append-before" | "append-after";
+        /**
+         * If true, clears the log file when relinkaConfig is executed with supportFreshLogFile: true.
+         * This is useful for starting with a clean log file on each run.
+         */
+        freshLogFile?: boolean;
+    };
     /**
      * If true, logs will be saved to a file.
      */
@@ -108,8 +112,16 @@ export type LogFileInfo = {
     path: string;
     mtime: number;
 };
+/** Options for relinkaConfig */
+export type RelinkaConfigOptions = {
+    supportFreshLogFile?: boolean;
+};
 /** Promise resolved once the user's config (if any) is merged. */
-export declare const relinkaConfig: Promise<RelinkaConfig>;
+export declare const loadRelinkaConfig: Promise<RelinkaConfig>;
+/**
+ * Enhanced relinkaConfig function that accepts options
+ */
+export declare function relinkaConfig(options?: RelinkaConfigOptions): Promise<RelinkaConfig>;
 /**
  * Shuts down the logger, flushing all buffers and clearing timers.
  * As Relinka user - call this at the end of your program to prevent hanging.

package/bin/impl.js

@@ -8,16 +8,14 @@ const EXIT_GUARD = Symbol.for("relinka.exitHandlersRegistered");
 const DEFAULT_RELINKA_CONFIG = {
   verbose: false,
   dirs: {
-    dailyLogs: false,
-    logDir: "logs",
-    maxLogFiles: 0,
-    specialDirs: {
-      distDirNames: ["dist", "dist-jsr", "dist-npm", "dist-libs"],
-      useParentConfigInDist: true
-    }
+    maxLogFiles: 0
   },
   disableColors: false,
-  logFilePath: "relinka.log",
+  logFile: {
+    outputPath: "logs.log",
+    nameWithDate: "disable",
+    freshLogFile: true
+  },
   saveLogsToFile: false,
   timestamp: {
     enabled: false,
@@ -115,9 +113,33 @@ function isUnicodeSupported() {
 let currentConfig = { ...DEFAULT_RELINKA_CONFIG };
 let isConfigInitialized = false;
 let resolveRelinkaConfig;
-export const relinkaConfig = new Promise((res) => {
+let userTerminalCwd;
+export const loadRelinkaConfig = new Promise((res) => {
   resolveRelinkaConfig = res;
 });
+export async function relinkaConfig(options = {}) {
+  if (!userTerminalCwd) {
+    userTerminalCwd = process.cwd();
+  }
+  const config = await loadRelinkaConfig;
+  if (options.supportFreshLogFile && isFreshLogFileEnabled(config)) {
+    try {
+      const logFilePath = getLogFilePath(config);
+      await fs.ensureDir(path.dirname(logFilePath));
+      await fs.writeFile(logFilePath, "");
+      if (isVerboseEnabled(config)) {
+        console.log(`[Relinka Fresh Log] Cleared log file: ${logFilePath}`);
+      }
+    } catch (err) {
+      if (isVerboseEnabled(config)) {
+        console.error(
+          `[Relinka Fresh Log Error] Failed to clear log file: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+  }
+  return config;
+}
 const logBuffers = /* @__PURE__ */ new Map();
 const activeTimers = [];
 let bufferFlushTimer = null;
@@ -193,20 +215,15 @@ function isVerboseEnabled(config) {
 function isColorEnabled(config) {
   return !(config.disableColors ?? DEFAULT_RELINKA_CONFIG.disableColors);
 }
-function getLogDir(config) {
-  return config.dirs?.logDir ?? DEFAULT_RELINKA_CONFIG.dirs?.logDir ?? "logs";
-}
-function isDailyLogsEnabled(config) {
-  return config.dirs?.dailyLogs ?? DEFAULT_RELINKA_CONFIG.dirs?.dailyLogs ?? false;
-}
 function shouldSaveLogs(config) {
   return config.saveLogsToFile ?? DEFAULT_RELINKA_CONFIG.saveLogsToFile ?? false;
 }
 function getMaxLogFiles(config) {
-  return config.dirs?.maxLogFiles ?? DEFAULT_RELINKA_CONFIG.dirs?.maxLogFiles ?? 0;
+  return config.dirs?.maxLogFiles ?? 0;
 }
 function getBaseLogName(config) {
-  return config.logFilePath ?? DEFAULT_RELINKA_CONFIG.logFilePath ?? "relinka.log";
+  const logFileConfig = config.logFile || DEFAULT_RELINKA_CONFIG.logFile || {};
+  return logFileConfig.outputPath ?? "logs.log";
 }
 function getBufferSize(config) {
   return config.bufferSize ?? DEFAULT_RELINKA_CONFIG.bufferSize ?? 4096;
@@ -217,6 +234,9 @@ function getMaxBufferAge(config) {
 function getCleanupInterval(config) {
   return config.cleanupInterval ?? DEFAULT_RELINKA_CONFIG.cleanupInterval ?? 1e4;
 }
+function isFreshLogFileEnabled(config) {
+  return config.logFile?.freshLogFile ?? DEFAULT_RELINKA_CONFIG.logFile?.freshLogFile ?? false;
+}
 function isDevEnv() {
   return process.env.NODE_ENV === "development";
 }
@@ -232,18 +252,27 @@ function getTimestamp(config) {
   return format.replace("YYYY", String(now.getFullYear())).replace("MM", String(now.getMonth() + 1).padStart(2, "0")).replace("DD", String(now.getDate()).padStart(2, "0")).replace("HH", String(now.getHours()).padStart(2, "0")).replace("mm", String(now.getMinutes()).padStart(2, "0")).replace("ss", String(now.getSeconds()).padStart(2, "0")).replace("SSS", String(now.getMilliseconds()).padStart(3, "0"));
 }
 function getLogFilePath(config) {
-  const logDir = getLogDir(config);
-  const daily = isDailyLogsEnabled(config);
-  let finalLogName = getBaseLogName(config);
-  if (daily) {
-    const datePrefix = `${getDateString()}-`;
-    finalLogName = datePrefix + finalLogName;
+  const logFileConfig = config.logFile || DEFAULT_RELINKA_CONFIG.logFile || {};
+  const nameWithDate = logFileConfig.nameWithDate || "disable";
+  const outputPath = getBaseLogName(config);
+  const dir = path.dirname(outputPath);
+  let filename = path.basename(outputPath);
+  if (nameWithDate !== "disable") {
+    const dateString = getDateString();
+    if (nameWithDate === "append-before") {
+      filename = `${dateString}-${filename}`;
+    } else if (nameWithDate === "append-after") {
+      const nameWithoutExt = filename.replace(/\.log$/, "");
+      filename = `${nameWithoutExt}-${dateString}.log`;
+    }
   }
-  if (finalLogName && !finalLogName.endsWith(".log")) {
-    finalLogName += ".log";
+  if (filename && !filename.endsWith(".log")) {
+    filename += ".log";
   }
-  const effectiveLogName = finalLogName || "relinka.log";
-  return path.resolve(process.cwd(), logDir, effectiveLogName);
+  const effectiveFilename = filename || "logs.log";
+  const finalPath = dir === "." ? effectiveFilename : path.join(dir, effectiveFilename);
+  const baseCwd = userTerminalCwd || process.cwd();
+  return path.resolve(baseCwd, finalPath);
 }
 function getLevelStyle(config, level) {
   const allLevels = config.levels || DEFAULT_RELINKA_CONFIG.levels || {};
@@ -305,6 +334,7 @@ const consoleMethodMap = {
   success: console.log,
   verbose: console.log,
   log: console.log,
+  internal: console.log,
   step: console.log,
   box: console.log,
   message: console.log,
@@ -322,16 +352,40 @@ function logToConsole(config, level, formattedMessage) {
   method(`${colorFn(formattedMessage)}\x1B[0m`);
 }
 async function getLogFilesSortedByDate(config) {
-  const logDirectoryPath = path.resolve(process.cwd(), getLogDir(config));
+  const logDirectoryPath = userTerminalCwd || process.cwd();
   try {
-    if (!await fs.pathExists(logDirectoryPath)) {
-      if (ENABLE_DEV_DEBUG) {
-        console.log(`[Dev Debug] Log directory not found: ${logDirectoryPath}`);
+    const files = await fs.readdir(logDirectoryPath);
+    const logFiles = [];
+    for (const file of files) {
+      const filePath = path.join(logDirectoryPath, file);
+      try {
+        const stats = await fs.stat(filePath);
+        if (stats.isFile() && file.endsWith(".log")) {
+          logFiles.push(file);
+        } else if (stats.isDirectory()) {
+          try {
+            const subFiles = await fs.readdir(filePath);
+            for (const subFile of subFiles) {
+              if (subFile.endsWith(".log")) {
+                logFiles.push(path.join(file, subFile));
+              }
+            }
+          } catch (subDirErr) {
+            if (isVerboseEnabled(config)) {
+              console.error(
+                `[Relinka FS Debug] Error reading subdirectory ${filePath}: ${subDirErr instanceof Error ? subDirErr.message : String(subDirErr)}`
+              );
+            }
+          }
+        }
+      } catch (err) {
+        if (isVerboseEnabled(config)) {
+          console.error(
+            `[Relinka FS Debug] Error accessing ${filePath}: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
       }
-      return [];
     }
-    const files = await fs.readdir(logDirectoryPath);
-    const logFiles = files.filter((f) => f.endsWith(".log"));
     if (logFiles.length === 0) return [];
     const fileInfoPromises = logFiles.map(
       async (fileName) => {
@@ -357,7 +411,7 @@ async function getLogFilesSortedByDate(config) {
   } catch (readErr) {
     if (isVerboseEnabled(config)) {
       console.error(
-        `[Relinka FS Error] Failed reading log directory ${logDirectoryPath}: ${readErr instanceof Error ? readErr.message : String(readErr)}`
+        `[Relinka FS Error] Failed reading directory ${logDirectoryPath}: ${readErr instanceof Error ? readErr.message : String(readErr)}`
       );
     }
     return [];
@@ -615,7 +669,7 @@ export async function relinkaAsync(type, message, ...args) {
     console.log();
     return;
   }
-  await relinkaConfig;
+  await relinkaConfig({ supportFreshLogFile: false });
   const levelName = type.toLowerCase();
   if (levelName === "fatal") {
     shouldNeverHappen(message, ...args);
@@ -658,7 +712,7 @@ export function formatBox(text) {
   const bottom = `\u2514${"\u2500".repeat(width)}\u2518`;
   const content = lines.map((line) => {
     const padding = width - line.length;
-    return `\u2502  ${line}${" ".repeat(padding)}\u2502`;
+    return `\u2502  ${line}${" ".repeat(padding - 2)}\u2502`;
   }).join("\n");
   return `${top}
 ${content}

package/bin/mod.d.ts

@@ -1,3 +1,3 @@
 export { message, step, log, logger } from "./alias.js";
-export type { RelinkaSpecialDirsConfig, RelinkaDirsConfig, LogLevelConfig, LogLevelsConfig, LogLevel, RelinkaConfig, LogFileInfo, RelinkaFunction, } from "./impl.js";
-export { relinkaConfig, relinkaShutdown, flushAllLogBuffers, shouldNeverHappen, truncateString, casesHandled, relinka, relinkaAsync, defineConfig, formatBox, } from "./impl.js";
+export type { RelinkaDirsConfig, LogLevelConfig, LogLevelsConfig, LogLevel, RelinkaConfig, LogFileInfo, RelinkaFunction, RelinkaConfigOptions, } from "./impl.js";
+export { loadRelinkaConfig, relinkaConfig, relinkaShutdown, flushAllLogBuffers, shouldNeverHappen, truncateString, casesHandled, relinka, relinkaAsync, defineConfig, formatBox, } from "./impl.js";

package/bin/mod.js

@@ -1,5 +1,6 @@
 export { message, step, log, logger } from "./alias.js";
 export {
+  loadRelinkaConfig,
   relinkaConfig,
   relinkaShutdown,
   flushAllLogBuffers,

package/package.json

@@ -10,7 +10,7 @@
   "license": "MIT",
   "name": "@reliverse/relinka",
   "type": "module",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "keywords": [
     "logger",
     "consola",