@reliverse/relinka 1.3.7 → 1.4.0

package/README.md

@@ -1,89 +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("info", ""); // Just prints a 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: [],
@@ -93,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/{relinka-impl/deprecated → deprecated}/components/levels/levels.d.ts

@@ -1,13 +1,13 @@
-import type { LogObject, LogTypeDeprecated } from "../../../../relinka-types.js";
-/**
- * A mapping of `LogTypeDeprecated` to its corresponding numeric log level.
- *
- * @type {Record<LogTypeDeprecated, number>} LogLevelsDeprecated - key-value pairs of log types to their numeric levels. See {@link LogTypeDeprecated}.
- */
-export declare const LogLevelsDeprecated: Record<LogTypeDeprecated, number>;
-/**
- * Maps `LogTypeDeprecated` to a `Partial<LogObject>`, primarily defining the log level.
- *
- * @type {Record<LogTypeDeprecated, Partial<LogObject>>} LogTypesDeprecated - key-value pairs of log types to partial log objects, specifying log levels. See {@link LogTypeDeprecated} and {@link LogObject}.
- */
-export declare const LogTypesDeprecated: Record<LogTypeDeprecated, Partial<LogObject>>;
+import type { LogObject, LogTypeDeprecated } from "../../types.js";
+/**
+ * A mapping of `LogTypeDeprecated` to its corresponding numeric log level.
+ *
+ * @type {Record<LogTypeDeprecated, number>} LogLevelsDeprecated - key-value pairs of log types to their numeric levels. See {@link LogTypeDeprecated}.
+ */
+export declare const LogLevelsDeprecated: Record<LogTypeDeprecated, number>;
+/**
+ * Maps `LogTypeDeprecated` to a `Partial<LogObject>`, primarily defining the log level.
+ *
+ * @type {Record<LogTypeDeprecated, Partial<LogObject>>} LogTypesDeprecated - key-value pairs of log types to partial log objects, specifying log levels. See {@link LogTypeDeprecated} and {@link LogObject}.
+ */
+export declare const LogTypesDeprecated: Record<LogTypeDeprecated, Partial<LogObject>>;

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

@@ -1,19 +1,19 @@
-import type { RelinkaInstanceDeprecated } from "../relinka-deprecated/relinka.js";
-import type { RelinkaOptionsDeprecated } from "../../../../relinka-types.js";
-export * from "./shared.js";
-/**
- * Factory function to create a new Relinka instance
- *
- * @param {Partial<RelinkaOptionsDeprecated & { fancy: boolean }>} [options={}] - Optional configuration options. See {@link RelinkaOptionsDeprecated}.
- * @returns {RelinkaInstanceDeprecated} A new Relinka instance configured with the given options.
- */
-export declare function createRelinkaBaseDeprecated(options?: Partial<RelinkaOptionsDeprecated & {
-    fancy: boolean;
-}>): RelinkaInstanceDeprecated;
-/**
- * Creates and exports a standard instance of Relinka with the default configuration.
- * This instance can be used directly for logging throughout the application.
- *
- * @type {RelinkaInstanceDeprecated} relinka - The default instance of Relinka.
- */
-export declare const relinkaBasicDeprecated: RelinkaInstanceDeprecated;
+import type { RelinkaInstanceDeprecated } from "../relinka-deprecated/relinka.js";
+import type { RelinkaOptionsDeprecated } from "../../types.js";
+export * from "./shared.js";
+/**
+ * Factory function to create a new Relinka instance
+ *
+ * @param {Partial<RelinkaOptionsDeprecated & { fancy: boolean }>} [options={}] - Optional configuration options. See {@link RelinkaOptionsDeprecated}.
+ * @returns {RelinkaInstanceDeprecated} A new Relinka instance configured with the given options.
+ */
+export declare function createRelinkaBaseDeprecated(options?: Partial<RelinkaOptionsDeprecated & {
+    fancy: boolean;
+}>): RelinkaInstanceDeprecated;
+/**
+ * Creates and exports a standard instance of Relinka with the default configuration.
+ * This instance can be used directly for logging throughout the application.
+ *
+ * @type {RelinkaInstanceDeprecated} relinka - The default instance of Relinka.
+ */
+export declare const relinkaBasicDeprecated: RelinkaInstanceDeprecated;

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

@@ -1,19 +1,19 @@
-import type { RelinkaOptionsDeprecated } from "../../../../relinka-types.js";
-import { type RelinkaInstanceDeprecated } from "../relinka-deprecated/relinka.js";
-export * from "./shared.js";
-/**
- * Creates a new Relinka instance configured specifically for browser environments.
- * This function sets up default reporters and a prompt method tailored to the browser's dialogue APIs.
- *
- * @param {Partial<RelinkaOptionsDeprecated>} [options={}] - Optional configuration options.
- * The options can override the default reporter and prompt behavior. See {@link RelinkaOptionsDeprecated}.
- * @returns {RelinkaInstanceDeprecated} A new Relinka instance optimized for use in browser environments.
- */
-export declare function createRelinkaBrowserDeprecatedDeprecated(options?: Partial<RelinkaOptionsDeprecated>): any;
-/**
- * A standard Relinka instance created with browser-specific configurations.
- * This instance can be used throughout a browser-based project.
- *
- * @type {RelinkaInstanceDeprecated} relinka - The default browser-configured Relinka instance.
- */
-export declare const relinkaBrowserDeprecated: RelinkaInstanceDeprecated;
+import type { RelinkaOptionsDeprecated } from "../../types.js";
+import { type RelinkaInstanceDeprecated } from "../relinka-deprecated/relinka.js";
+export * from "./shared.js";
+/**
+ * Creates a new Relinka instance configured specifically for browser environments.
+ * This function sets up default reporters and a prompt method tailored to the browser's dialogue APIs.
+ *
+ * @param {Partial<RelinkaOptionsDeprecated>} [options={}] - Optional configuration options.
+ * The options can override the default reporter and prompt behavior. See {@link RelinkaOptionsDeprecated}.
+ * @returns {RelinkaInstanceDeprecated} A new Relinka instance optimized for use in browser environments.
+ */
+export declare function createRelinkaBrowserDeprecatedDeprecated(options?: Partial<RelinkaOptionsDeprecated>): any;
+/**
+ * A standard Relinka instance created with browser-specific configurations.
+ * This instance can be used throughout a browser-based project.
+ *
+ * @type {RelinkaInstanceDeprecated} relinka - The default browser-configured Relinka instance.
+ */
+export declare const relinkaBrowserDeprecated: RelinkaInstanceDeprecated;

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/{relinka-impl/deprecated → deprecated}/components/relinka-deprecated/logger.d.ts

@@ -1,5 +1,5 @@
-type MessageKind = "log" | "info" | "warn" | "error" | "success";
-type VerboseKind = `${MessageKind}-verbose`;
-type AllKinds = MessageKind | VerboseKind;
-export declare const relinkaDeprecated: (_kind: AllKinds, title: string, content?: string, hint?: string) => void;
-export {};
+type MessageKind = "log" | "info" | "warn" | "error" | "success";
+type VerboseKind = `${MessageKind}-verbose`;
+type AllKinds = MessageKind | VerboseKind;
+export declare const relinkaDeprecated: (_kind: AllKinds, title: string, content?: string, hint?: string) => void;
+export {};

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

@@ -1,20 +1,20 @@
-import type { RelinkaOptionsDeprecated } from "../../../../relinka-types.js";
-import type { RelinkaInstanceDeprecated } from "./relinka.js";
-export * from "../modes/shared.js";
-/**
- * Factory function to create a new Relinka instance tailored for use in different environments.
- * It automatically adjusts logging levels based on environment variables and execution context.
- *
- * @param {Partial<RelinkaOptionsDeprecated & { fancy: boolean }>} [options={}] - Optional configuration options. See {@link RelinkaOptionsDeprecated}.
- * @returns {RelinkaInstanceDeprecated} A new Relinka instance with configurations based on the given options and the execution environment.
- */
-export declare function createRelinkaSharedDeprecated(options?: Partial<RelinkaOptionsDeprecated & {
-    fancy: boolean;
-}>): RelinkaInstanceDeprecated;
-/**
- * A default instance of Relinka, created and configured for immediate use.
- * This instance is configured based on the execution environment and the options provided.
- *
- * @type {RelinkaInstanceDeprecated} relinka - The default Relinka instance, ready to use.
- */
-export declare const relinkaInstanceDeprecated: RelinkaInstanceDeprecated;
+import type { RelinkaOptionsDeprecated } from "../../types.js";
+import type { RelinkaInstanceDeprecated } from "./relinka.js";
+export * from "../modes/shared.js";
+/**
+ * Factory function to create a new Relinka instance tailored for use in different environments.
+ * It automatically adjusts logging levels based on environment variables and execution context.
+ *
+ * @param {Partial<RelinkaOptionsDeprecated & { fancy: boolean }>} [options={}] - Optional configuration options. See {@link RelinkaOptionsDeprecated}.
+ * @returns {RelinkaInstanceDeprecated} A new Relinka instance with configurations based on the given options and the execution environment.
+ */
+export declare function createRelinkaSharedDeprecated(options?: Partial<RelinkaOptionsDeprecated & {
+    fancy: boolean;
+}>): RelinkaInstanceDeprecated;
+/**
+ * A default instance of Relinka, created and configured for immediate use.
+ * This instance is configured based on the execution environment and the options provided.
+ *
+ * @type {RelinkaInstanceDeprecated} relinka - The default Relinka instance, ready to use.
+ */
+export declare const relinkaInstanceDeprecated: RelinkaInstanceDeprecated;