@reliverse/relinka 1.4.0 → 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

@@ -2,11 +2,9 @@
 
 [💖 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 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.
+**@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.
 
-Whether you're building CLI tools, SDKs, or full-stack apps — Relinka helps you log with intention.
-
-## ✨ Why Relinka
+## Why Relinka
 
 - 🧙 Drop-in replacement for `node:console`, `consola`, or your internal logger
 - 💬 Supports: `info`, `warn`, `success`, `error`, `verbose`, `fatal`, `clear`
@@ -19,13 +17,13 @@ Whether you're building CLI tools, SDKs, or full-stack apps — Relinka helps yo
 
 ## Getting Started
 
-### 2️⃣ Install
+### 1. Install
 
 ```bash
 bun add @reliverse/relinka
 ```
 
-### 2️⃣ Use It
+### 2. Use It
 
 #### Direct Method (Recommended)
 
@@ -50,6 +48,7 @@ import {
   relinkaConfig,
   relinkaShutdown,
 } from "@reliverse/relinka";
+
 export async function main() {
   await relinkaAsync(
     // this automatically loads the config
@@ -74,17 +73,24 @@ export async function main() {
   //   "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();
 ```
 
 #### [🔜 Soon] Singleton Method
 
 ```ts
-const logger = initRelinkaInstance();
+const logger = initRelinkaInstance({/* per-project config */}); 
 logger("info", "Looks great!");
 ```
 
@@ -267,14 +273,18 @@ defineConfig({ ... }) // helper for relinka.config.ts
 - [x] Log rotation
 - [x] `fatal` type
 - [x] Runtime config
-- [ ] CLI interface (to manage logs, config, etc.)
+- [ ] Implement per-project config redefinition
 - [ ] Plugin support (custom formatters, hooks)
+- [ ] CLI interface (to manage logs, config, etc)
 
-## Thanks
+## Shoutouts
 
-Relinka's DX design was inspired by this gem:
+Relinka wouldn't exist without these gems:
 
-- [unjs/consola](https://github.com/unjs/consola)
+- [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
 

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/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/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);
 }

package/bin/impl.d.ts

@@ -108,9 +108,7 @@ export type LogFileInfo = {
     path: string;
     mtime: number;
 };
-/**
- * Promise that resolves once `reconf` loads and merges the config.
- */
+/** Promise resolved once the user's config (if any) is merged. */
 export declare const relinkaConfig: Promise<RelinkaConfig>;
 /**
  * Shuts down the logger, flushing all buffers and clearing timers.

package/bin/impl.js

@@ -4,7 +4,7 @@ import fs from "fs-extra";
 import os from "node:os";
 import path from "pathe";
 const ENABLE_DEV_DEBUG = false;
-const activeTimers = [];
+const EXIT_GUARD = Symbol.for("relinka.exitHandlersRegistered");
 const DEFAULT_RELINKA_CONFIG = {
   verbose: false,
   dirs: {
@@ -90,13 +90,14 @@ function isUnicodeSupported() {
 let currentConfig = { ...DEFAULT_RELINKA_CONFIG };
 let isConfigInitialized = false;
 let resolveRelinkaConfig;
-export const relinkaConfig = new Promise((resolve) => {
-  resolveRelinkaConfig = resolve;
+export const relinkaConfig = new Promise((res) => {
+  resolveRelinkaConfig = res;
 });
 const logBuffers = /* @__PURE__ */ new Map();
+const activeTimers = [];
+let bufferFlushTimer = null;
 let lastCleanupTime = 0;
 let cleanupScheduled = false;
-let bufferFlushTimer = null;
 async function initializeConfig() {
   try {
     const result = await loadConfig({
@@ -110,55 +111,42 @@ async function initializeConfig() {
     });
     currentConfig = result.config;
     isConfigInitialized = true;
+    resolveRelinkaConfig?.(currentConfig);
+    resolveRelinkaConfig = void 0;
     if (ENABLE_DEV_DEBUG) {
       console.log("[Dev Debug] Config file used:", result.configFile);
       console.log("[Dev Debug] All merged layers:", result.layers);
       console.log("[Dev Debug] Final configuration:", currentConfig);
     }
-    if (resolveRelinkaConfig) {
-      resolveRelinkaConfig(currentConfig);
-      resolveRelinkaConfig = void 0;
-    }
-    setupBufferFlushTimer();
   } catch (err) {
     console.error(
       `[Relinka Config Error] Failed to load config: ${err instanceof Error ? err.message : String(err)}`
     );
     currentConfig = { ...DEFAULT_RELINKA_CONFIG };
     isConfigInitialized = true;
-    if (resolveRelinkaConfig) {
-      resolveRelinkaConfig(currentConfig);
-      resolveRelinkaConfig = void 0;
-    }
+    resolveRelinkaConfig?.(currentConfig);
+    resolveRelinkaConfig = void 0;
+  } finally {
     setupBufferFlushTimer();
   }
 }
 function setupBufferFlushTimer() {
   if (bufferFlushTimer) {
     clearInterval(bufferFlushTimer);
-    const index = activeTimers.indexOf(bufferFlushTimer);
-    if (index !== -1) {
-      activeTimers.splice(index, 1);
-    }
+    activeTimers.splice(activeTimers.indexOf(bufferFlushTimer), 1);
   }
-  const maxBufferAge = getMaxBufferAge(currentConfig);
-  bufferFlushTimer = setInterval(
-    () => {
-      const now = Date.now();
-      for (const [filePath, buffer] of logBuffers.entries()) {
-        if (buffer.entries.length > 0 && now - buffer.lastFlush >= maxBufferAge) {
-          flushLogBuffer(currentConfig, filePath).catch((err) => {
-            console.error(
-              `[Relinka Buffer Flush Error] Failed to flush aged buffer: ${err instanceof Error ? err.message : String(err)}`
-            );
-          });
-        }
-      }
-    },
-    Math.min(maxBufferAge / 2, 2500)
-    // Check at least every 2.5 seconds or half the max age
-  );
+  const maxAge = getMaxBufferAge(currentConfig);
+  bufferFlushTimer = setInterval(flushDueBuffers, Math.min(maxAge / 2, 2500));
+  bufferFlushTimer.unref();
   activeTimers.push(bufferFlushTimer);
+  function flushDueBuffers() {
+    const now = Date.now();
+    for (const [fp, buf] of logBuffers) {
+      if (buf.entries.length && now - buf.lastFlush >= maxAge) {
+        flushLogBuffer(currentConfig, fp).catch(console.error);
+      }
+    }
+  }
 }
 initializeConfig().catch((err) => {
   console.error(
@@ -352,10 +340,14 @@ async function deleteFiles(filePaths, config) {
     );
   }
 }
+let sigintHandler;
+let sigtermHandler;
 export async function relinkaShutdown() {
   activeTimers.forEach((timer) => clearTimeout(timer));
   activeTimers.length = 0;
   cleanupScheduled = false;
+  if (sigintHandler) process.off("SIGINT", sigintHandler);
+  if (sigtermHandler) process.off("SIGTERM", sigtermHandler);
   await flushAllLogBuffers();
 }
 async function cleanupOldLogFiles(config) {
@@ -380,6 +372,7 @@ async function cleanupOldLogFiles(config) {
           }
         });
       }, delay);
+      timer.unref();
       activeTimers.push(timer);
     }
     return;
@@ -502,6 +495,23 @@ export function casesHandled(unexpectedCase) {
     `A case was not handled for value: ${truncateString(String(unexpectedCase ?? "unknown"))}`
   );
 }
+function registerExitHandlers() {
+  if (globalThis[EXIT_GUARD]) return;
+  globalThis[EXIT_GUARD] = true;
+  process.once("beforeExit", () => {
+    flushAllLogBuffers().catch(() => {
+    });
+  });
+  sigintHandler = () => {
+    flushAllLogBuffers().finally(() => process.exit(0));
+  };
+  sigtermHandler = () => {
+    flushAllLogBuffers().finally(() => process.exit(0));
+  };
+  process.once("SIGINT", sigintHandler);
+  process.once("SIGTERM", sigtermHandler);
+}
+registerExitHandlers();
 export function relinka(type, message, ...args) {
   if (type === "clear") {
     console.clear();
@@ -588,19 +598,3 @@ export async function relinkaAsync(type, message, ...args) {
 export function defineConfig(config) {
   return config;
 }
-process.on("beforeExit", () => {
-  flushAllLogBuffers().catch(() => {
-  });
-});
-process.on("SIGINT", () => {
-  flushAllLogBuffers().catch(() => {
-  }).finally(() => {
-    process.exit(0);
-  });
-});
-process.on("SIGTERM", () => {
-  flushAllLogBuffers().catch(() => {
-  }).finally(() => {
-    process.exit(0);
-  });
-});

package/bin/main.d.ts

@@ -14,7 +14,7 @@ export { box } from "./deprecated/utils/box.js";
 export type { ColorName, ColorFunction, } from "./deprecated/utils/deprecatedColors.js";
 export { colors, getColor, colorize, } from "./deprecated/utils/deprecatedColors.js";
 export { parseStack } from "./deprecated/utils/error.js";
-export { compileFormat, formatString, } from "./deprecated/utils/format.js";
+export { compileFormatCompat, formatStringCompat, } from "./deprecated/utils/format.js";
 export { isPlainObject, isLogObj } from "./deprecated/utils/log.js";
 export { writeStream } from "./deprecated/utils/stream.js";
 export { stripAnsi, centerAlign, rightAlign, leftAlign, align, } from "./deprecated/utils/string.js";

package/bin/main.js

@@ -35,8 +35,8 @@ export {
 } from "./deprecated/utils/deprecatedColors.js";
 export { parseStack } from "./deprecated/utils/error.js";
 export {
-  compileFormat,
-  formatString
+  compileFormatCompat,
+  formatStringCompat
 } from "./deprecated/utils/format.js";
 export { isPlainObject, isLogObj } from "./deprecated/utils/log.js";
 export { writeStream } from "./deprecated/utils/stream.js";

package/package.json

@@ -1,12 +1,12 @@
 {
   "dependencies": {
     "@reliverse/relico": "^1.1.0",
+    "@reliverse/repris": "^1.0.0",
     "@reliverse/runtime": "^1.0.3",
     "c12": "^3.0.3",
     "defu": "^6.1.4",
     "fs-extra": "^11.3.0",
     "pathe": "^2.0.3",
-    "printj": "^1.3.1",
     "std-env": "^3.9.0",
     "string-width": "^7.2.0"
   },
@@ -15,7 +15,7 @@
   "license": "MIT",
   "name": "@reliverse/relinka",
   "type": "module",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "keywords": [
     "logger",
     "consola",
@@ -34,22 +34,23 @@
   ],
   "devDependencies": {
     "@biomejs/biome": "1.9.4",
-    "@eslint/js": "^9.24.0",
+    "@eslint/js": "^9.25.1",
     "@reliverse/relidler-cfg": "^1.1.3",
     "@stylistic/eslint-plugin": "^4.2.0",
     "@total-typescript/ts-reset": "^0.6.1",
-    "@types/bun": "^1.2.9",
+    "@types/bun": "^1.2.10",
     "@types/fs-extra": "^11.0.4",
-    "@types/node": "^22.14.1",
+    "@types/node": "^22.15.2",
     "@types/sentencer": "^0.2.3",
-    "eslint": "^9.24.0",
+    "eslint": "^9.25.1",
     "eslint-plugin-no-relative-import-paths": "^1.6.1",
-    "eslint-plugin-perfectionist": "^4.11.0",
+    "eslint-plugin-perfectionist": "^4.12.3",
     "jiti": "^2.4.2",
-    "knip": "^5.50.2",
+    "knip": "^5.50.5",
     "sentencer": "^0.2.1",
+    "tsx": "^4.19.3",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.29.1"
+    "typescript-eslint": "^8.31.0"
   },
   "exports": {
     ".": "./bin/main.js"