📦 hbh-logrotator

A lightweight, extensible JSON log rotation library for Node.js. Designed for high-volume logging with automatic file rotation, flat JSON logs, or grouped JSON logs.

---

✨ Features

• 🔁 Automatic log rotation

  • Rotate by max number of entries
  • Rotate by time interval

• 📄 Flat JSON logging

  • Logs stored as a JSON array

• 🧩 Grouped JSON logging

  • Logs grouped by event type or custom key

• ⚙️ Extensible base class

  • Create custom log formats easily

• 🚀 Zero dependencies

• 🧠 Efficient streaming using fs.createWriteStream

---

📥 Installation

          
            1npm install hbh-logrotator
          
        

---

📌 Exports

          
            1import { FlatJSON, GroupedJSON, Base } from 'hbh-logrotator';
          
        

---

🛠️ Usage

1️⃣ Flat JSON Logger

Logs entries as a JSON array:

          
            1[2  { "event": "login", "user": "alice" },3  { "event": "logout", "user": "bob" }4]
          
        

Example

          
            1import { FlatJSON } from 'hbh-logrotator';3const logger = new FlatJSON('./logs', {4  maxEntries: 35});7logger.write({ event: 'login', user: 'alice' });8logger.write({ event: 'logout', user: 'bob' });9logger.write({ event: 'login', user: 'charlie' });
          
        

➡️ Automatically rotates after 3 entries.

---

2️⃣ Grouped JSON Logger

Groups logs by event (or a custom key):

          
            1{2  "login": [3    { "event": "login", "user": "alice" }4  ],5  "logout": [6    { "event": "logout", "user": "bob" }7  ]8}
          
        

Example

          
            1import { GroupedJSON } from 'hbh-logrotator';3const logger = new GroupedJSON('./logs', {4  maxEntries: 5,5  eventKey: 'event'6});8logger.write({ event: 'login', user: 'alice' });9logger.write({ event: 'logout', user: 'bob' });
          
        

---

⚙️ Configuration Options

---

🔁 Rotation Logic

A new log file is created when either condition is met:

• currentEntries >= maxEntries
• Date.now() - lastRotationTime >= rotationIntervalMs

Files are named automatically:

          
            1log_0.json2log_1.json3log_2.json4...
          
        

---

🧱 BaseLogRotator (Advanced Usage)

You can extend the base class to create custom log formats.

          
            1import { Base } from 'hbh-logrotator';3class CustomRotator extends Base {4  initFile() {5    this.currentStream.write('START\n');6  }8  handleEntry(entry) {9    this.currentStream.write(entry.message + '\n');10  }12  finalizeFile() {13    this.currentStream.write('END\n');14  }15}
          
        

---

🧹 Graceful Shutdown

Call flush() before exiting your app:

          
            1await logger.flush();
          
        

Ensures:

• JSON is closed properly
• File streams are safely ended

---

📂 Output Guarantees

---

🧪 Use Cases

• API request logging
• Event tracking
• Audit logs
• Background jobs
• Serverless environments
• Data pipelines

---

📜 License

ISC License © HBH

---

• Node.js log rotation
• JSON logging
• Log file rotation
• Structured logging
• Event-based logging
• Lightweight logger
• File-based logging