zario 0.3.5 → 0.4.0

package/README.md

@@ -1,359 +1,102 @@
-# zario
-
-A minimal, fast logging library for Node.js with TypeScript support.
-
-## What's New in 0.3.5
-
-- Added advanced filtering capabilities with LevelFilter, PrefixFilter, MetadataFilter, CompositeFilter, OrFilter, and PredicateFilter
-- Added structured logging extensions with LogEnrichmentPipeline and MetadataEnricher
-- Added TimeBasedAggregator.stop() method for proper timer cleanup
-- Improved error handling for aggregators and filters with try-catch protection
-- Enhanced thread safety with defensive copying of filters during iteration
-- Fixed enricher inheritance in child loggers
-- Added documentation for empty array behavior in CompositeFilter (allows all) and OrFilter (blocks all)
-- Added note about strict equality in MetadataFilter for complex objects
-
-## What's New in 0.2.11
-
-- Added HTTP transport support with new HttpTransport class
-- Added log batching functionality for efficient writes
-- Added compression support (.gz for gzip, .zz for deflate) for rotated files
-- Enhanced rotation with maxSize, maxFiles, and configurable compression
-
-## Installation
-
-```bash
-npm install zario
-```
-
-## Quick Start
-
-```js
-import { Logger, ConsoleTransport } from "zario";
-
-const logger = new Logger({
-  level: "info",
-  colorize: true,
-  transports: [new ConsoleTransport()],
-  prefix: "[MyApp]",
-});
-
-// Start logging
-logger.info("🚀 Server started on port 3000");
-logger.warn("⚠️ High memory usage detected");
-logger.error("❌ Database connection failed", { code: 500 });
-```
-
-## API Documentation
-
-### Logger Constructor Options
-
-| Option         | Type     | Description             |
-| -------------- | -------- | ----------------------- |
-| **level**      | `string` | Log level threshold     |
-| **json**       | `boolean`| Output in JSON format   |
-| **timestamp**  | `boolean`| Include timestamps      |
-| **prefix**     | `string` | Prepended label         |
-| **transports** | `array`  | Where logs are written (with transport-specific options like `path`, `maxSize`, `maxFiles`, `compression`, `batchInterval`, `compressOldFiles` for file transport) |
-| **customLevels** | `object` | Define custom log levels and their priorities |
-| **customColors** | `object` | Assign colors to custom log levels |
-| **filters** | `Filter[]` | Array of filters to apply before logging (LevelFilter, PrefixFilter, MetadataFilter, CompositeFilter, OrFilter, PredicateFilter) |
-| **aggregators** | `LogAggregator[]` | Array of log aggregators (BatchAggregator, TimeBasedAggregator, CompositeAggregator) |
-| **enrichers** | `LogEnrichmentPipeline` | Pipeline for structured logging extensions |
-
-### Log Levels
-
-| Level    | Method        | Use Case                   |
-|----------|---------------|----------------------------|
-| 🔍 DEBUG  | `logger.debug()` | Detailed debugging info    |
-| ✨ INFO   | `logger.info()`  | General information       |
-| ⚠️ WARN   | `logger.warn()`  | Warning messages          |
-| ❌ ERROR  | `logger.error()` | Error messages            |
-| 🤫 SILENT | `logger.silent()`| Not output to console     |
-| 📝 BORING | `logger.boring()`| Lowest priority messages  |
-
-### Transports
-
-#### Console Transport
-
-```js
-import { Logger, ConsoleTransport } from "zario";
-
-const logger = new Logger({
-  transports: [
-    new ConsoleTransport({ colorize: true })
-  ]
-});
-```
-
-#### File Transport
-
-```js
-import { Logger, FileTransport } from "zario";
-
-const logger = new Logger({
-  transports: [
-    new FileTransport({
-      path: './logs/app.log',
-      maxSize: 10485760, // 10MB in bytes
-      maxFiles: 5,
-      compression: 'gzip', // 'gzip', 'deflate', or 'none' (default: 'none')
-      batchInterval: 1000, // Batch interval in ms (0 to disable, default: 0)
-      compressOldFiles: true // Whether to compress old files during rotation (default: true)
-    })
-  ]
-});
-```
-
-#### HTTP Transport
-
-```js
-import { Logger, HttpTransport } from "zario";
-
-const logger = new Logger({
-  transports: [
-    new HttpTransport({
-      url: 'https://api.example.com/logs',
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'Authorization': 'Bearer your-token-here'
-      },
-      timeout: 10000,  // Request timeout in ms
-      retries: 3       // Number of retry attempts
-    })
-  ]
-});
-```
-
-### Advanced Filtering
-
-Filter logs based on various criteria using built-in filter classes:
-
-```js
-import {
-  Logger,
-  ConsoleTransport,
-  LevelFilter,
-  PrefixFilter,
-  MetadataFilter,
-  CompositeFilter,
-  OrFilter,
-  PredicateFilter
-} from "zario";
-
-// Level filter - only allow specific log levels
-const levelFilter = new LevelFilter(['info', 'error']);
-
-// Prefix filter - only allow logs with specific prefixes
-const prefixFilter = new PrefixFilter(['[API]', '[DB]']);
-
-// Metadata filter - only allow logs with specific metadata
-const metadataFilter = new MetadataFilter({ userId: 123 });
-
-// Composite filter - combines multiple filters with AND logic
-// Note: With an empty array, CompositeFilter allows all logs (vacuous truth)
-const compositeFilter = new CompositeFilter([levelFilter, prefixFilter]);
-
-// Or filter - combines multiple filters with OR logic
-// Note: With an empty array, OrFilter blocks all logs (no matching conditions)
-const orFilter = new OrFilter([levelFilter, metadataFilter]);
-
-// Predicate filter - custom filtering function
-const predicateFilter = new PredicateFilter((logData) => {
-  return logData.level !== 'debug'; // Filter out debug messages
-});
-
-// Create logger with filters
-const filteredLogger = new Logger({
-  level: 'debug',
-  transports: [new ConsoleTransport()],
-  filters: [compositeFilter, predicateFilter] // Apply multiple filters
-});
-```
-
-### Structured Logging Extensions
-
-Enhance your logs with additional metadata using structured logging extensions:
-
-```js
-import {
-  Logger,
-  ConsoleTransport,
-  LogEnrichmentPipeline,
-  MetadataEnricher
-} from "zario";
-
-// Create enrichers to add metadata to logs
-const staticEnricher = MetadataEnricher.addStaticFields({
-  service: 'user-service',
-  version: '1.0.0'
-});
-
-const dynamicEnricher = MetadataEnricher.addDynamicFields(() => ({
-  processId: process.pid,
-  memoryUsage: process.memoryUsage().heapUsed
-}));
-
-const processEnricher = MetadataEnricher.addProcessInfo();
-const envEnricher = MetadataEnricher.addEnvironmentInfo();
-
-// Create a pipeline with multiple enrichers
-const enricherPipeline = new LogEnrichmentPipeline([
-  staticEnricher,
-  dynamicEnricher,
-  processEnricher,
-  envEnricher
-]);
-
-// Create logger with enrichers
-const enrichedLogger = new Logger({
-  level: 'info',
-  transports: [new ConsoleTransport()],
-  enrichers: enricherPipeline
-});
-
-enrichedLogger.info('User login', { userId: 123 });
-// Output will include additional metadata fields
-
-// Add enrichers dynamically
-enrichedLogger.addEnricher((logData) => {
-  return {
-    ...logData,
-    timestamp: new Date().toISOString(),
-    additionalField: 'some-value'
-  };
-});
-```
-
-### Log Aggregation
-
-Aggregate logs in batches or based on time intervals:
-
-```js
-import {
-  Logger,
-  ConsoleTransport,
-  BatchAggregator,
-  TimeBasedAggregator,
-  CompositeAggregator
-} from "zario";
-
-// Batch aggregator - flushes when batch size is reached
-const batchAggregator = new BatchAggregator(10, (logs) => {
-  // Process batch of 10 logs
-  console.log(`Processing ${logs.length} logs`);
-});
-
-// Time-based aggregator - flushes after time interval
-const timeAggregator = new TimeBasedAggregator(5000, (logs) => {
-  // Process logs every 5 seconds
-  console.log(`Processing ${logs.length} logs`);
-});
-
-// Create logger with aggregators
-const aggregatedLogger = new Logger({
-  level: 'info',
-  transports: [new ConsoleTransport()],
-  aggregators: [batchAggregator]
-});
-
-// Manually flush aggregators
-aggregatedLogger.flushAggregators();
-
-// Stop time-based aggregator timer
-// timeAggregator.stop(); // Available for TimeBasedAggregator
-```
-
-### Methods
-
-- `logger.debug(message, metadata?)` - Debug level logging
-- `logger.info(message, metadata?)` - Info level logging
-- `logger.warn(message, metadata?)` - Warning level logging
-- `logger.error(message, metadata?)` - Error level logging
-- `logger.logWithLevel(level, message, metadata?)` - Log a message at an arbitrary/custom level
-- `logger.createChild(options)` - Creates a child logger with inherited settings
-- `logger.setLevel(level)` - Change the logger level at runtime
-- `logger.setFormat(format)` - Set the output format to text or json
-- `logger.addFilter(filter)` - Add a filter to the logger (LevelFilter, PrefixFilter, MetadataFilter, etc.)
-- `logger.removeFilter(filter)` - Remove a filter from the logger
-- `logger.addAggregator(aggregator)` - Add an aggregator to the logger (BatchAggregator, TimeBasedAggregator, etc.)
-- `logger.removeAggregator(aggregator)` - Remove an aggregator from the logger
-- `logger.flushAggregators()` - Manually flush all aggregators
-- `logger.addEnricher(enricher)` - Add an enricher to the logger for structured logging
-- `logger.startTimer(name)` - Create a performance timer
-
-## Usage Examples
-
-### Basic Usage
-
-```js
-import { Logger, ConsoleTransport } from "zario";
-
-const logger = new Logger({
-  level: "info",
-  colorize: true,
-  transports: [new ConsoleTransport()]
-});
-
-logger.info("Application started");
-logger.error("Something went wrong", { userId: 123 });
-```
-
-### JSON Format
-
-```js
-const logger = new Logger({ json: true });
-```
-
-### Custom Levels & Colors
-
-```js
-import { Logger, ConsoleTransport } from "zario";
-
-const logger = new Logger({
-  level: 'info',
-  customLevels: {
-    'success': 6,      // Higher priority than error (5).
-    'verbose': 1,      // Lower priority than debug (2).
-    'critical': 7,     // Highest priority.
-  },
-  customColors: {
-    'success': 'green',
-    'verbose': 'cyan',
-    'critical': 'brightRed',
-  },
-  transports: [
-    new ConsoleTransport()
-  ]
-});
-
-// Using custom levels.
-logger.logWithLevel('success', 'This is a success message in green!');
-logger.logWithLevel('verbose', 'This is a verbose message in cyan');
-logger.logWithLevel('critical', 'This is a critical message in bright red');
-```
-
-### Child Loggers
-
-```js
-const main = new Logger({ prefix: "[APP]" });
-const db = main.createChild({ prefix: "[DB]" });
-
-main.info("App initialized");
-db.error("Connection timeout");
-```
-
-### Multiple Transports
-
-```js
-import { Logger, ConsoleTransport, FileTransport } from "zario";
-
-const logger = new Logger({
-  level: 'info',
-  transports: [
-    new ConsoleTransport(),
-    new FileTransport({ path: './logs/app.log' })
-  ]
-});
-```
+<div align="center">
+
+<a id="top"></a>
+
+# 📝 Zario
+
+### A Minimal Logging Solution for TypeScript
+
+[![npm version](https://img.shields.io/npm/v/zario?style=for-the-badge&logo=npm&color=CB3837)](https://www.npmjs.com/package/zario)
+[![license](https://img.shields.io/npm/l/zario?style=for-the-badge&color=green)](./LICENSE)
+[![downloads](https://img.shields.io/npm/dt/zario?style=for-the-badge&logo=npm&color=orange)](https://www.npmjs.com/package/zario)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/zario?style=for-the-badge&logo=webpack&color=purple)](https://bundlephobia.com/package/zario)
+![GitHub Workflow Status](https://img.shields.io/github/workflow/status/Dev-Dami/zario?label=build)](https://github.com/Dev-Dami/zario/actions)
+
+**Built on January 8, 2026**
+
+<br/>
+
+**Fast** • **Lightweight** • **Zero Dependencies** • **TypeScript Native**
+
+<br/>
+
+[📖 Documentation](#-documentation) · [⚡ Quick Start](#-quick-start) · [✨ Features](#-features) · [🤝 Contributing](#-contributing)
+
+<br/>
+
+![separator](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png)
+
+</div>
+
+<br/>
+
+## Features
+
+- **Lightweight** — minimal footprint, fast execution
+- **Simple API** — intuitive methods like `info()`, `warn()`, `error()`
+- **Flexible formatting** — plain text or structured JSON
+- **Multiple transports** — Console, File (streaming rotation), HTTP (async retry), CircuitBreaker, and DeadLetterQueue
+- **Child loggers** — scoped logging for modules or requests
+- **Async mode** — non-blocking writes for high-performance applications
+- **Memory safe** — bounded queues and memory-efficient streaming
+- **Customizable** — custom log levels, colors, and filtering
+
+## 📦 Installation
+
+```bash
+npm install zario
+```
+
+## 🚀 Quick Start
+
+```typescript
+import { Logger, ConsoleTransport } from "zario";
+
+const logger = new Logger({
+  level: "info",
+  colorize: true,
+  transports: [new ConsoleTransport()],
+  prefix: "[MyApp]",
+});
+
+logger.info("🚀 Server started on port 3000");
+logger.warn("⚠️ High memory usage detected");
+logger.error("❌ Database connection failed", { code: 500 });
+```
+
+## 📖 Documentation
+
+Documentation:
+
+| Section                                             | Description                                                                   |
+| --------------------------------------------------- | ----------------------------------------------------------------------------- |
+| [📘 **Introduction**](./docs/introduction.md)       | Philosophy, core features, and common use cases.                              |
+| [🚀 **Getting Started**](./docs/getting-started.md) | Detailed installation and environment auto-configuration.                     |
+| [⚙️ **Configuration**](./docs/configuration.md)     | Full reference for all logger options, custom levels, and colors.             |
+| [📖 **API Reference**](./docs/api-reference.md)     | Detailed API documentation for the Logger class and utilities.                |
+| [📁 **Transports**](./docs/transports.md)           | Guide to Console, File, HTTP, CircuitBreaker, and DeadLetterQueue transports. |
+| [🧩 **Advanced Usage**](./docs/advanced-usage.md)   | Filters, Enrichers (Structured Logging), and Aggregators.                     |
+| [📊 **Log Formats**](./docs/log-formats.md)         | Specification for Text and JSON output formats.                               |
+| [🗺️ **Roadmap**](./docs/roadmap.md)                 | Future plans and upcoming features.                                           |
+
+## 🤝 Contributing
+
+We welcome contributions! Whether it's bug reports, feature requests, or code contributions. Please see our [Contributing Guide](./CONTRIBUTING.md) for more details.
+
+## 📄 License
+
+This project is licensed under the **MIT License** - see the [LICENSE](./LICENSE) file for full details.
+
+<br/>
+
+<div align="center">
+
+### Developed for developers
+
+⭐ Star this repository to show your support
+
+</div>
+
+<br/>
+
+[⬆ Back to Top](#top)

package/dist/cjs/aggregation/LogAggregator.js

@@ -1,57 +1,77 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CompositeAggregator = exports.TimeBasedAggregator = exports.BatchAggregator = void 0;
-/**
- * Aggregates logs in memory and flushes them in batches
- */
+//Aggregates logs in memory and flushes them in batches
 class BatchAggregator {
-    constructor(maxSize = 100, flushCallback) {
+    constructor(maxSize = 100, flushCallback, maxQueueSize = 10000) {
         this.logs = [];
+        this.pendingFlush = null;
         this.maxSize = maxSize;
+        this.maxQueueSize = maxQueueSize;
         this.flushCallback = flushCallback;
     }
     aggregate(logData, formatter) {
+        if (this.logs.length >= this.maxQueueSize) {
+            this.logs.shift();
+        }
         this.logs.push({ logData, formatter });
-        if (this.logs.length >= this.maxSize) {
+        if (this.logs.length >= this.maxSize && !this.pendingFlush) {
             const result = this.flush();
-            // Handle the case where flush returns a Promise (async flushCallback)
             if (result instanceof Promise) {
-                result.catch(error => {
-                    console.error('Error in BatchAggregator flush callback:', error);
+                this.pendingFlush = result.finally(() => {
+                    this.pendingFlush = null;
                 });
             }
         }
     }
     flush() {
-        if (this.logs.length > 0) {
-            const logsToFlush = [...this.logs];
-            this.logs = [];
-            return this.flushCallback(logsToFlush);
+        if (this.pendingFlush) {
+            return this.pendingFlush;
+        }
+        if (this.logs.length === 0) {
+            return;
+        }
+        const logsToFlush = [...this.logs];
+        const originalLogs = [...this.logs];
+        this.logs = [];
+        try {
+            const callbackResult = this.flushCallback(logsToFlush);
+            if (callbackResult instanceof Promise) {
+                return callbackResult.catch((error) => {
+                    this.logs = originalLogs;
+                    throw error;
+                });
+            }
+        }
+        catch (error) {
+            this.logs = originalLogs;
+            throw error;
         }
     }
 }
 exports.BatchAggregator = BatchAggregator;
-/**
- * Aggregates logs based on a time interval
- */
+//Aggregates logs based on a time interval
 class TimeBasedAggregator {
-    constructor(flushInterval, // in milliseconds
-    flushCallback) {
+    constructor(flushInterval, flushCallback, maxQueueSize = 10000) {
         this.logs = [];
         this.timer = null;
         this.flushInterval = flushInterval;
+        this.maxQueueSize = maxQueueSize;
         this.flushCallback = flushCallback;
     }
     aggregate(logData, formatter) {
+        if (this.logs.length >= this.maxQueueSize) {
+            this.logs.shift();
+        }
         this.logs.push({ logData, formatter });
-        // Start the timer if it's not already running
+        // Start timer if it's not already running
         if (!this.timer) {
             this.timer = setTimeout(() => {
                 const result = this.flush();
-                // Handle the case where flush returns a Promise (async flushCallback)
+                // Handle case where flush returns a Promise (async flushCallback)
                 if (result instanceof Promise) {
-                    result.catch(error => {
-                        console.error('Error in TimeBasedAggregator flush callback:', error);
+                    result.catch((error) => {
+                        console.error("Error in TimeBasedAggregator flush callback:", error);
                     });
                 }
             }, this.flushInterval);
@@ -59,19 +79,30 @@ class TimeBasedAggregator {
     }
     flush() {
         if (this.logs.length > 0) {
-            // Clear the timer if it exists
+            // Clear timer if it exists
             if (this.timer) {
                 clearTimeout(this.timer);
                 this.timer = null;
             }
             const logsToFlush = [...this.logs];
+            const originalLogs = [...this.logs];
             this.logs = [];
-            return this.flushCallback(logsToFlush);
+            try {
+                const callbackResult = this.flushCallback(logsToFlush);
+                if (callbackResult instanceof Promise) {
+                    return callbackResult.catch((error) => {
+                        this.logs = originalLogs;
+                        throw error;
+                    });
+                }
+            }
+            catch (error) {
+                this.logs = originalLogs;
+                throw error;
+            }
         }
     }
-    /**
-     * Stop the aggregator and cancel any pending timer without flushing
-     */
+    //Stop aggregator and cancel any pending timer without flushing
     stop() {
         if (this.timer) {
             clearTimeout(this.timer);
@@ -80,9 +111,7 @@ class TimeBasedAggregator {
     }
 }
 exports.TimeBasedAggregator = TimeBasedAggregator;
-/**
- * Combines multiple aggregators
- */
+//Combines multiple aggregators
 class CompositeAggregator {
     constructor(aggregators) {
         this.aggregators = aggregators;
@@ -101,8 +130,8 @@ class CompositeAggregator {
             }
         }
         // If any aggregator returns a promise, wait for all of them
-        if (results.some(r => r instanceof Promise)) {
-            const promiseResults = results.filter(r => r instanceof Promise);
+        if (results.some((r) => r instanceof Promise)) {
+            const promiseResults = results.filter((r) => r instanceof Promise);
             return Promise.all(promiseResults).then(() => { });
         }
     }

package/dist/cjs/core/Formatter.js

@@ -1,8 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Formatter = void 0;
-const TimeUtil_js_1 = require("../utils/TimeUtil.js");
-const ColorUtil_js_1 = require("../utils/ColorUtil.js");
+const index_js_1 = require("../utils/index.js");
 class Formatter {
     constructor(options = {}) {
         const { colorize = true, json = false, timestampFormat = "YYYY-MM-DD HH:mm:ss", timestamp = false, customColors = {}, } = options;
@@ -37,7 +36,7 @@ class Formatter {
     formatAsText(data) {
         let output = "";
         if (this.timestamp) {
-            output += `[${TimeUtil_js_1.TimeUtil.format(data.timestamp, this.timestampFormat)}] `;
+            output += `[${index_js_1.TimeUtil.format(data.timestamp, this.timestampFormat)}] `;
         }
         if (data.prefix) {
             output += `${data.prefix} `;
@@ -45,7 +44,7 @@ class Formatter {
         let level = data.level.toUpperCase();
         if (this.colorize) {
             const color = this.customColors[data.level] || data.level;
-            level = ColorUtil_js_1.ColorUtil.colorize(level, color);
+            level = index_js_1.ColorUtil.colorize(level, color);
         }
         output += `[${level}] ${data.message}`;
         if (data.metadata) {