@reliverse/relinka 1.3.8 → 1.4.1

package/LICENSE

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright (c) 2025 blefnk Nazar Kornienko
+Copyright (c) 2025 Nazar Kornienko (blefnk), Reliverse
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,21 +1,21 @@
-# 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. Whether you're building CLI tools, SDKs, or full-stack apps — Relinka helps you log with intention.
 
-## 🌟 Features
+## Why Relinka
 
-- 🧙 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
+- 🧙 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
 
-## 🚀 Getting Started
+## Getting Started
 
 ### 1. Install
 
@@ -23,68 +23,173 @@
 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();
+
+  // Make sure to exit the program after your CLI is done
+  // It's not required for Bun-only apps, but recommended
+  // for other runtimes, esp. for Node.js (incl. `tsx`)
+  process.exit(0);
 }
+
 await main();
 ```
 
-## 🧪 Advanced Usage
+#### [🔜 Soon] Singleton Method
+
+```ts
+const logger = initRelinkaInstance({/* per-project config */}); 
+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 +199,93 @@ 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
+- [ ] Implement per-project config redefinition
+- [ ] Plugin support (custom formatters, hooks)
+- [ ] CLI interface (to manage logs, config, etc)
 
-## 🙌 Shoutout
+## Shoutouts
 
-Relinka was inspired by this gem:
+Relinka wouldn't exist without these gems:
 
-- [unjs/consola](https://github.com/unjs/consola#readme)
+- [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)
 
-## 📄 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/deprecated/utils/format-new.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Compiles a format string with named or positional arguments to a standard format string.
+ * Uses @reliverse/repris's built-in compileFormat.
+ * @param {string} format - The format string containing named placeholders.
+ * @returns {string} The compiled format string with positional indices.
+ */
+export declare function compile(format: string): string;
+/**
+ * Formats a string using either an array or an object of arguments.
+ * Uses @reliverse/repris's built-in formatString.
+ * @param {string} format - The format string (named or positional).
+ * @param {any[] | Record<string, unknown>} args - Arguments to format into the string.
+ * @returns {string} The formatted string.
+ */
+export declare function formatStr(format: string, args: any[] | Record<string, unknown>): string;

package/bin/deprecated/utils/format-new.js

@@ -0,0 +1,13 @@
+import { compileFormat, formatString } from "@reliverse/repris";
+const _compileCache = {};
+export function compile(format) {
+  if (_compileCache[format]) {
+    return _compileCache[format];
+  }
+  const compiled = compileFormat(format);
+  _compileCache[format] = compiled;
+  return compiled;
+}
+export function formatStr(format, args) {
+  return formatString(format, args);
+}

package/bin/{core-impl/deprecated → deprecated}/utils/format.d.ts

@@ -4,11 +4,11 @@
  * @param {string} format - The format string containing the placeholders to replace.
  * @returns {string} The compiled format string with placeholders replaced by positional indices.
  */
-export declare function compileFormat(format: string): any;
+export declare function compileFormatCompat(format: string): string;
 /**
  * Formats a string according to a custom format, using vsprintf for string formatting.
  * @param {string} format - The custom format string.
  * @param {any[]} argv - The arguments to format into the string.
  * @returns {string} The formatted string.
  */
-export declare function formatString(format: string, argv: any): string;
+export declare function formatStringCompat(format: string, argv: any): string;

package/bin/{core-impl/deprecated → deprecated}/utils/format.js

@@ -1,4 +1,4 @@
-import { vsprintf } from "printj";
+import { vsprintf } from "@reliverse/repris";
 const FORMAT_ARGS = [
   ["additional", 5],
   ["message", 4],
@@ -7,7 +7,7 @@ const FORMAT_ARGS = [
   ["tag", 3]
 ];
 const _compileCache = {};
-export function compileFormat(format) {
+export function compileFormatCompat(format) {
   if (_compileCache[format]) {
     return _compileCache[format];
   }
@@ -21,6 +21,6 @@ export function compileFormat(format) {
   _compileCache[format] = _format;
   return _format;
 }
-export function formatString(format, argv) {
-  return vsprintf(compileFormat(format), argv);
+export function formatStringCompat(format, argv) {
+  return vsprintf(compileFormatCompat(format), argv);
 }