logsave-hub 🚀

logsave-hub is an ethical, easy-to-use logging utility for Node.js that supports both automatic console logging and explicit log APIs, with full ESM + CommonJS compatibility.

It is designed to be:

• ✅ Beginner-friendly
• ✅ Explicit & ethical (no hidden side effects)
• ✅ Works in both ESM and CJS
• ✅ Production-ready
• ✅ Built with TypeScript

---

✨ Features

• 📁 Automatically creates a log directory
• 🕒 Timestamped daily log files
• 🖥 Optional console.log / warn / error override
• ✍️ Explicit logging API (log.save, log.warn, log.error)
• 🔄 Works in ESM and CommonJS
• 🔒 No cloud upload, no data sharing — local only
• 🗑 Automatic log retention & cleanup (optional, default: 30 days)
• 📊 Built-in live web dashboard for real-time log viewing
• 🔌 Easy integration with Express + Socket.IO via dashboardRouter and attachDashboard

---

📦 Installation

Install using npm:

npm install logsave-hub

You'll also need express and socket.io if you want to use the live dashboard:

npm install express socket.io

---

🚀 Basic Usage

logsave-hub exposes two modes:

1. Console override mode (automatic)
2. Explicit logging mode (log.save())

You must explicitly initialize logging using enableLogging().

---

1️⃣ Console Override Mode (Automatic Logging)

In this mode, all console.log, console.warn, and console.error are automatically written to log files.

▶️ ESM Example

import enableLogging from "logsave-hub";

enableLogging({
  override: true,
  outDir: "./logs"
});

console.log("Server started");
console.warn("Low memory");
console.error("Something went wrong");

---

▶️ CommonJS Example

const enableLogging = require("logsave-hub");

enableLogging({
  override: true,
  outDir: "./logs"
});

console.log("Server started");
console.warn("Low memory");
console.error("Something went wrong");

---

2️⃣ Explicit Logging Mode (log.save())

In this mode, the console is not overridden. You explicitly control what gets logged.

▶️ ESM Example

import enableLogging, { log } from "logsave-hub";

enableLogging({
  override: false,
  outDir: "./logs"
});

log.save("Application started");
log.warn("Cache is almost full");
log.error("Database connection failed");

---

▶️ CommonJS Example

const enableLogging = require("logsave-hub");
const { log } = require("logsave-hub");

enableLogging({
  override: false,
  outDir: "./logs"
});

log.save("Application started");
log.warn("Cache is almost full");
log.error("Database connection failed");

---

🗂 Log Output

Logs are written to the specified directory (default: ./logs):

logs/
└─ app-2025-12-19.log

Example log content:

2025-12-19 17:16:21 [INFO] Server started
2025-12-19 17:16:31 [WARN] Cache is almost full
2025-12-19 17:16:41 [ERROR] Database connection failed

---

🗑 Log Retention

logsave-hub can automatically clean up old log files so your logs directory doesn't grow indefinitely.

• Retention period: 30 days by default when enabled
• Runs once on startup, then on a recurring schedule
• Fails silently — retention cleanup will never crash your app
• Disable it by setting retention: false

---

📊 Live Web Dashboard

logsave-hub ships with a built-in real-time dashboard for viewing your logs in the browser — just mount the router and attach it to a Socket.IO server.

Features:

• 🔴 Live streaming of new log entries via WebSockets
• 📁 Browse and view historical daily log files
• 🔍 Search and filter logs by level (Info / Warn / Error)
• 📈 Live session stats (total / info / warn / error counts)
• 📱 Responsive layout for desktop and mobile

▶️ ESM Example

import express from "express";
import { Server } from "socket.io";
import http from "http";
import enableLogging, { attachDashboard, dashboardRouter } from "logsave-hub";

const app = express();
const server = http.createServer(app);
const io = new Server(server);

attachDashboard(io);
app.use("/logsave-hub", dashboardRouter);

enableLogging({
  override: true,
  outDir: "./logs",
  retention: false
});

server.listen(3000, () => {
  console.log("Listening on port 3000");
});

console.log("Server started");
console.warn("Server started");
console.error("Server started");

---

▶️ CommonJS Example

const enableLogging = require("logsave-hub").default;
const { log, dashboardRouter, attachDashboard } = require("logsave-hub");
const express = require("express");
const { Server } = require("socket.io");
const http = require("http");

const app = express();
const server = http.createServer(app);
const io = new Server(server);

attachDashboard(io);
app.use("/logsave-hub", dashboardRouter);

enableLogging({
  override: true,
  outDir: "./logs",
  retention: true,
});

console.log("Server started");
console.warn("Server started");
console.error("Server started");

server.listen(3000);

setInterval(() => {
  log.save("Ping at", new Date().toISOString());
  log.warn("Ping at", new Date().toISOString());
  log.error("Ping at", new Date().toISOString());
}, 10000);

Once running, open http://localhost:3000/logsave-hub (or whichever path you mounted the router on) to view the live dashboard.

---

⚙️ Configuration Options

enableLogging({
  override?: boolean;   // default: true
  outDir?: string;      // default: "./logs"
  retention?: boolean;  // default: true
});

Option	Description
override	Whether to override console.log
outDir	Directory where logs are stored
retention	Whether to automatically purge old log files

---

❗ Important Notes

• enableLogging() must be called before using log.save()
• Calling enableLogging() multiple times is safe
• Logs are stored locally only
• No network, no cloud, no tracking

---

🧠 Why logsave-hub?

Many loggers either:

• Are too complex ❌
• Don't support both ESM & CJS ❌

logsave-hub is designed to be:

• Explicit
• Predictable
• Easy to integrate
• Safe for beginners and professionals

---

🧪 Supported Environments

• Node.js 20+
• Node.js 22+
• Node.js 24+

---

📜 License

MIT © Koda Adam

---

❤️ Contributing

Pull requests and suggestions are welcome. This package is built for the community.