@reliverse/relinka 1.3.8 → 1.4.0

package/README.md

@@ -1,90 +1,189 @@
-# Relinka: Stylish Logging Made Simple
+# Relinka: Logging that Actually Feels Good
 
-[💖 GitHub Sponsors](https://github.com/sponsors/blefnk) • [💬 Discord](https://discord.gg/Pb8uKbwpsJ) • [✨ Repo](https://github.com/reliverse/relinka-logger) • [📦 NPM](https://npmjs.com/@reliverse/relinka) • [📚 Docs](https://docs.reliverse.org)
+[💖 GitHub Sponsors](https://github.com/sponsors/blefnk) • [💬 Discord](https://discord.gg/Pb8uKbwpsJ) • [✨ Repo](https://github.com/reliverse/relinka-logger) • [📦 NPM](https://npmjs.com/@reliverse/relinka)
 
-**@reliverse/relinka** is your next favorite logging library — built to make your terminal (and browser console — soon) output look good, stay clean, and be actually helpful. It’s styled, structured, and smart. Oh, and it works with configs, files, and colors out of the box.
+**@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.
 
-## 🌟 Features
+Whether you're building CLI tools, SDKs, or full-stack apps — Relinka helps you log with intention.
 
-- 🧙 Drop-in replacement for `node:console` and `consola`
-- 💬 `relinka` supports: `info`, `warn`, `success`, `error`, `verbose`
-- 🎨 Beautiful, color-coded logs in the terminal
-- 🧠 Auto-formats messages, objects, and errors
-- 📁 Save logs to file (with daily logs, cleanup, and rotation)
-- 📦 Use it programmatically or through CLI-compatible tools
-- ⚙️ Smart customization via config
-- ✨ Extensible and future-proof
+## ✨ Why Relinka
 
-## 🚀 Getting Started
+- 🧙 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
 
-### 1. Install
+## Getting Started
+
+### 2️⃣ Install
 
 ```bash
 bun add @reliverse/relinka
 ```
 
-And, optionally, install the CLI globally to manage your config:
+### 2️⃣ Use It
 
-```bash
-bun i -g @reliverse/relinka-cli
+#### Direct Method (Recommended)
+
+- Place this **at the START** of your app's main function:
+
+```ts
+await relinkaConfig;
 ```
 
-### 2. Basic Usage
+- Place this **at the END** of your app's main function:
 
 ```ts
-import { relinkaConfig, relinka } from "@reliverse/relinka";
+await relinkaShutdown();
+```
+
+**Usage example**:
+
+```ts
+import {
+  relinka,
+  relinkaAsync,
+  relinkaConfig,
+  relinkaShutdown,
+} from "@reliverse/relinka";
 export async function main() {
-  await relinkaConfig;
+  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 message can be seen only if config was loaded AND debug is enabled",
+    "This SYNC verbose message can be seen only if verbose=true (in user config) AND config was loaded ",
   );
+  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", "Uh oh, something broke");
-  relinka("success", "Thanks for using Relinka! 👋");
+  relinka(
+    "error", // non-fatal issue level can be recovered
+    "Uh oh, something broke",
+  );
+  // 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();
 }
 await main();
 ```
 
-## 🧪 Advanced Usage
+#### [🔜 Soon] Singleton Method
+
+```ts
+const logger = initRelinkaInstance();
+logger("info", "Looks great!");
+```
 
-Want a clean blank line?
+#### [🔜 Soon] Object Method
 
 ```ts
-relinka("clear", ""); // Acts just like `console.clear()`
-relinka("info", ""); // Just prints a blank newline
+await relinkaConfig;
+relinka.info("Looks great!");
 ```
 
-🔜 Use the async logger if you want some advanced features (like typing text animation - soon):
+## Advanced Usage
 
 ```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 });
 ```
 
-## ⚙️ Configuration
+## Config
 
-Create a `relinka.config.ts` file with a content like:
+Create `relinka.config.ts`:
 
 ```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 debug to see verbose logs
-  debug: true,
-  // Show timestamp in each log message
-  withTimestamp: false,
+  // Enable to see verbose logs
+  verbose: false,
+
+  // Timestamp configuration
+  timestamp: {
+    enabled: false,
+    format: "HH:mm:ss",
+  },
+
   // Control whether logs are saved to a file
   saveLogsToFile: true,
+
   // Disable colors in the console
   disableColors: false,
+
   // Log file path
   logFilePath: "relinka.log",
+
+  levels: {
+    success: {
+      symbol: "✓",
+      fallbackSymbol: "[OK]",
+      color: "greenBright",
+      spacing: 3,
+    },
+    info: {
+      symbol: "i",
+      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: ".reliverse/logs", // store logs in a custom folder
+    logDir: "logs", // store logs in a custom folder
     maxLogFiles: 5, // keep only the 5 most recent log files
     specialDirs: {
       distDirNames: [],
@@ -94,62 +193,89 @@ export default defineConfig({
 });
 ```
 
-Supported config file names:
+Supported files:
 
 - `relinka.config.ts`
-- 🔜 `.relinka.config.js`
-- 🔜 `.relinkarc`
-- 🔜 or any other supported by c12
+- 🔜 other formats, supported by `reconf`, are coming soon
+
+## Log Files
+
+- Default: `logs/relinka.log`
+- Daily mode: `2025-04-11-relinka.log`
+- Auto-cleanup: keep latest N logs
+
+## API Summary
+
+```ts
+relinka("info", "message", optionalDetails);
+relinka("fatal", "something broke"); // throws
+relinka("clear", ""); // clears terminal
+
+await relinkaAsync("warn", "something async");
+```
+
+```ts
+defineConfig({ ... }) // helper for relinka.config.ts
+```
+
+## Built-in Utilities
+
+- ✅ Timestamping
+- ✅ File-safe formatting
+- ✅ Log rotation
+- ✅ Fatal logging (with debugger)
+- ✅ Colorized terminal output
 
-## 📁 Log Files
+## FAQ
 
-- Stored in `.reliverse/logs/` by default
-- Filename: `relinka.log` or `YYYY-MM-DD-relinka.log` if daily logs are enabled
-- Auto-rotates based on `maxLogFiles`
+### Why `relinka.config.ts` doesn't works for me?
 
-## 📚 API Summary
+→ You forget to load user's config by using `await relinkaConfig;` **at the START** of your app's main function.
 
-### relinka(level, message, ...args)
+### Why my terminal stucks after last relinka() usage?
 
-Logs synchronously. Skips debug logs if `debug: false`.
+→ You forget to flush the buffer. Place `await relinkaShutdown();` **at the END** of your app's main function.
 
-### relinkaAsync(level, message, ...args)
+### Why does TS linter tells that something wrong with `relinka("info", args)`?
 
-Async logger that waits for config automatically, and provides some additional advanced features.
+→ Add empty string: `relinka("info", "", args)`
 
-### defineConfig(config)
+### Does `fatal` throw?
 
-Helper to define typed config in `relinka.config.ts`
+→ Yes, always. It will halt execution and trigger `debugger` in dev mode.
 
-## 🧰 Utilities
+### What's coming next?
 
-✅ Timestamping  
-✅ Log file rotation  
-✅ File-safe formatting  
-✅ ANSI color support  
-✅ Error object handling
+- 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).
 
-## 💡 Tips
+## Tips
 
-- Want `@ts-expect-error` auto-injection? Check out [`@reliverse/reinject`](https://npmjs.com/@reliverse/reinject).
-- Using this in a CLI tool? Combine with [`@reliverse/prompts`](https://npmjs.com/@reliverse/prompts).
+- 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/relidler`](https://npmjs.com/@reliverse/relidler)
 
-## ✅ TODO
+## Roadmap
 
-- [x] File-based logging
-- [x] Timestamp support
+- [x] File logging
+- [x] Timestamps
 - [x] Daily logs
-- [x] Smart config
 - [x] Log rotation
-- [ ] CLI interface (optional)
-- [ ] Plugin support (custom formatters, log levels, etc)
+- [x] `fatal` type
+- [x] Runtime config
+- [ ] CLI interface (to manage logs, config, etc.)
+- [ ] Plugin support (custom formatters, hooks)
 
-## 🙌 Shoutout
+## Thanks
 
-Relinka was inspired by this gem:
+Relinka's DX design was inspired by this gem:
 
-- [unjs/consola](https://github.com/unjs/consola#readme)
+- [unjs/consola](https://github.com/unjs/consola)
 
-## 📄 License
+## License
 
-💖 MIT © [blefnk (Nazar Kornienko)](https://github.com/blefnk)
+💖 MIT © 2025 [blefnk Nazar Kornienko](https://github.com/blefnk)

package/bin/{core-impl/deprecated → deprecated}/components/levels/levels.d.ts

@@ -1,4 +1,4 @@
-import type { LogObject, LogTypeDeprecated } from "../../../../core-types.js";
+import type { LogObject, LogTypeDeprecated } from "../../types.js";
 /**
  * A mapping of `LogTypeDeprecated` to its corresponding numeric log level.
  *

package/bin/{core-impl/deprecated → deprecated}/components/modes/basic.d.ts

@@ -1,5 +1,5 @@
 import type { RelinkaInstanceDeprecated } from "../relinka-deprecated/relinka.js";
-import type { RelinkaOptionsDeprecated } from "../../../../core-types.js";
+import type { RelinkaOptionsDeprecated } from "../../types.js";
 export * from "./shared.js";
 /**
  * Factory function to create a new Relinka instance

package/bin/{core-impl/deprecated → deprecated}/components/modes/browser.d.ts

@@ -1,4 +1,4 @@
-import type { RelinkaOptionsDeprecated } from "../../../../core-types.js";
+import type { RelinkaOptionsDeprecated } from "../../types.js";
 import { type RelinkaInstanceDeprecated } from "../relinka-deprecated/relinka.js";
 export * from "./shared.js";
 /**

package/bin/deprecated/components/modes/shared.d.ts

@@ -0,0 +1,2 @@
+export { LogTypesDeprecated } from "../levels/levels.js";
+export type * from "../../types.js";

package/bin/deprecated/components/modes/shared.js

@@ -0,0 +1 @@
+export { LogTypesDeprecated } from "../levels/levels.js";

package/bin/{core-impl/deprecated → deprecated}/components/relinka-deprecated/mod.d.ts

@@ -1,4 +1,4 @@
-import type { RelinkaOptionsDeprecated } from "../../../../core-types.js";
+import type { RelinkaOptionsDeprecated } from "../../types.js";
 import type { RelinkaInstanceDeprecated } from "./relinka.js";
 export * from "../modes/shared.js";
 /**

package/bin/{core-impl/deprecated → deprecated}/components/relinka-deprecated/relinka.d.ts

@@ -1,5 +1,5 @@
-import type { LogTypeDeprecated } from "../../../../core-types.js";
-import type { InputLogObject, LogObject, RelinkaOptionsDeprecated, RelinkaReporterDeprecated } from "../../../../core-types.js";
+import type { LogTypeDeprecated } from "../../types.js";
+import type { InputLogObject, LogObject, RelinkaOptionsDeprecated, RelinkaReporterDeprecated } from "../../types.js";
 /**
  * Relinka class for logging management with support for pause/resume, mocking and customizable reporting.
  * Provides flexible logging capabilities including level-based logging, custom reporters and integration options.

package/bin/{core-impl/deprecated → deprecated}/components/reporters/basic.d.ts

@@ -1,4 +1,4 @@
-import type { LogObject, RelinkaReporterDeprecated, FormatOptions, RelinkaOptionsDeprecated } from "../../../../core-types.js";
+import type { LogObject, RelinkaReporterDeprecated, FormatOptions, RelinkaOptionsDeprecated } from "../../types.js";
 export declare class BasicReporter implements RelinkaReporterDeprecated {
     formatStack(stack: string): string;
     formatArgs(args: any[], opts: FormatOptions): string;

package/bin/{core-impl/deprecated → deprecated}/components/reporters/browser.d.ts

@@ -1,4 +1,4 @@
-import type { LogObject } from "../../../../core-types.js";
+import type { LogObject } from "../../types.js";
 export declare class BrowserReporter {
     options: any;
     defaultColor: string;

package/bin/{core-impl/deprecated → deprecated}/components/reporters/fancy.d.ts

@@ -1,5 +1,5 @@
-import type { LogLevelDeprecated, LogTypeDeprecated } from "../../../../core-types.js";
-import type { FormatOptions, LogObject } from "../../../../core-types.js";
+import type { LogLevelDeprecated, LogTypeDeprecated } from "../../types.js";
+import type { FormatOptions, LogObject } from "../../types.js";
 import { BasicReporter } from "./basic.js";
 export declare const TYPE_COLOR_MAP: Partial<Record<LogTypeDeprecated, string>>;
 export declare const LEVEL_COLOR_MAP: Partial<Record<LogLevelDeprecated, string>>;

package/bin/{core-impl/deprecated → deprecated}/components/reporters/fancy.js

@@ -1,9 +1,7 @@
 import { isUnicodeSupported } from "@reliverse/runtime";
 import stringWidth from "string-width";
 import { BasicReporter } from "./basic.js";
-import {
-  box
-} from "../../utils/box.js";
+import { box } from "../../utils/box.js";
 import { colors } from "../../utils/deprecatedColors.js";
 import { parseStack } from "../../utils/error.js";
 import { stripAnsi } from "../../utils/string.js";

package/bin/{core-types.d.ts → deprecated/types.d.ts}

@@ -1,35 +1,3 @@
-/** 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 options for the Relinka logger.
- * All properties are optional to allow for partial configuration.
- * Defaults will be applied during initialization.
- */
-export type RelinkaConfig = {
-    debug?: boolean;
-    dirs?: RelinkaDirsConfig;
-    disableColors?: boolean;
-    logFilePath?: string;
-    saveLogsToFile?: boolean;
-    withTimestamp?: boolean;
-};
-/** Represents information about a log file for cleanup purposes. */
-export type LogFileInfo = {
-    path: string;
-    mtime: number;
-};
-/** Log level types used by the logger. */
-export type LogLevel = "error" | "info" | "success" | "verbose" | "warn";
 /**
  * Defines the level of logs as specific numbers or special number types.
  *

package/bin/impl.d.ts

@@ -0,0 +1,149 @@
+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 = {
+    /**
+     * Symbol to display for this log level.
+     * @see https://symbl.cc
+     */
+    symbol: string;
+    /**
+     * Fallback symbol to use if Unicode is not supported.
+     */
+    fallbackSymbol: string;
+    /**
+     * Color to use for this log level.
+     */
+    color: DefaultColorKeys;
+    /**
+     * Number of spaces after the symbol/fallback
+     */
+    spacing?: number;
+};
+/** Configuration for all log levels. */
+export type LogLevelsConfig = Partial<Record<LogLevel, LogLevelConfig>>;
+/** Log level types used by the logger. */
+export type LogLevel = "error" | "fatal" | "info" | "success" | "verbose" | "warn" | "log";
+/**
+ * Configuration options for the Relinka logger.
+ * All properties are optional to allow for partial configuration.
+ * Defaults will be applied during initialization.
+ */
+export type RelinkaConfig = {
+    /**
+     * Enables verbose (aka debug) mode for detailed logging.
+     *
+     * `true` here works only for end-users of CLIs/libs when theirs developers
+     * has been awaited for user's config via `@reliverse/relinka`'s `await 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;
+    /**
+     * Disables color output in the console.
+     */
+    disableColors?: boolean;
+    /**
+     * Path to the log file.
+     */
+    logFilePath?: string;
+    /**
+     * If true, logs will be saved to a file.
+     */
+    saveLogsToFile?: boolean;
+    /**
+     * Configuration for timestamp in log messages.
+     */
+    timestamp?: {
+        /**
+         * If true, timestamps will be added to log messages.
+         */
+        enabled: boolean;
+        /**
+         * The format for timestamps. Default is YYYY-MM-DD HH:mm:ss.SSS
+         */
+        format?: string;
+    };
+    /**
+     * Allows to customize the log levels.
+     */
+    levels?: LogLevelsConfig;
+    /**
+     * Controls how often the log cleanup runs (in milliseconds)
+     * Default: 10000 (10 seconds)
+     */
+    cleanupInterval?: number;
+    /**
+     * Maximum size of the log write buffer before flushing to disk (in bytes)
+     * Default: 4096 (4KB)
+     */
+    bufferSize?: number;
+    /**
+     * Maximum time to hold logs in buffer before flushing to disk (in milliseconds)
+     * Default: 5000 (5 seconds)
+     */
+    maxBufferAge?: number;
+};
+/** Represents information about a log file for cleanup purposes. */
+export type LogFileInfo = {
+    path: string;
+    mtime: number;
+};
+/**
+ * Promise that resolves once `reconf` loads and merges the config.
+ */
+export declare const relinkaConfig: 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.
+ */
+export declare function relinkaShutdown(): Promise<void>;
+/**
+ * Flushes all log buffers to disk. Used before process exit or on demand.
+ */
+export declare function flushAllLogBuffers(): Promise<void>;
+/**
+ * If something truly impossible happened, log + throw.
+ */
+export declare function shouldNeverHappen(message: string, ...args: unknown[]): never;
+/**
+ * Truncates a string to a specified length, adding "…" if truncated.
+ */
+export declare function truncateString(msg: string, maxLength?: number): string;
+/**
+ * Exhaustiveness check. If we land here, we missed a union case.
+ */
+export declare function casesHandled(unexpectedCase: never): never;
+/**
+ * Logs a message synchronously using the current config.
+ * If type === "fatal", logs a fatal error and throws (never returns).
+ */
+export declare function relinka(type: LogLevel | "clear", message: string, ...args: unknown[]): undefined | never;
+/**
+ * Logs a message asynchronously, waiting for the config to be fully loaded.
+ * If type === "fatal", logs a fatal error and throws (never returns).
+ */
+export declare function relinkaAsync(type: LogLevel, message: string, ...args: unknown[]): Promise<void>;
+/**
+ * Type helper for user config files.
+ */
+export declare function defineConfig(config: Partial<RelinkaConfig>): Partial<RelinkaConfig>;